Tools and commands

The rib registers twenty-one tools, all prefixed chat_. Nine are for the operator or an orchestrating agent: five run swarms and four run the managed ClickClack server. Twelve work only inside a swarm agent’s turn: six for every agent, two for the lead, and four workflow tools for the lead of a swarm granted workflows. The rib registers no slash commands.

A tool failure is returned as an error result the caller can read. It never throws into the harness.

Operator tools

chat_swarm_start

Starts a swarm and returns at once with the swarm id and, when the host supports durable ops, a run id.

Input	Type	Default	Notes
task	string	required	1 to 8,000 characters.
project	string	none	A registered project’s id or name. Unknown fails the start.
work_tools	none | read | write	read	read grants Read, Grep, Glob, only when project is set. write reads too, and lets the lead spawn writers with their own worktree; it needs project, or the start is refused.
size	small | medium | large	medium	The preset the limits start from. The max_* inputs override single limits on top of it. See Limits and statuses.
max_agents	integer	5	1 to 12, lead included.
max_turns	integer	40	1 to 200, across the swarm.
max_turns_per_agent	integer	12	1 to 100. Turns each worker may take. The lead is bounded by max_turns only.
turn_timeout_s	integer	300	30 to 1,800. Seconds one agent turn may run.
max_minutes	integer	30	1 to 240. Wall clock for the whole swarm.
context	array	none	Task context items, below.
provider	string	host default	Serves every agent. An unregistered provider fails the start.
power	string	balanced	fast, balanced or deep. The provider’s model for that class, for every agent without a named model. It also sets the reasoning effort every turn asks for: low, medium or high. A model that refuses effort runs its turns without it.
effort	string	the power’s	none, low, medium, high or xhigh. The reasoning effort for every agent turn, overriding the power’s. A provider without effort support ignores it; a model that refuses it fails the turn.
model	string	the power’s model	Every agent, or the lead alone when worker_model is set.
worker_model	string	model	Workers only.
workflows	array	none	Catalog workflows the lead may start, each { name, isolated? }, at most 10. isolated defaults to true. Needs project. See Dispatch workflows.
factory	boolean	false	Factory mode: no turn or clock budget. The swarm runs while work lands and ends after a window of turns without any (15 small, 25 medium, 45 large), or at max_tokens. See Budgets and stopping.
max_tokens	number	by size	Ceiling on fresh tokens, 10,000 to 50,000,000: 150,000 small, 1,000,000 medium, 3,000,000 large by default; in factory mode 2,000,000, 3,000,000 and 6,000,000. See Budgets and stopping.
max_cost_usd	number	by size	Ceiling on list-price dollars, 0.1 to 5,000: $1 small, $10 medium, $60 large by default. Ignored on a host that does not price tokens.
lead_tools	string[]	none	Other ribs’ tools the lead holds, such as beads_ready or beads_close, at most 20. Each needs the operator’s crossRibGrants entry for the swarm rib; one without it is dropped from the lead’s turns.

Without provider, the host uses KEELSON_WORKFLOW_PROVIDER when it is set, and otherwise its first registered provider. Without model, that provider serves its own default model. The lead always runs model.

A context item:

Field	Type	Required	Notes
id	string	yes	Kebab-case, 1 to 40 characters, unique in the array.
kind	enum	yes	issue, pr, diff, review, checks, note.
title	string	yes	One line, 1 to 200 characters.
body	string	yes	1 to 60,000 characters, stored verbatim.
source_url	URL	no	http or https, up to 2,000 characters.
retrieved_at	datetime	no	ISO 8601 with an offset.
head_sha	string	for diff, review, checks	7 to 40 hex characters.
base_sha	string	no	7 to 40 hex characters.

At most 20 items and 300,000 body characters in total. Unknown fields are refused.

chat_swarm_status

Input	Type	Notes
swarm	string, optional	A swarm id. Omit to list every known swarm.

With an id, returns the summary: id, task, status, channelId, channelName, startedAt, endedAt, turnsUsed, limits, agents, size, sizeBase, provider, model, workerModel, power, effort, project, opId, clickclack (its URL and workspace), health (present only while something is wrong: socket drops, a ClickClack fault, lead failures, nudges, refused conclusions, or quietSince when the swarm went idle at an open gate), context (the item list without bodies), runs, activity, pace, messageCount, conclusion, draftConclusion, error, and rerunOf for a swarm started with Retry or Go deeper. draftConclusion is the lead’s last refused conclusion, present only when no conclusion landed. Each agent carries the model it asks for and the provider that served its last turn, the tokens its turns spent, as the provider reported them, and when it joined. usage sums them for the swarm. Each activity entry carries its time, text, kind (such as turn, spawn, ask, gate or conclusion), the actor (an agent id, or operator) and what it is about; a turn is one entry, written when it ends. messageCount counts every ingested channel message. The per-turn spans and recent message buffer the Swarms tab draws from are left out of status tools and the durable op record. The buffer keeps the newest 20 messages and their first 200 characters; Conversation shows the newest eight. Its optional MessageKind is "ask" | "run" | "conclusion": quiet run and gate bookkeeping posts use run. report is reserved for the lead’s published report and omitted because chat_report never posts to the channel. Without an id, returns a short row per swarm, starting swarms first, with its size, model, and tokens. The last 50 ended swarms are kept in the rib’s data directory, so they survive a restart.

chat_swarm_wait

Input	Type	Default	Notes
swarm	string	required	A swarm id.
timeout_s	integer	120	1 to 600.

Blocks until the swarm ends or the timeout passes. The result begins with RUNNING or ENDED, followed by the summary. Built for workflows; from chat, poll chat_swarm_status.

chat_swarm_stop

Input	Type	Notes
swarm	string	A running swarm’s id.

Aborts turns in flight, revokes every agent’s bot token, and ends the swarm as stopped.

chat_swarm_forget

Input	Type	Default	Notes
swarm	string	none	One ended swarm’s id.
older_than_days	number	none	Every ended swarm that ended more than this many days ago. 0 forgets every ended swarm.
confirm	boolean	false	Without it, the tool reports what it would forget.

Pass exactly one of swarm or older_than_days. Drops the swarms from the Swarms tab, chat_swarm_status, and the rib’s history, with their launches and reports. A live swarm is refused. Each channel’s transcript stays in ClickClack; chat_server_reset wipes those too.

chat_swarm_transcript

Input	Type	Default	Notes
swarm	string	required	A swarm id, running or ended.
thread	string	none	A thread’s root message id. Omit to read the whole channel.
tail	number	none	Only the last this many messages (1 to 200), in order.
offset	integer	0	Character offset to continue a long transcript from.

Reads a swarm’s channel as the operator: every message in order, thread replies included, or one thread. The result is headed by the channel, the message count, and the character range shown, and pages by 40,000 characters; call again with the offset it names. It answers for any swarm chat_swarm_status knows. It never starts a stopped managed server, and refuses a thread outside the swarm’s channel. Swarm agents do not hold it.

Generic run tools

The run id from chat_swarm_start works with the harness’s run_status, run_events, run_cancel, and run_steer. run_cancel stops the swarm the way chat_swarm_stop does, and leaves the run cancelled with no summary. run_steer posts its note in the channel as the operator.

Server tools

These act on the ClickClack server when the rib manages it. chat_server_status answers in either mode. The other three refuse when the server is external, and swarm agents can call none of them.

Tool	Inputs	Does
chat_server_status	none	Returns mode (managed or external), url, liveSwarms, and for a managed server running, pid, adopted, operator (started by hand), binary, and dataDir. Starts nothing.
chat_server_start	none	Starts the managed server, or confirms it is running. Returns the URL and the web UI address, <url>/app. A swarm starts the server on demand, so this is for opening the UI first.
chat_server_stop	none	Stops the managed server. Channels and transcripts stay on disk and return with the next start.
chat_server_reset	confirm?	Stops the server, deletes its data directory, and starts it empty. Without confirm: true it reports what it would delete and deletes nothing.

chat_server_stop and chat_server_reset refuse while a swarm is running or still starting. A reset deletes every channel, transcript, bot, and session, and it can’t be undone. It also clears the ended swarms chat_swarm_status lists, because their channels are gone.

Agent tools

These refuse any caller that is not inside a swarm turn. The calling agent is read from the turn context the engine sets, never from input.

Tool	Inputs	Does
chat_post	body	Writes a top-level message. Wakes no one without a mention.
chat_reply	message_id, body	Answers in the thread of any message id. Wakes the thread’s starter, or every agent in the thread when the starter replies. See Routing.
chat_read	thread_id?, limit?	Reads the channel’s latest messages, or one thread. limit defaults to 20, at most 50.
chat_roster	none	Lists agents with handle, role, turns, and status.
chat_context	id?, offset?	With no id, lists the context items. With one, returns the body under an attribution header, 20,000 characters per page.
chat_spawn	handle, role, brief, writes?	Adds a worker and posts the brief as a mention. Fails at the agent cap. writes: true is for the lead of a write swarm: the worker gets its own worktree and branch, and Edit, Write, and Bash there.
chat_done	summary	Lead only. Concludes the swarm. Posts the conclusion to the channel in parts of at most 8,000 characters.
chat_pr_open	title, body	Origin-backed writers only. Pushes the writer’s branch and opens a draft pull request against the default branch. Refuses local writers with a message naming chat_merge, uncommitted changes, and AI attribution in any commit, the title, or the body. A second call pushes again and returns the open pull request. Never merges.
chat_diff	writer, offset?	Any agent of a write swarm. A writer’s commits, uncommitted files, and diff against origin/<default> or refs/heads/<base>, paged by 40,000 characters. Local results include the full head SHA.
chat_merge	writer, head_sha	Local write lead only. Merges a settled writer’s peer-reviewed full 40- or 64-character hexadecimal SHA into the captured local base with --no-ff. Refuses dirty checkouts, changed heads, and AI attribution; aborts conflicts and returns their paths.
chat_report	title, html	Lead only. Publishes the swarm’s report, a designed HTML page the Swarms tab opens. Calling it again replaces it.

A message body and a brief are 1 to 8,000 characters, and summary 1 to 20,000. chat_pr_open takes a title of 1 to 200 characters and a pull request body of 1 to 20,000. A value over its limit is refused with its length and how many characters to cut. A refused summary is kept, and a swarm that ends without a conclusion carries it as draftConclusion. handle is up to 20 characters and is normalized to kebab-case and prefixed with the swarm id. role is up to 200 characters.

chat_reply and chat_read refuse a message or thread outside the swarm’s own channel.

chat_merge accepts only writer and head_sha, not a path, base, or message. Mode is decided once at boot: only git remote listing no origin enables local merges. The base is the root’s symbolic HEAD branch, resolved to its current tip for each new writer without fetching. The lead waits for writer settlement and read-only peer review. Root and writer must be clean, on their recorded branches, with the writer still at the reviewed head and no existing merge/rebase. Incoming AI-attributed commits are refused before mutation. The root queue runs git merge --no-ff --no-edit --no-autostash with the message Merge writer @<handle> branch <branch> into <base> and reviewed SHA. On conflict it lists paths, runs git merge --abort, and returns those paths; writer-local repair, checks, and new review are required before retrying. Git errors are surfaced. Local mode never fetches, pushes, calls gh, or changes remotes. Successful merges are ordinary activity lines, not PR or CI evidence. Cleanup keeps unmerged writers with reason “not merged into ”.

chat_report takes a title of up to 80 characters and an html body of up to 512 KB. It follows the contract of Keelson’s canvas_publish: inline CSS and script only, the system font stack, colors as CSS custom properties with a :root[data-theme="light"] override. A categorical palette declared on <body> as data-palette-dark and data-palette-light is checked for color-vision separation and contrast. An external script or stylesheet, or a failing palette, is refused with the reason. The lead also holds Keelson’s canvas_design_guide to read the design rules first.

Workflow tools

The lead of a swarm started with workflows also holds these. Workers never do.

Tool	Inputs	Does
chat_workflow_start	workflow, purpose, inputs?	Starts a granted workflow on the project and tracks the run. Returns the run id.
chat_workflow_status	run_id?	Lists the swarm’s runs, or one: status, the gate it waits on and those answered, branch, pull requests, isolation, CI verdict, and verified.
chat_workflow_cancel	run_id	Cancels a live run the swarm started.
chat_workflow_respond	run_id, decision, review, reason, feedback?	Answers a paused run’s approval gate for the operator. decision is approve or changes, and changes needs feedback, the change the run applies. review is the id of a message another agent or the operator wrote after the gate opened. Held only when Keelson lets the rib answer gates.

chat_done is refused while any run is live.

Related

• Agents and swarms: the tool boundary.
• Dispatch workflows: the workflow tools in use.
• Supply task context: the context input in use.
• Limits and statuses: the status and limits fields.