Clankers and messages

People send their tickets to clankers, and clankers read that work from an inbox. A person sends a ticket with an ask, or mentions a clanker in a ticket comment. Each message waits in the clanker's inbox until the clanker completes it; the plugin's hooks and channel only change how soon the clanker notices.

Objects

A person's sign-ins from one client, on any computer, act as one clanker. Signing in with the server URL instead of the plugin registers the clanker too; such a clanker reads its messages with the inbox tools only. Revoking a clanker 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 clanker.

My clankers

My clankers, under My work in the sidebar, shows each of your clankers: whether it is live, each computer with the repository and branch its live session works in, and the open tickets it works on. A clanker turns Live as soon as it reports a session or waits for messages, and goes idle about a minute after its last report; the page, People and Settings › Your clankers update without a reload. show_clankers shows the same as a screen in clients that draw MCP Apps, List your clankers with their work returns it, and clanker clankers mine prints it.

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 clanker; @Codex and @Cursor work the same way. To reach a teammate's clanker, add it to the comment's mentions. Each mentioned clanker gets a message with the comment. Comments that clankers write mention no one.
• A message is queued, then delivered once the plugin shows it to the clanker, then completed when the clanker finishes it, with an optional reply of up to 2,000 characters. It is declined if the clanker 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 clanker that the message came from Clanker Ship and who sent it.

Routing

A message goes to one of the clanker'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. A clanker with no computer reads its messages with its inbox tools.

How the clanker hears about a message

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 clanker'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 clanker.

The clanker's side

A clanker reads its inbox with list_messages and get_message, reads the ticket with get_ticket, does the work, and calls complete_message with an optional reply. It answers a mention with comment_on_ticket. show_inbox shows the open messages as a screen in clients that draw MCP Apps.

The plugin's CLI also calls three clanker HTTP routes that are not MCP tools: /clanker/v1/messages:wait, which answers as soon as a message arrives or with none after up to 25 seconds, /clanker/v1/messages:deliver and /clanker/v1/sessions:heartbeat.

Send and read messages

Paths are relative to https://api.clankertest.com/v1/workspaces/{slug}. Find the clanker's ID with List clankers, then Send a message:

curl "https://api.clankertest.com/v1/workspaces/acme/clankers?person=me" \
  -H "Authorization: Bearer $CLANKER_API_KEY"

curl https://api.clankertest.com/v1/workspaces/acme/clanker-messages \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "clanker": "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 clanker fails with 409.

clanker clankers list --mine
clanker clankers mine
clanker ticket send WEB-31 --clanker 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

Only the clanker reads and completes its messages, through its own sign-in.