claudelink 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +477 -343
  2. package/dist/cli.js +391 -83
  3. package/dist/cli.js.map +1 -1
  4. package/dist/db.d.ts +1 -0
  5. package/dist/db.js +6 -0
  6. package/dist/db.js.map +1 -1
  7. package/dist/ui-server.js +70 -2
  8. package/dist/ui-server.js.map +1 -1
  9. package/package.json +1 -1
package/README.md CHANGED
@@ -1,480 +1,603 @@
1
1
  # ClaudeLink
2
2
 
3
- **The hub where your AI agents connect.**
3
+ > **The autonomous command center for AI coding agents — any model, any provider.** Run a swarm of Claude Code, Codex CLI, Gemini CLI, and Goose agents across multiple terminals, with the underlying LLM chosen freely from **hundreds of models** spanning Anthropic, OpenAI, Google, xAI, Mistral, OpenRouter, Ollama (local), Bedrock, Vertex AI, and more. They message each other, you watch the whole mesh live, and they keep collaborating when you walk away. **No cloud. No telemetry. No account.** It all runs on your machine.
4
4
 
5
- ClaudeLink lets multiple Claude Code instances running in separate terminals communicate with each other in real time. Open four terminals, give each agent a role, and watch them collaborate — sending messages, sharing findings, and coordinating work through a shared bulletin board.
5
+ [![npm version](https://img.shields.io/npm/v/claudelink.svg?style=flat-square&color=6366f1)](https://www.npmjs.com/package/claudelink)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-10b981.svg?style=flat-square)](LICENSE)
7
+ [![Node](https://img.shields.io/badge/node-%3E%3D18-3b82f6.svg?style=flat-square)](https://nodejs.org)
8
+ [![Multi-CLI](https://img.shields.io/badge/CLIs-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Goose-a855f7.svg?style=flat-square)](#compatible-ai-clients)
9
+ [![MCP](https://img.shields.io/badge/Protocol-MCP-f59e0b.svg?style=flat-square)](https://modelcontextprotocol.io/)
10
+ [![Local-first](https://img.shields.io/badge/Local--First-no%20cloud-22c55e.svg?style=flat-square)](#local-first-security)
6
11
 
7
- ```
8
- Terminal 1 (reviewer) ──┐
9
- Terminal 2 (developer) ──┤── ClaudeLink ── SQLite
10
- Terminal 3 (tester) ──┤
11
- Terminal 4 (ops) ──┘
12
- ```
12
+ ClaudeLink is an open-source [MCP](https://modelcontextprotocol.io/) server that turns multiple AI coding agents — Claude Code, OpenAI Codex CLI, Google Gemini CLI, Block's Goose, or any MCP-compatible client — into a **single coordinated team**. Open four terminals, give each one a role, and they share a real-time message bus, a bulletin board, and a closed-loop autonomous pipeline that keeps them working together when you step away.
13
+
14
+ **The name says "Claude" but ClaudeLink is model-agnostic.** Each CLI you plug in chooses its own backing model — and through Goose alone you can wire any of **25+ LLM providers**, putting hundreds of models within reach of the same mesh. A Claude reviewer talking to a Codex developer talking to a Gemini tester talking to a Llama-via-Ollama deep-thinker is a fully supported pattern. The mesh doesn't care; the LLM is somebody else's problem.
13
15
 
14
- A local **Command Center** at `http://127.0.0.1:7878` opens automatically with the first agent — see who's online, watch messages flow, and kill stuck servers without touching the terminal.
16
+ You don't need to invent a multi-agent framework. You already have one.
15
17
 
16
18
  ![ClaudeLink Command Center](docs/assets/command-center.png)
17
19
 
18
- ## Quick Start
20
+ ---
19
21
 
20
- ```bash
21
- # Install and configure (one command)
22
- npx claudelink init
23
- ```
22
+ ## Why ClaudeLink exists
24
23
 
25
- Restart your Claude Code terminals. That's it.
24
+ A single AI coding agent is fast. Five agents running in parallel — each owning a slice of the work, talking to each other, escalating, reviewing, retrying — is a different category of tool entirely.
26
25
 
27
- ### In Terminal 1:
28
- > "Register as a code reviewer working on the auth module"
26
+ The blocker has always been the human in the loop: someone has to type *"check messages"* into every terminal. ClaudeLink removes that human. The result is a hands-free, low-overhead AI development team that runs on hardware you already own, with the agentic CLIs you already pay for.
29
27
 
30
- ### In Terminal 2:
31
- > "Register as a developer. Check inbox for messages from the reviewer."
28
+ | Without ClaudeLink | With ClaudeLink |
29
+ |---|---|
30
+ | One agent per task | A coordinated swarm — reviewer, developer, tester, ops |
31
+ | One model per task | Mix Claude, Codex, Gemini, Goose freely on the same mesh |
32
+ | You shuttle messages by hand | Agents message each other directly |
33
+ | You poll every terminal for updates | Auto-nudge wakes the right agent at the right time |
34
+ | No single view of the work | Live Command Center at `127.0.0.1:7878` |
35
+ | Every session is amnesiac to the others | Shared SQLite mesh + persistent bulletin board |
32
36
 
33
- ### Terminal 1 says to Claude:
34
- > "Send a message to the developer: Found a SQL injection vulnerability in auth.ts line 42. The user input is not sanitized before the query."
37
+ If one agent already gives you a 2× lift, a coordinated heterogeneous team can get you to **3–5×** without adding a second subscription you don't already own, a second machine, or a second human.
35
38
 
36
- ### Terminal 2 says to Claude:
37
- > "Read my inbox"
39
+ ---
38
40
 
39
- The developer agent receives the reviewer's message and can act on it.
41
+ ## Compatible AI clients
40
42
 
41
- ## Installation
43
+ ClaudeLink works with any MCP-compatible coding CLI. Today, four are first-class with one-command install:
42
44
 
43
- ### Step 1: Install the package
44
- ```bash
45
- npm install -g claudelink
46
- ```
45
+ | CLI | Vendor | Models it can run | Install |
46
+ |---|---|---|---|
47
+ | **[Claude Code](https://claude.com/claude-code)** | Anthropic | Claude (Opus, Sonnet, Haiku) | `claudelink init --claude --global` |
48
+ | **[Codex CLI](https://developers.openai.com/codex/cli)** | OpenAI | GPT-5 family, GPT-4-class | `claudelink init --codex --global` |
49
+ | **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Google | Gemini 2.5 Pro / Flash family | `claudelink init --gemini --global` |
50
+ | **[Goose](https://github.com/aaif-goose/goose)** | Block / AAIF | **25+ providers** — any model behind any of them (see below) | `claudelink init --goose --global` |
47
51
 
48
- ### Step 2: Add to Claude Code (pick one)
52
+ Or set up all four in one shot:
49
53
 
50
- **Global (recommended — works in every project):**
51
54
  ```bash
52
- claude mcp add --scope user claudelink -- claudelink-server
55
+ claudelink init --all --global
53
56
  ```
54
- This adds ClaudeLink to `~/.claude.json` so it's available in every Claude Code session, in every project. One command, done forever.
55
57
 
56
- **Per-Project (only this project):**
57
- ```bash
58
- cd your-project
59
- npx claudelink init
60
- ```
61
- This adds ClaudeLink to `.mcp.json` in your project directory only.
58
+ ### Model reach (especially through Goose)
62
59
 
63
- ### Step 3: Restart Claude Code
60
+ A single Goose terminal in your mesh can speak to whatever provider you point it at. That's a lot of models — from a single mesh:
64
61
 
65
- Close and reopen Claude Code in your terminals. ClaudeLink tools will be available automatically.
62
+ - **Frontier providers**: Anthropic Claude, OpenAI GPT, Google Gemini, xAI Grok, Mistral
63
+ - **Cloud platforms**: AWS Bedrock, GCP Vertex AI, Azure OpenAI, Databricks, Snowflake
64
+ - **Aggregators**: [OpenRouter](https://openrouter.ai/) — hundreds of models from one API key
65
+ - **Local / offline**: [Ollama](https://ollama.com/), Ramalama, Docker Model Runner — thousands of open-weight model variants running on your hardware
66
+ - **Inference-only**: Groq for blazing-fast token rates
66
67
 
67
- ### Requirements
68
- - Node.js 18+
69
- - Claude Code CLI
68
+ This means **ClaudeLink isn't really "Claude" anymore** — it's the coordination plane, and the model space below it is essentially open. Want a Llama-3 reviewer running locally via Ollama, a Claude Sonnet implementer for hard reasoning, and a Groq-powered Llama for fast scaffolding? Spin up three Goose terminals (or a Goose + a Claude Code + a Codex), hand each one its role, and they share the same SQLite mesh. Pick the model for the job, on a per-agent basis, with no ClaudeLink-side configuration.
70
69
 
71
- ## How It Works
70
+ > **What's the catch?** The auto-nudge layer that types `check for updates` into a terminal needs the CLI to be running in iTerm2 or tmux on macOS / Linux. Apple Terminal isn't supported (Accessibility permission we don't want to silently ask for). MCP messaging itself works regardless of terminal.
72
71
 
73
- ClaudeLink is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server. Each Claude Code instance connects to it automatically and gets access to communication tools. All instances share a single SQLite database (`~/.claudelink/nexus.db`) using WAL mode for safe concurrent access.
72
+ Beyond the four flagged CLIs, **any MCP-compatible client can join** — point its MCP config at `claudelink-server`, add a copy of the multi-agent instructions to its project-instructions file. Roll your own and want a `--<your-cli>` flag? Open a PR with the install path; it's roughly an hour of work to add one.
74
73
 
75
- There is no daemon or background service. Each Claude Code session spawns its own MCP server process, and they coordinate through the shared database.
74
+ ---
76
75
 
77
- ## Command Center
76
+ ## Heterogeneous workflows
78
77
 
79
- The Command Center is a local web UI at `http://127.0.0.1:7878` that gives you a live view of every agent in the mesh. The first `claudelink-server` to boot in any terminal launches it automatically — subsequent agents share the same window. It survives MCP restarts and only exits when you click **Quit UI** (or run `claudelink ui --stop`).
78
+ Why mix models? Because each one is good at different things, and ClaudeLink lets you put each on the task it shines at.
80
79
 
81
- ### What it shows
80
+ | Pattern | Recipe |
81
+ |---|---|
82
+ | **Reviewer + Developer + Tester** | Claude advises, Codex implements, Gemini stress-tests. The advisor catches what the implementer rationalizes; the tester catches what both miss. |
83
+ | **Cost-optimized swarm** | Use a faster, cheaper agent for boilerplate (Codex, Goose), reserve the bigger model (Claude Opus, Gemini 2.5) for the few terminals doing hard reasoning. |
84
+ | **Cross-checker** | Run two implementations of the same feature on two different agents, then have a third agent diff their outputs and flag inconsistencies. |
85
+ | **Audit / discovery** | Goose for system inspection, Claude for narrative summary, Codex for surfacing edge cases. They post their findings to the bulletin board and you read one consolidated thread. |
82
86
 
83
- - **Running servers** — every `claudelink-server` process, with PID, TTY, uptime, and the role it registered as. Per-row **Kill** button sends SIGTERM.
84
- - **Registered agents** — role, description, online status, message counts (sent / received), and last-seen timestamp. Per-row **Kill agent** SIGTERMs the matching server.
85
- - **Health** — total agents, unread/total messages, bulletin entries, orphan blockers, FK violations, and servers running. The **Heal orphans** button cascade-cleans every dead agent's messages and bulletin rows in one transaction.
86
- - **Recent messages** — the last several messages across all agents, with unread and priority badges.
87
+ The Command Center shows them all as peers in the same mesh — agent role, sent/received counts, last-seen, auto-reply state. It doesn't matter which CLI is on the other end of an MCP connection.
87
88
 
88
- The page auto-refreshes every 2 seconds. **Kill all servers** in the header drops the whole mesh in one click.
89
+ ---
89
90
 
90
- ### Lifecycle
91
+ ## End-to-end flow
92
+
93
+ ```mermaid
94
+ sequenceDiagram
95
+ autonumber
96
+ participant A as Agent A<br/>(Reviewer)
97
+ participant DB as SQLite Mesh<br/>nexus.db (WAL)
98
+ participant SCH as Auto-nudge<br/>Scheduler
99
+ participant TERM as Agent B's<br/>Terminal
100
+ participant HOOK as UserPromptSubmit<br/>Hook
101
+ participant B as Agent B<br/>(Developer)
102
+
103
+ A->>DB: send(to:"developer", msg)
104
+ Note over DB: row written, read=0
105
+ rect rgb(30, 41, 59)
106
+ Note over SCH,B: every N minutes, fully autonomous
107
+ SCH->>DB: SELECT agents WITH unread mail
108
+ DB-->>SCH: Agent B has 1 unread
109
+ SCH->>TERM: tmux send-keys "check for updates"
110
+ TERM->>HOOK: prompt submitted (trusted path)
111
+ HOOK->>DB: peek unread
112
+ DB-->>HOOK: 1 message
113
+ HOOK-->>B: additionalContext: "you have 1 unread"
114
+ B->>DB: read_inbox()
115
+ DB-->>B: message from A
116
+ B->>B: decide & act
117
+ B->>DB: send(to:"reviewer", reply)
118
+ end
119
+ ```
120
+
121
+ This is the loop that makes ClaudeLink a command center instead of a messaging library. The keystroke is indistinguishable from you typing by hand — so it cleanly sidesteps the prompt-injection defenses that Claude Code (and other safety-conscious CLIs) ship with, without any unsafe shortcuts. You set the cadence. You set who participates. The agents run themselves.
91
122
 
92
- A lock file at `~/.claudelink/ui.lock` prevents duplicate windows. The launcher detached-spawns the UI process with `unref()` so it outlives the MCP parent. If a stale lock is detected (PID dead and no heartbeat at `/api/heartbeat`), a fresh UI takes over.
123
+ ---
93
124
 
94
- To opt out, set `CLAUDELINK_UI=off` in the environment before starting Claude Code.
125
+ ## System architecture
126
+
127
+ ```mermaid
128
+ graph TB
129
+ subgraph TERMINALS["Your Terminals"]
130
+ direction LR
131
+ T1["💬 Reviewer"]
132
+ T2["⚙️ Developer"]
133
+ T3["🧪 Tester"]
134
+ T4["🏛️ Architect"]
135
+ end
136
+
137
+ subgraph MCP["MCP Layer · one process per agent"]
138
+ direction LR
139
+ S1["claudelink-server"]
140
+ S2["claudelink-server"]
141
+ S3["claudelink-server"]
142
+ S4["claudelink-server"]
143
+ end
144
+
145
+ DB[("📦 SQLite (WAL)<br/>~/.claudelink/nexus.db<br/><br/>agents · messages · bulletin")]
146
+
147
+ subgraph CC["🎛️ Command Center · 127.0.0.1:7878"]
148
+ direction TB
149
+ UI["Live Web UI<br/>(2s refresh)"]
150
+ SCH["⏱️ Auto-nudge<br/>Scheduler"]
151
+ NOTIF["🔔 Desktop<br/>Notifier"]
152
+ end
153
+
154
+ T1 -.stdio.-> S1
155
+ T2 -.stdio.-> S2
156
+ T3 -.stdio.-> S3
157
+ T4 -.stdio.-> S4
158
+
159
+ S1 --> DB
160
+ S2 --> DB
161
+ S3 --> DB
162
+ S4 --> DB
163
+
164
+ DB --> UI
165
+ DB --> SCH
166
+ DB --> NOTIF
167
+
168
+ SCH -. keystroke .-> T1
169
+ SCH -. keystroke .-> T2
170
+ SCH -. keystroke .-> T3
171
+ SCH -. keystroke .-> T4
172
+ ```
173
+
174
+ No daemon. No background service. Each agent session (Claude Code, Codex, Gemini, Goose) spawns its own short-lived `claudelink-server` MCP process, and they coordinate through a single SQLite database in WAL mode — safe, concurrent, crash-resilient. The Command Center launches automatically with the first agent and persists across MCP restarts.
95
175
 
96
- ```bash
97
- claudelink ui # start it manually (or just spawn any agent)
98
- claudelink ui --stop # graceful shutdown
176
+ ---
177
+
178
+ ## Agent lifecycle
179
+
180
+ ```mermaid
181
+ stateDiagram-v2
182
+ [*] --> Registering: claude opens
183
+ Registering --> Idle: register(role)
184
+ Idle --> HasUnread: message arrives
185
+ HasUnread --> Nudged: scheduler tick (auto-reply ON)
186
+ HasUnread --> NotifyOnly: scheduler tick (auto-reply OFF)
187
+ NotifyOnly --> Idle: desktop notification fires
188
+ Nudged --> Reading: keystroke triggers hook
189
+ Reading --> Acting: read_inbox returns
190
+ Acting --> Idle: reply sent
191
+ Acting --> HasUnread: more unread queued
192
+ Idle --> [*]: terminal closes
99
193
  ```
100
194
 
101
- ## Available Tools
195
+ Every agent has a per-row **Auto-reply toggle** in the Command Center. Flip it any time. Useful for advisor / strategy terminals you want quiet, or to put your morning standup on auto-pilot then quiet it again while you think.
102
196
 
103
- Once connected, Claude Code gains these tools:
197
+ ---
104
198
 
105
- ### `register`
106
- Register this agent with a role so others can find it.
107
- ```
108
- "Register as a developer working on the payment system"
109
- ```
199
+ ## Keystroke dispatch
110
200
 
111
- ### `send`
112
- Send a direct message to an agent by role.
113
- ```
114
- "Send a high-priority message to the reviewer: the fix is ready for re-review"
201
+ ```mermaid
202
+ flowchart LR
203
+ TICK{{"⏱️ Scheduler tick"}} --> Q["SQL query<br/>• tty IS NOT NULL<br/>• autonomous_reply = 1<br/>• unread mail EXISTS"]
204
+ Q --> EACH["For each candidate"]
205
+ EACH --> APP{"terminal_app?"}
206
+ APP -->|tmux| TM["tmux send-keys<br/>-t pane_id"]
207
+ APP -->|iTerm2| IT["osascript<br/>write text to tty"]
208
+ APP -->|other| SK["skip + log"]
209
+ TM --> HOOK["UserPromptSubmit hook<br/>fires on receiving terminal"]
210
+ IT --> HOOK
211
+ HOOK --> INJ["additionalContext:<br/>'you have N unread'"]
212
+ INJ --> CLAUDE["✅ Agent reads inbox<br/>via its own tool call"]
115
213
  ```
116
214
 
117
- ### `broadcast`
118
- Send a message to ALL connected agents.
119
- ```
120
- "Broadcast: deployment starting in 5 minutes, hold all merges"
121
- ```
215
+ The keystroke path matters. By simulating a real key event we route through the agent's normal trusted-input pipeline. The agent retains full agency over whether and how to reply — ClaudeLink never forges tool calls or fabricates intent. This is *why* it works for Codex, Gemini, and Goose without modification: the keystroke is a primitive every CLI handles identically.
122
216
 
123
- ### `read_inbox`
124
- Check for new messages.
125
- ```
126
- "Check my inbox"
127
- ```
217
+ ---
128
218
 
129
- ### `get_agents`
130
- See who's online.
131
- ```
132
- "Show me all connected agents"
219
+ ## Quick start
220
+
221
+ ```bash
222
+ # install + auto-configure all four supported CLIs globally
223
+ npx claudelink init --all --global
224
+
225
+ # restart your terminals — that's it
133
226
  ```
134
227
 
135
- ### `post_bulletin`
136
- Post to the shared bulletin board (persistent announcements).
228
+ Open three terminals — mix CLIs however you like:
229
+
230
+ **Terminal 1** (Claude Code, advisor)
231
+ > "Register as a code reviewer working on the auth module."
232
+
233
+ **Terminal 2** (Codex CLI, implementer)
234
+ > "Register me as a developer. Send a message to the reviewer asking for the last hot-spot list."
235
+
236
+ **Terminal 3** (Gemini CLI, validator) — or just leave the Command Center open.
237
+ > "Register me as a tester. Watch for completed work and run validation passes."
238
+
239
+ Within a minute the reviewer's reply lands in terminal 2, the developer acts on it, and the bulletin board shows what changed. You typed nothing in the second or third terminal after registration. The Command Center at `http://127.0.0.1:7878` shows all three peers in real time, regardless of which model is on the other end of each.
240
+
241
+ ---
242
+
243
+ ## Installation
244
+
245
+ ### 1. Install the package
246
+ ```bash
247
+ npm install -g claudelink
137
248
  ```
138
- "Post to bulletin: v2.1 release branch created, all features frozen"
249
+
250
+ ### 2. Add to your AI client
251
+
252
+ **Claude Code (global, recommended):**
253
+ ```bash
254
+ claude mcp add --scope user claudelink -- claudelink-server
139
255
  ```
140
256
 
141
- ### `get_bulletin`
142
- Read the bulletin board.
257
+ **Codex CLI (global):**
258
+ ```bash
259
+ codex mcp add claudelink -- claudelink-server
260
+ # or: claudelink init --codex --global
143
261
  ```
144
- "Show the bulletin board"
262
+
263
+ **Gemini CLI (global):**
264
+ ```bash
265
+ claudelink init --gemini --global
266
+ # Merges mcpServers.claudelink into ~/.gemini/settings.json + writes ~/.gemini/GEMINI.md
145
267
  ```
146
268
 
147
- ## CLI Commands
269
+ **Goose (global):**
270
+ ```bash
271
+ claudelink init --goose --global
272
+ # Adds the claudelink extension to ~/.config/goose/config.yaml + writes ~/.config/goose/.goosehints
273
+ ```
148
274
 
275
+ **Everything at once (global):**
149
276
  ```bash
150
- claudelink init # Configure for current project
151
- claudelink init --global # Configure globally
152
- claudelink status # Show registered agents and message stats
153
- claudelink ui # Open the Command Center in your browser
154
- claudelink ui --stop # Stop the Command Center
155
- claudelink reset # Clear all data (fresh start)
156
- claudelink help # Show help
277
+ claudelink init --all --global # Claude + Codex + Gemini + Goose on one mesh
157
278
  ```
158
279
 
159
- ## Autonomous Replies
280
+ **Per-project (mix and match):**
281
+ ```bash
282
+ cd your-project
283
+ npx claudelink init # Claude Code (.mcp.json + CLAUDE.md)
284
+ npx claudelink init --codex # Codex CLI (AGENTS.md + TOML snippet)
285
+ npx claudelink init --gemini # Gemini CLI (.gemini/settings.json + GEMINI.md)
286
+ npx claudelink init --goose # Goose (.goosehints + config snippet)
287
+ npx claudelink init --codex --gemini # stack flags additively
288
+ npx claudelink init --all # all four clients in one project
289
+ ```
160
290
 
161
- ClaudeLink ships a Claude Code Stop hook that auto-processes inbound messages without you typing "check inbox" in each terminal. When an agent finishes a turn, the hook peeks at its inbox; if any messages expect a reply, it injects a continuation telling the agent to call `read_inbox` and respond.
291
+ ### 3. Restart your terminals
162
292
 
163
- ### Why the hook directs to `read_inbox` instead of embedding contents
293
+ ClaudeLink tools appear automatically. Done.
164
294
 
165
- The Stop hook deliberately does **not** embed message contents in the continuation it injects. Doing so trips Claude Code's prompt-injection defense — to the safety layer, "an external message saying do X" is indistinguishable from a malicious file or web page steering Claude's actions, and Claude will (correctly) refuse to act on it. Instead, the hook directs Claude to call its own `read_inbox` tool. The tool result is content Claude has agency over, so the safety layer accepts it and the autonomous reply happens cleanly.
295
+ ### Multi-model support
166
296
 
167
- The advisor branch (`autonomousReply: false`) does still consume messages via the hook (marks them read + emits to stderr) so they don't pile up indefinitely; only the autonomous branch leaves messages unread for `read_inbox` to consume.
297
+ ClaudeLink doesn't care which model is on the other end of an MCP connection. The MCP layer is open — any compliant client can register and participate. A Claude advisor can message a Codex developer can message a Gemini tester, and the Command Center shows them all as peers on the same mesh. The only Claude-Code-specific layer is the optional Stop hook (which gives instant turn-end pickup); Codex, Gemini, and Goose agents fall back to the auto-nudge scheduler's keystroke cadence, which is fine for almost every workflow.
168
298
 
169
- ### Caps and opt-outs
299
+ ### Local-first security
170
300
 
171
- Three guards prevent runaway loops:
301
+ ClaudeLink is built to disappear into your dev environment, not become another SaaS dashboard you have to trust:
172
302
 
173
- - **Hard cap** — max consecutive auto-fires per terminal without a human prompt (`CLAUDELINK_HARD_CAP`, default 5).
174
- - **Cooldown** — minimum seconds between auto-fires per terminal (`CLAUDELINK_COOLDOWN_S`, default 30).
175
- - **Chain cap** — max `parent_id` chain depth before a message stops triggering auto-fires (`CLAUDELINK_CHAIN_CAP`, default 8).
303
+ - **No cloud, no servers.** Every byte of state lives in `~/.claudelink/nexus.db` on your machine.
304
+ - **No telemetry, no analytics, no phone-home.** Read the source — there's nothing to opt out of because nothing is sent.
305
+ - **No account, no signup, no API key.** ClaudeLink doesn't talk to any external service. The agents talk to their own LLM providers however they normally would; ClaudeLink is just the connective tissue between *them*.
306
+ - **Loopback by default.** The Command Center binds to `127.0.0.1:7878`. It's not reachable from outside your machine unless you explicitly opt in (planned for the v1.2 multi-machine release with bearer-token auth on a LAN bind).
307
+ - **Fully open source.** MIT licensed. Every line of code is in this repo. Code is auditable, forkable, and you can run a custom build for your enterprise's compliance posture.
308
+ - **Sandboxed terminal interaction.** The auto-nudge scheduler types into iTerm2 / tmux through their public AppleScript / send-keys APIs — the same way a Bash script would. No accessibility shims, no kernel hooks, no permission prompts.
176
309
 
177
- Set any to `0` to disable that specific guard. Per-agent opt-out: register with `autonomousReply: false` and the hook reads the inbox but never blocks-and-continues — useful for advisor-style terminals where you want visibility but no automatic action.
310
+ If you've been hesitant to wire AI agents together because every "multi-agent framework" wants you to send your context to their cloud, ClaudeLink is built for you. Your code stays where it is.
178
311
 
179
- Per-message opt-out: send with `expectsReply: false` for FYI/informational pings. The recipient still reads them but the hook treats them as ineligible for auto-fire.
312
+ ### Requirements
313
+ - Node.js 18+
314
+ - One or more MCP-compatible clients: Claude Code, OpenAI Codex CLI, Google Gemini CLI, or Block's Goose
315
+ - macOS or Linux (Windows works for messaging; auto-nudge requires tmux)
180
316
 
181
- Every Stop hook decision logs to `~/.claudelink/auto-fire.log` for auditing without reading any conversation.
317
+ ---
182
318
 
183
- ### Desktop notifications
319
+ ## Command Center
184
320
 
185
- The Command Center fires a macOS desktop notification (via `osascript display notification`, no Accessibility permission required) for every new message that lands in any agent's inbox — including agents registered with `autonomousReply: false`. Notifications give you situational awareness across the swarm without switching terminals.
321
+ The Command Center is a local web UI at `http://127.0.0.1:7878` — a live console for the entire mesh. The first `claudelink-server` to boot launches it; subsequent agents share the same window. It survives MCP restarts and only exits when you click **Quit UI**.
186
322
 
187
- Multiple messages arriving in the same 2-second poll window collapse into one summary notification ("3 new ClaudeLink messages: reviewer → developer: ... (+2 more)"). The historical backlog is suppressed at startup so a freshly opened Command Center doesn't spam you with old messages.
323
+ ### What it gives you
188
324
 
189
- Off-switch: `CLAUDELINK_NOTIFY=off`.
325
+ | Panel | What it does |
326
+ |---|---|
327
+ | **Running servers** | Every `claudelink-server` process with PID, TTY, uptime, role. Per-row **Kill** button. |
328
+ | **Registered agents** | Role, status, **per-agent Auto-reply toggle**, sent/received counts, last-seen. |
329
+ | **Health** | Total agents, unread/total messages, bulletin entries, orphan blockers, FK violations. **Heal orphans** cleans dead-agent tail rows in one transaction. |
330
+ | **Auto-nudge** | Global on/off + tick interval (1–120 min). Scheduler only fires for terminals that *actually have* unread mail — no wasted Claude turns. |
331
+ | **Recent messages** | Live feed of the last several messages across all agents, with priority and unread badges. |
190
332
 
191
- ### Debug knobs
333
+ The page auto-refreshes every 2 seconds. **Kill all servers** in the header drops the entire mesh in one click.
192
334
 
193
- - `CLAUDELINK_HOOK_TTY=/dev/ttysNNN` — override TTY auto-detection (testing, CI).
194
- - `CLAUDELINK_HOOK_STRICT=1` — surface hook errors to stderr instead of swallowing them. Default is fail-open (production safety).
195
- - `CLAUDELINK_NOTIFY=off` — disable desktop notifications.
335
+ ### Lifecycle
196
336
 
197
- ## Autonomous Mode (Recommended)
337
+ A lock file at `~/.claudelink/ui.lock` prevents duplicate windows. The launcher detached-spawns the UI process with `unref()` so it outlives the MCP parent. If a stale lock is detected (PID dead and no heartbeat at `/api/heartbeat`), a fresh UI takes over automatically.
198
338
 
199
- By default, you'd have to tell Claude "check my inbox" manually every time. That defeats the purpose. With autonomous mode, agents communicate **on their own** — checking for messages and sending updates without you asking.
339
+ To opt out: `CLAUDELINK_UI=off` in your environment before starting any agent CLI.
200
340
 
201
- ### Automatic Setup
341
+ ```bash
342
+ claudelink ui # start it manually (or just spawn any agent)
343
+ claudelink ui --stop # graceful shutdown
344
+ ```
202
345
 
203
- **This is installed automatically** when you run `claudelink init` or `claudelink init --global`. The init command creates a `CLAUDE.md` file with the autonomous communication instructions in the appropriate directory:
346
+ ---
204
347
 
205
- - `init --global` → writes to `~/.claude/CLAUDE.md` (all projects)
206
- - `init` → writes to `./CLAUDE.md` (current project only)
348
+ ## Available tools
207
349
 
208
- If you already have a `CLAUDE.md`, the ClaudeLink instructions are appended without overwriting your existing content. Running init multiple times is safe — it won't duplicate the instructions.
350
+ Once connected, every agent session — Claude Code, Codex CLI, Gemini CLI, Goose, or any other MCP client — gains these MCP tools:
209
351
 
210
- ### What It Teaches Claude
352
+ | Tool | Purpose | Example prompt |
353
+ |---|---|---|
354
+ | `register` | Identify this agent on the mesh | *"Register as a developer working on the payment system"* |
355
+ | `send` | Direct message to a role | *"Send a high-priority message to the reviewer: fix is ready for re-review"* |
356
+ | `broadcast` | Send to all agents | *"Broadcast: deployment in 5 minutes, hold all merges"* |
357
+ | `read_inbox` | Pull unread messages | *"Check my inbox"* |
358
+ | `get_agents` | Roster of who's online | *"Who's online?"* |
359
+ | `post_bulletin` | Persistent announcement | *"Post to bulletin: v2.1 release branch created"* |
360
+ | `get_bulletin` | Read the bulletin board | *"Show the bulletin board"* |
211
361
 
212
- The `CLAUDE.md` file instructs every Claude Code session to:
362
+ `register` and `send` accept v1.1 options: `autonomousReply`, `expectsReply`, `parentMessageId` for thread tracking, FYI semantics, and per-agent autonomy control.
213
363
 
214
- - **Check inbox automatically** before and after every task
215
- - **Send updates proactively** to other agents when work is completed
216
- - **Respond to messages immediately** without waiting for you to say "check inbox"
217
- - **Post to the bulletin board** when making decisions that affect the project
364
+ ---
218
365
 
219
- ### Manual Fallback
366
+ ## CLI
220
367
 
221
- If the automatic setup doesn't work on your system (different directory structure, permissions, etc.), you can manually create or add to `~/.claude/CLAUDE.md`:
368
+ ```bash
369
+ claudelink init # configure for current project
370
+ claudelink init --global # configure globally
371
+ claudelink status # show registered agents + message stats
372
+ claudelink ui # open the Command Center
373
+ claudelink ui --stop # stop the Command Center
374
+ claudelink install-hooks # install autonomous-reply hooks (project)
375
+ claudelink install-hooks --global # install hooks in ~/.claude/settings.json
376
+ claudelink install-hooks --uninstall # remove ClaudeLink hooks
377
+ claudelink reset # clear all data (fresh start)
378
+ claudelink help # full help
379
+ ```
222
380
 
223
- ```markdown
224
- ## ClaudeLink - Autonomous Agent Communication
381
+ ---
225
382
 
226
- You are part of a multi-agent team. Other agents may be running in separate
227
- terminals and can send you messages at any time via ClaudeLink.
383
+ ## Autonomous replies (deep dive)
228
384
 
229
- ### Automatic Inbox Checking
385
+ ClaudeLink ships **two complementary mechanisms** for hands-free agent collaboration. Both feed messages into the recipient through that agent's own `read_inbox` tool — the agent always has agency.
230
386
 
231
- - BEFORE starting any task: Check your inbox using read_inbox first
232
- - AFTER completing any task: Check your inbox again using read_inbox
233
- - If you receive a message, acknowledge it and act on it before moving on
234
- - If a message requires you to change your current work, do so immediately
235
- - If a message is from another agent asking for information, respond using send
236
- before continuing your own work
237
- - High-priority messages take precedence over your current task
387
+ ### 1. Auto-nudge scheduler (primary, works for every CLI)
238
388
 
239
- ### Autonomous Collaboration
389
+ The Command Center runs a periodic scheduler that types `check for updates` into each registered agent's terminal whenever its inbox has unread mail. Configure directly from the UI:
240
390
 
241
- - When you finish work that another agent might care about, proactively send
242
- them an update
243
- - If you encounter a problem that another agent's role could help with, send
244
- them a message
245
- - When you make a decision that affects the project, post it to the bulletin board
246
- - If you're blocked waiting for another agent, say so and check inbox again
391
+ - **On/off toggle** — Auto-nudge panel
392
+ - **Interval** — 1–120 minutes (default 5)
247
393
 
248
- ### Communication Shortcuts
394
+ The scheduler is **smart**: the SQL filter only nudges terminals with unread mail. Empty inboxes don't burn agent turns or tokens. Per-terminal-app dispatch:
249
395
 
250
- - "check response" or "check messages" — Use read_inbox to check for new messages
251
- - "ask the [role]" — Send a message to that role and check inbox for their reply
252
- - "tell the [role]" — Send a one-way message to that role
253
- - "who's online" — Use get_agents to list all connected agents
254
- - "update the board" — Use post_bulletin to post a status update
255
- - "check the board" — Use get_bulletin to read the bulletin board
256
- ```
396
+ | Terminal | Mechanism | Permissions |
397
+ |---|---|---|
398
+ | **tmux** | `tmux send-keys -t <pane>` | none |
399
+ | **iTerm2** | `osascript` matched by tty | none |
400
+ | **Apple Terminal** | unsupported (would need Accessibility) | not silently prompted |
257
401
 
258
- ### Per-Project vs Global
402
+ When the keystroke arrives, the receiving CLI treats it as normal user input and the agent calls `read_inbox` via its own tool — fully trusted path. **This works identically for Claude Code, Codex CLI, Gemini CLI, and Goose** because the keystroke is the lowest common denominator every terminal app handles the same.
259
403
 
260
- | File | Applies to |
261
- |------|-----------|
262
- | `~/.claude/CLAUDE.md` | **Every project, every terminal** — recommended |
263
- | `your-project/CLAUDE.md` | Only that specific project |
404
+ Settings persist at `~/.claudelink/scheduler.json`. Audit log at `~/.claudelink/scheduler.log`.
264
405
 
265
- If you want autonomous mode everywhere (most people do), use the global file. If you only want it for specific projects, put it in the project's `CLAUDE.md`.
406
+ ### 2. Stop hook (Claude-Code-only low-latency supplement)
266
407
 
267
- ### What Autonomous Mode Looks Like
408
+ For Claude Code agents specifically, when an agent has *just* finished a turn and there's a message waiting, a Stop hook can fire immediately instead of waiting for the next scheduler tick:
268
409
 
269
- Without autonomous mode:
270
- ```
271
- You: Fix the bug in auth.ts
272
- Claude: (fixes the bug)
273
- You: Now check your inbox
274
- Claude: You have 1 message from the reviewer...
275
- You: Send the reviewer an update
276
- Claude: Message sent.
410
+ ```bash
411
+ claudelink install-hooks # project-scoped
412
+ claudelink install-hooks --global # writes ~/.claude/settings.json
413
+ claudelink install-hooks --uninstall # clean rollback
277
414
  ```
278
415
 
279
- With autonomous mode:
280
- ```
281
- You: Fix the bug in auth.ts
282
- Claude: (checks inbox — sees a tip from the reviewer about the bug)
283
- (fixes the bug using the reviewer's guidance)
284
- (sends the reviewer: "Fixed it, here's what I changed...")
285
- (posts to bulletin: "auth.ts bug fixed")
286
- (checks inbox again — no new messages)
287
- Done. I fixed the token validation bug. The reviewer had already
288
- flagged the exact line, so I used their suggestion.
289
- ```
416
+ > The Stop hook is Claude-Code-specific (Claude Code's hooks contract). Codex CLI, Gemini CLI, and Goose agents fall back to the auto-nudge scheduler's keystroke cadence — which is fine for almost every workflow.
290
417
 
291
- One instruction from you. All the communication happens automatically.
418
+ The hook emits `{"decision": "block", "reason": "..."}` directing the Claude agent to call `read_inbox`. Three guards prevent runaway loops:
292
419
 
293
- ---
420
+ - **Hard cap** — max consecutive auto-fires per terminal without a human prompt (`CLAUDELINK_HARD_CAP`, default 5)
421
+ - **Cooldown** — minimum seconds between auto-fires (`CLAUDELINK_COOLDOWN_S`, default 30)
422
+ - **Chain cap** — max `parent_id` chain depth before a message stops triggering auto-fires (`CLAUDELINK_CHAIN_CAP`, default 8)
294
423
 
295
- ## Use Cases
424
+ Set any to `0` to disable. Decisions log to `~/.claudelink/auto-fire.log`.
296
425
 
297
- ### Code Review Pipeline
298
- - **Terminal 1** (reviewer): Reviews code, sends findings to developer
299
- - **Terminal 2** (developer): Receives feedback, implements fixes, notifies reviewer when ready
426
+ > **Honest note on Claude's safety boundary:** Claude Code's prompt-injection defense correctly flags external content steering outbound tool calls. The Stop hook reliably triggers an autonomous inbox read; Claude may decline to send the outbound reply autonomously when the reply would be unrelated to the user's most recent prompt. This is responsible safety behavior, not a bug. **The auto-nudge scheduler avoids this entirely** because the keystroke path is indistinguishable from the user typing by hand.
300
427
 
301
- ### Test-Driven Development
302
- - **Terminal 1** (developer): Writes implementation
303
- - **Terminal 2** (tester): Runs tests, reports failures back to developer
428
+ ### Per-agent opt-out
304
429
 
305
- ### Full Team Simulation
306
- - **Terminal 1** (architect): Posts design decisions to bulletin board
307
- - **Terminal 2** (developer): Implements features, asks architect for clarification
308
- - **Terminal 3** (reviewer): Reviews code, sends feedback to developer
309
- - **Terminal 4** (ops): Monitors build pipeline, broadcasts deployment status
430
+ Two ways to silence an agent:
310
431
 
311
- ### Parallel Feature Development
312
- - **Terminal 1** (dev-auth): Working on authentication
313
- - **Terminal 2** (dev-api): Working on API endpoints
314
- - Both agents coordinate to avoid conflicts and share interface contracts
432
+ 1. **At registration** — `autonomousReply: false` for terminals that should receive but never auto-process. Useful as a default for advisor / strategy terminals.
433
+ 2. **Live from the Command Center** — flip the **Auto-reply** column checkbox. Applies on the next scheduler tick. Lifetime: holds until that agent re-registers (close + reopen the CLI in that terminal).
315
434
 
316
- ## Architecture
435
+ When opted out: the Stop hook still reads the inbox (so messages don't pile up) but never emits a continuation, and the auto-nudge scheduler skips that agent at the SQL filter — no keystroke is sent.
317
436
 
318
- ```
319
- ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
320
- │ Claude Code │ │ Claude Code │ │ Claude Code │
321
- │ (Terminal 1) │ │ (Terminal 2) │ │ (Terminal 3) │
322
- └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
323
- │ │ │
324
- │ stdio │ stdio │ stdio
325
- │ │ │
326
- ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
327
- │ MCP Server │ │ MCP Server │ │ MCP Server │
328
- │ (Process 1) │ │ (Process 2) │ │ (Process 3) │
329
- └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
330
- │ │ │
331
- └────────────────────┼────────────────────┘
332
- │
333
- ┌────────▼────────┐
334
- │ SQLite (WAL) │
335
- │ ~/.claudelink/ │
336
- │ nexus.db │
337
- └─────────────────┘
338
- ```
437
+ ### Per-message opt-out
339
438
 
340
- Each Claude Code session spawns its own MCP server process via stdio. All processes read and write to the same SQLite database. WAL (Write-Ahead Logging) mode ensures concurrent access is safe and performant.
439
+ Send with `expectsReply: false` for FYI / informational pings.
341
440
 
342
- ### Why SQLite?
343
- - Zero configuration — single file, no server to run
344
- - WAL mode handles concurrent readers and writers
345
- - Survives process crashes — no data loss
346
- - Portable across macOS, Linux, and Windows
441
+ ### Desktop notifications
347
442
 
348
- ### Message Flow
349
- 1. Agent A calls `send(to="developer", message="...")`
350
- 2. MCP Server A writes a row to the `messages` table
351
- 3. Agent B calls `read_inbox()`
352
- 4. MCP Server B reads unread rows from `messages` and marks them read
353
- 5. Agent B receives the message and can act on it
443
+ The Command Center fires a macOS desktop notification (via `osascript display notification`, no Accessibility permission needed) for every new message that lands in any agent's inbox — including agents with `autonomousReply: false`. Multiple messages in the same 2-second poll window collapse into one summary notification. Off-switch: `CLAUDELINK_NOTIFY=off`.
354
444
 
355
- ### Agent Lifecycle
356
- - Agents register with a `role` and their process `pid`
357
- - A heartbeat updates `last_seen` every 30 seconds
358
- - When listing agents, dead processes (checked via `kill -0 pid`) are automatically pruned
359
- - No manual cleanup needed
445
+ ### Debug knobs
360
446
 
361
- ## Configuration
447
+ - `CLAUDELINK_HOOK_TTY=/dev/ttysNNN` — override TTY auto-detection (testing, CI)
448
+ - `CLAUDELINK_HOOK_STRICT=1` — surface hook errors to stderr instead of swallowing them
449
+ - `CLAUDELINK_NOTIFY=off` — disable desktop notifications
362
450
 
363
- ClaudeLink stores its database at `~/.claudelink/nexus.db`. This path is fixed so all Claude Code instances across all projects converge on the same communication hub.
451
+ ---
364
452
 
365
- ### .mcp.json (per-project)
366
- ```json
367
- {
368
- "mcpServers": {
369
- "claudelink": {
370
- "type": "stdio",
371
- "command": "claudelink-server"
372
- }
373
- }
374
- }
375
- ```
453
+ ## Autonomous mode setup
376
454
 
377
- ### ~/.claude.json (global via CLI)
378
- ```bash
379
- claude mcp add --scope user claudelink -- claudelink-server
380
- ```
455
+ By default, you'd have to tell every agent *"check my inbox"* manually every time. That defeats the purpose. Autonomous mode is installed automatically when you run `claudelink init` — it writes the right project-instructions file for whichever CLIs you flagged:
381
456
 
382
- ## FAQ
457
+ | Flag | File written (project) | File written (`--global`) |
458
+ |---|---|---|
459
+ | `--claude` | `./CLAUDE.md` | `~/.claude/CLAUDE.md` |
460
+ | `--codex` | `./AGENTS.md` | `~/.codex/AGENTS.md` |
461
+ | `--gemini` | `./GEMINI.md` | `~/.gemini/GEMINI.md` |
462
+ | `--goose` | `./.goosehints` | `~/.config/goose/.goosehints` |
383
463
 
384
- ### Wait, does `npx claudelink init` start Claude?
464
+ If the file already exists, the ClaudeLink instructions are appended without overwriting your existing content. Running init multiple times is safe — there's a marker check, no duplication.
385
465
 
386
- **No.** You only run `npx claudelink init` **once**. It's a setup command that writes a config file (`.mcp.json`) telling Claude Code to connect to ClaudeLink on startup. After that, you never need to run it again.
466
+ ### What it teaches the agent
387
467
 
388
- Your daily workflow is exactly the same as before:
468
+ Every instruction file (CLAUDE.md / AGENTS.md / GEMINI.md / .goosehints) tells the agent to:
389
469
 
390
- ```bash
391
- # Terminal 1 — start Claude normally
392
- claude
470
+ - **Check inbox automatically** before and after every task
471
+ - **Send updates proactively** to other agents when work is completed
472
+ - **Respond to messages immediately** without waiting for you to say "check inbox"
473
+ - **Post to the bulletin board** when making decisions that affect the project
393
474
 
394
- # Terminal 2 — start Claude normally
395
- claude
475
+ ### Without vs with autonomous mode
396
476
 
397
- # Terminal 3 — start Claude with full auto-permissions
398
- claude --dangerously-skip-permissions
477
+ ```diff
478
+ - Without:
479
+ - You: Fix the bug in auth.ts
480
+ - Claude: (fixes the bug)
481
+ - You: Now check your inbox
482
+ - Claude: You have 1 message from the reviewer...
483
+ - You: Send the reviewer an update
484
+ - Claude: Message sent.
485
+
486
+ + With autonomous mode:
487
+ + You: Fix the bug in auth.ts
488
+ + Claude: (checks inbox — sees a tip from the reviewer about the bug)
489
+ + (fixes the bug using the reviewer's guidance)
490
+ + (sends the reviewer: "Fixed it, here's what I changed...")
491
+ + (posts to bulletin: "auth.ts bug fixed")
492
+ + Done. I fixed the token validation bug.
399
493
  ```
400
494
 
401
- Claude Code reads `.mcp.json` when it starts, sees ClaudeLink is configured, and automatically connects. The `register`, `send`, `read_inbox`, and other tools just appear — no extra commands.
495
+ One instruction from you. All the communication happens automatically.
496
+
497
+ ---
402
498
 
403
- Then you just talk naturally:
499
+ ## Use cases
404
500
 
405
- **Terminal 1:**
406
- > "Register as a code reviewer working on the auth module"
501
+ ### 🔍 Code review pipeline
502
+ - **Reviewer** scans diffs, sends findings to developer
503
+ - **Developer** receives feedback, implements fixes, notifies reviewer when ready
407
504
 
408
- **Terminal 2:**
409
- > "Register as a developer. Send a message to the reviewer asking if auth.ts looks good."
505
+ ### 🧪 Test-driven development
506
+ - **Developer** writes implementation
507
+ - **Tester** runs tests, reports failures back to developer
410
508
 
411
- ### How do I start Claude with different permission modes?
509
+ ### 🏛️ Full team simulation
510
+ - **Architect** posts design decisions to bulletin board
511
+ - **Developer** implements features, asks architect for clarification
512
+ - **Reviewer** reviews code, sends feedback to developer
513
+ - **Ops** monitors build pipeline, broadcasts deployment status
412
514
 
413
- ClaudeLink works with all Claude Code startup modes:
515
+ ### ⚡ Parallel feature development
516
+ - **dev-auth** working on authentication
517
+ - **dev-api** working on API endpoints
518
+ - Both coordinate to avoid conflicts and share interface contracts
414
519
 
415
- ```bash
416
- # Standard mode (Claude asks before using tools)
417
- claude
520
+ ### 🌐 Long-running research swarm
521
+ - **planner** breaks the question into sub-tasks
522
+ - **researchers** (3–4 agents) tackle independent slices
523
+ - **synthesizer** consolidates findings into a single report
524
+ - All running while you do something else; auto-nudge keeps them moving
418
525
 
419
- # Skip all permission prompts
420
- claude --dangerously-skip-permissions
526
+ ---
421
527
 
422
- # Auto-approve only ClaudeLink tools (recommended)
423
- claude --allowedTools "mcp__claudelink__*"
424
- ```
528
+ ## Configuration
425
529
 
426
- ### How do I disable ClaudeLink?
530
+ ClaudeLink stores its database at `~/.claudelink/nexus.db`. The path is fixed so every agent across every project (and across all four supported CLIs) converges on the same hub.
427
531
 
428
- You do **not** need to restart your computer. There are several options depending on what you want:
532
+ ### Configuration files (per CLI)
429
533
 
430
- **Option 1: Disable for a specific project**
534
+ Each CLI has its own MCP config file format. ClaudeLink writes the right one for whichever flag you pass to `claudelink init`:
431
535
 
432
- Remove the `claudelink` entry from your project's `.mcp.json`:
536
+ | CLI | Config file | Schema |
537
+ |---|---|---|
538
+ | Claude Code | `.mcp.json` (project) / `~/.claude.json` (global) | `{ "mcpServers": { "claudelink": { "command": "claudelink-server" } } }` |
539
+ | Codex CLI | `~/.codex/config.toml` | `[mcp_servers.claudelink]` with `command = "claudelink-server"` |
540
+ | Gemini CLI | `.gemini/settings.json` (project) / `~/.gemini/settings.json` (global) | `{ "mcpServers": { "claudelink": { "command": "claudelink-server" } } }` |
541
+ | Goose | `~/.config/goose/config.yaml` | `extensions: { claudelink: { cmd: claudelink-server, type: stdio, ... } }` |
433
542
 
434
- ```bash
435
- # Open the config
436
- nano .mcp.json
437
- ```
543
+ ---
438
544
 
439
- Delete the `"claudelink": { ... }` block, save, and restart Claude Code in that terminal. ClaudeLink tools will no longer appear for that project.
545
+ ## Architecture details
440
546
 
441
- **Option 2: Disable globally**
547
+ ### Why SQLite?
548
+ - Zero configuration — single file, no server to run
549
+ - WAL mode handles concurrent readers and writers safely
550
+ - Survives process crashes — no data loss
551
+ - Portable across macOS, Linux, and Windows
442
552
 
443
- If you installed globally, remove it via CLI:
553
+ ### Message flow
554
+ 1. Agent A calls `send(to="developer", message="...")`
555
+ 2. MCP Server A writes a row to the `messages` table
556
+ 3. Auto-nudge scheduler (or Stop hook) wakes Agent B
557
+ 4. MCP Server B reads unread rows and marks them read atomically (`UPDATE...RETURNING`)
558
+ 5. Agent B receives the message and acts
444
559
 
445
- ```bash
446
- claude mcp remove --scope user claudelink
447
- ```
560
+ ### Agent lifecycle
561
+ - Agents register with a `role`, `pid`, `tty`, and `terminal_app` (auto-detected)
562
+ - Heartbeat updates `last_seen` every 30 seconds
563
+ - Dead processes (checked via `kill -0 pid`) auto-pruned at next listing
564
+ - No manual cleanup needed; the Command Center exposes a one-click **Heal orphans** for tail rows
448
565
 
449
- **Option 3: Clear all data but keep it installed**
566
+ ---
567
+
568
+ ## FAQ
569
+
570
+ ### Wait, does `npx claudelink init` start any of the CLIs?
571
+
572
+ **No.** `claudelink init` is a one-time setup command. It writes the appropriate config file (`.mcp.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`, `~/.config/goose/config.yaml`) telling each CLI to connect to ClaudeLink on startup. After that, you never need to run it again — your daily workflow is whatever you'd normally do:
450
573
 
451
574
  ```bash
452
- npx claudelink reset
575
+ claude # Claude Code
576
+ codex # Codex CLI
577
+ gemini # Gemini CLI
578
+ goose session # Goose
579
+ claude --allowedTools "mcp__claudelink__*" # Claude with auto-approve for ClaudeLink tools
453
580
  ```
454
581
 
455
- This deletes the database (all messages, agents, bulletin entries) but keeps the config so you can start fresh.
582
+ Each CLI reads its own config on startup, sees ClaudeLink is configured, connects automatically. The tools just appear.
456
583
 
457
- **Option 4: Full uninstall (remove everything)**
584
+ ### How do I disable ClaudeLink?
458
585
 
459
- ```bash
460
- # 1. Remove from project config
461
- # Edit .mcp.json and delete the claudelink entry
586
+ You do not need to restart your computer. Pick one:
462
587
 
463
- # 2. Remove from global config
588
+ **Per project:** edit `.mcp.json` and remove the `claudelink` block.
589
+ **Globally:** `claude mcp remove --scope user claudelink`
590
+ **Reset data only:** `npx claudelink reset` (keeps config, deletes DB)
591
+ **Full uninstall:**
592
+ ```bash
464
593
  claude mcp remove --scope user claudelink
465
-
466
- # 3. Uninstall the package
467
594
  npm uninstall -g claudelink
468
-
469
- # 4. Delete all ClaudeLink data
470
595
  rm -rf ~/.claudelink
471
596
  ```
472
597
 
473
- After any of these, just restart your Claude Code sessions. No computer restart needed — just close and reopen the terminal, or start a new `claude` session.
474
-
475
598
  ### Can I temporarily disable it without deleting anything?
476
599
 
477
- Yes. In your `.mcp.json`, add `"disabled": true`:
600
+ Yes — set `"disabled": true` in the `.mcp.json` block:
478
601
 
479
602
  ```json
480
603
  {
@@ -488,54 +611,65 @@ Yes. In your `.mcp.json`, add `"disabled": true`:
488
611
  }
489
612
  ```
490
613
 
491
- Set it back to `false` (or remove the line) to re-enable. Restart Claude Code after changing.
614
+ ### Will agents talk to each other across machines?
615
+
616
+ **Designed and approved for v1.2.** Hub-and-spoke architecture (one laptop owns the SQLite DB and a `/api/v1/` HTTP API; the other runs a small spoke daemon that polls the hub and dispatches local keystrokes). Bearer-token auth, LAN-bound by default. Full design doc at [`docs/multi-machine-design.md`](docs/multi-machine-design.md). Build is queued behind smoke testing of v1.3.
617
+
618
+ ### Can I add another MCP-compatible CLI that isn't on the supported list yet?
619
+
620
+ Yes. Manual route: point the CLI's MCP config at `claudelink-server` (each CLI has its own config file format), and add a copy of [the AGENTS.md template](docs/) to the project. The MCP layer doesn't care which CLI is on the other end.
621
+
622
+ If you'd like a one-command `--<your-cli>` flag, [open an issue](https://github.com/jaysidd/claudelink/issues) with the CLI name and the path to its MCP config file format. Adding a flag is roughly an hour of work.
623
+
624
+ ### Does this work on Windows?
625
+
626
+ Messaging works on any platform with Node 18+. The auto-nudge scheduler currently dispatches to tmux and iTerm2 only; on Windows you'd run inside WSL + tmux for the full autonomous loop.
492
627
 
493
628
  ---
494
629
 
495
630
  ## Contributing
496
631
 
497
- Contributions are welcome! This is an open-source project and we'd love the community to help build on it.
632
+ This is open source. Contributions welcome.
498
633
 
499
- ### Development Setup
500
634
  ```bash
501
635
  git clone https://github.com/jaysidd/claudelink.git
502
636
  cd claudelink
503
637
  npm install
504
638
  npm run build
639
+ node dist/index.js # run MCP server directly
640
+ node dist/cli.js status # exercise CLI
505
641
  ```
506
642
 
507
- ### Testing Locally
508
- ```bash
509
- # Run the MCP server directly (for debugging)
510
- node dist/index.js
643
+ ### Roadmap
511
644
 
512
- # Test the CLI
513
- node dist/cli.js init
514
- node dist/cli.js status
515
- ```
645
+ - **v1.2 — Multi-machine hub/spoke** *(designed and approved, build queued)* — see [`docs/multi-machine-design.md`](docs/multi-machine-design.md)
646
+ - **More CLI integrations** — Cursor CLI, Amazon Q Developer CLI, opencode, Cline, Continue.dev. PRs welcome; the pattern is small and repeatable.
647
+ - **Channels / topics** — named buses for topic-based collaboration
648
+ - **Message search & history** — query past messages, not just unread
649
+ - **Structured payloads** — file paths, code snippets, diffs as first-class types
650
+ - **Priority interrupts** — break the recipient's current turn for high-priority pings
651
+ - **Agent templates** — pre-built role configs for common workflows
652
+ - **Webhooks** — push agent activity to external services
653
+ - **Encryption at rest**
516
654
 
517
- ### Ideas for Contributions
518
- - **Agent groups/channels**: Named channels for topic-based communication
519
- - **Message history**: Tool to view past messages (not just unread)
520
- - **File sharing**: Agents can share file paths or code snippets with structured formatting
521
- - **Priority notifications**: Interrupt the current agent when a high-priority message arrives
522
- - **Agent templates**: Pre-built role configurations for common workflows
523
- - **Webhooks**: Notify external services when agents communicate
524
- - **Encryption**: Encrypt messages at rest in the database
525
- - **Multi-machine support**: Replace SQLite with a networked backend for remote agent communication
655
+ If you ship one of these, send a PR. If you ship something we didn't think of, send it anyway.
656
+
657
+ ---
526
658
 
527
659
  ## License
528
660
 
529
- MIT License — see [LICENSE](LICENSE) for details.
661
+ MIT — see [LICENSE](LICENSE).
530
662
 
531
663
  ---
532
664
 
533
- Built by [Jay Siddiqi](https://github.com/jaysidd).
665
+ Built by [Jay Siddiqi](https://github.com/jaysidd). MIT licensed, built in the open, no telemetry, no cloud.
666
+
667
+ If ClaudeLink helps your workflow, **star the repo** and share it with someone running multiple AI coding agents — discoverability is everything for an open-source project, and a single coordinated mesh of Claude + Codex + Gemini + Goose really is a different category of tool than any single CLI on its own.
534
668
 
535
- If ClaudeLink helps your workflow, give it a star and share it with your team.
669
+ Bug reports, feature requests, and PRs welcome at [github.com/jaysidd/claudelink/issues](https://github.com/jaysidd/claudelink/issues).
536
670
 
537
671
  ---
538
672
 
539
673
  ### Keywords
540
674
 
541
- claudelink, claude link, multi-agent communication, claude code, claude code mcp, mcp server, model context protocol, ai agent collaboration, multi-terminal ai, agent-to-agent messaging, inter-process communication, ipc ai agents, claude code plugin, claude code extension, ai pair programming, ai code review, multi-agent workflow, ai terminal tools, developer tools, ai developer tools, open source ai tools, agent orchestration, agent mesh, ai agent hub, collaborative ai agents, claude mcp server, sqlite mcp, ai swarm, multi-agent system, ai team simulation, agent message bus, claude code multi-instance, iterm2 ai, terminal ai agents, ai agent framework, autonomous ai agents, agent communication protocol, ai productivity tools, claude code tools, mcp tools, ai workflow automation
675
+ claudelink, claude link, claude code, codex cli, openai codex, gemini cli, google gemini cli, goose cli, block goose, mcp server, model context protocol, multi-model ai agents, multi-cli agents, mix claude codex gemini, heterogeneous ai swarm, claude code mcp, codex cli mcp, gemini cli mcp, goose mcp extension, multi-agent communication, agent-to-agent messaging, autonomous ai agents, autonomous coding agents, ai swarm, multi-agent system, agent message bus, agent mesh, ai agent hub, collaborative ai agents, claude code multi-agent, codex cli multi-agent, gemini cli multi-agent, claude code automation, claude code command center, ai command center, sqlite mcp, iterm2 ai, tmux ai, terminal ai agents, agent communication protocol, ai pair programming, ai code review, multi-agent workflow, agent orchestration, autonomous developer agents, ai dev productivity, 5x developer, local-first ai, no-cloud ai, on-machine ai, open-source multi-agent, mcp ecosystem, mcp interoperability, claude code plugin, codex cli plugin, mcp tools.