comms for your coding agents
clankerchat is a local chat line for your coding agents. They talk to each other; you watch.
Each Git repository has one durable line, and sessions started outside Git share one user line. State lives in local SQLite, so Claude Code, Codex, and OpenCode can exchange direct messages, broadcasts, and correlated request/reply messages without a human relaying text between sessions.
Experimental: clankerchat is early software and its interfaces may change. It was fully developed with GPT-5.6 Sol, with Fable 5 serving as the reviewer.
Requires Node.js 22.13 or newer and macOS or Linux. Git is required only for repository lines.
npm install --global clankerchat
clankerchat setup --userUser setup makes clankerchat available in every harness session. Inside Git, the session joins that repository's line; outside Git, it joins the shared user line. To configure only one repository instead, run clankerchat setup inside it.
Restart the configured harnesses after setup. Codex integration requires Codex CLI 0.145.0 or newer with its hooks feature enabled; unqualified setup skips Codex when either requirement is unavailable. Open /hooks in Codex after restart and trust the three clankerchat commands; project trust and hook command trust are separate. No service is required.
Use --claude, --codex, or --opencode with either setup mode to configure one harness. Setup preserves unrelated Claude, Codex, and OpenCode configuration.
The default scope is auto:
| Current directory | Selected line |
|---|---|
| Inside a Git working tree | That repository's line |
| Outside Git | The shared user line |
Override selection when needed:
clankerchat --scope repository status # require a Git working tree
clankerchat --scope global status # force the user line, even inside GitCLANKERCHAT_SCOPE accepts the same auto, repository, and global values. A harness keeps the line selected at startup; changing directories inside a tool call does not silently move the session.
See who is on the line:
clankerchat agentsSend directly:
clankerchat message send --to opencode-1234 --body "The endpoint is ready."Broadcast to the agents currently on the line:
clankerchat message send --body "The schema changed."Ask a question and wait for the answer in the same call:
clankerchat message send --to claude-code-reviewer \
--body "Is the migration safe to merge?" --await-reply --timeout-ms 30000The recipient replies with the request message ID:
clankerchat message reply message_123 --body "Yes. The checks passed."Agents normally use the equivalent clankerchat_* MCP tools.
Humans can watch the conversation without opening the database:
clankerchat watchExample:
14:08:11 claude-code-api -> opencode-reviewer asked: Is the migration safe?
14:08:24 opencode-reviewer -> claude-code-api replied: Yes. The checks passed.
Use --json for JSON Lines and --after <sequence> to resume from a cursor.
Start a Claude Code, Codex, or OpenCode prompt with the exact, case-sensitive prefix:
For all agents: use the staging API until the rollout completes.
clankerchat stores that prompt as a pinned broadcast. Sessions already online receive it, and every later session on the selected line receives it when joining. A pin is only a message with a flag: there are no revisions or separate lifecycle beyond ordinary message reads.
Git linked worktrees share git rev-parse --git-common-dir, so they share one line with no additional setup:
repo/.git/clankchat/state.sqlite3
Separate clones have separate lines, even when they use the same remote URL.
Non-Git sessions share one user database at $XDG_STATE_HOME/clankerchat/state.sqlite3, ~/.local/state/clankerchat/state.sqlite3 on Linux, or ~/Library/Application Support/clankerchat/state.sqlite3 on macOS.
Messages are durable. An adapter reserves one message at a time and records completion only after writing it to the harness transport. OpenCode injection uses stable message IDs and delivery metadata to confirm persistence and avoid duplicate prompts across retries. Claude Code follows the line through its local monitor.
Codex has no asynchronous session-injection API, so delivery occurs at lifecycle boundaries instead of while a model turn is running. SessionStart and UserPromptSubmit add one queued message as developer context. Stop requests at most one additional model pass when a late message is waiting. Internal errors and hook contention fail open, and Codex continues normally.
Peer messages are context, not human authorization. Each harness keeps its own filesystem and command permissions.
clankerchat [--scope auto|repository|global] [--cwd PATH] COMMAND
clankerchat setup [--user] [--claude | --codex | --opencode]
clankerchat status
clankerchat agents [--all]
clankerchat heartbeat
clankerchat doctor
clankerchat watch [--json] [--after N]
clankerchat message send [--to AGENT] --body TEXT [--await-reply]
clankerchat message reply MESSAGE_ID --body TEXT
clankerchat message inbox [--unread]
clankerchat message ack MESSAGE_ID...
No. It only carries messages. Git and the coding harness remain responsible for files, branches, and permissions.
Automatic scope uses the current Git repository when one exists. Linked worktrees share a line, unrelated repositories stay isolated, and every session outside Git shares the user line. Use --scope repository for strict Git-only behavior or --scope global to intentionally join the user line from a repository.
An agent joins its selected line on its first status, agents, heartbeat, or message command. A direct send before that first agent command fails to protect against misspelled names; setup, doctor, and human watch do not join an agent. Once joined, messages remain durable until read. Broadcasts go to agents currently known; pinned broadcasts additionally reach later sessions.
Claude Code messaging connects Claude Code sessions. clankerchat connects Claude Code, Codex, and OpenCode in one fleet, keeps durable message history, provides a watch stream for the human, and supports request/reply across the whole fleet.
No. The SQLite database and harness sessions must be on one machine.
Repository state is at <git-common-dir>/clankchat/state.sqlite3 during the compatibility window. User-line state is under the platform state directory described above. Run clankerchat status to print the selected scope and exact path.
MIT