How Clankie works

Clankie lives in a persistent service on one machine: yours, or a private hosted one. The app, the terminal console, and Discord are ways to reach him. The service owns his conversations, memory, tools, and access, so closing a client loses nothing.

You can use him without knowing any of this. It helps when you want to customize him, connect a team, or know where your work goes.

One identity, many conversations

There is one Clankie. A chat in the app, a project in the console, and a Discord room each have their own history and permissions, but the same character. What is said in one room does not leak into another.

His built-in agent runs on pi, which handles models, sessions, tools, skills, and compaction. Clankie adds the lasting identity, memory, his connections, and the authority each caller brings.

Other harnesses can take his seat: clankie claude, clankie codex, clankie opencode, and clankie grok open that tool as Clankie, with his persona, memory, and tools, on a chat of their own or an existing one (seat commands). While a seat is open, worker reports and wakes for its chat go to it; when it closes, pi takes over again.

Requests from Discord text or voice run as their own visible threads under Clankie, several at once, and the answer returns to the room that asked.

History, memory, and projects

Memory recall is filtered by who is asking: private operator notes never reach a social Discord room. Auto rounds and self-wakes use the conversation's existing permissions. They flag ready work left unstaffed when seats and plan usage have room, and ask him to plan ready work when the queue is empty. Automatic project updates are on by default: noteworthy evidenced progress prompts a visual-first update, roughly daily, and milestones can report sooner. Each project can turn progress updates off through its settings (round record and settings). See memory.

Models, skills, and tools

A model reasons, a tool acts, and a skill explains how to approach a task. Choosing a model installs no browser, signs in to no account, and gives no Discord room a shell. Chat, images, video, and voice are configured separately; hosted availability is listed on clankie.bot.

A team around him

Work stays where you track it. Clankie and his workers share one Linear-shaped tracker. It uses the tracker you choose for all projects or one project, such as your connected Linear account or durable local storage; clankie doctor shows which. Built-in work carries evidence bundles that someone else checks, and owner questions and run approvals arrive in the same owner mailbox. You can mirror a Linear project into a scratch built-in store for inspection while Linear remains authoritative.

Herdr holds the agents. Workers run in their real terminals, which you can watch and type into. Clankie hires and messages Claude Code, Codex, Pi, OpenCode, and Grok Build through each harness's own channel, never by typing into the pane, and reports when delivery is uncertain. Agents on other machines join through an approved outbound connection. A joined install can open its own clankie claude seat in the home's workspace chat; identity, tools and memory stay with the one Clankie. It can resume or reset that folder’s lead, and that lead, or Clankie himself at workers access, can hire Claude or Codex workers there who report through the same joined connection. See the join command for current limits. Older remote workers use a fleet link. In Machines, the owner chooses portal, workers, shell or screen access. Ordinary self-hosted limits are service preferences. On an installed Mac, the owner can prepare an OS-bounded launch with a private home and approved workspaces; the running service reports verified enforcement. A new launch is needed to restore full access. Live activation remains owner-held. The adapter guide lists support and limits. Supported idle hired seats can restart fresh in the same pane after saving their handoff and work item; fleet status names any refusal (settings and safeguards).

Registered local owner checkouts follow main automatically while the service runs, preserving local edits and reporting anything that blocks advancement. New hires fetch main and advance a clean, unused checkout that is merely behind; dirty or divergent work stays protected. Saved sessions keep their directory.

Agents can also message Clankie and each other (message_clankie, message_peer). Those messages are agent output and carry no owner authority; /fleet can switch peer messages off. A busy-looking agent or a claim of "done" is something to check, not proof the work is finished.

In the app, agents appear in Messages, as figures in Commons, and as live panes in Terminal. In the console, /chats, /agents, /rooms, /history, and /sessions open each kind of thread (vocabulary, console).

A joined screen can provide Clankie's computer body, including for a hosted Clankie. The owner confirms each session locally and chooses observation or input. A visible pet offers Stop; access reduction and loss of consent stop queued input. The host supports bounded native input with exact receipts. Observer acknowledgments cannot prove queue drain, so Stop retains a post-input lease. Real Mac and Windows driving checks remain open.

Where the service and data live

Locally, the service keeps running after the console closes, as long as the Mac stays awake and online; by default a self-hosted Mac keeps itself awake while plugged in (clankie awake). Hosted, closing a client leaves his work running within the plan's limits. The accepted Premium lifecycle keeps presence and scheduled Auto rounds running across idle periods; its managed-service rollout is pending. Inference still uses AI credits.

The host keeps service state and credentials: Keychain on macOS, a private file store on Linux. Connected GitHub, Linear, and Google accounts are stored there too, and can be reviewed or disconnected from the app or console. Model requests go to whichever provider you chose, so running locally does not make every model call local. See credentials.

The app reaches the host through the public gateway, which relays encrypted exchanges it cannot read (it sees only routing metadata, sizes, and timing). A self-hosted Mac can also offer a direct route with no account. Either way the host issues pairings and enforces every device's grants (network, privacy).

An owner can open a support window of up to 72 hours. Read access shows history and state but cannot send, change settings, or see terminals; revoking it ends access immediately (clankie support).

For a self-hosted browser app, core and relay accept browser API calls only from the owner's exact origin allowlist, configured with clankie http. Preflight enables the browser transport; pairing and device grants still decide access. The self-hosted setup describes the setting.

Go deeper

The architecture is the canonical system diagram and request-flow reference, and the reference shelf leads to the CLI, API, and subsystem guides. Decision records explain how the design got here.