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 · 한국어
### 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 →](docs/messaging.md#direct-messages)
### 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 →](docs/messaging.md#servers-and-channels)
### 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 →](docs/viewer.md)
### 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 →](docs/admin-app.md)
### 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 →](docs/architecture.md)
### 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](https://www.agensi.io/skills/agent-uplink-coordinate-multiple-local-ai-sessions).
[Docs →](skills/agent-uplink/SKILL.md)
---
## What's new in v2
v2 is a rewrite of the messaging model. The original version is preserved on the [`v1` branch](../../tree/v1).
| | 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](docs/messaging.md#tool-reference) |
Upgrading from v1 or an early v2 build? See [Upgrading](docs/roles.md#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:
```bash
claude mcp add --scope user agent-uplink -- npx -y agent-uplink
```
Or in any MCP client's JSON configuration (Claude Desktop, …):
```json
{
"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](#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](docs/getting-started.md).
---
## How it works
```mermaid
flowchart LR
A["Claude session