claudelink 1.1.1 → 1.3.1
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.
- package/README.md +470 -369
- package/dist/cli.js +391 -83
- package/dist/cli.js.map +1 -1
- package/dist/db.d.ts +1 -0
- package/dist/db.js +6 -0
- package/dist/db.js.map +1 -1
- package/dist/scheduler.js +19 -1
- package/dist/scheduler.js.map +1 -1
- package/dist/ui-server.js +70 -2
- package/dist/ui-server.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,513 +1,603 @@
|
|
|
1
1
|
# ClaudeLink
|
|
2
2
|
|
|
3
|
-
**The
|
|
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
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/claudelink)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](#compatible-ai-clients)
|
|
9
|
+
[](https://modelcontextprotocol.io/)
|
|
10
|
+
[](#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
13
|
|
|
14
|
-
|
|
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.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
You don't need to invent a multi-agent framework. You already have one.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
# Install and configure (one command)
|
|
22
|
-
npx claudelink init
|
|
23
|
-
```
|
|
20
|
+
---
|
|
24
21
|
|
|
25
|
-
|
|
22
|
+
## Why ClaudeLink exists
|
|
26
23
|
|
|
27
|
-
|
|
28
|
-
> "Register as a code reviewer working on the auth module"
|
|
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.
|
|
29
25
|
|
|
30
|
-
|
|
31
|
-
> "Register as a developer. Check inbox for messages from the reviewer."
|
|
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.
|
|
32
27
|
|
|
33
|
-
|
|
34
|
-
|
|
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 |
|
|
35
36
|
|
|
36
|
-
|
|
37
|
-
> "Read my inbox"
|
|
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.
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
---
|
|
40
40
|
|
|
41
|
-
##
|
|
41
|
+
## Compatible AI clients
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
npm install -g claudelink
|
|
46
|
-
```
|
|
43
|
+
ClaudeLink works with any MCP-compatible coding CLI. Today, four are first-class with one-command install:
|
|
47
44
|
|
|
48
|
-
|
|
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` |
|
|
49
51
|
|
|
50
|
-
|
|
51
|
-
```bash
|
|
52
|
-
claude mcp add --scope user claudelink -- claudelink-server
|
|
53
|
-
```
|
|
54
|
-
This adds ClaudeLink to `~/.claude.json` so it's available in every Claude Code session, in every project. One command, done forever.
|
|
52
|
+
Or set up all four in one shot:
|
|
55
53
|
|
|
56
|
-
**Per-Project (only this project):**
|
|
57
54
|
```bash
|
|
58
|
-
|
|
59
|
-
npx claudelink init
|
|
55
|
+
claudelink init --all --global
|
|
60
56
|
```
|
|
61
|
-
This adds ClaudeLink to `.mcp.json` in your project directory only.
|
|
62
57
|
|
|
63
|
-
###
|
|
58
|
+
### Model reach (especially through Goose)
|
|
64
59
|
|
|
65
|
-
|
|
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:
|
|
66
61
|
|
|
67
|
-
|
|
68
|
-
-
|
|
69
|
-
-
|
|
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
|
|
70
67
|
|
|
71
|
-
|
|
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.
|
|
72
69
|
|
|
73
|
-
|
|
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.
|
|
74
71
|
|
|
75
|
-
|
|
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.
|
|
76
73
|
|
|
77
|
-
|
|
74
|
+
---
|
|
78
75
|
|
|
79
|
-
|
|
76
|
+
## Heterogeneous workflows
|
|
80
77
|
|
|
81
|
-
|
|
78
|
+
Why mix models? Because each one is good at different things, and ClaudeLink lets you put each on the task it shines at.
|
|
82
79
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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. |
|
|
87
86
|
|
|
88
|
-
The
|
|
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.
|
|
89
88
|
|
|
90
|
-
|
|
89
|
+
---
|
|
91
90
|
|
|
92
|
-
|
|
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.
|
|
93
122
|
|
|
94
|
-
|
|
123
|
+
---
|
|
95
124
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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.
|
|
100
175
|
|
|
101
|
-
|
|
176
|
+
---
|
|
102
177
|
|
|
103
|
-
|
|
178
|
+
## Agent lifecycle
|
|
104
179
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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
|
|
109
193
|
```
|
|
110
194
|
|
|
111
|
-
|
|
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"
|
|
115
|
-
```
|
|
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.
|
|
116
196
|
|
|
117
|
-
|
|
118
|
-
Send a message to ALL connected agents.
|
|
119
|
-
```
|
|
120
|
-
"Broadcast: deployment starting in 5 minutes, hold all merges"
|
|
121
|
-
```
|
|
197
|
+
---
|
|
122
198
|
|
|
123
|
-
|
|
124
|
-
Check for new messages.
|
|
125
|
-
```
|
|
126
|
-
"Check my inbox"
|
|
127
|
-
```
|
|
199
|
+
## Keystroke dispatch
|
|
128
200
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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"]
|
|
133
213
|
```
|
|
134
214
|
|
|
135
|
-
|
|
136
|
-
Post to the shared bulletin board (persistent announcements).
|
|
137
|
-
```
|
|
138
|
-
"Post to bulletin: v2.1 release branch created, all features frozen"
|
|
139
|
-
```
|
|
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.
|
|
140
216
|
|
|
141
|
-
|
|
142
|
-
Read the bulletin board.
|
|
143
|
-
```
|
|
144
|
-
"Show the bulletin board"
|
|
145
|
-
```
|
|
217
|
+
---
|
|
146
218
|
|
|
147
|
-
##
|
|
219
|
+
## Quick start
|
|
148
220
|
|
|
149
221
|
```bash
|
|
150
|
-
|
|
151
|
-
claudelink init --global
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
claudelink ui --stop # Stop the Command Center
|
|
155
|
-
claudelink install-hooks # Install autonomous-reply hooks (project)
|
|
156
|
-
claudelink install-hooks --global # Install hooks in ~/.claude/settings.json
|
|
157
|
-
claudelink install-hooks --uninstall # Remove ClaudeLink hooks
|
|
158
|
-
claudelink reset # Clear all data (fresh start)
|
|
159
|
-
claudelink help # Show help
|
|
222
|
+
# install + auto-configure all four supported CLIs globally
|
|
223
|
+
npx claudelink init --all --global
|
|
224
|
+
|
|
225
|
+
# restart your terminals — that's it
|
|
160
226
|
```
|
|
161
227
|
|
|
162
|
-
|
|
228
|
+
Open three terminals — mix CLIs however you like:
|
|
163
229
|
|
|
164
|
-
|
|
230
|
+
**Terminal 1** (Claude Code, advisor)
|
|
231
|
+
> "Register as a code reviewer working on the auth module."
|
|
165
232
|
|
|
166
|
-
|
|
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."
|
|
167
235
|
|
|
168
|
-
|
|
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."
|
|
169
238
|
|
|
170
|
-
|
|
171
|
-
- **Interval** — minutes between ticks (default 5, clamped to 1–120)
|
|
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.
|
|
172
240
|
|
|
173
|
-
|
|
241
|
+
---
|
|
174
242
|
|
|
175
|
-
|
|
176
|
-
- **iTerm2** → `osascript` matched by tty (no Accessibility prompt)
|
|
177
|
-
- **Apple Terminal** → currently unsupported (would need Accessibility permission; logged as skipped)
|
|
243
|
+
## Installation
|
|
178
244
|
|
|
179
|
-
|
|
245
|
+
### 1. Install the package
|
|
246
|
+
```bash
|
|
247
|
+
npm install -g claudelink
|
|
248
|
+
```
|
|
180
249
|
|
|
181
|
-
|
|
250
|
+
### 2. Add to your AI client
|
|
182
251
|
|
|
183
|
-
|
|
252
|
+
**Claude Code (global, recommended):**
|
|
253
|
+
```bash
|
|
254
|
+
claude mcp add --scope user claudelink -- claudelink-server
|
|
255
|
+
```
|
|
184
256
|
|
|
185
|
-
|
|
257
|
+
**Codex CLI (global):**
|
|
258
|
+
```bash
|
|
259
|
+
codex mcp add claudelink -- claudelink-server
|
|
260
|
+
# or: claudelink init --codex --global
|
|
261
|
+
```
|
|
186
262
|
|
|
263
|
+
**Gemini CLI (global):**
|
|
187
264
|
```bash
|
|
188
|
-
claudelink
|
|
189
|
-
claudelink
|
|
190
|
-
claudelink install-hooks --uninstall # clean rollback
|
|
265
|
+
claudelink init --gemini --global
|
|
266
|
+
# Merges mcpServers.claudelink into ~/.gemini/settings.json + writes ~/.gemini/GEMINI.md
|
|
191
267
|
```
|
|
192
268
|
|
|
193
|
-
|
|
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
|
+
```
|
|
194
274
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
275
|
+
**Everything at once (global):**
|
|
276
|
+
```bash
|
|
277
|
+
claudelink init --all --global # Claude + Codex + Gemini + Goose on one mesh
|
|
278
|
+
```
|
|
198
279
|
|
|
199
|
-
|
|
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
|
+
```
|
|
200
290
|
|
|
201
|
-
|
|
291
|
+
### 3. Restart your terminals
|
|
202
292
|
|
|
203
|
-
|
|
293
|
+
ClaudeLink tools appear automatically. Done.
|
|
204
294
|
|
|
205
|
-
|
|
295
|
+
### Multi-model support
|
|
206
296
|
|
|
207
|
-
|
|
208
|
-
- The auto-nudge scheduler skips advisor agents entirely
|
|
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.
|
|
209
298
|
|
|
210
|
-
|
|
299
|
+
### Local-first security
|
|
211
300
|
|
|
212
|
-
|
|
301
|
+
ClaudeLink is built to disappear into your dev environment, not become another SaaS dashboard you have to trust:
|
|
213
302
|
|
|
214
|
-
|
|
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.
|
|
215
309
|
|
|
216
|
-
|
|
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.
|
|
217
311
|
|
|
218
|
-
|
|
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)
|
|
219
316
|
|
|
220
|
-
|
|
317
|
+
---
|
|
221
318
|
|
|
222
|
-
|
|
319
|
+
## Command Center
|
|
223
320
|
|
|
224
|
-
|
|
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**.
|
|
225
322
|
|
|
226
|
-
|
|
227
|
-
- `CLAUDELINK_HOOK_STRICT=1` — surface hook errors to stderr instead of swallowing them. Default is fail-open (production safety).
|
|
228
|
-
- `CLAUDELINK_NOTIFY=off` — disable desktop notifications.
|
|
323
|
+
### What it gives you
|
|
229
324
|
|
|
230
|
-
|
|
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. |
|
|
231
332
|
|
|
232
|
-
|
|
333
|
+
The page auto-refreshes every 2 seconds. **Kill all servers** in the header drops the entire mesh in one click.
|
|
233
334
|
|
|
234
|
-
###
|
|
335
|
+
### Lifecycle
|
|
235
336
|
|
|
236
|
-
|
|
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.
|
|
237
338
|
|
|
238
|
-
|
|
239
|
-
- `init` → writes to `./CLAUDE.md` (current project only)
|
|
339
|
+
To opt out: `CLAUDELINK_UI=off` in your environment before starting any agent CLI.
|
|
240
340
|
|
|
241
|
-
|
|
341
|
+
```bash
|
|
342
|
+
claudelink ui # start it manually (or just spawn any agent)
|
|
343
|
+
claudelink ui --stop # graceful shutdown
|
|
344
|
+
```
|
|
242
345
|
|
|
243
|
-
|
|
346
|
+
---
|
|
244
347
|
|
|
245
|
-
|
|
348
|
+
## Available tools
|
|
246
349
|
|
|
247
|
-
|
|
248
|
-
- **Send updates proactively** to other agents when work is completed
|
|
249
|
-
- **Respond to messages immediately** without waiting for you to say "check inbox"
|
|
250
|
-
- **Post to the bulletin board** when making decisions that affect the project
|
|
350
|
+
Once connected, every agent session — Claude Code, Codex CLI, Gemini CLI, Goose, or any other MCP client — gains these MCP tools:
|
|
251
351
|
|
|
252
|
-
|
|
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"* |
|
|
253
361
|
|
|
254
|
-
|
|
362
|
+
`register` and `send` accept v1.1 options: `autonomousReply`, `expectsReply`, `parentMessageId` for thread tracking, FYI semantics, and per-agent autonomy control.
|
|
255
363
|
|
|
256
|
-
|
|
257
|
-
## ClaudeLink - Autonomous Agent Communication
|
|
364
|
+
---
|
|
258
365
|
|
|
259
|
-
|
|
260
|
-
terminals and can send you messages at any time via ClaudeLink.
|
|
366
|
+
## CLI
|
|
261
367
|
|
|
262
|
-
|
|
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
|
+
```
|
|
263
380
|
|
|
264
|
-
|
|
265
|
-
- AFTER completing any task: Check your inbox again using read_inbox
|
|
266
|
-
- If you receive a message, acknowledge it and act on it before moving on
|
|
267
|
-
- If a message requires you to change your current work, do so immediately
|
|
268
|
-
- If a message is from another agent asking for information, respond using send
|
|
269
|
-
before continuing your own work
|
|
270
|
-
- High-priority messages take precedence over your current task
|
|
381
|
+
---
|
|
271
382
|
|
|
272
|
-
|
|
383
|
+
## Autonomous replies (deep dive)
|
|
273
384
|
|
|
274
|
-
-
|
|
275
|
-
them an update
|
|
276
|
-
- If you encounter a problem that another agent's role could help with, send
|
|
277
|
-
them a message
|
|
278
|
-
- When you make a decision that affects the project, post it to the bulletin board
|
|
279
|
-
- If you're blocked waiting for another agent, say so and check inbox again
|
|
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.
|
|
280
386
|
|
|
281
|
-
###
|
|
387
|
+
### 1. Auto-nudge scheduler (primary, works for every CLI)
|
|
282
388
|
|
|
283
|
-
|
|
284
|
-
- "ask the [role]" — Send a message to that role and check inbox for their reply
|
|
285
|
-
- "tell the [role]" — Send a one-way message to that role
|
|
286
|
-
- "who's online" — Use get_agents to list all connected agents
|
|
287
|
-
- "update the board" — Use post_bulletin to post a status update
|
|
288
|
-
- "check the board" — Use get_bulletin to read the bulletin board
|
|
289
|
-
```
|
|
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:
|
|
290
390
|
|
|
291
|
-
|
|
391
|
+
- **On/off toggle** — Auto-nudge panel
|
|
392
|
+
- **Interval** — 1–120 minutes (default 5)
|
|
292
393
|
|
|
293
|
-
|
|
294
|
-
|------|-----------|
|
|
295
|
-
| `~/.claude/CLAUDE.md` | **Every project, every terminal** — recommended |
|
|
296
|
-
| `your-project/CLAUDE.md` | Only that specific project |
|
|
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:
|
|
297
395
|
|
|
298
|
-
|
|
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 |
|
|
299
401
|
|
|
300
|
-
|
|
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.
|
|
301
403
|
|
|
302
|
-
|
|
303
|
-
```
|
|
304
|
-
You: Fix the bug in auth.ts
|
|
305
|
-
Claude: (fixes the bug)
|
|
306
|
-
You: Now check your inbox
|
|
307
|
-
Claude: You have 1 message from the reviewer...
|
|
308
|
-
You: Send the reviewer an update
|
|
309
|
-
Claude: Message sent.
|
|
310
|
-
```
|
|
404
|
+
Settings persist at `~/.claudelink/scheduler.json`. Audit log at `~/.claudelink/scheduler.log`.
|
|
311
405
|
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
Done. I fixed the token validation bug. The reviewer had already
|
|
321
|
-
flagged the exact line, so I used their suggestion.
|
|
406
|
+
### 2. Stop hook (Claude-Code-only low-latency supplement)
|
|
407
|
+
|
|
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:
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
claudelink install-hooks # project-scoped
|
|
412
|
+
claudelink install-hooks --global # writes ~/.claude/settings.json
|
|
413
|
+
claudelink install-hooks --uninstall # clean rollback
|
|
322
414
|
```
|
|
323
415
|
|
|
324
|
-
|
|
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.
|
|
325
417
|
|
|
326
|
-
|
|
418
|
+
The hook emits `{"decision": "block", "reason": "..."}` directing the Claude agent to call `read_inbox`. Three guards prevent runaway loops:
|
|
327
419
|
|
|
328
|
-
|
|
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)
|
|
329
423
|
|
|
330
|
-
|
|
331
|
-
- **Terminal 1** (reviewer): Reviews code, sends findings to developer
|
|
332
|
-
- **Terminal 2** (developer): Receives feedback, implements fixes, notifies reviewer when ready
|
|
424
|
+
Set any to `0` to disable. Decisions log to `~/.claudelink/auto-fire.log`.
|
|
333
425
|
|
|
334
|
-
|
|
335
|
-
- **Terminal 1** (developer): Writes implementation
|
|
336
|
-
- **Terminal 2** (tester): Runs tests, reports failures back to developer
|
|
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.
|
|
337
427
|
|
|
338
|
-
###
|
|
339
|
-
- **Terminal 1** (architect): Posts design decisions to bulletin board
|
|
340
|
-
- **Terminal 2** (developer): Implements features, asks architect for clarification
|
|
341
|
-
- **Terminal 3** (reviewer): Reviews code, sends feedback to developer
|
|
342
|
-
- **Terminal 4** (ops): Monitors build pipeline, broadcasts deployment status
|
|
428
|
+
### Per-agent opt-out
|
|
343
429
|
|
|
344
|
-
|
|
345
|
-
- **Terminal 1** (dev-auth): Working on authentication
|
|
346
|
-
- **Terminal 2** (dev-api): Working on API endpoints
|
|
347
|
-
- Both agents coordinate to avoid conflicts and share interface contracts
|
|
430
|
+
Two ways to silence an agent:
|
|
348
431
|
|
|
349
|
-
|
|
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).
|
|
350
434
|
|
|
351
|
-
|
|
352
|
-
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
353
|
-
│ Claude Code │ │ Claude Code │ │ Claude Code │
|
|
354
|
-
│ (Terminal 1) │ │ (Terminal 2) │ │ (Terminal 3) │
|
|
355
|
-
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
356
|
-
│ │ │
|
|
357
|
-
│ stdio │ stdio │ stdio
|
|
358
|
-
│ │ │
|
|
359
|
-
┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
|
|
360
|
-
│ MCP Server │ │ MCP Server │ │ MCP Server │
|
|
361
|
-
│ (Process 1) │ │ (Process 2) │ │ (Process 3) │
|
|
362
|
-
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
363
|
-
│ │ │
|
|
364
|
-
└────────────────────┼────────────────────┘
|
|
365
|
-
│
|
|
366
|
-
┌────────▼────────┐
|
|
367
|
-
│ SQLite (WAL) │
|
|
368
|
-
│ ~/.claudelink/ │
|
|
369
|
-
│ nexus.db │
|
|
370
|
-
└─────────────────┘
|
|
371
|
-
```
|
|
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.
|
|
372
436
|
|
|
373
|
-
|
|
437
|
+
### Per-message opt-out
|
|
374
438
|
|
|
375
|
-
|
|
376
|
-
- Zero configuration — single file, no server to run
|
|
377
|
-
- WAL mode handles concurrent readers and writers
|
|
378
|
-
- Survives process crashes — no data loss
|
|
379
|
-
- Portable across macOS, Linux, and Windows
|
|
439
|
+
Send with `expectsReply: false` for FYI / informational pings.
|
|
380
440
|
|
|
381
|
-
###
|
|
382
|
-
1. Agent A calls `send(to="developer", message="...")`
|
|
383
|
-
2. MCP Server A writes a row to the `messages` table
|
|
384
|
-
3. Agent B calls `read_inbox()`
|
|
385
|
-
4. MCP Server B reads unread rows from `messages` and marks them read
|
|
386
|
-
5. Agent B receives the message and can act on it
|
|
441
|
+
### Desktop notifications
|
|
387
442
|
|
|
388
|
-
|
|
389
|
-
- Agents register with a `role` and their process `pid`
|
|
390
|
-
- A heartbeat updates `last_seen` every 30 seconds
|
|
391
|
-
- When listing agents, dead processes (checked via `kill -0 pid`) are automatically pruned
|
|
392
|
-
- No manual cleanup needed
|
|
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`.
|
|
393
444
|
|
|
394
|
-
|
|
445
|
+
### Debug knobs
|
|
395
446
|
|
|
396
|
-
|
|
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
|
|
397
450
|
|
|
398
|
-
|
|
399
|
-
```json
|
|
400
|
-
{
|
|
401
|
-
"mcpServers": {
|
|
402
|
-
"claudelink": {
|
|
403
|
-
"type": "stdio",
|
|
404
|
-
"command": "claudelink-server"
|
|
405
|
-
}
|
|
406
|
-
}
|
|
407
|
-
}
|
|
408
|
-
```
|
|
451
|
+
---
|
|
409
452
|
|
|
410
|
-
|
|
411
|
-
```bash
|
|
412
|
-
claude mcp add --scope user claudelink -- claudelink-server
|
|
413
|
-
```
|
|
453
|
+
## Autonomous mode setup
|
|
414
454
|
|
|
415
|
-
|
|
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:
|
|
416
456
|
|
|
417
|
-
|
|
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` |
|
|
418
463
|
|
|
419
|
-
|
|
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.
|
|
420
465
|
|
|
421
|
-
|
|
466
|
+
### What it teaches the agent
|
|
422
467
|
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
468
|
+
Every instruction file (CLAUDE.md / AGENTS.md / GEMINI.md / .goosehints) tells the agent to:
|
|
469
|
+
|
|
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
|
|
426
474
|
|
|
427
|
-
|
|
428
|
-
claude
|
|
475
|
+
### Without vs with autonomous mode
|
|
429
476
|
|
|
430
|
-
|
|
431
|
-
|
|
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.
|
|
432
493
|
```
|
|
433
494
|
|
|
434
|
-
|
|
495
|
+
One instruction from you. All the communication happens automatically.
|
|
435
496
|
|
|
436
|
-
|
|
497
|
+
---
|
|
437
498
|
|
|
438
|
-
|
|
439
|
-
> "Register as a code reviewer working on the auth module"
|
|
499
|
+
## Use cases
|
|
440
500
|
|
|
441
|
-
|
|
442
|
-
|
|
501
|
+
### 🔍 Code review pipeline
|
|
502
|
+
- **Reviewer** scans diffs, sends findings to developer
|
|
503
|
+
- **Developer** receives feedback, implements fixes, notifies reviewer when ready
|
|
443
504
|
|
|
444
|
-
###
|
|
505
|
+
### 🧪 Test-driven development
|
|
506
|
+
- **Developer** writes implementation
|
|
507
|
+
- **Tester** runs tests, reports failures back to developer
|
|
445
508
|
|
|
446
|
-
|
|
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
|
|
447
514
|
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
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
|
|
451
519
|
|
|
452
|
-
|
|
453
|
-
|
|
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
|
|
454
525
|
|
|
455
|
-
|
|
456
|
-
claude --allowedTools "mcp__claudelink__*"
|
|
457
|
-
```
|
|
526
|
+
---
|
|
458
527
|
|
|
459
|
-
|
|
528
|
+
## Configuration
|
|
460
529
|
|
|
461
|
-
|
|
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.
|
|
462
531
|
|
|
463
|
-
|
|
532
|
+
### Configuration files (per CLI)
|
|
464
533
|
|
|
465
|
-
|
|
534
|
+
Each CLI has its own MCP config file format. ClaudeLink writes the right one for whichever flag you pass to `claudelink init`:
|
|
466
535
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
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, ... } }` |
|
|
542
|
+
|
|
543
|
+
---
|
|
471
544
|
|
|
472
|
-
|
|
545
|
+
## Architecture details
|
|
473
546
|
|
|
474
|
-
|
|
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
|
|
475
552
|
|
|
476
|
-
|
|
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
|
|
477
559
|
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
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
|
|
481
565
|
|
|
482
|
-
|
|
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:
|
|
483
573
|
|
|
484
574
|
```bash
|
|
485
|
-
|
|
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
|
|
486
580
|
```
|
|
487
581
|
|
|
488
|
-
|
|
582
|
+
Each CLI reads its own config on startup, sees ClaudeLink is configured, connects automatically. The tools just appear.
|
|
489
583
|
|
|
490
|
-
|
|
584
|
+
### How do I disable ClaudeLink?
|
|
491
585
|
|
|
492
|
-
|
|
493
|
-
# 1. Remove from project config
|
|
494
|
-
# Edit .mcp.json and delete the claudelink entry
|
|
586
|
+
You do not need to restart your computer. Pick one:
|
|
495
587
|
|
|
496
|
-
|
|
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
|
|
497
593
|
claude mcp remove --scope user claudelink
|
|
498
|
-
|
|
499
|
-
# 3. Uninstall the package
|
|
500
594
|
npm uninstall -g claudelink
|
|
501
|
-
|
|
502
|
-
# 4. Delete all ClaudeLink data
|
|
503
595
|
rm -rf ~/.claudelink
|
|
504
596
|
```
|
|
505
597
|
|
|
506
|
-
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.
|
|
507
|
-
|
|
508
598
|
### Can I temporarily disable it without deleting anything?
|
|
509
599
|
|
|
510
|
-
Yes
|
|
600
|
+
Yes — set `"disabled": true` in the `.mcp.json` block:
|
|
511
601
|
|
|
512
602
|
```json
|
|
513
603
|
{
|
|
@@ -521,54 +611,65 @@ Yes. In your `.mcp.json`, add `"disabled": true`:
|
|
|
521
611
|
}
|
|
522
612
|
```
|
|
523
613
|
|
|
524
|
-
|
|
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.
|
|
525
627
|
|
|
526
628
|
---
|
|
527
629
|
|
|
528
630
|
## Contributing
|
|
529
631
|
|
|
530
|
-
|
|
632
|
+
This is open source. Contributions welcome.
|
|
531
633
|
|
|
532
|
-
### Development Setup
|
|
533
634
|
```bash
|
|
534
635
|
git clone https://github.com/jaysidd/claudelink.git
|
|
535
636
|
cd claudelink
|
|
536
637
|
npm install
|
|
537
638
|
npm run build
|
|
639
|
+
node dist/index.js # run MCP server directly
|
|
640
|
+
node dist/cli.js status # exercise CLI
|
|
538
641
|
```
|
|
539
642
|
|
|
540
|
-
###
|
|
541
|
-
```bash
|
|
542
|
-
# Run the MCP server directly (for debugging)
|
|
543
|
-
node dist/index.js
|
|
643
|
+
### Roadmap
|
|
544
644
|
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
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**
|
|
549
654
|
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
- **File sharing**: Agents can share file paths or code snippets with structured formatting
|
|
554
|
-
- **Priority notifications**: Interrupt the current agent when a high-priority message arrives
|
|
555
|
-
- **Agent templates**: Pre-built role configurations for common workflows
|
|
556
|
-
- **Webhooks**: Notify external services when agents communicate
|
|
557
|
-
- **Encryption**: Encrypt messages at rest in the database
|
|
558
|
-
- **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
|
+
---
|
|
559
658
|
|
|
560
659
|
## License
|
|
561
660
|
|
|
562
|
-
MIT
|
|
661
|
+
MIT — see [LICENSE](LICENSE).
|
|
563
662
|
|
|
564
663
|
---
|
|
565
664
|
|
|
566
|
-
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.
|
|
567
668
|
|
|
568
|
-
|
|
669
|
+
Bug reports, feature requests, and PRs welcome at [github.com/jaysidd/claudelink/issues](https://github.com/jaysidd/claudelink/issues).
|
|
569
670
|
|
|
570
671
|
---
|
|
571
672
|
|
|
572
673
|
### Keywords
|
|
573
674
|
|
|
574
|
-
claudelink, claude link,
|
|
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.
|