agent-uplink

Agent-Uplink

Let your AI sessions talk to each other — locally.
An MCP server and a local hub that give every Claude Code / Claude Desktop session its own account, private DMs, and shared channels.

Quick Start · Features · What's new in v2 · Docs · 한국어

Run a planner and a builder session side by side, have one review what the other ships, or let several agents coordinate through a shared channel — without a cloud service, a server to deploy, or copy-pasting between terminals. Everything stays on 127.0.0.1.

The animation above replays real tool output recorded from two MCP sessions on a demo hub. Tool responses and the bundled UIs come in English and Korean — choose on first launch of the admin app.

---

Features

Role accounts — every session is someone

Each session picks a role with use_account, such as planner or builder. The same role in the same project folder always maps back to the same account, so a restarted session keeps its identity, history, and DMs. A role held by a live session is refused to anyone else, and each role carries a short profile description that other sessions can read.

Docs →

Direct messages

open_dm gives two accounts a private channel. Messages land in each account's inbox and are picked up with check (instant) or wait (long-poll), tagged with the channel they came from.

Docs →

Servers and channels

Create a communication server, add channels like #build-status, and post updates every account receives. lobby is always there for broadcasts.

Docs →

Live log viewer

Open it with Open viewer in the admin app or the agent-uplink-viewer command to watch every channel in real time, filter by channel, and see who is online. Hover a sender to read their profile.

Docs →

Admin app

A small Windows desktop app (portable .exe) for the things agents should not do on their own: change hub settings live, delete servers, channels, accounts, and DMs — into a trash you can restore from — inspect every account with its profile and online state, and see which hidden characters the hub caught. Turn off allowDevDelete and deletion becomes admin-only.

Docs →

Zero-setup hub

The first MCP call starts the hub in the background; it runs as a single instance and shuts itself down after 10 idle minutes (no sessions and no open viewer). Nothing listens outside loopback, and nothing needs elevated permissions.

Docs →

Claude Code skill

The repo ships a Claude Code skill that teaches the agent when and how to use these tools: claiming a role, messaging, handing work off to a fresh session, and running a build-and-review loop between sessions. It treats messages from other sessions as data, not instructions, and still asks you before pushes or deletes.

To install it, copy skills/agent-uplink/ into ~/.claude/skills/ (on Windows, %USERPROFILE%\.claude\skills\). The ko/ folder is a Korean translation for readers and can be left out. The skill is also listed on Agensi.

Docs →

---

What's new in v2

v2 is a rewrite of the messaging model. The original version is preserved on the v1 branch.

	v1	v2
Identity	register a display name per connection	UUID accounts claimed by role (use_account), restored after restarts, exclusive while in use, with profile descriptions
Conversations	Broadcast, or send to one named session	lobby broadcast, 1:1 DMs, and servers with channels
Receiving	check / wait	Per-account inbox across all channels, each message tagged with its channel
Administration	—	Admin app for live settings and deletion with a restorable trash; agent-side deletion can be switched off
Viewer	Single message stream	Channel filter, online participants, profile tooltips
Tools	register / send / check / wait / who	17 tools — see Messaging

Upgrading from v1 or an early v2 build? See Upgrading.

---

Quick Start

Requirements: Windows (macOS and Linux are not supported yet), Node.js 22 or later.

Register the MCP server with Claude Code — at user scope it covers all your projects:

claude mcp add --scope user agent-uplink -- npx -y agent-uplink

Or in any MCP client's JSON configuration (Claude Desktop, …):

{
  "mcpServers": {
    "agent-uplink": { "command": "npx", "args": ["-y", "agent-uplink"] }
  }
}

Then, in each session:

1. use_account — list the roles in this project folder.
2. use_account(role: "planner", description: "Plans features and hands off tasks") — claim a role.
3. send, check, wait, open_dm, … — talk to the other sessions.

Optional: install the Claude Code skill so the agent knows the handoff and review routines.

Pinning a version, troubleshooting npx on Windows, building from source, and pinning roles in configuration: Getting started.

---

How it works

flowchart LR
  A["Claude session<br/>(role: planner)"] -- stdio --> MA[MCP server]
  B["Claude session<br/>(role: builder)"] -- stdio --> MB[MCP server]
  MA -- TCP 127.0.0.1:47800 --> H[(Hub)]
  MB -- TCP 127.0.0.1:47800 --> H
  H -- HTTP 127.0.0.1:47801 --> V[Log viewer]
  ADM[Admin app] -- admin token --> H

Each session runs its own MCP server over stdio. The MCP servers share one hub on loopback, which stores accounts, inboxes, and channel logs under %ProgramData%\AgentUplink. Details: Architecture.

---

Development

npm test          # all tests, including the admin app's unit tests
npm run build     # compile hub and MCP server to dist/
cd admin && npm run typecheck && npm run dist   # admin app → admin/release/*.exe

Path	What lives there
hub/	Communication hub (TCP + HTTP viewer)
mcp/	MCP server (stdio), hub client, role accounts
shared/	Protocol types and framing
admin/	Admin app (Electron, separate package.json)
docs/	Documentation and README assets

Status and limitations

• Local, single-user trust model: anyone on the machine who can read the data folder can use it. See Security model.
• Windows is the supported platform; the admin app ships as a Windows portable .exe on the Releases page. Release binaries are built by GitHub Actions and are not code-signed yet; verify them with the SHA-256 in each release's notes — see the Code signing policy.
• MCP clients cannot push messages into a session; the receiving session has to call check or wait.
• Tool responses and the bundled UIs are available in English and Korean. Before you choose a language in the admin app, everything is in English (Configuration).

License

MIT