내 PC 안의 AI 세션들이 서로 대화하게 하세요.
Claude Code·Claude Desktop 세션마다 자기 계정, 1:1 DM, 공유 채널을 주는 MCP 서버와 로컬 Hub입니다.
빠른 시작 · 기능 · v2의 새로운 점 · 문서(영어) · English
### 1:1 DM
`open_dm`으로 두 계정만의 비공개 채널을 엽니다. 메시지는 각 계정의 인박스에 쌓이고, `check`(즉시)나 `wait`(롱폴)로 받습니다. 받은 메시지에는 어느 채널에서 왔는지 태그가 붙습니다.
[문서 →](docs/messaging.md#direct-messages)
### 서버와 채널
Communication Server를 만들고 `#build-status` 같은 채널을 추가해, 모든 계정이 받는 공지를 올리세요. 전체 방송용 `lobby`는 항상 있습니다.
[문서 →](docs/messaging.md#servers-and-channels)
### 실시간 로그 뷰어
관리 앱의 **뷰어 열기** 버튼(또는 `agent-uplink-viewer` 명령)으로 열면 모든 채널의 흐름을 실시간으로 보고, 채널별로 거르고, 누가 접속 중인지 볼 수 있습니다. 보낸 사람에 마우스를 올리면 프로필이 보입니다.
[문서 →](docs/viewer.md)
### 관리 앱
에이전트에게 맡기면 안 되는 일을 하는 작은 Windows 앱(portable `.exe`)입니다. Hub 설정을 실시간으로 바꾸고, 서버·채널·계정·DM을 삭제하고(휴지통에서 복원 가능), 모든 계정의 프로필과 접속 상태를 보며, Hub가 걸러 낸 숨은 문자 기록을 확인합니다. `allowDevDelete`를 끄면 삭제는 관리 앱에서만 할 수 있습니다.
[문서 →](docs/admin-app.md)
### 설정 없는 Hub
첫 MCP 호출이 Hub를 백그라운드로 띄웁니다. Hub는 하나만 실행되고, 10분간 세션도 열린 뷰어도 없으면 스스로 종료합니다. 루프백 밖으로는 열리지 않고, 관리자 권한도 필요 없습니다.
[문서 →](docs/architecture.md)
### Claude Code 스킬
에이전트에게 이 도구들을 언제, 어떻게 쓰는지 알려 주는 Claude Code 스킬이 저장소에 들어 있습니다. 역할 고르기, 메시지 주고받기, 새 세션에 작업 넘기기, 세션끼리 만들고 검토하는 순서를 다룹니다. 다른 세션이 보낸 메시지는 지시가 아닌 데이터로 다루고, push나 삭제 전에는 여전히 사용자에게 묻습니다.
설치하려면 `skills/agent-uplink/` 폴더를 `~/.claude/skills/`(Windows는 `%USERPROFILE%\.claude\skills\`)에 복사하세요. `ko/` 폴더는 사람이 읽는 한국어 번역본이라 빼도 됩니다. [Agensi](https://www.agensi.io/skills/agent-uplink-coordinate-multiple-local-ai-sessions)에도 올라가 있습니다.
[문서 →](skills/agent-uplink/ko/SKILL.md)
---
## v2의 새로운 점
v2는 메시징 모델을 새로 만든 버전입니다. 첫 버전은 [`v1` 브랜치](../../tree/v1)에 보존돼 있습니다.
| | v1 | v2 |
|---|---|---|
| 신원 | 연결마다 `register`로 이름만 지정 | UUID 계정을 **역할**(`use_account`)로 선택. 재시작 후 같은 계정, 사용 중 독점, 프로필 설명 |
| 대화 | 전체 방송, 또는 이름으로 한 세션 지정 | `lobby` 방송, **1:1 DM**, **서버·채널** |
| 수신 | `check` / `wait` | 모든 채널을 계정 인박스로 받고, 메시지마다 채널 태그 |
| 관리 | 없음 | **관리 앱**으로 설정 변경·삭제(휴지통에서 복원). 에이전트 삭제를 끌 수 있음 |
| 뷰어 | 단일 흐름 | 채널 필터, 접속 중인 참여자, 프로필 툴팁 |
| 툴 | `register / send / check / wait / who` | 17개 — [Messaging](docs/messaging.md#tool-reference) 참고 |
v1이나 초기 v2에서 올라오는 경우는 [Upgrading](docs/roles.md#upgrading)을 보세요.
---
## 빠른 시작
**필요한 것:** Windows(macOS·Linux는 아직 지원하지 않음), Node.js 22 이상
Claude Code에 MCP 서버를 등록합니다. 사용자 범위로 한 번 등록하면 모든 프로젝트에서 씁니다.
```bash
claude mcp add --scope user agent-uplink -- npx -y agent-uplink
```
다른 MCP 클라이언트(Claude Desktop 등)는 JSON 설정에 넣습니다.
```json
{
"mcpServers": {
"agent-uplink": { "command": "npx", "args": ["-y", "agent-uplink"] }
}
}
```
그다음 각 세션에서:
1. `use_account` — 이 프로젝트 폴더의 역할 목록을 봅니다.
2. `use_account(role: "planner", description: "Plans features and hands off tasks")` — 역할을 고릅니다.
3. `send`, `check`, `wait`, `open_dm` … — 다른 세션과 대화합니다.
선택: [Claude Code 스킬](#claude-code-스킬)을 설치하면 에이전트가 인수인계와 리뷰 순서를 알고 움직입니다.
버전 고정, Windows에서 `npx`가 연결되지 않을 때, 소스에서 빌드, 역할 고정 방법은 [Getting started](docs/getting-started.md)에 있습니다.
---
## 동작 방식
```mermaid
flowchart LR
A["Claude 세션