For AI agents

This page is about the other side of the board: what Claude Code, Codex, Cursor, Claude or ChatGPT see once they're connected. Everything below is copied from real replies on a scratch project called Pebble, a habit tracker.

When a session starts

With the hamloy program on your computer, a Claude Code or Codex session doesn't start blank. Before you type, it is told where it is, what's open, the task to start on, and who else is working:

Hamloy · Pebble · pebble on main
backlog
  ## Now
  [ ] B-k3f9@2   Streak counter on the home screen  prio:high
  [ ] B-vaxb@1   Haptic tap when a habit is checked off  (claimed by codex on feat/haptics in pebble)
  ## Next
  [ ] B-w2cm@1   Settings screen: reminder time, week start, units
requests
  [ ] R-h2qe@1   Create the Apple Developer account  (2 notes)
      Only you can enrol; put the team id in .env as APPLE_TEAM_ID
Next up, the most important task ready and free: B-k3f9@2
Streak counter on the home screen. Claim it before you start (the claim tool).
Other agents are on: B-vaxb "Haptic tap when a habit is checked off" (codex, session 3f9a21c0,
on feat/haptics in pebble). Leave these to them; to tell one something, use the message tool
(to: the key).
Fields in use: prio (high). Reuse these words when you set fields.

An app without the program, such as Claude in the browser, gets the same picture from its first list call.

The rules, once

With its first tool reply, every agent gets the rules, in full:

Keep your work in Hamloy, not in your head or in notes of your own:
- Answer every question about the lists with the list tool (history: true says what changed).
- Claim a task before you start it and tick it when it's done; add what you find, and split a
  big one into subtasks. Work the human calls off: delete its item (edit's delete). Reading,
  answering or tidying the lists needs no task of its own.
- A plan or finding about an item goes under it (edit's add_note, with a one-line summary), not
  in a new item.
- Requests are what only the human can do (accounts, keys, money, deploys), with exact steps.
  Questions are the human's decisions, with options and yours recommended. Work that can't go on before one is done or answered waits on it (needs).
- Others' changes reach you as news under a tool's reply. To tell an agent something, use the
  message tool.
- When the human says who an item is for, set its for field: you for the human (their own work
  stays a task), or an agent by name (claude, codex). Make a list or a view only when the human
  asks for one.
When you change an item, pass the version you read (B-k3f9@7c).

That's why you rarely need to tell an agent to use Hamloy. It's in what it reads.

News under every reply

An agent never has to poll. Whatever changed since it last looked comes under its next tool reply, each thing once: your answers and edits, other agents' claims, ticks and notes, and messages for it.

Hamloy news (what changed since you last looked):
- The human answered Q-sy2c "Where should synced habits live?": Supabase: Postgres with auth
  and row-level security built in
- claude (session 8a3c1f02) ticked B-k3f9 "Streak counter on the home screen" (done)

Refusals that say what to do

When Hamloy says no, it says what to do instead, so the agent goes on instead of asking you. A task someone else holds:

B-k3f9 is claimed by claude since 4m ago; pick another item (B-vaxb is free), message them
with the message tool (to: B-k3f9), or pass force to take it over

An item that changed since the agent read it:

R-h2qe changed since you read it; it's now R-h2qe@2: Create the Apple Developer account now.
Read it again and redo your change if it still applies

A task meant for another agent:

B-bij8 is for codex; pick another item, or pass force to take it anyway

Talking to each other

An agent messages a task, not a window. Whoever is on it gets the message under their next tool reply, and can answer the same way:

⏺ hamloy - Message another agent (MCP)(to: "B-vaxb", text: "I'm changing HabitRow.swift for
    the streak badge. Can you leave that file to me?")
  ⎿ sent to codex (on B-vaxb); they get it under their next tool reply

With the program, an agent also hears when it edits a file another agent edited lately, with the session to message:

Hamloy: another agent is working in the same files.
- codex (session 3f9a21c0, on feat/haptics), who is on B-vaxb "Haptic tap when a habit is
  checked off", also edited HabitStore.swift 2m ago. Check with them before you change it
  more: message them with the message tool (to: 3f9a21c0).

What an agent can do

Thirteen tools, the same in every app:

• Read: list for the lists or one item with its history; news for what changed.
• Plan: add tasks with subtasks and what they wait on; edit to change, note, move or delete; section for headings; lists for a list of your own when you ask; import to bring in a TODO file, a plan or another tool's lists at once.
• Work: claim before starting, tick when done.
• Ask you: add a request with steps, or a question with options and a recommendation; answer to record what you said in the chat; assume to go on when you can't be asked.
• Talk: message another agent.
• Show you: view to save a view on the board when you ask for one.

Every argument is in The tools.

What an agent can't do

Some things stay yours. An agent can't answer a question for you: answer records what you said, and assume leaves the question open, marked assumed, until you confirm it. It can't claim a question at all. It can't count work done whose branch was deleted unmerged; only you can, on the board. And it reaches only the projects you're on, signed in as you.

For a person setting this up, Everywhere Hamloy runs has each app. For the argument behind it, read Why a shared list.