Skip to content

Message reference ​

Every message type collins-service and its clients exchange, generated from the message table in collins/api/protocol.py. The transport, the frames, the handshake and the rules that hold for every message are in The service API; this page is the table.

This document and the module it is generated from are licensed MIT, unlike the rest of Collins.

Numbers ​

NameValueMeaning
PROTOCOL1The protocol this build speaks.
MIN_PROTOCOL1The oldest protocol this build still speaks.
MAX_FRAME1,048,576 (1 MiB)The largest frame either peer sends, in bytes; larger transfers are chunked.
MAX_INCOMING16,777,216 (16 MiB)The largest frame either peer accepts, in bytes.
MAX_PAYLOAD1,048,560The most payload bytes one binary frame carries (the frame less its header).
CHUNKED_MAX67,108,864 (64 MiB)The most bytes a chunked field runs to, in either direction.
ACK_BYTES65,536The client acks every this many bytes of live output fed to its terminal.
ACK_MS100... or this many milliseconds after the last unacked frame, whichever first.
ACK_WINDOW1,048,576 (1 MiB)The most unacked live bytes the service hands a client before holding the rest.
QUEUE_BYTES4,194,304 (4 MiB)One client's send queue per pty; overflow means a redraw.
KEEPALIVE_INTERVAL_S10WebSocket keepalive interval, seconds, both ends.
KEEPALIVE_PONG_TIMEOUT_S10WebSocket keepalive pong timeout, seconds, both ends.
LOCAL_PROOF_BYTES32The length of the local proof the service writes.
REQUEST_ID_MAX2^53 − 1The largest request id.
TEXT_MAX1,048,576 (1 MiB)The most characters of a text payload (a prompt, a paint, a cut, a tool reply).
PATH_MAX4,096The most characters of a path.
ID_MAX128The most characters of an id (session, client, service, box, notification, tool call).
JSON_MAX_DEPTH32The deepest nesting of a free JSON value.
JSON_MAX_NODES100,000The most values in a free JSON value, all depths together.
FILE_TEXT_MAX5,242,880 (5 MiB)The most bytes of a file fs.read answers or fs.write takes.
TRANSCRIPT_EXPORT_MAX16,777,216 (16 MiB)The most characters of a Markdown export.

Binary frame tags and flags ​

NameValueMeaning
TAG_OUTPUT0x01pty output, service to client; stream is the pty
TAG_INPUT0x02pty input, client to service; stream is the pty
TAG_BLOB0x03a chunk of a chunked message, either way; stream is the message id masked to 32 bits
FLAG_REDRAW0x01output: part of a redraw (not counted, not acked)
FLAG_REDRAW_END0x02output: the redraw's last frame

Enumerations ​

  • CAPABILITIES: The names a service may list in its hello reply's caps.
    background, composer, debug, files, git, internal, jobs, local, prs, sandbox, shells, tools, usage
  • ERRORS: The error codes a refusal carries; a receiver accepts any code-shaped string.
    direction, failed, gone, invalid, protocol, refused, sequence, stale, unknown
  • CHANNELS: A connection's channel in its hello.
    primary, sync
  • CHUNKED_FIELDS: The fields that may travel as blob frames, in the order they are looked for.
    stdout, text, paths, entries, results, names
  • CHUNKED_JSON_FIELDS: The chunked fields that are lists (their JSON is what travels).
    entries, names, paths, results
  • JOB_KINDS: The long-running operations job.start starts.
    chats.trust, clone, clone.repos, icon, login.repair, session.repair, worktree.check, worktree.restore, worktree.trash
  • JOB_STATES: The states a job event reports.
    cancelled, done, failed, refused, running
  • POST_KINDS: The notification kinds a client may post with notify.post.
    bell, message, update
  • CLI_STATUSES: cli.check's verdicts on a path.
    bad-name, missing, ok, version-managed, versioned
  • GIT_ENVS: The environments git.run runs git in.
    default, no_editor, no_prompt
  • PLAN_OPS: The operations a git.plan carries.
    add, apply-cached, apply-cached-reverse, apply-worktree-reverse, checkout, reset, trash
  • FILE_ENCODINGS: The encodings fs.read answers and fs.write takes.
    latin-1, utf-8
  • WATCH_KINDS: What fs.watch watches.
    dir, file
  • FS_STAT_KINDS: What fs.stat finds at a path.
    dir, file, missing, other, symlink
  • FS_ENTRY_KINDS: What an fs.list entry is.
    dir, file, symlink
  • FS_RENAME_REASONS: Why fs.rename was refused (the refusal's reason).
    empty, exists, missing, not_a_name, outside
  • FS_MKDIR_REASONS: Why fs.mkdir was refused (the refusal's reason).
    exists, no_parent, not_a_name, outside
  • FS_PASTE_ERRORS: Why one fs.paste entry failed (its result's error); open: a newer service may add to it.
    failed, into_itself, missing, no_room, not_a_dir, outside, source_outside

Conformance ​

What a server must serve to be a server of this API; the rules are in Implementing a server. The levels build on each other. A family is optional at any level: a server serves one by listing its name in caps, and answers a type it doesn't serve unknown. Each message type below names its family and level.

Every state key, and every field of service.status, session and item, belongs to one level or family. One that belongs to a family is emitted, read and written only by a server that lists the family. A client reads a key it never received as empty and a field it never received as unknown. Of service.status, only version and protocol are required.

Level 0: The wire ​

Enough for a client to connect and show an empty list.

Message types: hello, local, subscribe, service.status

service.status fields: version, protocol, ptys, busy, clients, started, pid, cli, home

Also:

  • subscribe's snapshot may be empty: no item and no pty, then a rows with an empty list.
  • service.status needs only version and protocol.
  • A server with no local proof leaves local_proof out of its hello and refuses local refused. The client then stays remote, which is correct.
  • A server should send implementation. A hello with neither that nor any family is the shape of a service from before families, and a client may offer to restart it.

Level 1: Sessions and terminals ​

Enough to run a Claude Code session in a terminal, with its list row, whether it is busy or unread, its model and effort, a prompt typed into it, and closing it.

Message types: attach, detach, resize, focus, theme, ack, spawn, pty.info, pty.capture, prompt, write, paint, close, session, resolver.arm, state.set, state.get, item, rows, store.flags, pty, pty-exited

State keys: settings, service_id

session fields: pty, handle, session, cwd, agent_cwd, pid, takes_prompt, agent_running, running_command, busy, finished, model, effort, permission_mode, transcript_path, landed, reset

item fields: session, path, cwd, resume_cwd, display_name, subtitle, preview, mtime, created, size, status, busy, unread, running, removed, project, cli_title, provider, state, syncing

Also:

  • spawn: kind: "agent" with cwd, session, prompt, model, effort, permission_mode, cols, rows, provider, which every server accepts. An unknown provider reads as Claude.
  • spawn: a field whose value asks for nothing (an empty add_dirs, a false worktree with a worktree_name beside it, a false sandbox) is accepted and ignored.
  • spawn: a server refuses refused, with a msgid saying why, only a value that asks for a feature it lacks: sandbox: true, sandbox_box or sandbox_plan without sandbox; history or ordinal without shells; worktree: true, a non-empty add_dirs, fork, continue_recent or another optional field when it can't honour them.
  • close: the modes exit and kill.
  • store.flags: status and unread.
  • state.set: as an event, the settings key, with the server's defaults; a setting left out reads as the client's default. As a request, a server may refuse every write refused.
  • state.get: answers every key the server emits state.set for, and refuses any other gone.
  • resolver.arm: answer ok. A server with no resolver ignores it.
  • item: project, cli_title, provider, state and syncing are optional, and a missing one reads as absent.
  • The input frames, resize, focus, theme and ack are honoured.
  • service.status: a Level 1 server should send cli and home. A client reads a missing cli as unknown, and without home it can't abbreviate paths or start a path picker at home.

Level 2: The store ​

A list a person can organise: names, favorites, archives, projects, trash, the transcript's links and export, folder trust and the notification history. Levels 1 and 2 together are the sessions profile, the one to aim for first.

Message types: put-away, forgotten, store.lookup, store.page-archived, store.refresh, store.show-archived, store.rename, store.regenerate-name, store.favorite, store.archive, store.archive-project, store.trash, store.delete, store.add-project, store.keep-projects, store.forget-project, store.move-project, store.forget, store.transcript-tail, store.transcript-export, trust.check, trust.grant, notify, notify.post, notify.remove, notify.clear, notify.green, notify.rekey, notify.test, seen

State keys: names, generated_names, cli_titles, emojis, favorites, archived, archived_at, archived_projects, project_order, virtual_projects, project_worktree, session_drafts, new_chat_drafts, expanded_groups, notifications

item fields: favorite

Family git: Git ​

The git page and everything else that asks about a repository.

Message types: git.run, git.info, git.sizes, git.watch, git.unwatch, git-changed, git.plan

Also:

  • GET /api/blob?kind=git.
  • The git builders, each with git's own semantics.

Family files: Files ​

The editor's files, the file tree, quick open, the path picker and a project's icon.

Message types: fs.trash, fs.read, fs.write, fs.watch, fs.unwatch, file-changed, dir-changed, fs.stat, fs.list, fs.walk, fs.rename, fs.paste, fs.mkdir, fs.names, fs.dirs, fs.newdir

session fields: touched_files

Also:

  • GET /api/blob?kind=icon.
  • Every path an fs.* request of a client that has not proved local names is confined to the roots the server knows (its sessions' directories) and refused refused outside them, except fs.dirs and fs.newdir, which browse the whole filesystem.

Family prs: Pull requests ​

What a session's pull requests are and every action on one.

Message types: prs.restore, pr, pr-status, pr.set, pr.fetch, pr.sweep, pr.detail, pr.threads, pr.blob, pr.action, pr.comment, pr.review, pr.thread

State keys: session_prs

service.status fields: gh

session fields: prs

Also:

  • GET /api/blob?kind=pr.

Family sandbox: Sandboxed sessions ​

Sessions in a filesystem sandbox, and the grants that widen one.

Message types: sandbox.plan, sandbox.grants, sandbox.allow, sandbox.revoke, sandbox.tools, sandbox.restart, sandbox.derive, sandbox.drop, sandbox.forget, sandbox

State keys: project_sandbox, sandboxed_sessions, sandbox_grants, sandbox_project_grants, sandbox_tools

service.status fields: sandbox, live

session fields: sandboxed, sandbox_box, sandbox_plan_path, defaults_owed, can_restart

Also:

  • spawn: the fields sandbox, sandbox_box, sandbox_plan.
  • pty: the fields sandboxed and box.
  • pty.info: the field plan.

Family tools: Session tools ​

The tools a running agent calls that need a screen, the marks on a diff, and files handed between a client and a session.

Message types: tool, tool-reply, diff.notes, diff.set-notes

State keys: session_attachments, diff_notes, pending_diffs

session fields: attachments

Also:

  • GET /api/blob?kind=file and kind=remote.
  • PUT /api/upload.

Family jobs: Long-running operations ​

Work that outlasts a request, such as a clone, a worktree's trash or restore, a login repair or an icon's generation. JOB_KINDS lists them all.

Message types: job.start, job.cancel, job

Family usage: Token use ​

The usage panel, the model catalog, the CLI's defaults and saving a generated icon.

Message types: usage.get, models.get, models.defaults, icon.save

Family background: Background agents ​

Handing a session to the CLI's background agents and following it there.

Message types: store.forward

State keys: session_forwards, pending_detaches

item fields: background, backgrounding, can_background, forward

Also:

  • close: the mode background.

Family shells: Panel shells ​

Plain shells beside a session, and their history.

Message types: panel.key, panel.history, clear

Also:

  • spawn: kind: "shell".

Family composer: The composer ​

Lifting the text out of the CLI's input box and putting it back, switching the model or effort, and mentioning a file.

Message types: switch, send, mention, cut, cut.cancel, draft.restore, composer

session fields: entered, foreign_paste, prompt_block

Family internal: The Collins service's own ​

What the Collins service does for its own window's timing and its own test suite. Another server need not serve it.

Message types: focus.terminal, close.nudge, close.end, shells, transcript.update, transcript.set, transcript.relocate, cwd.settle, shells.follow, finish.witness, baseline.absorb, baseline.cmdlines, restart.worktreeless, service.restart, cli.check

State keys: process_baselines, resume_on_start, ptys, pty_next_id, inflight_copies

service.status fields: keeper, keeper_mismatch, keeper_unread, keeper_held, unkept

session fields: fork, forked, provider, options, continue_recent, resolver_cwd, initial_command, worktree_launch, new_chat_prompt, shells_follow_armed, closing, unstarted, lookup_empty, ledger_armed

Family debug: The debug probe ​

Collins' own test probe, served only with the service's debug API on. No other client or server should rely on it.

Message types: debug.session.get, debug.session.set, debug.session.call, debug.screen, debug.pty, debug.local, debug.sandbox

Refusal sentences a client matches ​

A client reads almost nothing from a refusal but its code. These three msgids are the exceptions: send them exactly.

NameSentenceWhen
ALREADY_RUNNING_MSGIDThis session is already running in the Collins servicespawn refused refused because the session already runs; args.pty names its pty, and the client attaches to that instead.
PTY_GONE_MSGIDno such ptyA request refused gone because no such pty exists; args.pty names it. The client takes the pty as ended.
FOLDER_GONE_MSGIDThe folder is not therefs.list, fs.walk, fs.names or fs.dirs refused gone because the folder is not there. A file tree drops its rows.

Message types ​

A request carries an integer id and is answered by exactly one response; an event carries none and is never answered. Fields a type does not list are dropped by the receiver. required fields must be present; nullable ones may be null.

Connecting ​

hello ​

The client introduces itself; the service answers with its own facts.

Family: core · Level 0

Request, client → service, answered by one response.

Request fields

FieldValuePresence
protocolinteger, 0–65,535required
min_protocolinteger, 0–65,535optional
versionstring, 1–64 charactersrequired
client_idstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
devicestring, at most 255 charactersoptional
localestring, at most 64 characters, matching [A-Za-z0-9_.@-]{1,64}optional
termobject (fields below)optional
term.vteinteger, 0–99,999,999optional
term.fgstring, at most 7 characters, matching #[0-9A-Fa-f]{6}optional
term.bgstring, at most 7 characters, matching #[0-9A-Fa-f]{6}optional
term.schemestring, one of dark, lightoptional
term.palettelist of exactly 16 items of: string, at most 7 characters, matching #[0-9A-Fa-f]{6}optional
channelstring, one of primary, syncoptional

Reply fields (on ok: true)

FieldValuePresence
protocolinteger, 0–65,535required
min_protocolinteger, 0–65,535required
versionstring, 1–64 charactersrequired
service_idstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
hoststring, at most 255 charactersoptional
implementationstring, at most 64 charactersoptional
capslist of at most 64 items of: string, at most 64 characters, matching [a-z][a-z0-9_.-]{0,63}optional
local_proofobject (fields below)optional
local_proof.pathabsolute path, at most 4,096 characters, no NULrequired
local_proof.lengthinteger, 1–4,096required

local ​

The client proves it shares the service's filesystem and uid.

Family: core · Level 0

Request, client → service, answered by one response.

Request fields

FieldValuePresence
proofstring, at most 8,192 characters, matching (?:[0-9a-f]{2}){1,4096}required

Reply fields (on ok: true)

No fields.

subscribe ​

Send the snapshot as events, then answer, then keep sending events.

Family: core · Level 0

Request, client → service, answered by one response.

Request fields

No fields.

Reply fields (on ok: true)

FieldValuePresence
itemsinteger, 0–2^31 − 1optional
ptysinteger, 0–2^31 − 1optional

Terminals ​

attach ​

Show a pty: a redraw, then live output.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
colsinteger, 1–2,000required
rowsinteger, 1–1,000required

Reply fields (on ok: true)

FieldValuePresence
colsinteger, 1–2,000required
rowsinteger, 1–1,000required
activebooleanrequired
sized_forstring, at most 255 charactersoptional
modeslist of at most 512 items of: string, 1–16 charactersoptional

detach ​

Stop showing a pty; it keeps running.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

No fields.

resize ​

The client's grid for a pty changed.

Family: core · Level 1

Event, client → service, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
colsinteger, 1–2,000required
rowsinteger, 1–1,000required

focus ​

A client's view of a pty gained or lost focus.

Family: core · Level 1

Event, client → service, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
focusedbooleanrequired

focus.terminal ​

The session asks its active client to put the keyboard in the terminal.

Family: internal · Level 3

Optional for another client. Asks for the keyboard to go to the terminal. A client can ignore it.

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

theme ​

The client's terminal colours or scheme changed.

Family: core · Level 1

Event, client → service, never answered.

Event fields

FieldValuePresence
termobject (fields below)required
term.vteinteger, 0–99,999,999optional
term.fgstring, at most 7 characters, matching #[0-9A-Fa-f]{6}optional
term.bgstring, at most 7 characters, matching #[0-9A-Fa-f]{6}optional
term.schemestring, one of dark, lightoptional
term.palettelist of exactly 16 items of: string, at most 7 characters, matching #[0-9A-Fa-f]{6}optional

ack ​

The client has fed this much of a pty's live output to its terminal (flow control).

Family: core · Level 1

Event, client → service, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
offsetinteger, 0–2^64 − 1required

spawn ​

Start a session or a panel shell in a new pty.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
kindstring, one of agent, shellrequired
cwdabsolute path, at most 4,096 characters, no NULrequired
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
providerstring, at most 32 charactersoptional
promptstring, at most 1,048,576 (1 MiB) charactersoptional
modelstring, at most 128 charactersoptional
effortstring, at most 32 charactersoptional
permission_modestring, at most 32 charactersoptional
add_dirslist of at most 64 items of: absolute path, at most 4,096 characters, no NULoptional
worktreebooleanoptional
worktree_namestring, at most 128 charactersoptional
sandboxbooleanoptional
sandbox_boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
forkbooleanoptional
continue_recentbooleanoptional
jsonl_pathabsolute path, at most 4,096 characters, no NULoptional
sandbox_planabsolute path, at most 4,096 characters, no NULoptional
fork_resolvebooleanoptional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
colsinteger, 1–2,000optional
rowsinteger, 1–1,000optional
historystring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
ordinalinteger, 0–65,535optional

Reply fields (on ok: true)

FieldValuePresence
ptyinteger, 1–2^32 − 1required
colsinteger, 1–2,000required
rowsinteger, 1–1,000required
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
cwdabsolute path, at most 4,096 characters, no NULoptional

panel.key ​

File a shell's panel history under a new key, or under none; name the session it belongs to.

Family: shells · Level 3

Optional for another client. Only for a client that keeps its shells' scrollback between runs.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
historystring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required, nullable
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

No fields.

panel.history ​

Write a session's panel history: each shell's scrollback, from its pty's model or as text.

Family: shells · Level 3

Optional for another client. Only for a client that keeps its shells' scrollback between runs.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
keystring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
shellslist of at most 64 items of: object (fields below)required
shells[].ordinalinteger, 0–10,000required
shells[].ptyinteger, 1–2^32 − 1optional
shells[].textstring, at most 1,048,576 (1 MiB) charactersoptional
shells[].keepbooleanoptional
partialbooleanoptional

Reply fields (on ok: true)

No fields.

pty.info ​

A pty's process facts: its child, its shell, the foreground, the shell's cwd, its plan.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
kindstring, 1–32 charactersrequired
child_pidinteger, 1–2^31 − 1optional, nullable
shell_pidinteger, 1–2^31 − 1optional, nullable
foreground_pgrpinteger, -1–2^31 − 1optional, nullable
running_commandbooleanrequired
process_cwdabsolute path, at most 4,096 characters, no NULoptional, nullable
cwdabsolute path, at most 4,096 characters, no NULoptional
planabsolute path, at most 4,096 characters, no NULoptional, nullable
colsinteger, 1–2,000optional
rowsinteger, 1–1,000optional

pty.capture ​

A pty's text, scrollback and screen, from the service's model.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
textstring, at most 1,048,576 (1 MiB) charactersrequired

prompt ​

Type text into the agent's box and submit it.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
textstring, 1–1,048,576 (1 MiB) charactersrequired
focusbooleanoptional
when_emptybooleanoptional

Reply fields (on ok: true)

No fields.

switch ​

Post a model and/or effort switch to the agent.

Family: composer · Level 3

Request, client → service, answered by one response.

Request fields

At least one of model, effort must be present.

FieldValuePresence
ptyinteger, 1–2^32 − 1required
modelstring, 1–128 charactersoptional
effortstring, 1–32 charactersoptional
composer_openbooleanoptional

Reply fields (on ok: true)

No fields.

write ​

Type raw keystrokes into the agent's pty.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
textstring, 1–1,048,576 (1 MiB) charactersrequired
mentionbooleanoptional

Reply fields (on ok: true)

No fields.

send ​

The composer's send: submit its draft, now or once a cut has settled.

Family: composer · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
textstring, 1–1,048,576 (1 MiB) charactersrequired
composer_openbooleanoptional

Reply fields (on ok: true)

FieldValuePresence
sentbooleanrequired

mention ​

Type a file's mention token into the agent's box.

Family: composer · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
pathabsolute path, at most 4,096 characters, no NULrequired
start_lineinteger, 0–2^31 − 1optional
end_lineinteger, 0–2^31 − 1optional

Reply fields (on ok: true)

No fields.

cut ​

Begin the composer's open-cut; cut events say what it found.

Family: composer · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
statestring, one of cancelled, refused, seededrequired
textstring, at most 1,048,576 (1 MiB) charactersoptional

cut.cancel ​

Call a cut off: the composer closed, or the box holds its text again.

Family: composer · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

No fields.

draft.restore ​

A closing composer's draft goes back into the agent's box, in pieces.

Family: composer · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
textstring, 1–1,048,576 (1 MiB) charactersrequired

Reply fields (on ok: true)

FieldValuePresence
restoredbooleanrequired

clear ​

Wipe a shell's screen and scrollback. On an agent pty Collins' service erases the input box; no client sends that and it is not promised.

Family: shells · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

No fields.

paint ​

Insert text into a pty's output stream, past the filter: the screen model takes it and every attached client sees it. The pty itself is not written.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
textstring, 1–1,048,576 (1 MiB) charactersrequired

Reply fields (on ok: true)

No fields.

close ​

End a pty's session: exit types the agent's own exit keys, background its handoff command, kill forces it; text is keystrokes to type instead of the server's own. A background close of a session that cannot be handed off is refused.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
modestring, one of background, exit, killrequired
textstring, at most 256 charactersoptional
forcebooleanoptional

Reply fields (on ok: true)

No fields.

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
statestring, one of budgetrequired
phasestring, at most 32 charactersoptional

close.nudge ​

Feed the exit keystroke again to a CLI parked on a screen.

Family: internal · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

No fields.

close.end ​

The page is gone: the close poll stops.

Family: internal · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

No fields.

The session on the service ​

session ​

An agent session's facts, whole on attach and as changed fields after.

Family: core · Level 1

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional, nullable
forkbooleanoptional
providerstring, at most 32 charactersoptional
optionsJSON object (bounded: see Free JSON)optional, nullable
continue_recentbooleanoptional
cwdabsolute path, at most 4,096 characters, no NULoptional, nullable
agent_cwdabsolute path, at most 4,096 characters, no NULoptional, nullable
pidinteger, 1–2^31 − 1optional, nullable
resolver_cwdabsolute path, at most 4,096 characters, no NULoptional, nullable
initial_commandstring, at most 4,096 charactersoptional, nullable
worktree_launchbooleanoptional
new_chat_promptstring, at most 4,096 charactersoptional, nullable
shells_follow_armedbooleanoptional
closingbooleanoptional
sandboxedbooleanoptional
sandbox_boxstring, at most 128 charactersoptional
sandbox_plan_pathabsolute path, at most 4,096 characters, no NULoptional, nullable
defaults_owedbooleanoptional
can_restartbooleanoptional
takes_promptbooleanoptional
enteredobject (fields below)optional, nullable
entered.textstring, at most 4,096 charactersrequired
entered.rows_belowinteger, 0–1,000required
prompt_blockstring, at most 4,096 charactersoptional
unstartedbooleanoptional
foreign_pastebooleanoptional
agent_runningbooleanoptional
running_commandbooleanoptional
modelstring, at most 128 charactersoptional, nullable
effortstring, at most 32 charactersoptional, nullable
permission_modestring, at most 32 charactersoptional, nullable
transcript_pathabsolute path, at most 4,096 characters, no NULoptional, nullable
prslist of at most 100 items of: JSON object (bounded: see Free JSON)optional
lookup_emptybooleanoptional
touched_fileslist of at most 64 items of: absolute path, at most 4,096 characters, no NULoptional
attachmentslist of at most 1,000 items of: JSON object (bounded: see Free JSON)optional
ledger_armedbooleanoptional
landedbooleanoptional
resetbooleanoptional
busybooleanoptional
finishedbooleanoptional
forkedstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

composer ​

The session asks the active client's composer for something.

Family: composer · Level 3

Optional for another client. Asks a client with a composer for something. Without one, ignore it.

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
whatstring, one of refocus, resend, stashrequired
textstring, at most 1,048,576 (1 MiB) charactersoptional

shells ​

The session says something about the panel shells beside it.

Family: internal · Level 3

Optional for another client. About shells beside a session. A client that opens none can ignore it.

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
whatstring, one of stalerequired

resolver.arm ​

A client mapped the tab: the transcript resolver's background budget starts over.

Family: core · Level 1

Optional for another client. The window sends this when a tab is first shown. The service binds a session to its id without it.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

No fields.

transcript.update ​

Re-read the transcript now; with discover, ask the branch which PR it has.

Family: internal · Level 3

Optional for another client. The window's footer asks for a read sooner. The service follows each transcript itself.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
discoverbooleanoptional

Reply fields (on ok: true)

No fields.

transcript.set ​

Tail another transcript (or none).

Family: internal · Level 3

Optional for another client. No Collins client sends this. The service finds each session's transcript itself.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
pathabsolute path, at most 4,096 characters, no NULrequired, nullable

Reply fields (on ok: true)

No fields.

transcript.relocate ​

Follow the session's transcript to where the CLI moved it.

Family: internal · Level 3

Optional for another client. No Collins client sends this. The service follows a transcript the CLI moved.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
pathabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

No fields.

prs.restore ​

Re-adopt the pull requests saved for the session.

Family: prs · Level 3

Optional for another client. Shows a session's saved pull requests before the next read. Pull requests in the transcript come back on their own; one found only by a branch lookup is saved nowhere else.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
recordslist of at most 100 items of: JSON object (bounded: see Free JSON)required

Reply fields (on ok: true)

No fields.

cwd.settle ​

Whether the agent has moved, as the editor rooted at root should see it.

Family: internal · Level 3

Optional for another client. Only for a file view that follows the agent's directory.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
cwdabsolute path, or ~ / ~/… in the service's home, at most 4,096 charactersoptional, nullable
rootabsolute path, at most 4,096 characters, no NULrequired
judgebooleanoptional

Reply fields (on ok: true)

FieldValuePresence
scopestring, at most 32 charactersoptional

shells.follow ​

Whether the shells beside a new chat are owed the offer to follow its worktree.

Family: internal · Level 3

Optional for another client. Only for a client with shells beside a new chat.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
armedbooleanrequired

Reply fields (on ok: true)

No fields.

finish.witness ​

What the transcript says right now, for the finish ledger.

Family: internal · Level 3

Optional for another client. No Collins client sends this; only the test suite does.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
stamplist of exactly 2 items of: integer, 0–2^31 − 1required
sizeinteger, 0–2^53 − 1required, nullable

baseline.absorb ​

Fold what runs under a pristine fresh spawn into its plumbing baseline.

Family: internal · Level 3

Optional for another client. No Collins client sends this; only the test suite does.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
capturingbooleanrequired

baseline.cmdlines ​

The cmdlines running directly below the session's agent right now.

Family: internal · Level 3

Optional for another client. No Collins client sends this; only the test suite does.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
cmdlineslist of at most 1,000 items of: string, at most 4,096 charactersrequired

restart.worktreeless ​

Type the new-session command again with the worktree dropped.

Family: internal · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

No fields.

The debug probe ​

debug.session.get ​

An attribute of a session, JSON-encoded (a method answers callable).

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
namestring, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255}required

Reply fields (on ok: true)

FieldValuePresence
valueany JSON value (bounded: see Free JSON)optional, nullable
callablebooleanoptional

debug.session.set ​

Set an attribute of a session.

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
namestring, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255}required
valueany JSON value (bounded: see Free JSON)required, nullable

Reply fields (on ok: true)

No fields.

debug.session.call ​

Call a method of a session with JSON arguments; its result JSON-encoded.

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
namestring, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255}required
argslist of at most 16 items of: any JSON value (bounded: see Free JSON)optional
kwargsJSON object (bounded: see Free JSON)optional

Reply fields (on ok: true)

FieldValuePresence
valueany JSON value (bounded: see Free JSON)optional, nullable

debug.screen ​

A pty's screen model, as the checks read it.

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
rowslist of at most 1,000 items of: string, at most 8,000 charactersrequired
cursorlist of exactly 2 items of: integer, 0–2,000required
columnsinteger, 1–2,000required
row_countinteger, 1–1,000required
capturestring, at most 1,048,576 (1 MiB) charactersrequired

debug.pty ​

A pty's process facts, as the checks read them.

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required

Reply fields (on ok: true)

FieldValuePresence
child_pidinteger, 1–2^31 − 1required, nullable
foreground_pgrpinteger, -1–2^31 − 1required, nullable
shell_pidinteger, 1–2^31 − 1required, nullable
process_cwdabsolute path, at most 4,096 characters, no NULrequired, nullable

debug.local ​

Set whether the service treats the asking client as local (a check's stand-in for ssh).

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
localbooleanrequired

Reply fields (on ok: true)

No fields.

debug.sandbox ​

Call a method of the service's sandbox host, its live grants, or the core.

Family: debug · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
targetstring, one of core, grants, hostrequired
namestring, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255}required
argslist of at most 16 items of: any JSON value (bounded: see Free JSON)optional
kwargsJSON object (bounded: see Free JSON)optional

Reply fields (on ok: true)

FieldValuePresence
valueany JSON value (bounded: see Free JSON)optional, nullable

State ​

state.set ​

Write a shared state key (request), or a key changed (event).

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
keystring, 1–64 characters, matching [A-Za-z_][A-Za-z0-9_.-]{0,63}required
entrystring, 1–4,096 charactersoptional
valueany JSON value (bounded: see Free JSON)required, nullable

Reply fields (on ok: true)

No fields.

Event, service → client, never answered.

Event fields

FieldValuePresence
keystring, 1–64 characters, matching [A-Za-z_][A-Za-z0-9_.-]{0,63}required
entrystring, 1–4,096 charactersoptional
valueany JSON value (bounded: see Free JSON)required, nullable

state.get ​

Read a shared state key.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

FieldValuePresence
keystring, 1–64 characters, matching [A-Za-z_][A-Za-z0-9_.-]{0,63}required
entrystring, 1–4,096 charactersoptional

Reply fields (on ok: true)

FieldValuePresence
valueany JSON value (bounded: see Free JSON)required, nullable

The store ​

item ​

A session row appeared, changed or went away.

Family: core · Level 1

Event, service → client, never answered.

Event fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
removedbooleanoptional
projectstring, at most 4,096 charactersoptional
cwdabsolute path, at most 4,096 characters, no NULoptional, nullable
resume_cwdabsolute path, at most 4,096 characters, no NULoptional, nullable
display_namestring, at most 1,024 charactersoptional
cli_titlestring, at most 1,024 charactersoptional
subtitlestring, at most 256 charactersoptional
previewstring, at most 4,096 charactersoptional
providerstring, at most 32 charactersoptional
favoritebooleanoptional
statusstring, at most 32 charactersoptional
statestring, at most 32 charactersoptional
busybooleanoptional
unreadbooleanoptional
syncingbooleanoptional
backgroundingbooleanoptional
can_backgroundbooleanoptional
backgroundstring, at most 32 charactersoptional
runningbooleanoptional
mtimefinite numberoptional
createdfinite numberoptional
sizeinteger, 0–2^53 − 1optional
pathabsolute path, at most 4,096 characters, no NULoptional
forwardstring, at most 32 charactersoptional

rows ​

The sidebar's rows after a refresh: their order, groups and counts.

Family: core · Level 1

Event, service → client, never answered.

Event fields

FieldValuePresence
rowslist of at most 10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
groupslist of at most 10,000 items of: object (fields below)optional
groups[].kindstring, 1–32 charactersrequired
groups[].namestring, at most 1,024 charactersoptional
groups[].labelstring, at most 1,024 charactersoptional
groups[].countinteger, 1–10,000required
emptylist of at most 10,000 items of: object (fields below)optional
empty[].kindstring, 1–32 charactersrequired
empty[].namestring, at most 1,024 charactersoptional
empty[].labelstring, at most 1,024 charactersoptional
empty[].cwdabsolute path, at most 4,096 characters, no NULoptional
orderlist of at most 10,000 items of: string, at most 1,024 charactersoptional
order_changedbooleanoptional
show_archivedbooleanoptional
totalinteger, 0–2^31 − 1optional
hiddeninteger, 0–2^31 − 1optional
sizeinteger, 0–2^53 − 1optional
projectslist of at most 10,000 items of: string, at most 1,024 charactersoptional
chatsinteger, 0–2^31 − 1optional

put-away ​

A session was archived: whatever it still asked of the user goes with it.

Family: core · Level 2

Event, service → client, never answered.

Event fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

forgotten ​

A session's transcript went (the archive sweep): what a client kept for it goes too.

Family: core · Level 2

Event, service → client, never answered.

Event fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

store.lookup ​

Send one session's item, archived or not (a session the client was never sent), and answer with it.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
foundbooleanrequired
sessionslist of at most 10,000 items of: JSON object (bounded: see Free JSON)optional

store.page-archived ​

Send the sessions kept out of sight as items, keep them current, and answer with them.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

No fields.

Reply fields (on ok: true)

FieldValuePresence
itemsinteger, 0–2^31 − 1optional
sessionslist of at most 10,000 items of: JSON object (bounded: see Free JSON)optional

store.refresh ​

Rescan the transcripts.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
forcebooleanoptional

Reply fields (on ok: true)

No fields.

store.show-archived ​

Draw the rows kept out of sight (Show archived sessions).

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
showbooleanrequired

Reply fields (on ok: true)

No fields.

store.rename ​

Name a session; an empty name clears the manual one.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
namestring, at most 1,024 charactersrequired

Reply fields (on ok: true)

No fields.

store.regenerate-name ​

Title a session again with the title model, over a manual name.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

No fields.

store.favorite ​

Add sessions to the favorites, or take them out.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionslist of 1–10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
favoritebooleanrequired

Reply fields (on ok: true)

No fields.

store.archive ​

Archive sessions, or restore them.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionslist of 1–10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
archivedbooleanrequired

Reply fields (on ok: true)

No fields.

store.archive-project ​

Archive a whole project, or restore it.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
projectstring, 1–1,024 charactersrequired
archivedbooleanrequired

Reply fields (on ok: true)

No fields.

store.trash ​

Move sessions' transcripts to the trash; the ones that failed, with why.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionslist of 1–10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
errorsobject of at most 10,000 entries, keys matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}, values: string, at most 4,096 charactersoptional

store.delete ​

Delete a session's transcript for good; why it failed, when it did.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
errorstring, at most 4,096 charactersoptional

store.forward ​

A session continued under a new id (a /bg fork): carry its records over.

Family: background · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
tostring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

No fields.

store.add-project ​

Put a folder in the sidebar before a session has run there.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

No fields.

store.keep-projects ​

Keep projects in the sidebar after their sessions go.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
projectslist of 1–10,000 items of: string, 1–1,024 charactersrequired

Reply fields (on ok: true)

No fields.

store.forget-project ​

Drop a kept project from the sidebar.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
projectstring, 1–1,024 charactersrequired

Reply fields (on ok: true)

No fields.

store.move-project ​

Move a project in the sidebar order, before another or to the end.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
projectstring, 1–1,024 charactersrequired
beforestring, 1–1,024 charactersoptional, nullable

Reply fields (on ok: true)

No fields.

store.forget ​

A session's transcript went: its panel history, records and box go too.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

No fields.

store.flags ​

What the person did at a client's screen, for a session's row: its status, unread off.

Family: core · Level 1

Request, client → service, answered by one response.

Request fields

At least one of status, busy, unread, backgrounding, can_background must be present.

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
statusstring, at most 32 charactersoptional
busybooleanoptional
unreadbooleanoptional
backgroundingbooleanoptional
can_backgroundbooleanoptional

Reply fields (on ok: true)

No fields.

store.transcript-tail ​

The links in the tail of a session's transcript, for finishing a wrapped link.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
linkslist of at most 1,000 items of: string, 1–1,024 charactersrequired

store.transcript-export ​

A session's transcript rendered as Markdown, for the client to save to a file of its own.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
textstring, at most 16,777,216 (16 MiB) charactersrequired
text_chunkedbooleanoptional
text_bytesinteger, 0–2^53 − 1optional

trust.check ​

Whether the CLI trusts a folder already, and the folder a trust is recorded on.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
trustedbooleanrequired
rootabsolute path, at most 4,096 characters, no NULoptional

trust.grant ​

Record the CLI's folder trust: on the folder's root, or on a launch directory.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
scopestring, one of launch, rootrequired

Reply fields (on ok: true)

FieldValuePresence
writtenbooleanrequired

pty ​

A pty appeared or changed (a row of the pty table).

Family: core · Level 1

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
kindstring, 1–32 charactersrequired
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
cwdabsolute path, at most 4,096 characters, no NULoptional
pidinteger, 1–2^31 − 1optional
colsinteger, 1–2,000optional
rowsinteger, 1–1,000optional
sandboxedbooleanoptional
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
activebooleanoptional
sized_forstring, at most 255 charactersoptional
tablebooleanoptional

pty-exited ​

A pty's child exited and the pty is gone; status is null when it is unknown (a keeper crash). With table true it is the subscription's word that an agent's row left the pty table instead: the CLI exited, the pty lives on with its shell, and status is null.

Family: core · Level 1

Event, service → client, never answered.

Event fields

FieldValuePresence
ptyinteger, 1–2^32 − 1required
statusinteger, -2,147,483,648–2^31 − 1required, nullable
tablebooleanoptional

pr ​

A session's linked pull requests, as prstatus records.

Family: prs · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
prslist of at most 100 items of: JSON object (bounded: see Free JSON)required
attachedlist of at most 100 items of: http(s) URL, at most 4,096 charactersoptional

pr-status ​

A pull request's fetched status changed (the fetch cache's entry, by URL).

Family: prs · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
urlhttp(s) URL, at most 4,096 charactersrequired
statusJSON object (bounded: see Free JSON)required

pr.set ​

Replace a session's saved pull requests.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
prslist of at most 100 items of: JSON object (bounded: see Free JSON)required

Reply fields (on ok: true)

No fields.

pr.fetch ​

Fetch pull requests' statuses again (dropping what is cached, when asked).

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
urlslist of 1–100 items of: http(s) URL, at most 4,096 charactersrequired
invalidatebooleanoptional

Reply fields (on ok: true)

No fields.

pr.sweep ​

The sidebar's sweep: fetch and discover the pull requests of sessions.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
targetslist of 1–10,000 items of: object (fields below)required
targets[].sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
targets[].prslist of at most 100 items of: JSON object (bounded: see Free JSON)optional
targets[].cwdabsolute path, at most 4,096 characters, no NULoptional

Reply fields (on ok: true)

FieldValuePresence
resultsobject of at most 10,000 entries, keys matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}, values: list of at most 100 items of: JSON object (bounded: see Free JSON)optional

pr.detail ​

A pull request's page: everything gh says about it.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
urlhttp(s) URL, at most 4,096 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
detailJSON object (bounded: see Free JSON)optional

pr.threads ​

A pull request's review threads.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
urlhttp(s) URL, at most 4,096 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
threadslist of at most 1,000 items of: JSON object (bounded: see Free JSON)optional

pr.blob ​

Name the blob URL of one file of a repository at a commit (an image the Files view shows).

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
repositorystring, 1–1,024 charactersrequired
refstring, 1–256 charactersrequired
pathstring, 1–4,096 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
urlstring, at most 16,384 charactersoptional
errorstring, at most 4,096 charactersoptional

pr.action ​

Run one of a pull request's actions through gh (practions.perform).

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
prJSON object (bounded: see Free JSON)required
keystring, 1–32 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
errorstring, at most 4,096 charactersoptional

pr.comment ​

Comment on a pull request.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
prJSON object (bounded: see Free JSON)required
bodystring, 1–1,048,576 (1 MiB) charactersrequired

Reply fields (on ok: true)

FieldValuePresence
errorstring, at most 4,096 charactersoptional

pr.review ​

Review a pull request: approve, or request changes.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
prJSON object (bounded: see Free JSON)required
verdictstring, 1–32 charactersrequired
bodystring, at most 1,048,576 (1 MiB) charactersoptional

Reply fields (on ok: true)

FieldValuePresence
errorstring, at most 4,096 charactersoptional

pr.thread ​

Reply in a pull request's review thread, or resolve it.

Family: prs · Level 3

Request, client → service, answered by one response.

Request fields

At least one of body, resolved must be present.

FieldValuePresence
prJSON object (bounded: see Free JSON)required
threadstring, 1–200 characters, matching [A-Za-z0-9+/=_-]{1,200}required
bodystring, 1–1,048,576 (1 MiB) charactersoptional
resolvedbooleanoptional

Reply fields (on ok: true)

FieldValuePresence
errorstring, at most 4,096 charactersoptional

Notifications ​

notify ​

A notification record, its body as msgid and args.

Family: core · Level 2

Event, service → client, never answered.

Event fields

FieldValuePresence
notificationstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
kindstring, 1–32 charactersrequired
sessionstring, at most 128 characters, matching (?:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})?optional
titlestring, at most 1,024 charactersoptional
projectstring, at most 1,024 charactersoptional
msgidstring, 1–4,096 charactersoptional
argsobject of at most 32 entries, keys matching [A-Za-z_][A-Za-z0-9_]{0,63}, values: string (at most 4,096 characters), number, boolean or nulloptional
whenfinite numberrequired
readbooleanoptional
countinteger, 1–2^31 − 1optional
urlhttp(s) URL, at most 4,096 charactersoptional
removedbooleanoptional

notify.post ​

Add a row to the notification history (the service mints it).

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
kindstring, one of bell, message, updaterequired
sessionstring, at most 128 characters, matching (?:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})?optional
titlestring, at most 1,024 charactersoptional
projectstring, at most 1,024 charactersoptional
msgidstring, 1–4,096 charactersrequired
argsobject of at most 32 entries, keys matching [A-Za-z_][A-Za-z0-9_]{0,63}, values: string (at most 4,096 characters), number, boolean or nulloptional
readbooleanoptional
urlhttp(s) URL, at most 4,096 charactersoptional
keystring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

FieldValuePresence
notificationstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

notify.remove ​

Drop rows from the notification history.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
idslist of 1–200 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
removedinteger, 0–2^31 − 1optional

notify.clear ​

Drop every row of the notification history but the finished runs'.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

No fields.

Reply fields (on ok: true)

FieldValuePresence
removedinteger, 0–2^31 − 1optional

notify.green ​

A finished run's row: raise it (unread) or take it down.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
onbooleanrequired
titlestring, at most 1,024 charactersoptional
projectstring, at most 1,024 charactersoptional

Reply fields (on ok: true)

FieldValuePresence
changedbooleanrequired

notify.rekey ​

File a placeholder's rows under the session it resolved to.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
tostring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

FieldValuePresence
movedinteger, 0–2^31 − 1optional

notify.test ​

Run a notify command as given, whether or not a client is attached.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

FieldValuePresence
commandstring, at most 4,096 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
statusinteger, -255–255optional
errorstring, at most 4,096 charactersoptional

seen ​

Notifications or a session were seen: a client says so, the service tells the rest.

Family: core · Level 2

Request, client → service, answered by one response.

Request fields

At least one of ids, session, all must be present.

FieldValuePresence
idslist of at most 200 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
allbooleanoptional

Reply fields (on ok: true)

No fields.

Event, service → client, never answered.

Event fields

At least one of ids, session, all must be present.

FieldValuePresence
idslist of at most 200 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
allbooleanoptional

Long-running operations ​

job.start ​

Start a long-running operation; its progress and outcome arrive as job events.

Family: jobs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
kindstring, one of chats.trust, clone, clone.repos, icon, login.repair, session.repair, worktree.check, worktree.restore, worktree.trashrequired
argsJSON object (bounded: see Free JSON)optional

Reply fields (on ok: true)

FieldValuePresence
jobstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

job.cancel ​

End a job early.

Family: jobs · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
jobstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

No fields.

job ​

A job's progress, or how it ended.

Family: jobs · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
jobstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
kindstring, 1–32 charactersrequired
statestring, 1–32 charactersrequired
msgidstring, 1–4,096 charactersoptional
argsobject of at most 32 entries, keys matching [A-Za-z_][A-Za-z0-9_]{0,63}, values: string (at most 4,096 characters), number, boolean or nulloptional
resultJSON object (bounded: see Free JSON)optional

Token use ​

usage.get ​

The plan's usage, as the usage panel shows it, or why there is none.

Family: usage · Level 3

Request, client → service, answered by one response.

Request fields

No fields.

Reply fields (on ok: true)

FieldValuePresence
snapshotJSON object (bounded: see Free JSON)optional
kindstring, at most 32 charactersoptional
errorstring, at most 4,096 charactersoptional

models.get ​

The model catalog: the service's cache, fetched again when asked.

Family: usage · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
fetchbooleanoptional
refreshbooleanoptional

Reply fields (on ok: true)

FieldValuePresence
modelslist of at most 256 items of: JSON object (bounded: see Free JSON)optional
cachedbooleanoptional
fetched_atfinite numberoptional
failedbooleanoptional

models.defaults ​

The CLI's default model for a directory, and its effort for a model.

Family: usage · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULoptional
modelstring, at most 128 charactersoptional

Reply fields (on ok: true)

FieldValuePresence
modelstring, at most 128 charactersoptional
effortstring, at most 32 charactersoptional

icon.save ​

Write a generated project icon into the project.

Family: usage · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
svgstring, 1–1,048,576 (1 MiB) charactersrequired

Reply fields (on ok: true)

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULoptional

Session tools ​

tool ​

A UI-bound tool call for the session's active client.

Family: tools · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
callstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
sessionstring, at most 128 characters, matching (?:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})?optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
namestring, 1–64 characters, matching [a-z][a-z0-9_]{0,63}required
argumentsJSON object (bounded: see Free JSON)required
sandboxedbooleanoptional

tool-reply ​

The active client's answer to a tool call.

Family: tools · Level 3

Event, client → service, never answered.

Event fields

FieldValuePresence
callstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
okbooleanrequired
textstring, at most 1,048,576 (1 MiB) charactersrequired

diff.notes ​

A session's notes and highlights on its diff, whole.

Family: tools · Level 3

Event, service → client, never answered.

Event fields

At least one of handle, session must be present.

FieldValuePresence
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
noteslist of at most 1,000 items of: JSON object (bounded: see Free JSON)required
highlightslist of at most 5,000 items of: JSON object (bounded: see Free JSON)required

diff.set-notes ​

Write a session's notes and highlights on its diff, whole.

Family: tools · Level 3

Request, client → service, answered by one response.

Request fields

At least one of handle, session must be present.

FieldValuePresence
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
noteslist of at most 1,000 items of: JSON object (bounded: see Free JSON)required
highlightslist of at most 5,000 items of: JSON object (bounded: see Free JSON)required

Reply fields (on ok: true)

No fields.

Sandboxed sessions ​

sandbox.plan ​

The plan a sandboxed session's box was launched with.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

FieldValuePresence
planJSON object (bounded: see Free JSON)required

sandbox.grants ​

What the Sandboxed chip draws: grants, defaults, tools, staleness.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

FieldValuePresence
grantslist of at most 256 items of: object (fields below)optional
grants[].pathabsolute path, at most 4,096 characters, no NULrequired
grants[].statusstring, at most 32 charactersrequired
grants[].insideabsolute path, at most 4,096 characters, no NULoptional
grants[].linkedbooleanoptional
grants[].reasonstring, at most 1,024 charactersoptional
launchedlist of at most 256 items of: absolute path, at most 4,096 characters, no NULoptional
defaultslist of at most 256 items of: absolute path, at most 4,096 characters, no NULoptional
toolsobject of at most 64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: booleanoptional
availableobject of at most 64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: booleanoptional
overriddenbooleanoptional
hostedbooleanoptional
stalebooleanoptional
can_restartbooleanoptional

sandbox.allow ​

Allow a directory to a session's box, or make it a project default.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
pathabsolute path, at most 4,096 characters, no NULrequired
scopestring, one of project, sessionrequired

Reply fields (on ok: true)

FieldValuePresence
livebooleanoptional

sandbox.revoke ​

Take a directory back from a session's box, or from the project defaults.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
pathabsolute path, at most 4,096 characters, no NULrequired
scopestring, one of project, sessionrequired

Reply fields (on ok: true)

FieldValuePresence
livebooleanoptional

sandbox.tools ​

Set which session tools a sandboxed session is offered, or reset them.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

At least one of tools, reset must be present.

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
toolsobject of 1–64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: booleanoptional
resetbooleanoptional

Reply fields (on ok: true)

FieldValuePresence
toolsobject of at most 64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: booleanoptional

sandbox.restart ​

Exit a sandboxed session and resume it with the current plan.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

No fields.

sandbox.derive ​

A sibling's plan, derived from a box's launched one for its directory.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
cwdabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
planabsolute path, at most 4,096 characters, no NULoptional
boxstring, at most 128 charactersoptional
reasonstring, at most 4,096 charactersoptional

sandbox.drop ​

A derived plan and its box, let go of: nothing will launch from them.

Family: sandbox · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
planabsolute path, at most 4,096 characters, no NULoptional

Reply fields (on ok: true)

No fields.

sandbox.forget ​

A session's transcript went: its box, and what it was allowed, go too.

Family: sandbox · Level 3

Optional for another client. No Collins client sends this. store.forget already does it.

Request, client → service, answered by one response.

Request fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
ptyinteger, 1–2^32 − 1optional
handlestring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional

Reply fields (on ok: true)

No fields.

sandbox ​

A sandboxed session's grants or plan changed; a delivery for the toast; the probe's verdict.

Family: sandbox · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
boxstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
whatstring, at most 32 charactersoptional
reasonstring, at most 4,096 charactersoptional
ptyinteger, 1–2^32 − 1optional
sessionstring, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}optional
pathabsolute path, at most 4,096 characters, no NULoptional
deliveryobject (fields below)optional
delivery.pathabsolute path, at most 4,096 characters, no NULrequired
delivery.statusstring, at most 32 charactersrequired
delivery.insideabsolute path, at most 4,096 characters, no NULoptional
delivery.linkedbooleanoptional
delivery.reasonstring, at most 1,024 charactersoptional
revokedbooleanoptional

Git over the API ​

git.run ​

Run one of the git builders, by name and keyword args, on the service's git.

Family: git · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
builderstring, 1–64 characters, matching [a-z][a-z0-9_]{0,63}required
argsJSON object (bounded: see Free JSON)optional
stdinstring, at most 1,048,576 (1 MiB) charactersoptional
timeoutfinite numberoptional
envstring, one of default, no_editor, no_promptoptional

Reply fields (on ok: true)

FieldValuePresence
statusinteger, -1–2^31 − 1required, nullable
stdoutstring, at most 67,108,864 (64 MiB) charactersoptional
stderrstring, at most 65,536 charactersoptional
unreachablebooleanoptional
stdout_chunkedbooleanoptional
stdout_bytesinteger, 0–2^53 − 1optional

git.info ​

Everything gitinfo reads off a repository's .git, at once (the client's per-cwd mirror).

Family: git · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
changesbooleanoptional
statebooleanoptional
known_refsstring, at most 64 charactersoptional

Reply fields (on ok: true)

FieldValuePresence
rootabsolute path, at most 4,096 characters, no NULrequired, nullable
git_dirabsolute path, at most 4,096 characters, no NULoptional, nullable
branchstring, at most 1,024 charactersoptional, nullable
default_branchstring, at most 1,024 charactersoptional, nullable
github_urlhttp(s) URL, at most 4,096 charactersoptional, nullable
index_mtimeinteger, 0–2^53 − 1optional, nullable
headstring, at most 64 charactersoptional, nullable
markerslist of at most 8 items of: string, at most 32 charactersoptional
operationstring, at most 32 charactersoptional, nullable
refsstring, at most 64 charactersoptional, nullable
remoteslist of at most 4,096 items of: string, at most 1,024 charactersoptional
headsobject of at most 4,096 entries, values: string, at most 40 characters, matching [0-9a-f]{40}optional
remote_headsobject of at most 4,096 entries, values: string, at most 40 characters, matching [0-9a-f]{40}optional
changesobject (fields below)optional, nullable
changes.stagedbooleanrequired
changes.unstagedbooleanrequired
statestring, at most 64 charactersoptional, nullable

git.sizes ​

The size on disk of repository paths (the read's too-large gate for untracked and unmerged files).

Family: git · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
pathslist of at most 4,000 items of: string, 1–512 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
sizesobject of at most 4,000 entries, values: integer, 0–2^53 − 1required

git.watch ​

Watch a tree for this client: the page's directory monitors and its 2 s tick, on the service.

Family: git · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
handlestring, 1–64 charactersrequired
fileslist of at most 4,000 items of: string, at most 512 charactersoptional
statestring, at most 64 charactersoptional, nullable
working_treebooleanoptional

Reply fields (on ok: true)

No fields.

git.unwatch ​

Stop one watch of this client's, by its handle.

Family: git · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
handlestring, 1–64 charactersrequired

Reply fields (on ok: true)

No fields.

git-changed ​

A watched working tree moved: the three signatures, each a short digest.

Family: git · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
treestring, at most 64 charactersrequired
refsstring, at most 64 charactersrequired
statestring, at most 64 charactersrequired, nullable

git.plan ​

Carry a gitpatch plan out on the service, refused stale when its keys moved.

Family: git · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
cwdabsolute path, at most 4,096 characters, no NULrequired
loadany JSON value (bounded: see Free JSON)required
pathstring, 1–512 charactersrequired
previous_pathstring, at most 512 charactersoptional, nullable
parent_targetstring, at most 256 charactersoptional, nullable
opstring, one of add, apply-cached, apply-cached-reverse, apply-worktree-reverse, checkout, reset, trashrequired
pathslist of at most 4,000 items of: string, 1–512 charactersrequired
patchstring, at most 1,048,576 (1 MiB) charactersoptional, nullable
three_waybooleanoptional
keyslist of at most 4,000 items of: string, at most 1,024 charactersoptional

Reply fields (on ok: true)

FieldValuePresence
appliedbooleanrequired
stdoutstring, at most 65,536 charactersoptional
stderrstring, at most 65,536 charactersoptional
unreachablebooleanoptional
three_waybooleanoptional
conflictsbooleanoptional

fs.trash ​

Move files to the trash on the service's machine. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathslist of 1–4,000 items of: absolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
trashedlist of at most 4,000 items of: absolute path, at most 4,096 characters, no NULoptional
removedlist of at most 4,000 items of: absolute path, at most 4,096 characters, no NULoptional

Files over the API ​

fs.read ​

A file's text off the service's machine, with the mtime the save that follows expects. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
maxinteger, 1–5,242,880 (5 MiB)optional

Reply fields (on ok: true)

FieldValuePresence
textstring, at most 5,242,880 (5 MiB) charactersrequired
encodingstring, one of latin-1, utf-8required
mtimeinteger, 0–2^53 − 1required
sizeinteger, 0–2^53 − 1required
binarybooleanrequired
text_chunkedbooleanoptional
text_bytesinteger, 0–2^53 − 1optional

fs.write ​

Write a file's text on the service's machine, refused stale when its mtime moved. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
textstring, at most 5,242,880 (5 MiB) charactersrequired
expect_mtimeinteger, 0–2^53 − 1required, nullable
encodingstring, one of latin-1, utf-8optional
text_chunkedbooleanoptional
text_bytesinteger, 0–2^53 − 1optional

Reply fields (on ok: true)

FieldValuePresence
mtimeinteger, 0–2^53 − 1required
sizeinteger, 0–2^53 − 1required
encodingstring, one of latin-1, utf-8required

fs.watch ​

Watch a file (file-changed) or a directory's entries (dir-changed) for this client, on the service. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
kindstring, one of dir, filerequired
handlestring, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
mtimeinteger, 0–2^53 − 1optional, nullable

Reply fields (on ok: true)

No fields.

fs.unwatch ​

Stop a watch of this client's, by its handle. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
handlestring, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required

Reply fields (on ok: true)

No fields.

file-changed ​

A watched file moved: its stat now (null when gone), debounced 300 ms on the service.

Family: files · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
handlestring, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
pathabsolute path, at most 4,096 characters, no NULrequired
mtimeinteger, 0–2^53 − 1required, nullable
sizeinteger, 0–2^53 − 1required, nullable
gonebooleanrequired

dir-changed ​

Something changed in a watched directory, debounced 300 ms on the service: list it again.

Family: files · Level 3

Event, service → client, never answered.

Event fields

FieldValuePresence
handlestring, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}required
pathabsolute path, at most 4,096 characters, no NULrequired

The tree, quick open and roots ​

fs.stat ​

What is at a path on the service's machine, and whether it is inside a root. Any path, for any client.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, or ~ / ~/… in the service's home, at most 4,096 charactersrequired
rootabsolute path, at most 4,096 characters, no NULoptional

Reply fields (on ok: true)

FieldValuePresence
kindstring, one of dir, file, missing, other, symlinkrequired
sizeinteger, 0–2^53 − 1required, nullable
mtimeinteger, 0–2^53 − 1required, nullable
insidebooleanrequired
pathabsolute path, at most 4,096 characters, no NULoptional

fs.list ​

A directory's entries in the tree's order, with the ignored names marked. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
hiddenbooleanrequired
rootabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
entrieslist of at most 5,000 items of: object (fields below)required
entries[].namestring, 1–1,024 charactersrequired
entries[].kindstring, one of dir, file, symlinkrequired
entries[].ignoredbooleanrequired
truncatedbooleanrequired
entries_chunkedbooleanoptional
entries_bytesinteger, 0–2^53 − 1optional

fs.walk ​

Every file under a root, relative and breadth-first, for quick open. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
rootabsolute path, at most 4,096 characters, no NULrequired
hiddenbooleanrequired

Reply fields (on ok: true)

FieldValuePresence
pathslist of at most 20,000 items of: string, 1–4,096 charactersrequired
truncatedbooleanrequired
paths_chunkedbooleanoptional
paths_bytesinteger, 0–2^53 − 1optional

File operations ​

fs.rename ​

Rename a file or folder in place on the service's machine, never over anything. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
targetabsolute path, at most 4,096 characters, no NULrequired
rootabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
mtimeinteger, 0–2^53 − 1required, nullable

fs.paste ​

Copy (or move, for a cut) files into a folder on the service's machine, never over anything. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
entrieslist of 1–1,000 items of: absolute path, at most 4,096 characters, no NULrequired
targetabsolute path, at most 4,096 characters, no NULrequired
cutbooleanrequired
rootabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
resultslist of at most 1,000 items of: object (fields below)required
results[].sourceabsolute path, at most 4,096 characters, no NULrequired
results[].targetabsolute path, at most 4,096 characters, no NULrequired, nullable
results[].mtimeinteger, 0–2^53 − 1required, nullable
results[].errorstring, at most 32 charactersrequired, nullable
results[].messagestring, at most 4,096 charactersoptional
results_chunkedbooleanoptional
results_bytesinteger, 0–2^53 − 1optional

fs.mkdir ​

Make one folder on the service's machine, inside a root, never over anything. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
rootabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

No fields.

fs.names ​

The non-directory names in a root, for the bare root-name links. Confined to the service's roots for a client that has not proved local.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
rootabsolute path, at most 4,096 characters, no NULrequired

Reply fields (on ok: true)

FieldValuePresence
nameslist of at most 5,000 items of: string, 1–1,024 charactersrequired
truncatedbooleanrequired
names_chunkedbooleanoptional
names_bytesinteger, 0–2^53 − 1optional

The path picker ​

fs.dirs ​

A folder's subfolders on the service's machine, anywhere: the path picker's listing. Unconfined: the whole filesystem, for every client.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, or ~ / ~/… in the service's home, at most 4,096 charactersrequired
hiddenbooleanrequired

Reply fields (on ok: true)

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired
entrieslist of at most 5,000 items of: object (fields below)required
entries[].namestring, 1–1,024 charactersrequired
entries[].symlinkbooleanrequired
truncatedbooleanrequired
entries_chunkedbooleanoptional
entries_bytesinteger, 0–2^53 − 1optional

fs.newdir ​

Make one folder on the service's machine under any folder that is there: the picker's New folder. Unconfined: the whole filesystem, for every client.

Family: files · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathabsolute path, or ~ / ~/… in the service's home, at most 4,096 charactersrequired

Reply fields (on ok: true)

FieldValuePresence
pathabsolute path, at most 4,096 characters, no NULrequired

The service itself ​

service.restart ​

Restart the service: now, or once no session is busy; or call a waiting restart off.

Family: internal · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
whenstring, one of cancel, idle, nowrequired

Reply fields (on ok: true)

No fields.

service.status ​

What the service is running.

Family: core · Level 0

Request, client → service, answered by one response.

Request fields

No fields.

Reply fields (on ok: true)

FieldValuePresence
versionstring, 1–64 charactersrequired
protocolinteger, 0–65,535required
ptysinteger, 0–2^31 − 1optional
busyinteger, 0–2^31 − 1optional
clientsinteger, 0–2^31 − 1optional
startedfinite numberoptional
sandboxstring, at most 4,096 charactersoptional
livestring, at most 4,096 charactersoptional
pidinteger, 1–2^31 − 1optional
ghstring, at most 32 charactersoptional
keeperinteger, 1–2^31 − 1optional
unkeptinteger, 0–2^31 − 1optional
keeper_mismatchinteger, 0–2^31 − 1optional
keeper_unreadbooleanoptional
keeper_heldinteger, 0–2^31 − 1optional
clistring, at most 4,096 charactersoptional
homeabsolute path, at most 4,096 characters, no NULoptional

cli.check ​

The service's claude CLI: where it is, where it might be, and a path's verdict.

Family: internal · Level 3

Request, client → service, answered by one response.

Request fields

FieldValuePresence
pathstring, at most 4,096 charactersoptional

Reply fields (on ok: true)

FieldValuePresence
foundstring, at most 4,096 charactersrequired
detectedstring, at most 4,096 charactersoptional
statusstring, one of bad-name, missing, ok, version-managed, versionedoptional

Git builders ​

What git.run's builder may name, with the keyword arguments its args takes. A client never sends a command line: the service builds it, and refuses arguments that don't fit (invalid). Every path is taken literally, never as a glob. Each command below runs as git <command> in cwd; the diff builders also pin git's prefix and quoting settings, so their output doesn't depend on the user's config.

A load is what a diff is of: the string unstaged, staged or branch (which needs parent_target), {"show": "<ref>"} for a commit, or {"range": "<a>...<b>"} for a range, with exactly three dots.

BuilderArgumentsRuns
commit_argvsummary: string, body?: stringcommit -q -m <summary> [-m <body>]
fixup_argvsha: stringcommit -q -m "fixup! <sha>": the index as a fixup of a commit
stage_all_argvnoneadd -A
unstage_all_argvnonereset -q
add_paths_argvpaths: list of stringadd -A -- <paths>
reset_paths_argvpaths: list of stringreset -q -- <paths>
remove_paths_argvpaths: list of stringrm -q -- <paths>
checkout_paths_argvpaths: list of stringcheckout -q -- <paths>
checkout_side_argvside: string, paths: list of stringcheckout -q --<side> -- <paths>, with side ours or theirs
checkout_branch_argvbranch: stringcheckout <branch>
pull_argvnonepull --no-edit
apply_argvcached: boolean, reverse: boolean, three_way?: booleanapply --recount --unidiff-zero [--cached] [--reverse] [--3way] -, the patch in stdin
revert_argvsha: string, commit: booleanrevert --no-edit <sha> when commit is true, else revert --no-commit <sha>
revert_quit_argvnonerevert --quit
continue_argvkind: string<kind> --continue, with kind one of rebase, am, merge, cherry-pick, revert
abort_argvkind: string<kind> --abort, the same kinds
log_argvrange_args: list of string, limit: integerlog --no-decorate --format=%H%x00%h%x00%s%x1e -n <limit> <range_args> --
unpushed_argvnonerev-list HEAD --not --remotes --
stack_walk_argvlower: string or null, upper: string, limit: integerrev-list --topo-order -n <limit> <lower>..<upper> --
commit_subject_argvref: stringlog -1 --format=%s <ref>^{commit} --
commit_message_argvref: stringlog -1 --format=%H%x00%an%x00%aI%x00%s%x00%b <ref>^{commit} --
resolve_commit_argvref: stringrev-parse --verify --quiet <ref>^{commit}
rev_parse_argvrev: stringrev-parse --verify --quiet <rev>
head_abbrev_argvnonerev-parse --short HEAD
merge_base_argva: string, b: stringmerge-base <a> <b>
branch_tips_argvnonefor-each-ref --format=%(objectname) %(refname:short) refs/heads
has_remote_tracking_argvnonefor-each-ref --count=1 --format=%(refname) refs/remotes/
status_argvnone--no-optional-locks status --porcelain=v2 -z --untracked-files=all
status_porcelain_argvnone--no-optional-locks status --porcelain
staged_paths_argvnonediff --cached --name-only -z
unmerged_stages_argvpath: stringls-files -u -z -- <path>
check_ignore_argvnone--no-optional-locks check-ignore -z --stdin, the paths in stdin
diff_argvload: load, parent_target?: string, untracked?: boolean, pathspecs?: list of string, excludes?: list of stringdiff --no-ext-diff --find-renames --no-color <revisions> -- <paths> for the load, or show_argv's command for a commit. untracked changes nothing here
numstat_argvload: load, parent_target?: string, pathspecs?: list of stringThe same load with --numstat -z
show_argvref: string, pathspecs?: list of string, excludes?: list of stringshow --format= --no-ext-diff --find-renames --no-color <ref> -- <paths>
untracked_diff_argvpath: stringdiff --no-color --no-ext-diff --no-index -- /dev/null <path>: a new file as a diff
conflict_diff_argvpaths: list of stringdiff --no-ext-diff --find-renames --no-color --ours -- <paths>
file_at_argvref: string, path: stringshow <ref>:<path>; an empty ref is the index

State keys ​

What state.get and state.set may name. A map is a JSON object whose entries entry reads and writes one at a time, a set a list of distinct strings, a list an ordered list. A key that is not writable is refused refused, and an unknown one gone. Where a family of requests exists (store.*, sandbox.*, notify.*), use it: a direct write skips what the service does on top of it.

KeyFormA client may writeHolds
service_idscalarnoThis service's id, as the hello reply names it.
namesmapyesSession id to the name a person gave it.
generated_namesmapyesSession id to its generated title.
cli_titlesmapyesSession id to the title the CLI gave it.
emojismapyesSession id to its tab emoji.
favoritessetyesThe favorite sessions' ids.
archivedsetyesThe archived sessions' ids. store.archive is the way to change it.
archived_atmapyesSession id to when it was archived, in seconds.
archived_projectssetyesThe archived projects.
project_worktreemapyesProject to whether its new sessions start in a worktree.
project_sandboxmapyesProject to whether its new sessions start sandboxed.
sandboxed_sessionsmapyesSession id to its sandbox's box id.
sandbox_grantsmapyesBox id to its directory grants. Use sandbox.allow and sandbox.revoke.
sandbox_project_grantsmapyesProject to the grants its new sessions start with.
sandbox_toolsmapyesBox id to the session tools it is offered. Use sandbox.tools.
project_orderlistyesThe projects in sidebar order. store.move-project is the way to change it.
virtual_projectsmapyesProject name to its folder, for one kept with no sessions.
expanded_groupssetnoSidebar groups once open. No longer written; a device keeps its own.
session_prsmapyesSession id to its pull request records.
session_attachmentsmapyesSession id to its attachment records.
session_draftsmapyesSession id to its unsent prompt.
new_chat_draftsmapyesDraft id to a new chat not started yet.
process_baselinesmapyesSession id to the processes that don't count as it being busy.
session_forwardsmapyesA session id to the id it continued under.
pending_detachesmapyesSession id to a background handoff still to be replayed.
resume_on_startlistnoThe sessions a stopping service ended, resumable when reopened.
ptysmapnoThe pty table, by app id.
pty_next_idmapnoThe next pty id, by app id.
inflight_copieslistnoThe tree copies fs.paste has in flight.
notificationslistnoThe notification history. Use the notify.* requests.
diff_notesmapnoSession id to the marks on its diff. Use diff.set-notes.
pending_diffsmapnoSession id to a show_diff asked for with no client attached.
settingsmapyesThe service's settings, written one entry at a time (below).

Service settings ​

The entries of settings. A value of another type is refused refused. So is a setting not listed here: appearance, geometry, sounds and the like belong to each client, which keeps its own.

SettingValueWhat it does
claude_cli_pathstringWhere the CLI is when the service's PATH doesn't say.
notify_commandstringA command run for a notification when no client is attached.
title_modelstringThe --model for generated session titles; empty is automatic.
icon_modelstringThe --model for generated project icons; empty is automatic.
auto_renew_loginbooleanRepair an expired CLI login with one headless run.
worktree_new_sessionsbooleanStart new sessions in a git worktree.
clone_directorystringWhere a cloned repository goes by default.
sandbox_new_sessionsbooleanStart new sessions sandboxed.
sandbox_bypass_permissionsbooleanSandboxed sessions default to bypassing permissions.
sandbox_share_ghbooleanShare the GitHub CLI login with sandboxed sessions.
sandbox_share_sshbooleanShare the ssh agent with sandboxed sessions.
sandbox_settings_editablebooleanLet sandboxed sessions write the CLI's settings.
attach_prompt_prsbooleanAttach pull requests a session's first prompt links to.
pr_title_sessionsbooleanTitle a session after its newest pull request.
cli_title_sessionsbooleanShow the titles the CLI gives its sessions.
refresh_prs_on_launchbooleanRefresh pull requests once when a client starts.
archive_running_sessionstringArchiving a session with a running tab: ask, exit or background.
archive_worktreestringA session's worktree on archive: ask, always or never.
archive_on_claude_aibooleanMirror archiving to the session's claude.ai page.
auto_delete_archived_afterintegerTrash archived sessions after this many units; 0 is never.
auto_delete_archived_unitstringThat unit: days, weeks, months or years.
background_status_pollbooleanPoll background agents' status on a timer as well.
progress_termpropbooleanRead busy from the CLI's own progress announcements.
git_parent_branchstringThe branch a session's branch is measured against when none is found.
git_untrackedbooleanInclude untracked files in working-tree reviews.
git_log_pageintegerCommits per page of a commit list.
welcome_seenbooleanThe first-run welcome has been answered.
gh_welcome_dismissedbooleanThe GitHub CLI notice has been dismissed for good.
mcp_tool_<tool>booleanWhether sessions are offered this session tool.
sandbox_tool_<tool>booleanWhether sandboxed sessions are offered it by default.

The session tools: set_session_title, open_in_editor, show_diff, diff_context, annotate_diff, highlight_diff, clear_diff_marks, show_image, notify_user, attach_pr, start_session, read_terminal, run_in_terminal.

Unofficial community tool — not affiliated with or endorsed by Anthropic. Released under GPL-3.0. Forked from agent-session-manager by Máté Molnár.