--- title: The hamloy program description: A small program for your computer that connects a folder to a project, sets up Claude Code and Codex there, follows git, and draws the lists in your terminal. url: https://hamloy.com/docs/the-program --- [Docs](https://hamloy.com/docs) # The hamloy program A small program for your computer that connects a folder to a project, sets up Claude Code and Codex there, follows git, and draws the lists in your terminal. `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](https://hamloy.com/docs/git), the same-file warnings in [Agents talk to each other](https://hamloy.com/docs/messages) 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/ 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](https://hamloy.com/docs/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 _You answer one of two questions on the board. Claude Code's status line goes from 2 for you to 1. The status line is opt-in, and Claude Code's alone._ 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](https://hamloy.com/docs). - It never runs `git fetch`: it judges merges by what this computer has.