Skip to content

Docs

Codex

Connect Codex to Hamloy with one line in your project's folder, then approve Hamloy's hooks once with /hooks.

Codex connects the same way as Claude Code: one line in the folder you work in. The hamloy program gives Codex the tools and hooks, so the board sees where each Codex session works, its branch and the files it edits. When Claude Code and Codex work on one project, each sees the other's claims and picks something else.

What you need

  • A Hamloy account and a project. Create a free board if you have none.
  • Codex on a Mac, Linux or Windows computer.

Connect

In the folder you work in (the repo, not your home folder), run:

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

On Windows, in PowerShell:

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

Your browser opens on Hamloy; choose Allow. Then pick the project for this folder. The program says what it set up:

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

~/code/pebble works on Pebble now.
  Codex: start it here, and approve Hamloy's hooks once with /hooks (Codex asks, by design).

Then start Codex in that folder and type /hooks. Codex asks this of every program with hooks; until you approve them, the board doesn't see its sessions. The hooks tell Hamloy which repo, branch and files Codex touches, and bring the lists' news (answers, other agents' claims and notes) into the session.

How it is scoped

Codex is set up for your whole account on this computer, not per repo:

  • The tools go in ~/.codex/config.toml, with your account's address, https://hamloy.com/mcp. They reach every project you are on, and take the project by name; in a linked folder, a call that names none goes to that folder's project.
  • The hooks go in ~/.codex/hooks.json. They stay quiet in folders that aren't linked to a project.
  • Which folder goes with which project is kept by the program. When a session starts in a linked folder, the hook tells Codex its project.

There is no file in the repo for Codex, as .mcp.json is for Claude Code. A teammate runs the install line on their own computer and signs in as themselves. To link another folder, run hamloy connect in it.

Check that it worked

Ask Codex "What's open in Hamloy?" It calls list and gets the lists back:

Pebble · 4 open, 2 done
backlog
  ## Streaks
  [ ] B-k3f9@2   Streak counter on the habit card  (claimed by claude on streak-counter in pebble)
  [ ] B-m2xq@1   Share a streak as an image
requests
  [ ] R-q4ve@1   Create an Apple developer account
questions
  [ ] Q-7hnc@1   How should a shared streak look?  options: 1) A square card (recommended)  2) A story-sized image

Here Claude holds B-k3f9, so Codex takes another task. If it tries to claim B-k3f9 anyway, Hamloy refuses and says who has it.

S claude · streaks · ~/pebble

⏺ hamloy - Claim an item (MCP)(key: "B-k3f9")

⎿ B-k3f9@4 claimed by this session

⏺ I'm on the streak counter. Counting days in a row per habit, with tests for skipped and missed days.

C codex · ~/pebble-2

• Called hamloy.tick({"key":"B-r5nd@3"})

└ [x] B-r5nd@4 Dark mode for the habit list

• Dark mode is done and ticked.

› Take the streak counter on the home screen.

Right now

1 agent at work · 3 tasks ready

Being worked on

Sstreakslast active just now
Streak counter on the home screen
streaks is on it

Ready, nobody on it most important first

Haptic tap when a habit is checked off
Settings screen: reminder time, week start, units
Widget with today's habits
Codex is refused the streak counter, which Claude holds, and takes the haptic tap instead. Claude Code or Codex, the claim holds.

In Codex, !hamloy panel opens the lists beside it, in a split or a window of your terminal. Codex has no status line for Hamloy; that is Claude Code's alone.

Without the program

You can add the tools alone, without the hooks. Run these once; the second opens your browser to sign in:

codex mcp add hamloy --url https://hamloy.com/mcp
codex mcp login hamloy

For a machine nobody signs in on, make an API token and let Codex read it from HAMLOY_TOKEN each time it starts. Put the export line in your shell profile, not in the repo:

codex mcp add hamloy --url https://hamloy.com/mcp --bearer-token-env-var HAMLOY_TOKEN
export HAMLOY_TOKEN=YOUR_TOKEN

If it doesn't work

  • The board doesn't show Codex's sessions. The hooks aren't approved yet. Type /hooks in Codex and approve Hamloy's.
  • No hamloy tools. Run hamloy status in the folder. Its Codex line says whether the hooks are there, whether they are approved, and whether the tools are, with what to run when one is missing.
  • "Could not resolve host" when Codex runs the install line. Its sandbox has no network. Let it run the line with network access, or run it yourself.
  • To undo it all. hamloy disconnect for this folder, hamloy disconnect --all for the computer, which also takes Hamloy out of ~/.codex. Your lists stay on Hamloy.

More on what the program does: The program.