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
| Name | Value | Meaning |
|---|---|---|
PROTOCOL | 1 | The protocol this build speaks. |
MIN_PROTOCOL | 1 | The oldest protocol this build still speaks. |
MAX_FRAME | 1,048,576 (1 MiB) | The largest frame either peer sends, in bytes; larger transfers are chunked. |
MAX_INCOMING | 16,777,216 (16 MiB) | The largest frame either peer accepts, in bytes. |
MAX_PAYLOAD | 1,048,560 | The most payload bytes one binary frame carries (the frame less its header). |
CHUNKED_MAX | 67,108,864 (64 MiB) | The most bytes a chunked field runs to, in either direction. |
ACK_BYTES | 65,536 | The client acks every this many bytes of live output fed to its terminal. |
ACK_MS | 100 | ... or this many milliseconds after the last unacked frame, whichever first. |
ACK_WINDOW | 1,048,576 (1 MiB) | The most unacked live bytes the service hands a client before holding the rest. |
QUEUE_BYTES | 4,194,304 (4 MiB) | One client's send queue per pty; overflow means a redraw. |
KEEPALIVE_INTERVAL_S | 10 | WebSocket keepalive interval, seconds, both ends. |
KEEPALIVE_PONG_TIMEOUT_S | 10 | WebSocket keepalive pong timeout, seconds, both ends. |
LOCAL_PROOF_BYTES | 32 | The length of the local proof the service writes. |
REQUEST_ID_MAX | 2^53 − 1 | The largest request id. |
TEXT_MAX | 1,048,576 (1 MiB) | The most characters of a text payload (a prompt, a paint, a cut, a tool reply). |
PATH_MAX | 4,096 | The most characters of a path. |
ID_MAX | 128 | The most characters of an id (session, client, service, box, notification, tool call). |
JSON_MAX_DEPTH | 32 | The deepest nesting of a free JSON value. |
JSON_MAX_NODES | 100,000 | The most values in a free JSON value, all depths together. |
FILE_TEXT_MAX | 5,242,880 (5 MiB) | The most bytes of a file fs.read answers or fs.write takes. |
TRANSCRIPT_EXPORT_MAX | 16,777,216 (16 MiB) | The most characters of a Markdown export. |
Binary frame tags and flags
| Name | Value | Meaning |
|---|---|---|
TAG_OUTPUT | 0x01 | pty output, service to client; stream is the pty |
TAG_INPUT | 0x02 | pty input, client to service; stream is the pty |
TAG_BLOB | 0x03 | a chunk of a chunked message, either way; stream is the message id masked to 32 bits |
FLAG_REDRAW | 0x01 | output: part of a redraw (not counted, not acked) |
FLAG_REDRAW_END | 0x02 | output: the redraw's last frame |
Enumerations
CAPABILITIES: The names a service may list in its hello reply'scaps.background,composer,debug,files,git,internal,jobs,local,prs,sandbox,shells,tools,usageERRORS: The error codes a refusal carries; a receiver accepts any code-shaped string.direction,failed,gone,invalid,protocol,refused,sequence,stale,unknownCHANNELS: A connection'schannelin its hello.primary,syncCHUNKED_FIELDS: The fields that may travel as blob frames, in the order they are looked for.stdout,text,paths,entries,results,namesCHUNKED_JSON_FIELDS: The chunked fields that are lists (their JSON is what travels).entries,names,paths,resultsJOB_KINDS: The long-running operationsjob.startstarts.chats.trust,clone,clone.repos,icon,login.repair,session.repair,worktree.check,worktree.restore,worktree.trashJOB_STATES: The states ajobevent reports.cancelled,done,failed,refused,runningPOST_KINDS: The notification kinds a client may post withnotify.post.bell,message,updateCLI_STATUSES:cli.check's verdicts on a path.bad-name,missing,ok,version-managed,versionedGIT_ENVS: The environmentsgit.runruns git in.default,no_editor,no_promptPLAN_OPS: The operations agit.plancarries.add,apply-cached,apply-cached-reverse,apply-worktree-reverse,checkout,reset,trashFILE_ENCODINGS: The encodingsfs.readanswers andfs.writetakes.latin-1,utf-8WATCH_KINDS: Whatfs.watchwatches.dir,fileFS_STAT_KINDS: Whatfs.statfinds at a path.dir,file,missing,other,symlinkFS_ENTRY_KINDS: What anfs.listentry is.dir,file,symlinkFS_RENAME_REASONS: Whyfs.renamewas refused (the refusal'sreason).empty,exists,missing,not_a_name,outsideFS_MKDIR_REASONS: Whyfs.mkdirwas refused (the refusal'sreason).exists,no_parent,not_a_name,outsideFS_PASTE_ERRORS: Why onefs.pasteentry failed (its result'serror); 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: noitemand nopty, then arowswith an empty list.service.statusneeds onlyversionandprotocol.- A server with no local proof leaves
local_proofout of its hello and refuseslocalrefused. 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"withcwd,session,prompt,model,effort,permission_mode,cols,rows,provider, which every server accepts. An unknownproviderreads as Claude.spawn: a field whose value asks for nothing (an emptyadd_dirs, a falseworktreewith aworktree_namebeside it, a falsesandbox) is accepted and ignored.spawn: a server refusesrefused, with amsgidsaying why, only a value that asks for a feature it lacks:sandbox: true,sandbox_boxorsandbox_planwithoutsandbox;historyorordinalwithoutshells;worktree: true, a non-emptyadd_dirs,fork,continue_recentor another optional field when it can't honour them.close: the modesexitandkill.store.flags:statusandunread.state.set: as an event, thesettingskey, with the server's defaults; a setting left out reads as the client's default. As a request, a server may refuse every writerefused.state.get: answers every key the server emitsstate.setfor, and refuses any othergone.resolver.arm: answerok. A server with no resolver ignores it.item:project,cli_title,provider,stateandsyncingare optional, and a missing one reads as absent.- The input frames,
resize,focus,themeandackare honoured. service.status: a Level 1 server should sendcliandhome. A client reads a missingclias unknown, and withouthomeit 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 refusedrefusedoutside them, exceptfs.dirsandfs.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 fieldssandbox,sandbox_box,sandbox_plan.pty: the fieldssandboxedandbox.pty.info: the fieldplan.
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=fileandkind=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 modebackground.
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.
| Name | Sentence | When |
|---|---|---|
ALREADY_RUNNING_MSGID | This session is already running in the Collins service | spawn refused refused because the session already runs; args.pty names its pty, and the client attaches to that instead. |
PTY_GONE_MSGID | no such pty | A request refused gone because no such pty exists; args.pty names it. The client takes the pty as ended. |
FOLDER_GONE_MSGID | The folder is not there | fs.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
| Field | Value | Presence |
|---|---|---|
protocol | integer, 0–65,535 | required |
min_protocol | integer, 0–65,535 | optional |
version | string, 1–64 characters | required |
client_id | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
device | string, at most 255 characters | optional |
locale | string, at most 64 characters, matching [A-Za-z0-9_.@-]{1,64} | optional |
term | object (fields below) | optional |
term.vte | integer, 0–99,999,999 | optional |
term.fg | string, at most 7 characters, matching #[0-9A-Fa-f]{6} | optional |
term.bg | string, at most 7 characters, matching #[0-9A-Fa-f]{6} | optional |
term.scheme | string, one of dark, light | optional |
term.palette | list of exactly 16 items of: string, at most 7 characters, matching #[0-9A-Fa-f]{6} | optional |
channel | string, one of primary, sync | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
protocol | integer, 0–65,535 | required |
min_protocol | integer, 0–65,535 | required |
version | string, 1–64 characters | required |
service_id | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
host | string, at most 255 characters | optional |
implementation | string, at most 64 characters | optional |
caps | list of at most 64 items of: string, at most 64 characters, matching [a-z][a-z0-9_.-]{0,63} | optional |
local_proof | object (fields below) | optional |
local_proof.path | absolute path, at most 4,096 characters, no NUL | required |
local_proof.length | integer, 1–4,096 | required |
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
| Field | Value | Presence |
|---|---|---|
proof | string, 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)
| Field | Value | Presence |
|---|---|---|
items | integer, 0–2^31 − 1 | optional |
ptys | integer, 0–2^31 − 1 | optional |
Terminals
attach
Show a pty: a redraw, then live output.
Family: core · Level 1
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
cols | integer, 1–2,000 | required |
rows | integer, 1–1,000 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
cols | integer, 1–2,000 | required |
rows | integer, 1–1,000 | required |
active | boolean | required |
sized_for | string, at most 255 characters | optional |
modes | list of at most 512 items of: string, 1–16 characters | optional |
detach
Stop showing a pty; it keeps running.
Family: core · Level 1
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
cols | integer, 1–2,000 | required |
rows | integer, 1–1,000 | required |
focus
A client's view of a pty gained or lost focus.
Family: core · Level 1
Event, client → service, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
focused | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
theme
The client's terminal colours or scheme changed.
Family: core · Level 1
Event, client → service, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
term | object (fields below) | required |
term.vte | integer, 0–99,999,999 | optional |
term.fg | string, at most 7 characters, matching #[0-9A-Fa-f]{6} | optional |
term.bg | string, at most 7 characters, matching #[0-9A-Fa-f]{6} | optional |
term.scheme | string, one of dark, light | optional |
term.palette | list 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
offset | integer, 0–2^64 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
kind | string, one of agent, shell | required |
cwd | absolute path, at most 4,096 characters, no NUL | required |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
provider | string, at most 32 characters | optional |
prompt | string, at most 1,048,576 (1 MiB) characters | optional |
model | string, at most 128 characters | optional |
effort | string, at most 32 characters | optional |
permission_mode | string, at most 32 characters | optional |
add_dirs | list of at most 64 items of: absolute path, at most 4,096 characters, no NUL | optional |
worktree | boolean | optional |
worktree_name | string, at most 128 characters | optional |
sandbox | boolean | optional |
sandbox_box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
fork | boolean | optional |
continue_recent | boolean | optional |
jsonl_path | absolute path, at most 4,096 characters, no NUL | optional |
sandbox_plan | absolute path, at most 4,096 characters, no NUL | optional |
fork_resolve | boolean | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
cols | integer, 1–2,000 | optional |
rows | integer, 1–1,000 | optional |
history | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
ordinal | integer, 0–65,535 | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
cols | integer, 1–2,000 | required |
rows | integer, 1–1,000 | required |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
cwd | absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
history | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required, nullable |
handle | string, 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
| Field | Value | Presence |
|---|---|---|
key | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
shells | list of at most 64 items of: object (fields below) | required |
shells[].ordinal | integer, 0–10,000 | required |
shells[].pty | integer, 1–2^32 − 1 | optional |
shells[].text | string, at most 1,048,576 (1 MiB) characters | optional |
shells[].keep | boolean | optional |
partial | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
kind | string, 1–32 characters | required |
child_pid | integer, 1–2^31 − 1 | optional, nullable |
shell_pid | integer, 1–2^31 − 1 | optional, nullable |
foreground_pgrp | integer, -1–2^31 − 1 | optional, nullable |
running_command | boolean | required |
process_cwd | absolute path, at most 4,096 characters, no NUL | optional, nullable |
cwd | absolute path, at most 4,096 characters, no NUL | optional |
plan | absolute path, at most 4,096 characters, no NUL | optional, nullable |
cols | integer, 1–2,000 | optional |
rows | integer, 1–1,000 | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
text | string, at most 1,048,576 (1 MiB) characters | required |
prompt
Type text into the agent's box and submit it.
Family: core · Level 1
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
text | string, 1–1,048,576 (1 MiB) characters | required |
focus | boolean | optional |
when_empty | boolean | optional |
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.
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
model | string, 1–128 characters | optional |
effort | string, 1–32 characters | optional |
composer_open | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
text | string, 1–1,048,576 (1 MiB) characters | required |
mention | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
text | string, 1–1,048,576 (1 MiB) characters | required |
composer_open | boolean | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
sent | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
path | absolute path, at most 4,096 characters, no NUL | required |
start_line | integer, 0–2^31 − 1 | optional |
end_line | integer, 0–2^31 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
state | string, one of cancelled, refused, seeded | required |
text | string, at most 1,048,576 (1 MiB) characters | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
handle | string, 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
text | string, 1–1,048,576 (1 MiB) characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
restored | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
text | string, 1–1,048,576 (1 MiB) characters | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
mode | string, one of background, exit, kill | required |
text | string, at most 256 characters | optional |
force | boolean | optional |
Reply fields (on ok: true)
No fields.
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
state | string, one of budget | required |
phase | string, at most 32 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional, nullable |
fork | boolean | optional |
provider | string, at most 32 characters | optional |
options | JSON object (bounded: see Free JSON) | optional, nullable |
continue_recent | boolean | optional |
cwd | absolute path, at most 4,096 characters, no NUL | optional, nullable |
agent_cwd | absolute path, at most 4,096 characters, no NUL | optional, nullable |
pid | integer, 1–2^31 − 1 | optional, nullable |
resolver_cwd | absolute path, at most 4,096 characters, no NUL | optional, nullable |
initial_command | string, at most 4,096 characters | optional, nullable |
worktree_launch | boolean | optional |
new_chat_prompt | string, at most 4,096 characters | optional, nullable |
shells_follow_armed | boolean | optional |
closing | boolean | optional |
sandboxed | boolean | optional |
sandbox_box | string, at most 128 characters | optional |
sandbox_plan_path | absolute path, at most 4,096 characters, no NUL | optional, nullable |
defaults_owed | boolean | optional |
can_restart | boolean | optional |
takes_prompt | boolean | optional |
entered | object (fields below) | optional, nullable |
entered.text | string, at most 4,096 characters | required |
entered.rows_below | integer, 0–1,000 | required |
prompt_block | string, at most 4,096 characters | optional |
unstarted | boolean | optional |
foreign_paste | boolean | optional |
agent_running | boolean | optional |
running_command | boolean | optional |
model | string, at most 128 characters | optional, nullable |
effort | string, at most 32 characters | optional, nullable |
permission_mode | string, at most 32 characters | optional, nullable |
transcript_path | absolute path, at most 4,096 characters, no NUL | optional, nullable |
prs | list of at most 100 items of: JSON object (bounded: see Free JSON) | optional |
lookup_empty | boolean | optional |
touched_files | list of at most 64 items of: absolute path, at most 4,096 characters, no NUL | optional |
attachments | list of at most 1,000 items of: JSON object (bounded: see Free JSON) | optional |
ledger_armed | boolean | optional |
landed | boolean | optional |
reset | boolean | optional |
busy | boolean | optional |
finished | boolean | optional |
forked | string, 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
what | string, one of refocus, resend, stash | required |
text | string, at most 1,048,576 (1 MiB) characters | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
what | string, one of stale | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
discover | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
path | absolute path, at most 4,096 characters, no NUL | required, 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
path | absolute path, at most 4,096 characters, no NUL | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
records | list 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
cwd | absolute path, or ~ / ~/… in the service's home, at most 4,096 characters | optional, nullable |
root | absolute path, at most 4,096 characters, no NUL | required |
judge | boolean | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
scope | string, at most 32 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
armed | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
stamp | list of exactly 2 items of: integer, 0–2^31 − 1 | required |
size | integer, 0–2^53 − 1 | required, 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
capturing | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
cmdlines | list of at most 1,000 items of: string, at most 4,096 characters | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
name | string, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255} | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
value | any JSON value (bounded: see Free JSON) | optional, nullable |
callable | boolean | optional |
debug.session.set
Set an attribute of a session.
Family: debug · Level 3
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
name | string, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255} | required |
value | any 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
name | string, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255} | required |
args | list of at most 16 items of: any JSON value (bounded: see Free JSON) | optional |
kwargs | JSON object (bounded: see Free JSON) | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
value | any 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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
rows | list of at most 1,000 items of: string, at most 8,000 characters | required |
cursor | list of exactly 2 items of: integer, 0–2,000 | required |
columns | integer, 1–2,000 | required |
row_count | integer, 1–1,000 | required |
capture | string, at most 1,048,576 (1 MiB) characters | required |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
child_pid | integer, 1–2^31 − 1 | required, nullable |
foreground_pgrp | integer, -1–2^31 − 1 | required, nullable |
shell_pid | integer, 1–2^31 − 1 | required, nullable |
process_cwd | absolute path, at most 4,096 characters, no NUL | required, 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
| Field | Value | Presence |
|---|---|---|
local | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
target | string, one of core, grants, host | required |
name | string, 1–256 characters, matching [A-Za-z_][A-Za-z0-9_.]{0,255} | required |
args | list of at most 16 items of: any JSON value (bounded: see Free JSON) | optional |
kwargs | JSON object (bounded: see Free JSON) | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
value | any 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
| Field | Value | Presence |
|---|---|---|
key | string, 1–64 characters, matching [A-Za-z_][A-Za-z0-9_.-]{0,63} | required |
entry | string, 1–4,096 characters | optional |
value | any JSON value (bounded: see Free JSON) | required, nullable |
Reply fields (on ok: true)
No fields.
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
key | string, 1–64 characters, matching [A-Za-z_][A-Za-z0-9_.-]{0,63} | required |
entry | string, 1–4,096 characters | optional |
value | any 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
| Field | Value | Presence |
|---|---|---|
key | string, 1–64 characters, matching [A-Za-z_][A-Za-z0-9_.-]{0,63} | required |
entry | string, 1–4,096 characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
value | any 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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
removed | boolean | optional |
project | string, at most 4,096 characters | optional |
cwd | absolute path, at most 4,096 characters, no NUL | optional, nullable |
resume_cwd | absolute path, at most 4,096 characters, no NUL | optional, nullable |
display_name | string, at most 1,024 characters | optional |
cli_title | string, at most 1,024 characters | optional |
subtitle | string, at most 256 characters | optional |
preview | string, at most 4,096 characters | optional |
provider | string, at most 32 characters | optional |
favorite | boolean | optional |
status | string, at most 32 characters | optional |
state | string, at most 32 characters | optional |
busy | boolean | optional |
unread | boolean | optional |
syncing | boolean | optional |
backgrounding | boolean | optional |
can_background | boolean | optional |
background | string, at most 32 characters | optional |
running | boolean | optional |
mtime | finite number | optional |
created | finite number | optional |
size | integer, 0–2^53 − 1 | optional |
path | absolute path, at most 4,096 characters, no NUL | optional |
forward | string, at most 32 characters | optional |
rows
The sidebar's rows after a refresh: their order, groups and counts.
Family: core · Level 1
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
rows | list of at most 10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
groups | list of at most 10,000 items of: object (fields below) | optional |
groups[].kind | string, 1–32 characters | required |
groups[].name | string, at most 1,024 characters | optional |
groups[].label | string, at most 1,024 characters | optional |
groups[].count | integer, 1–10,000 | required |
empty | list of at most 10,000 items of: object (fields below) | optional |
empty[].kind | string, 1–32 characters | required |
empty[].name | string, at most 1,024 characters | optional |
empty[].label | string, at most 1,024 characters | optional |
empty[].cwd | absolute path, at most 4,096 characters, no NUL | optional |
order | list of at most 10,000 items of: string, at most 1,024 characters | optional |
order_changed | boolean | optional |
show_archived | boolean | optional |
total | integer, 0–2^31 − 1 | optional |
hidden | integer, 0–2^31 − 1 | optional |
size | integer, 0–2^53 − 1 | optional |
projects | list of at most 10,000 items of: string, at most 1,024 characters | optional |
chats | integer, 0–2^31 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
session | string, 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
| Field | Value | Presence |
|---|---|---|
session | string, 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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
found | boolean | required |
sessions | list 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)
| Field | Value | Presence |
|---|---|---|
items | integer, 0–2^31 − 1 | optional |
sessions | list 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
| Field | Value | Presence |
|---|---|---|
force | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
show | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
name | string, at most 1,024 characters | required |
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
| Field | Value | Presence |
|---|---|---|
session | string, 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
| Field | Value | Presence |
|---|---|---|
sessions | list of 1–10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
favorite | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
sessions | list of 1–10,000 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
archived | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
project | string, 1–1,024 characters | required |
archived | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
sessions | list 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)
| Field | Value | Presence |
|---|---|---|
errors | object of at most 10,000 entries, keys matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127}, values: string, at most 4,096 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
error | string, at most 4,096 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
to | string, 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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
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
| Field | Value | Presence |
|---|---|---|
projects | list of 1–10,000 items of: string, 1–1,024 characters | required |
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
| Field | Value | Presence |
|---|---|---|
project | string, 1–1,024 characters | required |
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
| Field | Value | Presence |
|---|---|---|
project | string, 1–1,024 characters | required |
before | string, 1–1,024 characters | optional, 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
| Field | Value | Presence |
|---|---|---|
session | string, 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.
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
status | string, at most 32 characters | optional |
busy | boolean | optional |
unread | boolean | optional |
backgrounding | boolean | optional |
can_background | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
links | list of at most 1,000 items of: string, 1–1,024 characters | required |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
text | string, at most 16,777,216 (16 MiB) characters | required |
text_chunked | boolean | optional |
text_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
trusted | boolean | required |
root | absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
scope | string, one of launch, root | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
written | boolean | required |
pty
A pty appeared or changed (a row of the pty table).
Family: core · Level 1
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
kind | string, 1–32 characters | required |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
cwd | absolute path, at most 4,096 characters, no NUL | optional |
pid | integer, 1–2^31 − 1 | optional |
cols | integer, 1–2,000 | optional |
rows | integer, 1–1,000 | optional |
sandboxed | boolean | optional |
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
active | boolean | optional |
sized_for | string, at most 255 characters | optional |
table | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
pty | integer, 1–2^32 − 1 | required |
status | integer, -2,147,483,648–2^31 − 1 | required, nullable |
table | boolean | optional |
pr
A session's linked pull requests, as prstatus records.
Family: prs · Level 3
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
prs | list of at most 100 items of: JSON object (bounded: see Free JSON) | required |
attached | list of at most 100 items of: http(s) URL, at most 4,096 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
url | http(s) URL, at most 4,096 characters | required |
status | JSON 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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
prs | list 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
| Field | Value | Presence |
|---|---|---|
urls | list of 1–100 items of: http(s) URL, at most 4,096 characters | required |
invalidate | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
targets | list of 1–10,000 items of: object (fields below) | required |
targets[].session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
targets[].prs | list of at most 100 items of: JSON object (bounded: see Free JSON) | optional |
targets[].cwd | absolute path, at most 4,096 characters, no NUL | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
results | object 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
| Field | Value | Presence |
|---|---|---|
url | http(s) URL, at most 4,096 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
detail | JSON 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
| Field | Value | Presence |
|---|---|---|
url | http(s) URL, at most 4,096 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
threads | list 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
| Field | Value | Presence |
|---|---|---|
repository | string, 1–1,024 characters | required |
ref | string, 1–256 characters | required |
path | string, 1–4,096 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
url | string, at most 16,384 characters | optional |
error | string, at most 4,096 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
pr | JSON object (bounded: see Free JSON) | required |
key | string, 1–32 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
error | string, at most 4,096 characters | optional |
pr.comment
Comment on a pull request.
Family: prs · Level 3
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
pr | JSON object (bounded: see Free JSON) | required |
body | string, 1–1,048,576 (1 MiB) characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
error | string, at most 4,096 characters | optional |
pr.review
Review a pull request: approve, or request changes.
Family: prs · Level 3
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
pr | JSON object (bounded: see Free JSON) | required |
verdict | string, 1–32 characters | required |
body | string, at most 1,048,576 (1 MiB) characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
error | string, at most 4,096 characters | optional |
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.
| Field | Value | Presence |
|---|---|---|
pr | JSON object (bounded: see Free JSON) | required |
thread | string, 1–200 characters, matching [A-Za-z0-9+/=_-]{1,200} | required |
body | string, 1–1,048,576 (1 MiB) characters | optional |
resolved | boolean | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
error | string, at most 4,096 characters | optional |
Notifications
notify
A notification record, its body as msgid and args.
Family: core · Level 2
Event, service → client, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
notification | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
kind | string, 1–32 characters | required |
session | string, at most 128 characters, matching (?:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})? | optional |
title | string, at most 1,024 characters | optional |
project | string, at most 1,024 characters | optional |
msgid | string, 1–4,096 characters | optional |
args | object 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 null | optional |
when | finite number | required |
read | boolean | optional |
count | integer, 1–2^31 − 1 | optional |
url | http(s) URL, at most 4,096 characters | optional |
removed | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
kind | string, one of bell, message, update | required |
session | string, at most 128 characters, matching (?:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})? | optional |
title | string, at most 1,024 characters | optional |
project | string, at most 1,024 characters | optional |
msgid | string, 1–4,096 characters | required |
args | object 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 null | optional |
read | boolean | optional |
url | http(s) URL, at most 4,096 characters | optional |
key | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
notification | string, 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
| Field | Value | Presence |
|---|---|---|
ids | list 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)
| Field | Value | Presence |
|---|---|---|
removed | integer, 0–2^31 − 1 | optional |
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)
| Field | Value | Presence |
|---|---|---|
removed | integer, 0–2^31 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
on | boolean | required |
title | string, at most 1,024 characters | optional |
project | string, at most 1,024 characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
changed | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
to | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
moved | integer, 0–2^31 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
command | string, at most 4,096 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
status | integer, -255–255 | optional |
error | string, at most 4,096 characters | optional |
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.
| Field | Value | Presence |
|---|---|---|
ids | list of at most 200 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
all | boolean | optional |
Reply fields (on ok: true)
No fields.
Event, service → client, never answered.
Event fields
At least one of ids, session, all must be present.
| Field | Value | Presence |
|---|---|---|
ids | list of at most 200 items of: string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
all | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
kind | string, one of chats.trust, clone, clone.repos, icon, login.repair, session.repair, worktree.check, worktree.restore, worktree.trash | required |
args | JSON object (bounded: see Free JSON) | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
job | string, 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
| Field | Value | Presence |
|---|---|---|
job | string, 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
| Field | Value | Presence |
|---|---|---|
job | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
kind | string, 1–32 characters | required |
state | string, 1–32 characters | required |
msgid | string, 1–4,096 characters | optional |
args | object 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 null | optional |
result | JSON 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)
| Field | Value | Presence |
|---|---|---|
snapshot | JSON object (bounded: see Free JSON) | optional |
kind | string, at most 32 characters | optional |
error | string, at most 4,096 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
fetch | boolean | optional |
refresh | boolean | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
models | list of at most 256 items of: JSON object (bounded: see Free JSON) | optional |
cached | boolean | optional |
fetched_at | finite number | optional |
failed | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | optional |
model | string, at most 128 characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
model | string, at most 128 characters | optional |
effort | string, at most 32 characters | optional |
icon.save
Write a generated project icon into the project.
Family: usage · Level 3
Request, client → service, answered by one response.
Request fields
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
svg | string, 1–1,048,576 (1 MiB) characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
call | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
session | string, at most 128 characters, matching (?:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})? | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
name | string, 1–64 characters, matching [a-z][a-z0-9_]{0,63} | required |
arguments | JSON object (bounded: see Free JSON) | required |
sandboxed | boolean | optional |
tool-reply
The active client's answer to a tool call.
Family: tools · Level 3
Event, client → service, never answered.
Event fields
| Field | Value | Presence |
|---|---|---|
call | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
ok | boolean | required |
text | string, at most 1,048,576 (1 MiB) characters | required |
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.
| Field | Value | Presence |
|---|---|---|
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
notes | list of at most 1,000 items of: JSON object (bounded: see Free JSON) | required |
highlights | list 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.
| Field | Value | Presence |
|---|---|---|
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
notes | list of at most 1,000 items of: JSON object (bounded: see Free JSON) | required |
highlights | list 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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
plan | JSON 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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
grants | list of at most 256 items of: object (fields below) | optional |
grants[].path | absolute path, at most 4,096 characters, no NUL | required |
grants[].status | string, at most 32 characters | required |
grants[].inside | absolute path, at most 4,096 characters, no NUL | optional |
grants[].linked | boolean | optional |
grants[].reason | string, at most 1,024 characters | optional |
launched | list of at most 256 items of: absolute path, at most 4,096 characters, no NUL | optional |
defaults | list of at most 256 items of: absolute path, at most 4,096 characters, no NUL | optional |
tools | object of at most 64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: boolean | optional |
available | object of at most 64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: boolean | optional |
overridden | boolean | optional |
hosted | boolean | optional |
stale | boolean | optional |
can_restart | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
path | absolute path, at most 4,096 characters, no NUL | required |
scope | string, one of project, session | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
live | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
path | absolute path, at most 4,096 characters, no NUL | required |
scope | string, one of project, session | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
live | boolean | optional |
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.
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
tools | object of 1–64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: boolean | optional |
reset | boolean | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
tools | object of at most 64 entries, keys matching [a-z][a-z0-9_]{0,63}, values: boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
cwd | absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
plan | absolute path, at most 4,096 characters, no NUL | optional |
box | string, at most 128 characters | optional |
reason | string, at most 4,096 characters | optional |
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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
plan | absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
pty | integer, 1–2^32 − 1 | optional |
handle | string, 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
| Field | Value | Presence |
|---|---|---|
box | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
what | string, at most 32 characters | optional |
reason | string, at most 4,096 characters | optional |
pty | integer, 1–2^32 − 1 | optional |
session | string, 1–128 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | optional |
path | absolute path, at most 4,096 characters, no NUL | optional |
delivery | object (fields below) | optional |
delivery.path | absolute path, at most 4,096 characters, no NUL | required |
delivery.status | string, at most 32 characters | required |
delivery.inside | absolute path, at most 4,096 characters, no NUL | optional |
delivery.linked | boolean | optional |
delivery.reason | string, at most 1,024 characters | optional |
revoked | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
builder | string, 1–64 characters, matching [a-z][a-z0-9_]{0,63} | required |
args | JSON object (bounded: see Free JSON) | optional |
stdin | string, at most 1,048,576 (1 MiB) characters | optional |
timeout | finite number | optional |
env | string, one of default, no_editor, no_prompt | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
status | integer, -1–2^31 − 1 | required, nullable |
stdout | string, at most 67,108,864 (64 MiB) characters | optional |
stderr | string, at most 65,536 characters | optional |
unreachable | boolean | optional |
stdout_chunked | boolean | optional |
stdout_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
changes | boolean | optional |
state | boolean | optional |
known_refs | string, at most 64 characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
root | absolute path, at most 4,096 characters, no NUL | required, nullable |
git_dir | absolute path, at most 4,096 characters, no NUL | optional, nullable |
branch | string, at most 1,024 characters | optional, nullable |
default_branch | string, at most 1,024 characters | optional, nullable |
github_url | http(s) URL, at most 4,096 characters | optional, nullable |
index_mtime | integer, 0–2^53 − 1 | optional, nullable |
head | string, at most 64 characters | optional, nullable |
markers | list of at most 8 items of: string, at most 32 characters | optional |
operation | string, at most 32 characters | optional, nullable |
refs | string, at most 64 characters | optional, nullable |
remotes | list of at most 4,096 items of: string, at most 1,024 characters | optional |
heads | object of at most 4,096 entries, values: string, at most 40 characters, matching [0-9a-f]{40} | optional |
remote_heads | object of at most 4,096 entries, values: string, at most 40 characters, matching [0-9a-f]{40} | optional |
changes | object (fields below) | optional, nullable |
changes.staged | boolean | required |
changes.unstaged | boolean | required |
state | string, at most 64 characters | optional, 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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
paths | list of at most 4,000 items of: string, 1–512 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
sizes | object of at most 4,000 entries, values: integer, 0–2^53 − 1 | required |
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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
handle | string, 1–64 characters | required |
files | list of at most 4,000 items of: string, at most 512 characters | optional |
state | string, at most 64 characters | optional, nullable |
working_tree | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
handle | string, 1–64 characters | required |
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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
tree | string, at most 64 characters | required |
refs | string, at most 64 characters | required |
state | string, at most 64 characters | required, 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
| Field | Value | Presence |
|---|---|---|
cwd | absolute path, at most 4,096 characters, no NUL | required |
load | any JSON value (bounded: see Free JSON) | required |
path | string, 1–512 characters | required |
previous_path | string, at most 512 characters | optional, nullable |
parent_target | string, at most 256 characters | optional, nullable |
op | string, one of add, apply-cached, apply-cached-reverse, apply-worktree-reverse, checkout, reset, trash | required |
paths | list of at most 4,000 items of: string, 1–512 characters | required |
patch | string, at most 1,048,576 (1 MiB) characters | optional, nullable |
three_way | boolean | optional |
keys | list of at most 4,000 items of: string, at most 1,024 characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
applied | boolean | required |
stdout | string, at most 65,536 characters | optional |
stderr | string, at most 65,536 characters | optional |
unreachable | boolean | optional |
three_way | boolean | optional |
conflicts | boolean | optional |
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
| Field | Value | Presence |
|---|---|---|
paths | list of 1–4,000 items of: absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
trashed | list of at most 4,000 items of: absolute path, at most 4,096 characters, no NUL | optional |
removed | list of at most 4,000 items of: absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
max | integer, 1–5,242,880 (5 MiB) | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
text | string, at most 5,242,880 (5 MiB) characters | required |
encoding | string, one of latin-1, utf-8 | required |
mtime | integer, 0–2^53 − 1 | required |
size | integer, 0–2^53 − 1 | required |
binary | boolean | required |
text_chunked | boolean | optional |
text_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
text | string, at most 5,242,880 (5 MiB) characters | required |
expect_mtime | integer, 0–2^53 − 1 | required, nullable |
encoding | string, one of latin-1, utf-8 | optional |
text_chunked | boolean | optional |
text_bytes | integer, 0–2^53 − 1 | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
mtime | integer, 0–2^53 − 1 | required |
size | integer, 0–2^53 − 1 | required |
encoding | string, one of latin-1, utf-8 | required |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
kind | string, one of dir, file | required |
handle | string, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
mtime | integer, 0–2^53 − 1 | optional, 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
| Field | Value | Presence |
|---|---|---|
handle | string, 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
| Field | Value | Presence |
|---|---|---|
handle | string, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
path | absolute path, at most 4,096 characters, no NUL | required |
mtime | integer, 0–2^53 − 1 | required, nullable |
size | integer, 0–2^53 − 1 | required, nullable |
gone | boolean | required |
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
| Field | Value | Presence |
|---|---|---|
handle | string, 1–64 characters, matching [A-Za-z0-9][A-Za-z0-9._:-]{0,127} | required |
path | absolute path, at most 4,096 characters, no NUL | required |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, or ~ / ~/… in the service's home, at most 4,096 characters | required |
root | absolute path, at most 4,096 characters, no NUL | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
kind | string, one of dir, file, missing, other, symlink | required |
size | integer, 0–2^53 − 1 | required, nullable |
mtime | integer, 0–2^53 − 1 | required, nullable |
inside | boolean | required |
path | absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
hidden | boolean | required |
root | absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
entries | list of at most 5,000 items of: object (fields below) | required |
entries[].name | string, 1–1,024 characters | required |
entries[].kind | string, one of dir, file, symlink | required |
entries[].ignored | boolean | required |
truncated | boolean | required |
entries_chunked | boolean | optional |
entries_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
root | absolute path, at most 4,096 characters, no NUL | required |
hidden | boolean | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
paths | list of at most 20,000 items of: string, 1–4,096 characters | required |
truncated | boolean | required |
paths_chunked | boolean | optional |
paths_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
target | absolute path, at most 4,096 characters, no NUL | required |
root | absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
mtime | integer, 0–2^53 − 1 | required, 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
| Field | Value | Presence |
|---|---|---|
entries | list of 1–1,000 items of: absolute path, at most 4,096 characters, no NUL | required |
target | absolute path, at most 4,096 characters, no NUL | required |
cut | boolean | required |
root | absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
results | list of at most 1,000 items of: object (fields below) | required |
results[].source | absolute path, at most 4,096 characters, no NUL | required |
results[].target | absolute path, at most 4,096 characters, no NUL | required, nullable |
results[].mtime | integer, 0–2^53 − 1 | required, nullable |
results[].error | string, at most 32 characters | required, nullable |
results[].message | string, at most 4,096 characters | optional |
results_chunked | boolean | optional |
results_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
root | absolute path, at most 4,096 characters, no NUL | required |
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
| Field | Value | Presence |
|---|---|---|
root | absolute path, at most 4,096 characters, no NUL | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
names | list of at most 5,000 items of: string, 1–1,024 characters | required |
truncated | boolean | required |
names_chunked | boolean | optional |
names_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, or ~ / ~/… in the service's home, at most 4,096 characters | required |
hidden | boolean | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
entries | list of at most 5,000 items of: object (fields below) | required |
entries[].name | string, 1–1,024 characters | required |
entries[].symlink | boolean | required |
truncated | boolean | required |
entries_chunked | boolean | optional |
entries_bytes | integer, 0–2^53 − 1 | optional |
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
| Field | Value | Presence |
|---|---|---|
path | absolute path, or ~ / ~/… in the service's home, at most 4,096 characters | required |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
path | absolute path, at most 4,096 characters, no NUL | required |
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
| Field | Value | Presence |
|---|---|---|
when | string, one of cancel, idle, now | required |
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)
| Field | Value | Presence |
|---|---|---|
version | string, 1–64 characters | required |
protocol | integer, 0–65,535 | required |
ptys | integer, 0–2^31 − 1 | optional |
busy | integer, 0–2^31 − 1 | optional |
clients | integer, 0–2^31 − 1 | optional |
started | finite number | optional |
sandbox | string, at most 4,096 characters | optional |
live | string, at most 4,096 characters | optional |
pid | integer, 1–2^31 − 1 | optional |
gh | string, at most 32 characters | optional |
keeper | integer, 1–2^31 − 1 | optional |
unkept | integer, 0–2^31 − 1 | optional |
keeper_mismatch | integer, 0–2^31 − 1 | optional |
keeper_unread | boolean | optional |
keeper_held | integer, 0–2^31 − 1 | optional |
cli | string, at most 4,096 characters | optional |
home | absolute path, at most 4,096 characters, no NUL | optional |
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
| Field | Value | Presence |
|---|---|---|
path | string, at most 4,096 characters | optional |
Reply fields (on ok: true)
| Field | Value | Presence |
|---|---|---|
found | string, at most 4,096 characters | required |
detected | string, at most 4,096 characters | optional |
status | string, one of bad-name, missing, ok, version-managed, versioned | optional |
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.
| Builder | Arguments | Runs |
|---|---|---|
commit_argv | summary: string, body?: string | commit -q -m <summary> [-m <body>] |
fixup_argv | sha: string | commit -q -m "fixup! <sha>": the index as a fixup of a commit |
stage_all_argv | none | add -A |
unstage_all_argv | none | reset -q |
add_paths_argv | paths: list of string | add -A -- <paths> |
reset_paths_argv | paths: list of string | reset -q -- <paths> |
remove_paths_argv | paths: list of string | rm -q -- <paths> |
checkout_paths_argv | paths: list of string | checkout -q -- <paths> |
checkout_side_argv | side: string, paths: list of string | checkout -q --<side> -- <paths>, with side ours or theirs |
checkout_branch_argv | branch: string | checkout <branch> |
pull_argv | none | pull --no-edit |
apply_argv | cached: boolean, reverse: boolean, three_way?: boolean | apply --recount --unidiff-zero [--cached] [--reverse] [--3way] -, the patch in stdin |
revert_argv | sha: string, commit: boolean | revert --no-edit <sha> when commit is true, else revert --no-commit <sha> |
revert_quit_argv | none | revert --quit |
continue_argv | kind: string | <kind> --continue, with kind one of rebase, am, merge, cherry-pick, revert |
abort_argv | kind: string | <kind> --abort, the same kinds |
log_argv | range_args: list of string, limit: integer | log --no-decorate --format=%H%x00%h%x00%s%x1e -n <limit> <range_args> -- |
unpushed_argv | none | rev-list HEAD --not --remotes -- |
stack_walk_argv | lower: string or null, upper: string, limit: integer | rev-list --topo-order -n <limit> <lower>..<upper> -- |
commit_subject_argv | ref: string | log -1 --format=%s <ref>^{commit} -- |
commit_message_argv | ref: string | log -1 --format=%H%x00%an%x00%aI%x00%s%x00%b <ref>^{commit} -- |
resolve_commit_argv | ref: string | rev-parse --verify --quiet <ref>^{commit} |
rev_parse_argv | rev: string | rev-parse --verify --quiet <rev> |
head_abbrev_argv | none | rev-parse --short HEAD |
merge_base_argv | a: string, b: string | merge-base <a> <b> |
branch_tips_argv | none | for-each-ref --format=%(objectname) %(refname:short) refs/heads |
has_remote_tracking_argv | none | for-each-ref --count=1 --format=%(refname) refs/remotes/ |
status_argv | none | --no-optional-locks status --porcelain=v2 -z --untracked-files=all |
status_porcelain_argv | none | --no-optional-locks status --porcelain |
staged_paths_argv | none | diff --cached --name-only -z |
unmerged_stages_argv | path: string | ls-files -u -z -- <path> |
check_ignore_argv | none | --no-optional-locks check-ignore -z --stdin, the paths in stdin |
diff_argv | load: load, parent_target?: string, untracked?: boolean, pathspecs?: list of string, excludes?: list of string | diff --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_argv | load: load, parent_target?: string, pathspecs?: list of string | The same load with --numstat -z |
show_argv | ref: string, pathspecs?: list of string, excludes?: list of string | show --format= --no-ext-diff --find-renames --no-color <ref> -- <paths> |
untracked_diff_argv | path: string | diff --no-color --no-ext-diff --no-index -- /dev/null <path>: a new file as a diff |
conflict_diff_argv | paths: list of string | diff --no-ext-diff --find-renames --no-color --ours -- <paths> |
file_at_argv | ref: string, path: string | show <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.
| Key | Form | A client may write | Holds |
|---|---|---|---|
service_id | scalar | no | This service's id, as the hello reply names it. |
names | map | yes | Session id to the name a person gave it. |
generated_names | map | yes | Session id to its generated title. |
cli_titles | map | yes | Session id to the title the CLI gave it. |
emojis | map | yes | Session id to its tab emoji. |
favorites | set | yes | The favorite sessions' ids. |
archived | set | yes | The archived sessions' ids. store.archive is the way to change it. |
archived_at | map | yes | Session id to when it was archived, in seconds. |
archived_projects | set | yes | The archived projects. |
project_worktree | map | yes | Project to whether its new sessions start in a worktree. |
project_sandbox | map | yes | Project to whether its new sessions start sandboxed. |
sandboxed_sessions | map | yes | Session id to its sandbox's box id. |
sandbox_grants | map | yes | Box id to its directory grants. Use sandbox.allow and sandbox.revoke. |
sandbox_project_grants | map | yes | Project to the grants its new sessions start with. |
sandbox_tools | map | yes | Box id to the session tools it is offered. Use sandbox.tools. |
project_order | list | yes | The projects in sidebar order. store.move-project is the way to change it. |
virtual_projects | map | yes | Project name to its folder, for one kept with no sessions. |
expanded_groups | set | no | Sidebar groups once open. No longer written; a device keeps its own. |
session_prs | map | yes | Session id to its pull request records. |
session_attachments | map | yes | Session id to its attachment records. |
session_drafts | map | yes | Session id to its unsent prompt. |
new_chat_drafts | map | yes | Draft id to a new chat not started yet. |
process_baselines | map | yes | Session id to the processes that don't count as it being busy. |
session_forwards | map | yes | A session id to the id it continued under. |
pending_detaches | map | yes | Session id to a background handoff still to be replayed. |
resume_on_start | list | no | The sessions a stopping service ended, resumable when reopened. |
ptys | map | no | The pty table, by app id. |
pty_next_id | map | no | The next pty id, by app id. |
inflight_copies | list | no | The tree copies fs.paste has in flight. |
notifications | list | no | The notification history. Use the notify.* requests. |
diff_notes | map | no | Session id to the marks on its diff. Use diff.set-notes. |
pending_diffs | map | no | Session id to a show_diff asked for with no client attached. |
settings | map | yes | The 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.
| Setting | Value | What it does |
|---|---|---|
claude_cli_path | string | Where the CLI is when the service's PATH doesn't say. |
notify_command | string | A command run for a notification when no client is attached. |
title_model | string | The --model for generated session titles; empty is automatic. |
icon_model | string | The --model for generated project icons; empty is automatic. |
auto_renew_login | boolean | Repair an expired CLI login with one headless run. |
worktree_new_sessions | boolean | Start new sessions in a git worktree. |
clone_directory | string | Where a cloned repository goes by default. |
sandbox_new_sessions | boolean | Start new sessions sandboxed. |
sandbox_bypass_permissions | boolean | Sandboxed sessions default to bypassing permissions. |
sandbox_share_gh | boolean | Share the GitHub CLI login with sandboxed sessions. |
sandbox_share_ssh | boolean | Share the ssh agent with sandboxed sessions. |
sandbox_settings_editable | boolean | Let sandboxed sessions write the CLI's settings. |
attach_prompt_prs | boolean | Attach pull requests a session's first prompt links to. |
pr_title_sessions | boolean | Title a session after its newest pull request. |
cli_title_sessions | boolean | Show the titles the CLI gives its sessions. |
refresh_prs_on_launch | boolean | Refresh pull requests once when a client starts. |
archive_running_session | string | Archiving a session with a running tab: ask, exit or background. |
archive_worktree | string | A session's worktree on archive: ask, always or never. |
archive_on_claude_ai | boolean | Mirror archiving to the session's claude.ai page. |
auto_delete_archived_after | integer | Trash archived sessions after this many units; 0 is never. |
auto_delete_archived_unit | string | That unit: days, weeks, months or years. |
background_status_poll | boolean | Poll background agents' status on a timer as well. |
progress_termprop | boolean | Read busy from the CLI's own progress announcements. |
git_parent_branch | string | The branch a session's branch is measured against when none is found. |
git_untracked | boolean | Include untracked files in working-tree reviews. |
git_log_page | integer | Commits per page of a commit list. |
welcome_seen | boolean | The first-run welcome has been answered. |
gh_welcome_dismissed | boolean | The GitHub CLI notice has been dismissed for good. |
mcp_tool_<tool> | boolean | Whether sessions are offered this session tool. |
sandbox_tool_<tool> | boolean | Whether 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.