Skip to main content

Build an agent on Kosuke

Your agent can drive Kosuke through the MCP server, the CLI or the API. Whichever it uses, the same rules apply. Follow each turn to its end. Answer the agent in the session when it asks. Stop when a person or the credit limit stops you.

Pick a client​

ClientBest forHow it follows a turnSet up
MCP serverA coding agent such as Claude Code, Codex or Cursor.ship starts the work, watch follows the job and returns the last reply, and submit opens the pull request.Connect your coding agent
CLIShell scripts, and agents that run commands.kosuke sessions watch streams the turn's events as they happen and exits when the job ends.Kosuke CLI
APIYour own code, in any language.Poll the job until it ends, then read the session's messages. Generate a client from the OpenAPI document.Quickstart

Every client acts as its member. The CLI and the API use an API key. The MCP server signs the member in through the browser, or takes an API key from a client with no browser.

Rules your agent follows​

  1. Read delivery after every send. job gives a chatJobId to follow. queued means the message waits Up next behind the running turn. See Follow a turn.
  2. Follow each turn to its end. Wait until the job leaves pending and running, polling every few seconds or streaming with kosuke sessions watch. See Follow a turn.
  3. Answer the agent's Clarifications. A job that ends awaiting_response holds questions in its last message, and Up next pauses. Send the answers as an ordinary message. See Follow a turn.
  4. Read the reply from the messages. The job carries its status, errors and timestamps, not the reply. The agent's words are in the session's messages. See Follow a turn.
  5. Wake the sandbox before you read files, the diff or git state. Request the session's preview, and wait while it reports provisioning. A paused sandbox answers the changed-file list with an empty list and the patch with 503. See Sandboxes and previews.
  6. Stop on 402 CREDIT_LIMIT_REACHED. Retrying fails until an admin sorts out billing. The preview shows the same state as creditLimitReached: true. See Responses and errors.
  7. Stop on JOB_STOPPED or a job that ends cancelled. A person stopped that turn on purpose. Wait for them before you start another. See Follow a turn.
  8. Send model ids as provider:model__effort, such as anthropic:opus__high. On a send, Kosuke ignores an id it cannot run and keeps the session's model, so read the session back. See Follow a turn.
  9. Send skills as messages. /kosuke:open-pr opens the pull request. /kosuke:sync-branch brings in the Target Branch, or the open pull request's base once there is one. Codex sessions take $kosuke:open-pr and $kosuke:sync-branch. See Pull requests and sync.
  10. Read a 404 as "not found or no access". Project routes answer 404 for both, so do not retry one. See Responses and errors.
  11. Give each agent its own API key. Revoke it when the agent retires. See Authentication.

A turn from start to finish​

With the MCP server, one change takes four tool calls:

  1. ship with the project id and the prompt. It returns the session and the job.
  2. watch with the project id, the session id and the job id. Call it again while it returns done: false.
  3. submit with the project id and the session id. It sends /kosuke:open-pr, or $kosuke:open-pr on Codex, and returns the job. While a turn is running, it returns delivery: queued instead.
  4. watch on that job. The pull request link is on the session once the job ends.

The same flow in curl is in Ship a change end to end.

Next steps​