The hamloy program

hamloy is a small program for your computer. It connects a folder to a project, sets up Claude Code and Codex to work on it, tells Hamloy where each agent works and what it edits, notices when work is merged, and draws the lists in your terminal.

Agents can use Hamloy without it, through the tools alone. The program adds what only your computer knows: the folder, the branch, the files an agent edits, and what is merged. Following git, the same-file warnings in Agents talk to each other and taking a claim back after a restart all need it.

Install

On macOS or Linux:

curl -fsSL https://hamloy.com/install | sh

On Windows, in PowerShell:

irm https://hamloy.com/install.ps1 | iex

It puts the program in ~/.local/bin after checking it against Hamloy's checksums. It runs on macOS, Linux and Windows, on Intel and ARM. It keeps itself up to date: once a day, when an assistant starts, it asks Hamloy for the newest version in the background, checks it against the checksums the same way, swaps it in, and brings its hooks up to date. The board says so beside that assistant. hamloy update does it at once, and HAMLOY_NO_UPDATE=1 turns the daily update off.

Connect a folder

In your project's folder:

hamloy connect

It signs you in through the browser, asks which project the folder is for (a new one named after the folder, or one you have), and sets up Claude Code and Codex, whichever is on the computer. Each step gets one line:

The program
  ✓ put hamloy in ~/.local/bin/hamloy
Signing in to https://hamloy.com
  ✓ signed in; the sign-in is kept in the Keychain
The project for ~/pebble
  ✓ linked ~/pebble to Pebble
Claude Code
  ✓ ~/.claude/settings.json: the program's hooks (quiet in folders not linked to a project)
  ✓ ~/.claude/commands/hamloy.md: the /hamloy command, which shows the lists without asking the model
  ✓ ~/.claude.json: the project's tools for ~/pebble, signed in through the program
Codex
  ✓ ~/.codex/hooks.json: the program's hooks (quiet in folders not linked to a project)
  ✓ ~/.codex/config.toml: your projects' tools for Codex, signed in through the program
  ✓ ~/.codex/AGENTS.md: a note naming the folders kept in Hamloy, so Codex looks for its tools

~/pebble works on Pebble now.
  Claude Code: start it here (or restart it), and type /hamloy to see the lists.
  Codex: start it here, and approve Hamloy's hooks once with /hooks (Codex asks, by design).
  The board: https://hamloy.com/p/<the project's id>
  Undo: hamloy disconnect (this folder), hamloy disconnect --all (this computer)

Running it again is safe: what is set up already says so and is left alone. hamloy connect --project Pebble names the project instead of asking.

Nothing is written into your folder, and every worktree and branch of the repo works on the same project. Claude Code gets the tools for this one project; Codex gets them for all your projects, and asks you once to approve new hooks.

hamloy connect --share also writes .mcp.json in the folder, so teammates who clone the repo find the project. See Teams and sharing.

What the hooks do

The hooks run when a session starts or ends, when you send a prompt, after each step an agent takes, when it stops, and for subagents. They tell Hamloy:

• the computer's name and the folder;
• the repo, branch and commit, and whether there are uncommitted changes;
• the paths of files an agent edits, never what is in them;
• the first line of each prompt, cut to 120 characters, only if you turn it on with hamloy config prompts on.

In return the agent hears, at the start, the open lists and what is next up (what is under a heading named Later only as a count, so the ideas you put off don't cost it tokens every step). When it claims an item it hasn't read, the reply gives that item's summary and notes. Later it hears its news and messages without waiting for its next Hamloy tool call. That is the same for Claude Code and Codex. A subagent hears only what its session is on and how much is open, since its session keeps the lists.

hamloy off quiets the hooks in a folder: the board doesn't hear where agents work there or what they edit, and merges aren't checked. The agents keep their tools. hamloy on undoes it.

The lists in your terminal

• hamloy show draws the lists once: hamloy show todo, hamloy show questions, hamloy show B-k3f9.
• hamloy watch keeps them drawn as they change.
• hamloy panel opens hamloy watch beside the agent. It splits the window in tmux, Zellij, iTerm2, WezTerm, Kitty (with remote control on) and Windows Terminal, and elsewhere opens a window beside yours. From inside Claude Code or Codex, type !hamloy panel.

✓ Opened the panel on the right (tmux). q in it, or hamloy panel off, closes it.

The panel has the board's pages as tabs: Overview, what is for you, who is on what now, the Map, what has gone quiet, recent changes, branches, and your saved views. Tab and 1–9 move between them; q closes it.

You can also change the lists from your terminal, as you: hamloy add, tick, note, set, answer, message and more; hamloy help lists them. These don't run inside an agent's shell, so an agent changes the lists through the tools, as itself.

The status line in Claude Code

Claude Code can show a Hamloy line under its prompt: what this session is on, how many items wait for you, and how many are ready to start. A session that is on nothing sees what is next instead:

Hamloy  ◐ B-k3f9 Streak counter on the…  2 for you · 5 ready
Hamloy  2 for you · 5 ready · next B-25qb Show the week as dots

It is off until you turn it on:

hamloy statusline on

If you have a status line of your own, it is left alone; hamloy statusline on --below keeps yours and puts Hamloy's under it. hamloy statusline off takes it out.

Codex has no Hamloy status line: its status line takes only its own items. Use hamloy show or the panel there.

Disconnect

• hamloy disconnect unlinks this folder and takes the project's tools out of Claude Code for it. The hooks, the /hamloy command and the status line stay, quiet in folders not linked; hamloy disconnect --all takes them out.
• hamloy disconnect --all unlinks every folder, takes out the hooks and Codex's setup, and signs out, removing the sign-in from the computer.
• Disconnect beside the program on Hamloy's Connect page, under Connected apps, refuses it from then on, say for a computer you no longer have. Its hooks and settings stay on that computer until hamloy disconnect --all is run there. Run hamloy connect there and it signs in again.
• hamloy uninstall does that, then takes the program itself off the computer: the program, its settings, and the two lines the install put in your shell's profile.

Your lists stay on Hamloy either way. hamloy status shows what is set up, here and on the computer.

Limits

• The program sets up Claude Code and Codex. Other clients connect through the tools alone; see Docs.
• It never runs git fetch: it judges merges by what this computer has.