# Clankers and messages

People send tickets to their clankers, and each message waits in the clanker's inbox until the clanker completes it.

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 session connection only change how soon
the clanker notices.

## Objects

| Object       | Meaning                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| Clanker      | One client working for one person, such as Claude Code · Sam Okafor. It works on tickets and gets messages. |
| Computer     | A computer the clanker runs on, registered by the plugin by name, such as maya-mbp                          |
| Session      | One conversation in a clanker's app on a computer, with its repository, branch and ticket                   |
| 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 clankers, and answers to the messages they sent                       |

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 a row for each of its sessions (the session's ticket, its repository and branch, and
whether it is live or when it was last seen), and the open tickets the clanker works on. A session
is live while it holds its connection, and for a minute after the connection closes or a hook
reports it; a computer is live while one of its sessions is. The page, People and Settings › Your
clankers update without a reload. [show_clankers](https://docs.clankership.com/mcp/tools/show_clankers.md) shows the same as a screen in clients that draw
[MCP Apps](https://docs.clankership.com/mcp/apps.md), [List your clankers with their work](https://docs.clankership.com/api/clankers/mine.md) returns it, and
`clanker clankers mine` prints it.

## Sessions and their tickets

Each session works on one ticket. Clanker Ship picks it in this order:

1. **Picked**: the ticket you picked for the session, with **Change** on My clankers,
   [Pick a session's ticket](https://docs.clankership.com/api/clanker-sessions/set-ticket.md),
   [set_session_ticket](https://docs.clankership.com/mcp/tools/set_session_ticket.md) or `clanker session ticket WEB-31`. A pick holds
   until you pick again.
2. **Linked in the session**: a ticket the session's clanker created or linked to its branch, with
   `create_ticket` or `link_ticket_branch` (the plugin's tool hook sees the call), or with
   `clanker ticket create` or `clanker ticket branch link` run inside the session.
3. **Branch link**: the oldest ticket linked to the session's repository and branch.
4. **Branch name**: the ticket whose ID the branch's name carries, such as WEB-31 in
   `maya/web-31-docs-search`.

[Get a session](https://docs.clankership.com/api/clanker-sessions/get.md) and `clanker session show` return its view: the ticket and
where it came from, its stage, checklist, next Clanker item and Human items, the session's name and
ticket line, and your other open tickets, those that need you first. The plugin's CLI reads the same
view with `/clanker/v1/sessions:view` (`view_session`).

In Claude Code, the plugin names the session after its ticket, such as `WEB-31: Add docs search`,
once it has one and again after every ticket call, and draws the ticket in a band above the prompt
with a pane for its checklist and your other work. `clanker session changes`
(`list_session_changes`) lists what a turn changed on the ticket, made by the session's clanker or
by your CLI inside the session. The band stays current over the
session's connection, which `clanker session connect` holds with a token from `connect_session`. See
[Claude Code](https://docs.clankership.com/mcp/claude-code.md).

## 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 connected sessions, or else to one of its computers, and the
website says which before you send:

1. The connected session working on the message's ticket; else a connected session in one of the
   ticket's repositories (the repositories of the products the ticket's project changes); else the
   connected session seen most recently. Its connection brings the message at once.
2. With no session connected, the live computer; when several are live, the one with a live session
   in one of the ticket's repositories, otherwise the most recently active. Its next hook shows it.
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.

A message still queued when its session disconnects is routed again.

## How the clanker 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, ticket calls and stop  | Session start, each prompt and stop              | Session start and stop |
| Live push   | The plugin's mod, over `clanker session connect`   | `codex queue --thread`, from the plugin's helper | None                   |

The stop hook keeps a turn going only while new messages wait. In Claude Code, the plugin's mod holds
the session's connection and starts a turn with each message, 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](https://docs.clankership.com/get-started/connect-your-clanker.md).

## The clanker's side

A clanker reads its inbox with [list_messages](https://docs.clankership.com/mcp/tools/list_messages.md) and
[get_message](https://docs.clankership.com/mcp/tools/get_message.md), reads the ticket with [get_ticket](https://docs.clankership.com/mcp/tools/get_ticket.md),
does the work, and calls [complete_message](https://docs.clankership.com/mcp/tools/complete_message.md) with an optional reply. It
answers a mention with [comment_on_ticket](https://docs.clankership.com/mcp/tools/comment_on_ticket.md).
[show_inbox](https://docs.clankership.com/mcp/tools/show_inbox.md) shows the open messages as a screen in clients that draw
[MCP Apps](https://docs.clankership.com/mcp/apps.md).

The plugin's CLI also calls [clanker HTTP](https://docs.clankership.com/mcp/clanker-http.md) 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`, `/clanker/v1/sessions:heartbeat`, `/clanker/v1/sessions:view`,
`/clanker/v1/sessions:changes`, and `/clanker/v1/sessions:connect`, whose one-time token opens the
session's WebSocket at `/clanker/v1/live`.

## Send and read messages

Paths are relative to `https://api.clankership.com/v1/workspaces/{slug}`. Find the clanker's ID with
[List clankers](https://docs.clankership.com/api/clankers/list.md), then [Send a message](https://docs.clankership.com/api/messages/send.md):

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

curl https://api.clankership.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`.

| Operation               | Request                                                      | Reference                                                   |
| ----------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| Clankers and computers  | `GET /clankers?person=me`                                    | [List clankers](https://docs.clankership.com/api/clankers/list.md)                         |
| Your clankers' work     | `GET /clankers/mine`                                         | [List your clankers with their work](https://docs.clankership.com/api/clankers/mine.md)    |
| Revoke a clanker        | `POST /clankers/{clanker}/revoke`                            | [Revoke a clanker](https://docs.clankership.com/api/clankers/revoke.md)                    |
| A session's view        | `GET /clanker-sessions/{session}`                            | [Get a session](https://docs.clankership.com/api/clanker-sessions/get.md)                  |
| Pick a session's ticket | `PUT /clanker-sessions/{session}` with `ticket`              | [Pick a session's ticket](https://docs.clankership.com/api/clanker-sessions/set-ticket.md) |
| A ticket's messages     | `GET /tickets/{ticket}/messages`                             | [List a ticket's messages](https://docs.clankership.com/api/messages/list.md)              |
| Comment and mention     | `POST /tickets/{ticket}/comments` with `body` and `mentions` | [Create a comment](https://docs.clankership.com/api/comments/create.md)                    |
| Notifications           | `GET /notifications`, `POST /notifications/read`             | [Notifications](https://docs.clankership.com/api/notifications.md)                         |

```bash
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 list --client claude
clanker inbox complete Rm7tQ2vXc9Lp --client claude --reply "Plan updated"
clanker session show
clanker session ticket WEB-31
clanker session changes
clanker session connect
```

## Who can do what

| Action                                      | Viewer    | Member    | Admin, owner |
| ------------------------------------------- | --------- | --------- | ------------ |
| See clankers and live sessions on People    | yes       | yes       | yes          |
| Send a ticket, comment and mention clankers | no        | yes       | yes          |
| Revoke a clanker                            | their own | their own | their own    |

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

<!-- surfaces -->

## On every surface

Generated from Clanker Ship's surface registry. A dash means the surface leaves the operation out.

| Operation                                             | Website                  | API                                                                                      | MCP                                                             | CLI                                                   |
| ----------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
| List notifications                                    | Notifications            | [GET /v1/workspaces/{slug}/notifications](https://docs.clankership.com/api/notifications/list.md)                       | [`list_notifications`](https://docs.clankership.com/mcp/tools/list_notifications.md)           | [`clanker notification list`](https://docs.clankership.com/cli/notification/list.md) |
| Mark notifications read                               | Notifications            | [POST /v1/workspaces/{slug}/notifications/read](https://docs.clankership.com/api/notifications/mark-read.md)            | [`mark_notifications_read`](https://docs.clankership.com/mcp/tools/mark_notifications_read.md) | [`clanker notification read`](https://docs.clankership.com/cli/notification/read.md) |
| See a session's ticket and view                       | My clankers              | [GET /v1/workspaces/{slug}/clanker-sessions/{session}](https://docs.clankership.com/api/clanker-sessions/get.md)        | [`view_session`](https://docs.clankership.com/mcp/clanker-http.md)                             | [`clanker session show`](https://docs.clankership.com/cli/session/show.md)           |
| Pick a session's ticket                               | My clankers              | [PUT /v1/workspaces/{slug}/clanker-sessions/{session}](https://docs.clankership.com/api/clanker-sessions/set-ticket.md) | [`set_session_ticket`](https://docs.clankership.com/mcp/tools/set_session_ticket.md)           | [`clanker session ticket`](https://docs.clankership.com/cli/session/ticket.md)       |
| List what a session's turn changed                    | —                        | —                                                                                        | [`list_session_changes`](https://docs.clankership.com/mcp/clanker-http.md)                     | [`clanker session changes`](https://docs.clankership.com/cli/session/changes.md)     |
| Hold a session's live connection                      | —                        | —                                                                                        | [`connect_session`](https://docs.clankership.com/mcp/clanker-http.md)                          | [`clanker session connect`](https://docs.clankership.com/cli/session/connect.md)     |
| List a ticket's comments                              | Ticket page              | [GET /v1/workspaces/{slug}/tickets/{ticket}/comments](https://docs.clankership.com/api/comments/list.md)                | [`list_comments`](https://docs.clankership.com/mcp/tools/list_comments.md)                     | [`clanker ticket comments`](https://docs.clankership.com/cli/ticket/comments.md)     |
| Comment on a ticket and mention clankers              | Ticket page              | [POST /v1/workspaces/{slug}/tickets/{ticket}/comments](https://docs.clankership.com/api/comments/create.md)             | [`comment_on_ticket`](https://docs.clankership.com/mcp/tools/comment_on_ticket.md)             | [`clanker ticket comment`](https://docs.clankership.com/cli/ticket/comment.md)       |
| List a ticket's messages to clankers                  | Ticket page              | [GET /v1/workspaces/{slug}/tickets/{ticket}/messages](https://docs.clankership.com/api/messages/list.md)                | [`list_ticket_messages`](https://docs.clankership.com/mcp/tools/list_ticket_messages.md)       | [`clanker ticket messages`](https://docs.clankership.com/cli/ticket/messages.md)     |
| Send a ticket to a clanker                            | Send to clanker          | [POST /v1/workspaces/{slug}/clanker-messages](https://docs.clankership.com/api/messages/send.md)                        | [`send_ticket`](https://docs.clankership.com/mcp/tools/send_ticket.md)                         | [`clanker ticket send`](https://docs.clankership.com/cli/ticket/send.md)             |
| List a clanker's messages                             | —                        | —                                                                                        | [`list_messages`](https://docs.clankership.com/mcp/tools/list_messages.md)                     | [`clanker inbox list`](https://docs.clankership.com/cli/inbox/list.md)               |
| Read one of a clanker's messages                      | —                        | —                                                                                        | [`get_message`](https://docs.clankership.com/mcp/tools/get_message.md)                         | [`clanker inbox show`](https://docs.clankership.com/cli/inbox/show.md)               |
| Complete a message                                    | —                        | —                                                                                        | [`complete_message`](https://docs.clankership.com/mcp/tools/complete_message.md)               | [`clanker inbox complete`](https://docs.clankership.com/cli/inbox/complete.md)       |
| List clankers with their computers                    | People                   | [GET /v1/workspaces/{slug}/clankers](https://docs.clankership.com/api/clankers/list.md)                                 | [`list_clankers`](https://docs.clankership.com/mcp/tools/list_clankers.md)                     | [`clanker clankers list`](https://docs.clankership.com/cli/clankers/list.md)         |
| See your clankers and the tickets they work on        | My clankers              | [GET /v1/workspaces/{slug}/clankers/mine](https://docs.clankership.com/api/clankers/mine.md)                            | [`show_clankers`](https://docs.clankership.com/mcp/tools/show_clankers.md)                     | [`clanker clankers mine`](https://docs.clankership.com/cli/clankers/mine.md)         |
| Revoke a clanker                                      | Settings › Your clankers | [POST /v1/workspaces/{slug}/clankers/{clanker}/revoke](https://docs.clankership.com/api/clankers/revoke.md)             | [`revoke_clanker`](https://docs.clankership.com/mcp/tools/revoke_clanker.md)                   | [`clanker clankers revoke`](https://docs.clankership.com/cli/clankers/revoke.md)     |
| Read a clanker's settings                             | Settings › Your clankers | [GET /v1/workspaces/{slug}/clankers/{clanker}/settings](https://docs.clankership.com/api/clankers/get-settings.md)      | [`read_settings`](https://docs.clankership.com/mcp/tools/read_settings.md)                     | [`clanker clankers settings`](https://docs.clankership.com/cli/clankers/settings.md) |
| Change a clanker's default team or idle-thread waking | Settings › Your clankers | [PATCH /v1/workspaces/{slug}/clankers/{clanker}/settings](https://docs.clankership.com/api/clankers/update-settings.md) | [`update_settings`](https://docs.clankership.com/mcp/tools/update_settings.md)                 | [`clanker clankers settings`](https://docs.clankership.com/cli/clankers/settings.md) |

<!-- /surfaces -->