Working with agents

Sign a coding agent in, give it work, and see what it did, from the CLI, the MCP server or the REST API.

Set up an agent

Hand your agent one prompt

Paste this into Claude Code, Codex, Cursor or any coding agent. It reads the docs index, installs the CLI and the skills, and works through setup, stopping where a person is needed.

Read https://status.sailfork.com/llms.txt.
Install the sailfork CLI with `curl -fsSL https://status.sailfork.com/install | sh`, run `sailfork skill install`, then run `sailfork onboard status --json` and follow the next command it gives until setup is done.

Install the skills

Two skills ship inside the CLI, so they always match its commands: sailfork (pull requests, issues and CI) and caisson (editing a repository on the server with no clone).

sailfork skill install                         # ~/.claude/skills, every project on this machine
sailfork skill install --project               # this repository's .claude/skills, shared through git
sailfork skill install --dir ~/.codex/skills   # any other agent's skills folder

Connect the MCP server

The remote server signs in through the browser. The local one runs over stdio as the account sailfork auth login signed in. Other clients and the read-only and per-toolset addresses are on MCP server.

claude mcp add --transport http sailfork https://status.sailfork.com/mcp
claude mcp add sailfork -- sailfork mcp

Start every session with context

As a session-start hook, this prints the pull requests, reviews and issues waiting in the current clone. The settings to add are on Working with agents.

sailfork hook session-start

Give it the docs

WhatAddress
Index of every page, for an agent to pick fromhttps://status.sailfork.com/llms.txt
Every page in one filehttps://status.sailfork.com/llms-full.txt
One page as MarkdownAdd .md to its address, as in https://status.sailfork.com/docs/ci.md, or send Accept: text/markdown
Every CLI command and flag as JSONsailfork commands --json, and sailfork schema <command> for what it prints

An agent's first session

With the CLI installed and signed in, an agent can take an issue to a merged pull request in a few commands. Each one prints JSON with --json.

sailfork onboard status --json --jq .next
sailfork issue next --claim --json --jq .number
sailfork issue start 7
sailfork brief 7
sailfork cs ship <caisson id> -m "Fix the tide math" --closes 7
sailfork wait pr <number> --checks

issue start claims the issue and opens a caisson, a working copy on the server, so the agent needs no clone. brief returns everything to start in one call. cs ship commits and opens the pull request. wait blocks until the checks finish, so the agent does not poll.

Three ways in

Use it whenSigns in with
The CLIThe agent has a shell. Every command takes --json, and the CLI is the most complete surface.sailfork auth login, or SAILFORK_TOKEN
The MCP serverThe agent is an assistant with no shell, or you want typed tools and a limit on what it can do.OAuth in the browser, or the CLI's login for sailfork mcp
The REST APIYou are writing your own agent or service.A personal access token as Authorization: Bearer

All three do the same things as a person does in the web app, under the same rules. A caisson, a pull request or a CI run looks the same whichever way it was made.

The CLI

Install it and sign in. An agent cannot approve its own sign-in, so a person does the first step:

sailfork auth login --device --json

This prints a code and an address to approve in a browser, and --no-wait and --resume let an agent print the code, hand it to the person, and finish later. sailfork auth setup-git --yes makes the CLI git's credential helper, so git push works too. Without a person at hand, set SAILFORK_TOKEN to a token.

Habits that keep an agent's calls cheap and predictable:

  • Use -R owner/repo instead of cd, and --jq instead of pipes, so one allowlisted sailfork command per call is enough.
  • --json prints all fields. --json=number,title keeps only those.
  • Output is capped at 64 KiB when a coding agent runs the CLI. Text is cut at a line with a note on how to get the rest, and JSON is shortened so it still parses and says what it left out. --max-bytes N or SAILFORK_MAX_BYTES changes the cap, and 0 lifts it.
  • --summary prints the compact form of pr view, issue view, ci view, ci logs (failed steps only) and pr diff (a per-file stat).
  • Under --json, a failure prints one JSON object on stderr with code, exitCode, message, retryable and often a hint.
  • Prompts and editors appear only on a terminal. Without one, a command that needs an answer fails and names the flag.

Exit codes tell an agent what to do next:

CodeMeaning
0Success
1Other failure, a failed check, or a condition that can no longer be met
3Not signed in, or the token was rejected
4Not found. For a private repository this also means you cannot see it.
5Forbidden
6Conflict: the file or branch changed, or a merge is refused
9Unavailable, retry later
10Precondition failed, such as --match-head-commit not matching
11Needs approval: a person must approve a held caisson write
12Pending: checks still running, or wait timed out

sailfork help exit-codes has the full list.

MCP

claude mcp add --transport http sailfork https://status.sailfork.com/mcp connects an assistant through the browser, with no token to paste. sailfork mcp runs the same tools over stdio as the account the CLI is signed in as. You can limit either to read-only tools or to some toolsets. See MCP server.

REST

Every route is documented in the REST API. sailfork api <path> makes an authenticated request from the CLI, with -f key=value fields and --paginate for lists.

Tokens and scopes

An agent works as a token. Create one under Settings, Keys and tokens, and give it only the scopes it needs: repo:read, repo:write, repo:admin, user, org:read, org:admin and sandbox. A token can also be limited to some repositories. See Tokens for the details.

  • A token cannot approve a write that a caisson rule holds for a person. Only a person in the browser can.
  • An organization has no setting that makes agent commits signed or limits how long agent keys live. The Agents controls on its Security page are not available yet: the server stores and enforces neither. A token's own expiry is the limit. See Tokens and Organizations.
  • A token with the sandbox scope can start sandboxes on your organization's machines.
  • An OAuth connection to the MCP server works on /mcp only, and the person chooses read only or read and write, and which repositories, when approving it.

How agent work is attributed

Sailfork marks work that comes from a coding agent so reviewers can tell it from a person's. The CLI and the MCP server send the client's name with every request (X-Sailfork-Agent), for example claude-code, an id for the run (X-Sailfork-Session), and how it reached Sailfork (X-Sailfork-Surface: cli or mcp). An agent's name shows a terminal icon for work done through the CLI and the MCP logo for work done over MCP.

  • The CLI detects a coding agent from the variables the agent sets. SAILFORK_AGENT=<name> names one yourself, and SAILFORK_AGENT=none turns detection off. SAILFORK_SESSION=<id> names the run. sailfork doctor prints what it detected.
  • The MCP server uses the name the client gives in its handshake, so Claude Code 1.0.3 and claude-code/2.1 are one agent.
  • A pull request, a comment or an issue progress update made this way is marked as agent work and names the client. A commit made through a caisson that an agent opened with a token is marked too.
  • A CI run whose commit came from such a caisson is marked as agent work on the Runs page.
  • A plain git push carries no header, so pushed commits are not marked unless a caisson made them.

A reviewer sees the mark next to the author, and the caisson's session log lists every read, edit and commit.

Leases on issues

When an agent claims an issue (sailfork issue claim 7, or issue next --claim), it takes a lease. A lease does not change the assignee, and it ends when you give the issue back with sailfork issue release 7, when --minutes runs out, or when the agent does not renew it. The issue then returns to Ready. Two sessions that share a token cannot both hold an issue: the second gets a 409 and takes over with issue release first.

The Agents page in the web app lists the issues your agents hold a lease on right now, and an issue page shows the agent working on it.

sailfork issue context 7 --state "..." --next "..." leaves a working context on the issue for whoever picks it up next, and issue release --note leaves a handoff note.

Turning it off

A person can turn this off for their account in Settings, Keys and tokens, under Agent tracking: Track agent work. Their tokens, CLI and MCP clients then read as them, with no agent marks and no leases. Plan limits and review rules still apply, because those key on the token.

Check the setup

sailfork onboard status --json lists every setup step as done, todo or needs_human, with the exact next command. An agent can run it at any point. It never prints a token.

{
  "complete": false,
  "next": { "step": "repository", "command": "sailfork repo create fenil/ocean-landing" },
  "steps": [{ "id": "signed_in", "state": "done" }]
}

The steps are signed_in, git, owner, repository, agent (optional) and teammates. A step marked needs_human carries a human object with the address to open and what to do there. --import plans a move from GitHub: it checks that GitHub is connected and says what a person must do if it is not.

sailfork doctor --json checks sign-in, token scopes and expiry, the git credential helper, the server version and which repository is in use. Each check is ok, warn or fail with the command that fixes it, and the exit code is 1 when one fails.

Start on an issue or pull request

sailfork brief <number> returns everything to begin work in one call.

sailfork brief 12 -R fenil/ocean-landing --json

For a pull request it returns the diff stat, the unresolved review threads with the code around each line, the CI counts with each failed check's failing step and last log lines, the open caissons on the head branch and the issues it closes. For an issue it returns the lease, the parent, blockers, sub-issues and linked pull requests. Both include the newest comments (10 by default, --comments <n|all> changes it). A part that cannot be read is named in gaps and the rest still answers.

The same data is the brief tool in the MCP server. sailfork pr feedback <number> prints just the unresolved threads.

Notes for the next agent

sailfork note keeps short facts about a repository for the agents and people who work it next: how to run the tests, a command that is slow, a path to leave alone.

sailfork note add "Run cargo test -p ledger, not the whole workspace: it takes 20 minutes." -R fenil/ocean-landing
sailfork note list -R fenil/ocean-landing
sailfork note edit 3 "Run cargo test -p ledger."
sailfork note delete 3 --yes
  • A note is one fact of at most 400 characters. A repository keeps at most 30 notes and 4,000 characters in all.
  • Writers add, edit and delete. Only members can read them, public repository or not.
  • A note with something that looks like a credential is refused.
  • Notes are untrusted text. brief, caisson open and the MCP tools wrap each one as [untrusted repository note by @handle, day: ...] text [end of note], so an agent treats it as data and not as an instruction.
  • Every change is in the audit log with the text it replaced.

Install the agent skills

The CLI carries two agent skills that match it: caisson (the loop for working in a caisson) and sailfork (pull requests, issues and CI). Installing them tells an agent how to use the commands correctly.

sailfork skill install
sailfork skill install --project
sailfork skill install --dir ~/.agents/skills

With no flag the skills go in ~/.claude/skills, for every project on this machine. --project writes to the current repository's .claude/skills, so they are shared through git, and --dir writes to a folder you name, for agents that read skills elsewhere. Run it again after sailfork upgrade to bring the skills in step with the CLI. It rewrites only files that changed.

Start each session oriented

sailfork hook session-start prints what needs the agent in the current repository: its open pull requests with checks and review, reviews waiting on it and issues assigned to it (at most 10 of each), plus how to wait for CI without polling. It prints nothing outside a Sailfork clone, and it gives up after 5 seconds, so it never blocks a session. Signed out, it prints a sign-in hint.

Claude Code adds a SessionStart hook's output to the session. Add this to .claude/settings.json, or to ~/.claude/settings.json for every clone:

.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "sailfork hook session-start 2>/dev/null || true", "timeout": 10 }
        ]
      }
    ]
  }
}

sailfork status -R fenil/ocean-landing prints the same list on demand.

Wait instead of polling

sailfork wait blocks until something reaches a state, so an agent runs it as one background command and does not loop.

CommandWaits until
wait pr <n> --checksThe checks finish: exit 0 when they pass, 1 when one fails
wait pr <n> --mergedThe pull request merges: exit 1 if it is closed instead
wait pr <n> --reviewA new review or comment arrives: exit 1 if the review asks for changes
wait run <id>A CI run finishes: exit 1 if it failed
wait caisson <id> --state reviewThe caisson reaches that state (editing, waiting, review, merged or stopped)
wait issue <n> --state in-reviewThe issue reaches a state (open, closed) or a status (in-review, done, ...)

Each takes --timeout (default 10m) and --interval (default 5s). A timeout exits 12. sailfork pr merge <n> --auto asks the server to merge once the checks pass and the rules allow it, as you and only at the head you reviewed, and returns at once (--cancel-auto turns it off; a notice tells you if it was dropped). sailfork events --follow streams what happens on your repositories: reviews, comments, CI, merges and pushes.

Discover the CLI

An agent does not need the docs to find a command.

sailfork commands --json --jq '.commands[] | select(.mutates) | .path'
sailfork commands pr merge --json --jq '.commands[0].flags[].long'
sailfork schema pr view

sailfork commands --json lists every command and whether it changes anything; false flags such as mutates and leaf are left out. sailfork commands pr merge --json adds that command's flags, the global flags (types, defaults, choices and environment variables) and examples. sailfork schema <command> prints the JSON Schema of what a command prints under --json, such as sailfork schema issue list.

Take an action back

sailfork undo takes back your most recent action: a comment, a label, assignee, status or title change, a close, a merge, a deleted branch or file, or a created token.

sailfork undo --list
sailfork undo --dry-run
sailfork undo 4f2a

--list shows your recent actions with ids and whether each can still be undone. Actions are kept for 7 days and can be undone within 24 hours, once. An action that cannot be reversed, because the thing changed again since, a comment is gone, or the base branch moved past a merge, is refused with the reason. For a merge that cannot be reversed, the message gives the git commands for a revert pull request. --yes confirms when there is no terminal to ask on.

For agents that read the web

Every docs page is Markdown at its address plus .md, or with an Accept: text/markdown header. https://status.sailfork.com/llms.txt indexes the docs, the CLI, the MCP endpoints and the API, and https://status.sailfork.com/llms-full.txt adds the details an agent needs. The CLI guide and help have .md versions too.

An agent that drives this site in a browser with WebMCP gets typed tools from document.modelContext instead of guessing from the page. Each page lists only the tools that fit it, tools that change data open a confirmation dialog first, and repository text comes back marked as untrusted data. See In the browser for the list.

Loading Sailfork