The console

The console is a full conversation with Clankie in your terminal. Ask for help, work on a project, configure his connections, or inspect an agent's progress. For the first installation, follow Get started; for models, skills, and worker setup, use Customize Clankie.

In local mode, clankie starts the service if needed and opens the console; in hosted mode it connects to your remote Clankie through the paired-device transport, with a smaller command set. First launch asks which. / opens command suggestions, Ctrl+/ the workbench. Any terminal works; Herdr is optional. This page describes the local console; the CLI is the headless equivalent.

Live agents

While agents are working, a one-line dock under the editor counts them by status and how many need a look. ↓ from an empty prompt expands it to the whole fleet, blocked or disconnected first, then working, done and idle; agents on another machine are labeled with it. Rows name only what needs a look; the Ctrl+G picker (see Keys) shows each agent's full detail and opens its conversation.

An agent's conversation shows its newest 20 turns and then follows live (clankie conversations show ID reads older ones). A bar above the transcript names who you are talking to, and the bar and input border take the harness color: yellow for Claude, blue for others. Messages go through the same native delivery as /agents, and drafts stay with their conversations. Escape returns to where you were without stopping the worker.

When a harness holds the conversation's seat (for example clankie claude), the footer names it, such as claude seat, in place of the model.

Slash commands

$ opens the skill picker, and /skill-name task runs a skill directly. A command typed bare opens its menu (/project, /access, /accounts, /devices, /machines, /minecraft, /update), and settings commands such as /autonomy, /awake, /browser, and /routing list each setting with its value. With arguments, a command runs the same code as the CLI. This table is generated from the console's command registry.

Keys

Workspaces

Starting clankie opens the existing main Clankie conversation regardless of the launch directory. Use --chat <conversationId> to select another retained conversation, /cd <path> to select a project, or /new [title] to create a fresh conversation in the current workspace. Tools run in the selected conversation's workspace, not the directory of the launching terminal (ADR 0111).

The console opens on a blank page under a "scroll up for earlier messages" divider; switching conversations starts at the latest messages. Older history loads in bounded pages when you scroll up, keeping the visible text in place. The live tail continues independently while those pages load.

/cd <path> moves to the newest retained conversation for another project, opening its first on first visit; /cd alone names the current one. The console's own ! shell escape, path completion, footer, and /status follow the same directory. The process keeps its selection in memory rather than persisting a second session pointer.

The service retains recent inactive conversation directories for explicit resume: at most 64 conversations, 30 days of inactivity, and 256 MiB. A conversation's public replay log retains at most 500 events. Active, newly created, and default-global conversations are protected from automatic removal.

The service stays up when a console exits, so sibling Herdr panes do not disconnect each other. Logs live under ${XDG_STATE_HOME:-~/.local/state}/clankie/ rather than entering the fullscreen display. State-home symlinks are supported when owned by the user and their targets are owned and not writable by others. Private capability and update directories remain owner-only; links in shared writable directories are refused.

Operator behavior

• Enter sends a prompt or steers Clankie's active Pi turn. Alt+Enter queues a separate follow-up after the current turn and any earlier queued prompts. The console keeps observing until all accepted inputs settle; Esc interrupts the current turn. Accepted local steers and follow-ups appear above the editor until their durable runs settle, with up to three previews and an overflow count. This view follows the active observation; switching rooms, detaching, or restarting clears it. The conversation log retains the messages. Acceptance is not execution: the service does not publish a separate dequeue event, so the preview says “awaiting completion.” These choices also apply to /skill-name prompts.
• Failed sends return the message to the editor, preserving any newer draft. A failure before sending says Message not sent. If the send loses its acknowledgement, Delivery unconfirmed asks you to check the conversation before retrying. Sends never retry automatically; an accepted turn's dropped observation reconnects without resending its message.
• /chats (aliases /chat, /conversation, /conversations) opens only personal and workspace chats with Clankie. /chats <name-or-path> switches directly.
• Live agents appear below the editor in a two-line dock with status counts and a selected-agent preview. Rows name the worker and its issue when available. Version skew and unverified catalogs are muted notes; "need a look" counts actionable failures, missing reports, stalled progress and unconfirmed hires. The picker explains each flag and how to clear it. Statuses use the shell colors and machines are dim. Ctrl+G opens a scrolling modal of every agent; Up/Down selects, and Enter opens the existing persona conversation. Escape returns without cancelling the worker; drafts stay with their conversation. Ctrl+Y opens that exact agent's pane in its full Herdr workspace, using the selected connection. It attaches only, or focuses without nesting when already inside the same session. The dock disappears when empty. Escape closes the modal; the selected agent's full name, harness, status, machine and distinct current step wrap below its list. Unavailable-agent errors show a readable message instead of Herdr's JSON.
• /agents opens the agents that are live now (a Herdr seat here or on a remote fleet). Offline agents that kept a thread sit behind one "Past agents" entry, newest first; offline agents without a thread are not listed, since there is nothing to open.
• /rooms opens group channels and Discord text/voice rooms. A Discord channel ID also selects its room with /rooms <id>.
• /history searches all retained threads, including agent threads. History includes ongoing threads; it does not mean archived, completed, or online. /history <conversationId> selects any retained thread directly.
• /sessions browses saved harness sessions on local or SSH hosts; these are execution records, distinct from agent identities. Existing /agents session arguments remain supported. See the product vocabulary. Discord rooms are read-only inspection views, with expandable context and tool arguments/results (Ctrl+O toggles tools). Their transport still owns input; typing in the inspector cannot send to Discord or grant operator authority. Press x to close an inactive operator conversation; active, default, and transport-owned room conversations stay protected. Switching rebuilds the transcript and follows its live tail. Linked machines use their native session readers, including Claude account profiles; terminal summaries are never used as chat history. An opened chat keeps a private display cache so an offline machine shows its last known transcript with an offline notice. Local chats show at most the last 9,000 entries. Linked-machine chats show the newest 500 records within a 4 MiB read; older history stays in the native transcript. The private cache holds at most 64 snapshots and 32 MiB in total, evicting the oldest snapshots. --chat <conversationId> opens the same record directly; clankie conversations list|show|tail exposes it as JSON.
• /new [title] starts and selects a conversation with fresh model context in the current workspace. The previous conversation remains available through /conversation.
• /btw [question] (alias /side) opens an ephemeral side conversation from the current Pi branch on a clean screen at the fork boundary. Its inherited history is reference-only. Ctrl+X switches between the fork and the main thread while both stay alive; Ctrl+C discards the fork and restores the main transcript. The footer names the open side conversation from either side.
• /question list shows Clankie's pending owner asks across source conversations. /question reads the selected source's immutable target; answer with /question answer NUMBER, /question text TEXT or /question worker JSON for native question-ID maps. /question cancel marks it moot. Cards show what waits, recommendation, steps and source; answers resolve everywhere and wake that source without granting credentials or changing room trust.
• /auto on uses the owner credential; the captain bearer receives HTTP 403. The headless equivalent is clankie auto on.
• /autonomy off|low|high|full sets the owner's autonomy dial, how much Clankie decides without asking (ADR 0263). /auto on|off is the master switch for unprompted work: projects on Auto and scheduled self-wakes (ADR 0264). /project lists projects under the Auto switch, each with its status line (agents working, landed today, needs you), and sets a project's Auto and focus. /autonomy clear removes the selected conversation's pending wake.
• /cd opens the conversation for another directory and moves the console's shell escape and completion with it.
• Type /skill-name for direct skill invocation or $ at a token boundary for the skill picker. The transcript records a compact skill loaded receipt.
• /activity shows the current goal, commentary, intent, observed outcome, and the loopback watch URL without controlling the body.
• /skills lists the skills shipped with Clankie. Every shipped skill is always on for sessions and local hires.
• /accounts codex list and /accounts claude list show discovered signed-in identities and their homes, matching usage and app Settings. Multiple homes with one identity produce one account. add HOME --label LABEL is an optional discovery override; remove LABEL forgets the override without changing sign-in. Re-signs produce one notice; saved choices stay with the original identity.
• /share [list | request JSON] controls owner-only local Activity artifact shares; see the CLI. Hosted launch/admission remains pending.
• /games opens a toggle dialog for PokeAgent play; press Enter to enable or disable it. /games on|off remains available for direct use. Restart Clankie to apply a change. Saves live with the world server, not here.
• /evaluator (developer diagnostic) opens a menu for the independent evaluator, whose footer badge reads evaluator on while enabled: turn it on or off, switch harness, open its Herdr pane, read recent assessments, retry failures. /evaluator status|enable --harness codex|claude|disable|open|retry ID still work.
• /browser record on|off saves each burst of Clankie's browsing as a WebM under ~/.clankie/runner/browser/recordings/; /browser shows the setting. It applies from his next burst, without a restart.
• /memory browses and edits episodes and permitted Discord person facts through operator-only APIs.
• /vt (aliases /voice-log, /voice-transcripts) opens a live overlay of retained Discord voice transcripts, including Clankie's generated wording labeled with playback outcome. Cut-off text may include an unheard ending. clankie discord transcripts reads the same page headlessly. Ctrl+Shift+V toggles the same view; Esc or /vt off closes it. Exact speech appears only when discord.voiceTranscriptLoggingEnabled is on (ADR 0121); otherwise the overlay points at /discord. This is not /trace: voice lanes there are captain handoffs, not the Discord conversation.
• /status renders clankie status, then adds console presence, conversation, workspace, model context, activity availability, and the Herdr pane roster. /doctor renders the full install report from clankie doctor --json.
• /awake [on|off] is clankie awake: the launcher's keep-awake while plugged in, with the Mac's current power state (always on).
• /herdr offers Use an existing Herdr session or Create a session for Clankie, followed by Restart now or Later. /herdr use NAME and /herdr create are the direct equivalents. Clankie’s own session tracks official stable Herdr releases; staged updates apply when its server next starts, preserving active workers and their matching CLI.
• /board, /board focus, and /board close manage the herdr-lead companion board. A seated turn receives the current agent census.
• /connect configures Linear and email and can open Discord setup. /discord connects a server with Participant or Admin, fleet display on/off and a tracking level. Its invitation requests the role's permissions and its checks flag missing grants. Server owners and room skills have common choices. Raw IDs, body diagnostics and individual grants stay under Advanced. Normal setup has no channel or Discord-role pickers. The explicit diagnostic CLI is clankie discord setup test-post --channel NAME.
• /setup is where a new owner starts, and the console opens it on its own while Clankie cannot take a turn: how he should think (subscription, API key, local model, or a provider already signed in), then which model. It continues to phone sign-in and pairing through /remote-access and /pair, offers /connect, then asks for the first agent's folder and task. Send the reviewed request to Clankie or edit it in the composer; he owns the native hire. Pairing completes only when an active phone with chat access is observed. Escape or /cancel pauses the flow; /setup reads the actual state on return. /setup rooms lists all optional rooms and opens their existing commands (ADR 0190).
• /auth writes provider keys and OAuth credentials to the credential broker. /auth status may also report compatibility provider environment fallbacks; Discord and body credentials remain broker-only except documented operator/captain test overrides.
• /voice selects OpenAI Realtime, Grok Voice, or OpenAI plus ElevenLabs and configures the active model, voice, xAI reasoning effort, and brokered API keys. /voice status shows the effective settings and environment overrides. eleven_v4_turbo opts into dialogue synthesis; unset keeps legacy Flash. Headless clankie voice status, voice model set MODEL_ID, and voice model clear inspect, select, or restore the default without restarting.
• YouTube music is an ordinary prompt, not a slash command. Audible playback is on the active Discord body's Vox primary-voice role; see the Discord media guide.
• /provider, /model, and /effort select the captain through the launcher command modules. The header carries the effective Pi model and effort after subscription routing, effective-ref variant precedence, and model-supported clamping. /image-model and /video-model select generation models. Non-secret model configuration lives in ~/.config/clankie/clankie.json.
• /provider → "add a local endpoint…" declares an OpenAI-compatible local runtime (ds4, Ollama, LM Studio, vLLM) by base URL, reads its model list from GET {baseURL}/models, and needs no credential. The service picks the new provider up on clankie restart captain. Agents and scripts use the same write path through clankie model add-local / clankie model set (JSON on stdout); do not edit clankie.json by hand. Full contract: docs/cli.md.
• /layout shows or hides the header banner. The main welcome uses only Clankie's head; agent chats omit the welcome block. Native lead turns use the same animated working indicator as service turns.
• /jump <pane|agent> focuses a herdr agent (herdr agent focus), and any pane id in the transcript — w18:p1J, wherever Clankie or a tool wrote it — is clickable for the same jump. Only a refusal reaches the transcript; a working jump moves the session, which says it better. /status lists the pane ids to aim at.
• ! on empty input opens the inline shell. Each tool call is one row: hovering highlights it, and clicking opens its full call and output beneath it. Alt+↑/Alt+↓ select a row from the keyboard and Enter opens or closes it. Ctrl+O opens or closes every tool row and bash block at once; clicking a bash block toggles just that one. Esc interrupts an in-flight turn: the service aborts Clankie's live model turn and the run settles as cancelled in the durable log. When the run cannot be cancelled (an older service, or it already settled) — or on a second Esc — the console detaches instead and the service continues the turn.
• clankie health reports operator credential source and env/store consistency without fingerprints or secret values. Remove an active CLANKIE_OPERATOR_TOKEN override before rotating the stored credential.

/discord edits each joined server’s Participant or Admin role, owners, fleet toggle, and a tracking level, and requests exactly that role's permissions. Setup marks proven missing permissions needs and unknown ones not checked. Admin controls its dedicated server except deleting it or transferring ownership. Raw Server owners and room skills have their own choices; raw IDs and individual grants live under Advanced. Opening or saving setup never posts.

Account connections

/connect accounts (or /connections → Accounts) shows each connected service's identity and permissions. Gmail and Calendar are read-only; Drive uses Google's file picker, and Clankie's tools only read the files you pick. Disconnecting any Google service disconnects all three and reports whether the provider revoked access. See account setup.

Follow Linear

Connecting Linear and following its activity are separate. /connect linear does both; bare /linear opens Follow Linear with its Wake rules and destination chats. Project activity goes to its configured lead chat, otherwise global-default with the project named. Notifications become read after the target chat confirms its wake. Queued activity follows current routes, with unavailable lead receivers falling back to global-default; a missing receiver gets one notice and waits quietly while its chat history stays intact. Default rules wake for signed comments and mentions from the owner emails in those rules, assignments or delegations to Clankie, and reactions on his comments. Other activity is visible without waking him. He can adjust the rules himself (linear_wake, clankie linear wake set). The Linear reference covers webhooks, status, and recovery.

Headless

Scripts use the CLI: most commands print JSON and exit 0 or 1, while pairing, device listing, and credential rotation print for people unless you pass --json. Secrets are only entered interactively (/auth, /discord, /connect, /voice) so tokens never become flags.