AgentLink 🚀

Universal, cross-machine, cross-provider collaboration & context layer for AI coding agents.

AgentLink lets several AI coding agents — Claude Code, OpenAI Codex, Cursor, Antigravity, OpenCode, Roo Code — work on the same codebase at once without colliding. It runs as a small daemon (control plane) that every agent connects to over the Model Context Protocol (MCP). Agents announce who they are, claim the files they're editing, exchange compact context packets, and hand off tasks with test evidence — locally, across a LAN, or across the internet.

Install: npm install -g @aj69op/agentlink → run agentlink Package: @aj69op/agentlink v1.1.0 (latest) · Node ≥ 22.5 Live mesh: agentlink-sn0b.onrender.com (public health/version endpoint)

Why AgentLink?

Multi-agent coding fails in three predictable ways. AgentLink targets each one:

1. Silent file overwrites → advisory file claims with real-time overlap detection warn peers before two agents edit the same path.
2. Context amnesia & bloat → instead of dumping whole transcripts or raw diffs, the Context Intelligence Engine sends compact, structured packets (task, files_changed, summary, impact, action_required, provenance) only to the agents whose work intersects the change.
3. Lossy task handoffs → evidence-rich handoffs carry tests run, pass/fail status, known risks, decisions, and next steps.

Think of it as Slack + a shared whiteboard for AI agents: they message and broadcast what changed (Slack), and everyone sees who holds which file in real time (whiteboard).

Architecture

                       ┌──────────────── AgentLink daemon (control plane) ────────────────┐
                       │  SQLite mesh: agents · messages · claims · context · tasks        │
                       │  ★ Context Intelligence Engine: relevance router + packetizer     │
                       │  MCP server (10 tools) · REST API · WebSocket hub · Web dashboard  │
                       └───────▲───────────────▲──────────────────▲──────────────▲─────────┘
             local MCP (stdio) │  remote MCP    │ (HTTP+token)      │ WebSocket    │ REST
                               │  over LAN/tunnel│                  │              │
                        Claude Code        Friend's Codex        Dashboard    talk / CLI /
                        Codex, Cursor,     Cursor, Claude…       (browser)    git hooks / CI
                        OpenCode, Roo…     (another machine)

Two ways an agent connects:

• Local MCP — agent + daemon on the same machine; tools read/write the local DB.
• Remote MCP — agent talks to a remote daemon over HTTP (LAN IP or public tunnel), so a teammate's editor joins your mesh across the internet.

Quick start

Use it (installed CLI)

npm install -g @aj69op/agentlink        # or: npx @aj69op/agentlink <command>
agentlink daemon --port 3721            # dashboard at http://localhost:3721
agentlink demo --port 3721              # scripted 2-agent demo (fills the dashboard)

Connect your AI editors in one step

# Local daemon:
agentlink join http://localhost:3721 --workspace A2A --role backend
# Remote/hosted daemon (with auth):
agentlink join https://your-host --secret "<token>" --workspace A2A --role frontend

join auto-detects installed harnesses (Codex, Cursor, OpenCode, Roo, Claude Code) and wires each one — no manual config editing. The optional --role (e.g. backend, frontend, qa, smart-contracts) lets peers message you by function, not agent id.

Team roles & smart routing

Tag each teammate's agent with a --role, then agents target roles instead of ids — agentlink_send_message accepts to_role: "backend" and the daemon fans the message out to every active agent in that role (falling back to a workspace broadcast if none are online). Available on join, mcp, and every setup-*.

Knowledge auto-reply: when an agent sends a question (type: "ask"), the daemon first checks whether a peer has already published the answer as a context packet and, on a confident match, answers instantly citing the source packet + commit (zero LLM tokens) — no waiting on the peer. Misses fall through to the role peer, whose agent replies.

Build from source

cd agentlink
npm install
npm run build
node dist/index.js daemon --port 3721

Connecting a single harness

join handles all of these at once, but you can wire one at a time:

| Harness | Command | | :--- | :--- | | OpenAI Codex | agentlink setup-codex --name Codex --workspace A2A (writes ~/.codex/config.toml) | | Cursor | agentlink setup-cursor --name Cursor --workspace A2A (~/.cursor/mcp.json; --project for repo-local) | | OpenCode | agentlink setup-opencode --name OpenCode --workspace A2A (~/.config/opencode/opencode.json) | | Roo Code | agentlink setup-roo --name Roo --workspace A2A (.roo/mcp.json in the repo) | | Claude Code | claude mcp add-json -s user agentlink '{"type":"stdio","command":"node","args":["<abs>/dist/index.js","mcp","--provider","claude","--workspace","A2A"]}' | | Antigravity | add an agentlink server to .agents/mcp_config.json running node <abs>/dist/index.js mcp --provider antigravity |

Each setup-* (and join) accepts --remote <url> and --secret <token> to point at a remote mesh. All are idempotent and non-destructive (they merge, preserving other servers). Adapters spawn node directly (not npx.cmd) to avoid the Windows spawn EINVAL issue. Details per harness: docs/codex-adapter.md, docs/cursor-adapter.md, docs/opencode-roo-adapters.md, docs/remote-mcp.md.

Authentication

Open by default for local use. Before exposing the daemon over a LAN or the internet, enable bearer-token auth:

agentlink daemon --port 3721 --secret "a-long-random-secret"   # or set AGENTLINK_SECRET

All /api/v1/* (except /health) and the WebSocket then require Authorization: Bearer <secret>; /health and the A2A discovery card stay public. Clients and the dashboard send the token automatically. See docs/authentication.md.

Deploy verification: /api/v1/health and the A2A discovery card both report the running version, so you can confirm which build a remote/hosted daemon is serving with a single public request (curl https://<host>/api/v1/health).

Cross-machine

Same LAN — zero-config discovery (mDNS):

agentlink daemon --port 3721 --discovery    # advertise
agentlink discover                          # find peers from another machine

Anywhere — public tunnel (ngrok / cloudflared):

agentlink daemon --port 3721 --secret "my-secret" --tunnel
# 🌍 Tunnel: https://<random>.trycloudflare.com

Auto-detects ngrok then cloudflared (--tunnel-provider to force one). Always pair a public tunnel with --secret. See docs/cross-machine.md.

Teammates then join with one line:

npx @aj69op/agentlink join https://<your-url> --secret "<token>" --workspace A2A

Git & CI automation

agentlink install-hooks --workspace A2A        # post-commit → shares each commit as a context packet
agentlink test-report --run "npm test"         # run tests, broadcast pass/fail (or hand off with evidence)

The hook never blocks a commit; test-report parses vitest/pytest/jest and preserves the exit code (CI-safe). See docs/git-hooks.md.

Deploy (host the mesh)

The daemon is a Docker image, so it runs anywhere. Fastest reliable free path is Render + an uptime pinger (a render.yaml blueprint is included); a VPS or Oracle Always-Free VM gives a dedicated always-on box.

docker build -t agentlink .
docker run -d --restart=always -p 3721:3721 \
  -e AGENTLINK_SECRET="a-long-random-secret" -v agentlink-data:/data agentlink
# or: docker compose up -d

Full guide (Render blueprint, VPS, Oracle Cloud, tunnels, keep-alive): docs/deploy.md. The daemon binds --port, else AGENTLINK_PORT, else PORT (cloud hosts inject it), else 3721.

Standalone binaries (no Node needed): npm run build:binary → dist-bin/agentlink.exe; npm run build:binary:all also cross-builds Linux/macOS (macOS needs codesign --sign - on a Mac).

MCP tools

| Tool | Purpose | | :--- | :--- | | agentlink_identify | Register identity, provider, machine, workspace, current focus | | agentlink_list_agents | View connected peers, their active tasks and claimed files | | agentlink_send_message | Direct message, question, or broadcast — with optional rich media attachments (files, images, diffs, links) | | agentlink_inbox | Read incoming messages / questions / context updates (attachments included) | | agentlink_reply | Answer a specific message (correlated by conversation ID), optionally with attachments | | agentlink_claim_work | Claim file/module paths with conflict & overlap warnings | | agentlink_release_work | Release claims when done | | agentlink_share_context | Push a compact context packet (summary, impact, action) — optionally with attachments | | agentlink_get_context | Retrieve recent context packets for the workspace | | agentlink_handoff_work | Transfer a task with structured evidence and test results |

REST resources mirror these under /api/v1/*; the A2A discovery card is at /.well-known/agent.json.

Testing

npm test        # 93 tests across 16 files (vitest)

Covers claims/overlap, relevance routing, HTTP + WebSocket, auth (incl. WS token), remote-MCP, the adapters, discovery encode/decode, git hooks, test-report parsing, team roles + to_role routing, knowledge auto-reply, rich media attachments, and a 3-agent e2e flow.

Documentation

• docs/beginner-guide.md — Complete Beginner's Guide (Zero-to-Hero, how to connect and use)
• docs/rich-media.md — rich media attachments (files, images, diffs, links)
• docs/authentication.md — bearer-token auth
• docs/cross-machine.md — mDNS discovery + tunnels
• docs/remote-mcp.md — join a mesh on another machine
• docs/git-hooks.md — post-commit hook + test-report
• docs/deploy.md — hosting (Render, VPS, Oracle, Docker)
• docs/codex-adapter.md · docs/cursor-adapter.md · docs/opencode-roo-adapters.md — per-harness setup
• TEAM_HANDOFF.md — plain-English explainer · BUILD_STATUS.md — status snapshot
• HANDOFF.md — staged roadmap · CONTRIBUTING.md — keep the stage docs current with every change

License

MIT