# Agents and messages People send tickets to their coding agents, and each message waits in the agent's inbox until the agent completes it. People send their tickets to coding agents, and agents read that work from an inbox. A person sends a ticket with an ask, or mentions an agent in a ticket comment. Each message waits in the agent's inbox until the agent completes it; the plugin's hooks and channel only change how soon the agent notices. ## Objects | Object | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------- | | Registered agent | One client working for one person, such as Claude Code ยท Sam Okafor. It owns tickets and gets messages. | | Computer | A computer the agent runs on, registered by the plugin by name, such as maya-mbp | | Session | One running agent on a computer, with its repository and branch. Seen in the last minute, it is live. | | Message | A ticket with an ask (`draft`, `refine`, `plan` or `build`), or a mention in a comment | | Notification | What a person sees: messages to their agents, and answers to the messages they sent | A person's sign-ins from one client, on any computer, act as one registered agent. Signing in with the server URL instead of the plugin registers the agent too; such an agent reads its messages with the inbox tools only. Revoking an agent ends every sign-in at once, declines the messages waiting in its inbox and tells their senders. The next sign-in from that client registers a new agent. ## Messages - Members send tickets they can change; viewers and account API keys send nothing. The ask is Draft the ticket (`draft`), Refine the ticket (`refine`), Write the plan (`plan`) or Build it (`build`), with an optional note of up to 2,000 characters. - Typing `@Claude` in a comment mentions your own Claude Code agent; `@Codex` and `@Cursor` work the same way. To reach a teammate's agent, add it to the comment's mentions. Each mentioned agent gets a message with the comment. Comments that agents write mention no one. - A message is `queued`, then `delivered` once the plugin shows it to the agent, then `completed` when the agent finishes it, with an optional reply of up to 2,000 characters. It is `declined` if the agent is revoked first. The sender is notified either way. Messages are requests within the ticket's scope, from the named sender. The plugin tells the agent that the message came from Clanker Ship and who sent it. ## Routing A message goes to one of the agent's computers, and the website says which before you send: 1. The live computer. 2. When several are live, the one with a live session in one of the ticket's repositories: the repositories of the products the ticket's project changes. Otherwise the most recently active. 3. When none is live, the computer seen most recently, at its next session. 4. An agent with no computer reads its messages with its inbox tools. ## How the agent hears about a message | Way | Claude Code | Codex | Cursor | | ----------- | -------------------------------------------------- | ------------------------------------------------ | ---------------------- | | Inbox tools | `list_messages`, `get_message`, `complete_message` | The same | The same | | Hooks | Session start, each prompt and stop | Session start, each prompt and stop | Session start and stop | | Live push | `clanker channel` (research preview) | `codex queue --thread`, from the plugin's helper | None | The stop hook keeps a turn going only while new messages wait. In Claude Code, start a session with `claude --channels plugin:clanker-ship@clankership` so the channel pushes each message in, even while the session is idle. In Codex, the plugin starts a helper that hands each message to the thread while the agent's **Wake idle threads for new messages** setting is on; when it cannot, the message stays queued and the next prompt's hook shows it. The hooks need the CLI signed in (`clanker auth login`) and the repository linked to the workspace (`clanker link acme`); see [Connect your agent](https://docs.qa.clankership.net/get-started/connect-your-agent.md). ## The agent's side An agent reads its inbox with [list_messages](https://docs.qa.clankership.net/mcp/tools/list_messages.md) and [get_message](https://docs.qa.clankership.net/mcp/tools/get_message.md), reads the ticket with [get_ticket](https://docs.qa.clankership.net/mcp/tools/get_ticket.md), does the work, and calls [complete_message](https://docs.qa.clankership.net/mcp/tools/complete_message.md) with an optional reply. It answers a mention with [comment_on_ticket](https://docs.qa.clankership.net/mcp/tools/comment_on_ticket.md). [show_inbox](https://docs.qa.clankership.net/mcp/tools/show_inbox.md) shows the open messages as a screen in clients that draw [MCP Apps](https://docs.qa.clankership.net/mcp/apps.md). The plugin's CLI also calls three [agent HTTP](https://docs.qa.clankership.net/mcp/agent-http.md) routes that are not MCP tools: `/agent/v1/messages:wait`, which answers as soon as a message arrives or with none after up to 25 seconds, `/agent/v1/messages:deliver` and `/agent/v1/sessions:heartbeat`. ## Send and read messages Paths are relative to `https://api.clankertest.com/v1/workspaces/{slug}`. Find the agent's ID with [List agents](https://docs.qa.clankership.net/api/agents/list.md), then [Send a message](https://docs.qa.clankership.net/api/messages/send.md): ```bash curl "https://api.clankertest.com/v1/workspaces/acme/agents?person=me" \ -H "Authorization: Bearer $CLANKER_API_KEY" curl https://api.clankertest.com/v1/workspaces/acme/agent-messages \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent": "Ag5HvB1mZr8K", "ticket": "WEB-31", "ask": "plan", "note": "Keep the search box in the header." }' ``` The response is the message, with status `201`, the computer routing chose, and `status: "queued"`. Sending to a revoked agent fails with `409`. | Operation | Request | Reference | | -------------------- | ------------------------------------------------------------ | ---------------------------------------------- | | Agents and computers | `GET /agents?person=me` | [List agents](https://docs.qa.clankership.net/api/agents/list.md) | | Revoke an agent | `POST /agents/{agent}/revoke` | [Revoke an agent](https://docs.qa.clankership.net/api/agents/revoke.md) | | A ticket's messages | `GET /tickets/{ticket}/messages` | [List a ticket's messages](https://docs.qa.clankership.net/api/messages/list.md) | | Comment and mention | `POST /tickets/{ticket}/comments` with `body` and `mentions` | [Create a comment](https://docs.qa.clankership.net/api/comments/create.md) | | Notifications | `GET /notifications`, `POST /notifications/read` | [Notifications](https://docs.qa.clankership.net/api/notifications.md) | ```bash clanker agent list --mine clanker ticket send WEB-31 --agent Ag5HvB1mZr8K --ask plan --note "Keep the search box in the header." clanker ticket comment WEB-31 --body "@Claude add a case for an empty query to the plan" clanker inbox --client claude clanker inbox complete Rm7tQ2vXc9Lp --client claude --reply "Plan updated" ``` ## Who can do what | Action | Viewer | Member | Admin, owner | | ----------------------------------------- | --------- | --------- | ------------ | | See agents and live sessions on People | yes | yes | yes | | Send a ticket, comment and mention agents | no | yes | yes | | Revoke an agent | their own | their own | their own | Only the agent reads and completes its messages, through its own sign-in.