ClaudeLink

The hub where your AI agents connect.

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.

Terminal 1 (reviewer)  ──┐
Terminal 2 (developer) ──┤── ClaudeLink ── SQLite
Terminal 3 (tester)    ──┤
Terminal 4 (ops)       ──┘

Quick Start

# Install and configure (one command)
npx claudelink init

Restart your Claude Code terminals. That's it.

In Terminal 1:

"Register as a code reviewer working on the auth module"

In Terminal 2:

"Register as a developer. Check inbox for messages from the reviewer."

Terminal 1 says to Claude:

"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."

Terminal 2 says to Claude:

"Read my inbox"

The developer agent receives the reviewer's message and can act on it.

Installation

Step 1: Install the package

npm install -g claudelink

Step 2: Add to Claude Code (pick one)

Global (recommended — works in every project):

claude mcp add --scope user claudelink -- claudelink-server

This adds ClaudeLink to ~/.claude.json so it's available in every Claude Code session, in every project. One command, done forever.

Per-Project (only this project):

cd your-project
npx claudelink init

This adds ClaudeLink to .mcp.json in your project directory only.

Step 3: Restart Claude Code

Close and reopen Claude Code in your terminals. ClaudeLink tools will be available automatically.

Requirements

• Node.js 18+
• Claude Code CLI

How It Works

ClaudeLink is an MCP (Model Context Protocol) 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.

There is no daemon or background service. Each Claude Code session spawns its own MCP server process, and they coordinate through the shared database.

Available Tools

Once connected, Claude Code gains these tools:

register

Register this agent with a role so others can find it.

"Register as a developer working on the payment system"

send

Send a direct message to an agent by role.

"Send a high-priority message to the reviewer: the fix is ready for re-review"

broadcast

Send a message to ALL connected agents.

"Broadcast: deployment starting in 5 minutes, hold all merges"

read_inbox

Check for new messages.

"Check my inbox"

get_agents

See who's online.

"Show me all connected agents"

post_bulletin

Post to the shared bulletin board (persistent announcements).

"Post to bulletin: v2.1 release branch created, all features frozen"

get_bulletin

Read the bulletin board.

"Show the bulletin board"

CLI Commands

claudelink init            # Configure for current project
claudelink init --global   # Configure globally
claudelink status          # Show registered agents and message stats
claudelink reset           # Clear all data (fresh start)
claudelink help            # Show help

Autonomous Mode (Recommended)

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.

Automatic Setup

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:

• init --global → writes to ~/.claude/CLAUDE.md (all projects)
• init → writes to ./CLAUDE.md (current project only)

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.

What It Teaches Claude

The CLAUDE.md file instructs every Claude Code session to:

• Check inbox automatically before and after every task
• Send updates proactively to other agents when work is completed
• Respond to messages immediately without waiting for you to say "check inbox"
• Post to the bulletin board when making decisions that affect the project

Manual Fallback

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:

## ClaudeLink - Autonomous Agent Communication

You are part of a multi-agent team. Other agents may be running in separate
terminals and can send you messages at any time via ClaudeLink.

### Automatic Inbox Checking

- BEFORE starting any task: Check your inbox using read_inbox first
- AFTER completing any task: Check your inbox again using read_inbox
- If you receive a message, acknowledge it and act on it before moving on
- If a message requires you to change your current work, do so immediately
- If a message is from another agent asking for information, respond using send
  before continuing your own work
- High-priority messages take precedence over your current task

### Autonomous Collaboration

- When you finish work that another agent might care about, proactively send
  them an update
- If you encounter a problem that another agent's role could help with, send
  them a message
- When you make a decision that affects the project, post it to the bulletin board
- If you're blocked waiting for another agent, say so and check inbox again

### Communication Shortcuts

- "check response" or "check messages" — Use read_inbox to check for new messages
- "ask the [role]" — Send a message to that role and check inbox for their reply
- "tell the [role]" — Send a one-way message to that role
- "who's online" — Use get_agents to list all connected agents
- "update the board" — Use post_bulletin to post a status update
- "check the board" — Use get_bulletin to read the bulletin board

Per-Project vs Global

File	Applies to
~/.claude/CLAUDE.md	Every project, every terminal — recommended
your-project/CLAUDE.md	Only that specific project

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.

What Autonomous Mode Looks Like

Without autonomous mode:

You: Fix the bug in auth.ts
Claude: (fixes the bug)
You: Now check your inbox
Claude: You have 1 message from the reviewer...
You: Send the reviewer an update
Claude: Message sent.

With autonomous mode:

You: Fix the bug in auth.ts
Claude: (checks inbox — sees a tip from the reviewer about the bug)
       (fixes the bug using the reviewer's guidance)
       (sends the reviewer: "Fixed it, here's what I changed...")
       (posts to bulletin: "auth.ts bug fixed")
       (checks inbox again — no new messages)
       Done. I fixed the token validation bug. The reviewer had already
       flagged the exact line, so I used their suggestion.

One instruction from you. All the communication happens automatically.

---

Use Cases

Code Review Pipeline

• Terminal 1 (reviewer): Reviews code, sends findings to developer
• Terminal 2 (developer): Receives feedback, implements fixes, notifies reviewer when ready

Test-Driven Development

• Terminal 1 (developer): Writes implementation
• Terminal 2 (tester): Runs tests, reports failures back to developer

Full Team Simulation

• Terminal 1 (architect): Posts design decisions to bulletin board
• Terminal 2 (developer): Implements features, asks architect for clarification
• Terminal 3 (reviewer): Reviews code, sends feedback to developer
• Terminal 4 (ops): Monitors build pipeline, broadcasts deployment status

Parallel Feature Development

• Terminal 1 (dev-auth): Working on authentication
• Terminal 2 (dev-api): Working on API endpoints
• Both agents coordinate to avoid conflicts and share interface contracts

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Claude Code  │     │  Claude Code  │     │  Claude Code  │
│  (Terminal 1) │     │  (Terminal 2) │     │  (Terminal 3) │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       │ stdio              │ stdio              │ stdio
       │                    │                    │
┌──────▼───────┐     ┌──────▼───────┐     ┌──────▼───────┐
│  MCP Server   │     │  MCP Server   │     │  MCP Server   │
│  (Process 1)  │     │  (Process 2)  │     │  (Process 3)  │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
                   ┌────────▼────────┐
                   │   SQLite (WAL)   │
                   │  ~/.claudelink/  │
                   │    nexus.db      │
                   └─────────────────┘

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.

Why SQLite?

• Zero configuration — single file, no server to run
• WAL mode handles concurrent readers and writers
• Survives process crashes — no data loss
• Portable across macOS, Linux, and Windows

Message Flow

1. Agent A calls send(to="developer", message="...")
2. MCP Server A writes a row to the messages table
3. Agent B calls read_inbox()
4. MCP Server B reads unread rows from messages and marks them read
5. Agent B receives the message and can act on it

Agent Lifecycle

• Agents register with a role and their process pid
• A heartbeat updates last_seen every 30 seconds
• When listing agents, dead processes (checked via kill -0 pid) are automatically pruned
• No manual cleanup needed

Configuration

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.

.mcp.json (per-project)

{
  "mcpServers": {
    "claudelink": {
      "type": "stdio",
      "command": "claudelink-server"
    }
  }
}

~/.claude.json (global via CLI)

claude mcp add --scope user claudelink -- claudelink-server

FAQ

Wait, does npx claudelink init start Claude?

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.

Your daily workflow is exactly the same as before:

# Terminal 1 — start Claude normally
claude

# Terminal 2 — start Claude normally
claude

# Terminal 3 — start Claude with full auto-permissions
claude --dangerously-skip-permissions

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.

Then you just talk naturally:

Terminal 1:

"Register as a code reviewer working on the auth module"

Terminal 2:

"Register as a developer. Send a message to the reviewer asking if auth.ts looks good."

How do I start Claude with different permission modes?

ClaudeLink works with all Claude Code startup modes:

# Standard mode (Claude asks before using tools)
claude

# Skip all permission prompts
claude --dangerously-skip-permissions

# Auto-approve only ClaudeLink tools (recommended)
claude --allowedTools "mcp__claudelink__*"

How do I disable ClaudeLink?

You do not need to restart your computer. There are several options depending on what you want:

Option 1: Disable for a specific project

Remove the claudelink entry from your project's .mcp.json:

# Open the config
nano .mcp.json

Delete the "claudelink": { ... } block, save, and restart Claude Code in that terminal. ClaudeLink tools will no longer appear for that project.

Option 2: Disable globally

If you installed globally, remove it via CLI:

claude mcp remove --scope user claudelink

Option 3: Clear all data but keep it installed

npx claudelink reset

This deletes the database (all messages, agents, bulletin entries) but keeps the config so you can start fresh.

Option 4: Full uninstall (remove everything)

# 1. Remove from project config
#    Edit .mcp.json and delete the claudelink entry

# 2. Remove from global config
claude mcp remove --scope user claudelink

# 3. Uninstall the package
npm uninstall -g claudelink

# 4. Delete all ClaudeLink data
rm -rf ~/.claudelink

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.

Can I temporarily disable it without deleting anything?

Yes. In your .mcp.json, add "disabled": true:

{
  "mcpServers": {
    "claudelink": {
      "type": "stdio",
      "command": "claudelink-server",
      "disabled": true
    }
  }
}

Set it back to false (or remove the line) to re-enable. Restart Claude Code after changing.

---

Contributing

Contributions are welcome! This is an open-source project and we'd love the community to help build on it.

Development Setup

git clone https://github.com/jaysidd/claudelink.git
cd claudelink
npm install
npm run build

Testing Locally

# Run the MCP server directly (for debugging)
node dist/index.js

# Test the CLI
node dist/cli.js init
node dist/cli.js status

Ideas for Contributions

• Agent groups/channels: Named channels for topic-based communication
• Message history: Tool to view past messages (not just unread)
• File sharing: Agents can share file paths or code snippets with structured formatting
• Priority notifications: Interrupt the current agent when a high-priority message arrives
• Web dashboard: A local web UI to visualize agent activity
• Agent templates: Pre-built role configurations for common workflows
• Webhooks: Notify external services when agents communicate
• Encryption: Encrypt messages at rest in the database
• Multi-machine support: Replace SQLite with a networked backend for remote agent communication

License

MIT License — see LICENSE for details.

---

Built by Jay Siddiqi.

If ClaudeLink helps your workflow, give it a star and share it with your team.

---

Keywords

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