CLI AI 에이전트를 위한 교차 에이전트 메시징 (agmsg)

CLI AI 에이전트를 위한 교차 에이전트 메시징 (Cross-agent messaging). 데몬도, 네트워크도, 복잡함도 없습니다.

이제 에이전트 사이에서 복사-붙여넣기를 수행하는 심부름꾼 역할을 그만두세요. Claude Code, Codex, Gemini CLI, GitHub Copilot CLI 및 기타 모든 CLI 에이전트들이 공유된 로컬 SQLite 데이터베이스를 통해 서로 직접 메시지를 주고받습니다. 중간에 사람이 개입할 필요가 없습니다.

이것이 아닌 것:

• MCP가 아닙니다. MCP 서버도, 추가적인 런타임 (runtime)도 필요 없습니다. 오직 bash와 sqlite3만 있으면 됩니다.
• 하위 에이전트 (subagents)가 아닙니다. agmsg는 서로 다른 도구 간의 피어 (peer) 세션을 연결합니다. spawn을 통해 자신의 터미널에서 새로운 피어 에이전트를 실행할 수 있지만, 이는 agmsg를 통해 대화하는 독립적인 세션이지, 이 도구가 관리하는 자식 프로세스 (child process)가 아닙니다.
• 메시지 큐 (message queue)가 아닙니다. 브로커 (broker)는 없습니다. SQLite 파일이 바닥이고, 에이전트들이 플레이어입니다.

동일한 팀에 남겨진 두 개의 monitor 모드 Claude Code 인스턴스는 인간의 개입 없이 서로 틱택토 (tic-tac-toe) 게임을 합니다. 각 인스턴스는 상대방의 수를 실시간으로 파악합니다:

[IMG:1]

실제 사용 시에는 다음과 같이 작동합니다. Claude Code가 Codex에게 코드 리뷰를 요청하고 agmsg를 통해 결과를 돌려받는 모습입니다:

[IMG:2]

요구 사항: bash와 sqlite3가 필요합니다. macOS에는 두 가지 모두 포함되어 있습니다. 최소 사양의 Linux 환경 (일부 Debian/Ubuntu 컨테이너, Alpine 등)에서는 먼저 sqlite3를 설치해야 할 수도 있습니다 — sudo apt-get install -y sqlite3 또는 해당 배포판의 상응하는 명령어를 사용하세요.

# 1. 설치 (한 줄 명령어)
bash <(curl -fsSL https://raw.githubusercontent.com/fujibee/agmsg/main/setup.sh)
# 또는 코드를 검토하고 싶다면 먼저 클론(clone)하세요
...

그게 전부입니다. 슬래시 명령어를 사용하면 처음 실행 시 팀 이름과 에이전트 이름을 묻고, 전달 모드 (delivery mode)를 선택하라고 요청합니다 (Claude Code의 기본값은 실시간 푸시인 monitor이며, Codex는 Monitor 도구가 없기 때문에 turn이 기본값입니다). 그 이후에는 에이전트와 자연스럽게 대화하면 됩니다 — 아래의 '첫 실행' 섹션을 참조하세요.

다른 설치 방법을 선호하시나요? npm / npx 및 Claude Code 플러그인 마켓플레이스 경로에 대해서는 아래 '설치' 섹션을 참조하세요.

agmsg는 가벼운 전송 계층 (transport)입니다. 각 에이전트는 공유 SQLite 파일로부터 읽어 들여 에이전트가 반응할 수 있는 텍스트로 수신 메시지를 노출하는 훅 (hook, 또는 전달 모드에 따라 Monitor 스트림)을 가집니다. 전송은 행을 추가하는 send.sh 호출을 통해 이루어집니다. 데몬 (daemon), 소켓 (socket), 브로커 (broker)는 없습니다. 파일이 공유된 바닥이며, 에이전트들이 그 위에서 차례를 지키며 작업합니다.

저장소는 WAL 모드 (Write-Ahead Logging) SQLite이므로, 충돌 없이 여러 명의 읽기 작업자와 단일 쓰기 작업자가 공존할 수 있습니다. 히스토리 (history)는 영구적입니다. 메시지는 세션이 종료된 후에도 DB에 남아 있으며, history.sh를 통해 오래된 룸 (room)을 새로운 에이전트로 다시 재생 (replay)할 수 있습니다.

어떤 설치 경로를 선택하든 agmsg는 ~/.agents/skills/agmsg/에 위치하게 됩니다. 귀하의 설정에 맞는 방식을 선택하세요.

어떤 경로가 최신 버전을 제공하나요? git clone 및 setup.sh (curl) 경로는 main 브랜치에서 직접 설치되므로 항상 최신 상태를 유지합니다. npm 패키지와 Claude Code 플러그인은 정해진 주기에 따라 태그된 릴리스 (tagged releases)를 기반으로 제작되므로, main 브랜치보다 몇 개의 수정 사항이 뒤처질 수 있습니다. 대부분의 사용자에게는 문제가 없으나, 방금 병합된 변경 사항을 구체적으로 원하는 경우에는 리포지토리 (repo)를 클론하세요. /agmsg version (또는 scripts/version.sh)을 통해 현재 실행 중인 버전을 언제든지 정확히 확인할 수 있습니다. 태그된 릴리스는 v1.0.3과 같이 표시되며, 마지막 릴리스보다 앞선 체크아웃 (checkout) 상태는 v1.0.3-6-g1a2b3c4 (v1.0.3 이후 6개의 커밋)와 같이 표시됩니다.

npx agmsg # 일회성 실행, 글로벌 설치 없음
# 또는
npm i -g agmsg && agmsg install

npm 패키지는 표준 setup.sh를 다운로드하고 실행하는 가벼운 부트스트래퍼 (bootstrapper)입니다. 이 패키지는 SLSA 출처 증명 (provenance)과 함께 npm 신뢰할 수 있는 게시자 (Trusted Publisher, OIDC)를 통해 이 리포지토리에서 npm으로 게시되었습니다. 증명 (attestation)은 https://www.npmjs.com/package/agmsg 에서 확인할 수 있습니다.

Claude Code 내부에서:

/plugin marketplace add fujibee/agmsg
/plugin install agmsg@fujibee-agmsg
/reload-plugins
...

플러그인 설치 경로는 스킬 (skill)을 ~/.claude/plugins/cache/에 배치하며, /agmsg의 첫 호출 시 ~/.agents/skills/agmsg/를 채우는 부트스트랩 (bootstrap)이 실행됩니다.

(데이터베이스, 스크립트, 팀 레지스트리 (team registry))를 구성하므로 런타임 (runtime)은 스크립트 설치와 동일합니다. 만약 환경에 sqlite3가 없다면 (일부 최소형 Linux 컨테이너에는 기본적으로 포함되어 있지 않습니다), 부트스트랩 (bootstrap) 과정에서 명확한 에러 메시지가 표시됩니다 — sqlite3를 설치한 후 /agmsg를 다시 호출하십시오.

먼저 저장소 (repo)를 클론 (clone)한 다음 설치 프로그램을 실행하십시오 — 이 경로는 항상 최신 main 브랜치를 추적합니다:

git clone https://github.com/fujibee/agmsg.git
cd agmsg
./install.sh # 대화형 (명령어 이름을 묻습니다, 기본값: agmsg)
...

**명령어 이름 (command name)**은 다음을 결정합니다:

• 스킬 (Skill) 폴더:
  ~/.agents/skills/<cmd>/

• Claude Code / Copilot CLI:
  /<cmd>

• Codex / Gemini CLI / Antigravity:
  $<cmd>

--cmd와 --agent-type은 직접 스크립트 경로를 통해서만 사용할 수 있습니다; npm 및 플러그인 (plugin) 경로는 항상 agmsg로 설치되며 호스트 에이전트 (agent) 유형을 자동으로 감지합니다.

설치 후, 새로운 스킬을 인식할 수 있도록 에이전트를 재시작하십시오 (Claude Code / Codex / Gemini CLI / Copilot CLI / Antigravity).

Windows의 Git Bash에서 install.sh가 실행될 때는 다음과 같은 선택적 네이티브 헬퍼 (native helpers)들도 함께 설치됩니다:

~/.agents/agmsg.ps1 — PowerShell 함수 래퍼 (wrapper)
~/.agents/agmsg-run.sh — 해당 래퍼에서 사용하는 Git Bash 러너 (runner)
~/.agents/bin/sqlite3 — Windows용 호환성 심 (shim)
sqlite3.exe 출력

PowerShell 명령을 활성화하려면, 생성된 파일을 PowerShell 프로필 (profile)에서 도트 소싱 (dot-source) 하십시오:

. "$HOME\.agents\agmsg.ps1"

그러면 PowerShell 세션에서 다음을 실행할 수 있습니다:

agmsg
agmsg history
agmsg team
...

설치 프로그램은 동일한 프로필 라인을 출력하지만, 사용자의 프로필을 자동으로 수정하지는 않습니다.

에이전트 (Claude Code, Codex, Gemini CLI 등)에서 프로젝트를 열고 다음을 실행하십시오:

/agmsg # Claude Code, Copilot CLI
$agmsg # Codex, Gemini CLI, Antigravity

처음 사용할 때 팀 이름 (team name) (기존 팀에 합류하거나 새 팀 생성)과 이 프로젝트를 위한 **에이전트 이름 (agent name)**을 묻습니다 — 이것이 온보딩 (onboarding)의 전부입니다. 그 이후에는 에이전트와 자연스럽게 대화하십시오:

"deploy가 완료되었다고 alice에게 메시지를 보내줘""내 메시지 확인해줘""팀에 누가 있어"*

에이전트는 적절한 서브커맨드 (subcommand)를 선택하여 사용자를 대신해 실행합니다. 아래 내용은 암기할 필요가 없습니다. 하단의 스크립트 참조 (script reference)는 자동화, 스크립트, 그리고 CI를 위한 것입니다.

팀 이름 변경, 탈퇴, 두 번째 프로젝트에서 동일한 팀에 참여하기, 또는 프로젝트의 등록 정보 삭제에 대해서는 docs/teams.md를 참조하십시오.

동일한 프로젝트, 동일한 에이전트 유형, 다른 역할(role) — 예를 들어 아키텍처 리뷰를 위한 tech-lead 정체성과 요구사항 작업을 위한 biz-analyst 정체성이 모두 동일한 워크스페이스 (workspace) 상에 존재하는 경우입니다. 툴셋 (toolset)과 자산 (assets)은 공유되며, 오직 역할만 다릅니다.

/agmsg actas tech-lead # tech-lead로 전환 (아직 등록되지 않았다면 생성)
/agmsg actas biz-analyst # biz-analyst로 전환
/agmsg drop biz-analyst # 이 프로젝트에서 해당 역할을 제거

actas <name>

은 **세션 간 독점적 (exclusive across sessions)**입니다. 이는 송신 및 수신을 모두 <name>으로 전환하고, 피어 세션 (peer sessions)이 동일한 이름에 구독하는 것을 방지하는 잠금 (lock)을 점유하며, 다른 세션이 이미 잠금을 보유하고 있다면 거부합니다. drop은 잠금을 해제합니다. 만약 잠금이 걸린 상태로 멈춘다면, 잠금을 보유한 세션에서 역할을 제거하거나 해당 세션을 종료하십시오.

독점 모델 (exclusivity model), 복구 (recovery), 활성 상태 / PID 재활용 (liveness / PID recycling), Codex 주의사항 (Codex caveat) 등 전체 메커니즘에 대해서는 docs/actas.md를 참조하십시오.

actas가 현재 세션을 다른 역할로 전환하는 반면, spawn은 부팅 시 역할을 부여받는 **별도의 에이전트 프로세스 (separate agent process)**를 띄웁니다 — 협업자들을 확장 (fanning out)할 때 유용합니다.

/agmsg spawn codex reviewer # 새로운 codex 에이전트, 참여하여 "reviewer"가 됨
/agmsg spawn claude-code alice --window # 새로운 tmux 윈도우에서 새로운 claude-code 에이전트 실행

spawn <type> <name>

은 먼저 <name>에 참여한 후, 대상 CLI를 초기 프롬프트 (initial prompt)로 actas 슬래시 커맨드 (/<your-command> actas <name>, 설치한 커맨드 이름과 일치해야 함)와 함께 실행합니다. 현재 세션이 tmux 내부라면, 새로운 팬 (pane)에서 열립니다 (또는 새로운 윈도우를 위해 --window, 수평/수직 분할을 위해 --split h|v 사용).

방향을 위해); 그렇지 않으면 새로운 OS 터미널 (OS terminal) 창을 엽니다.

기본적으로 spawn은

새로운 에이전트가 실제로 리스닝(listening)할 때까지 블록(blocks)합니다 — 즉, 에이전트의 워처(watcher)가 연결되어 준비 상태 센티널(readiness sentinel)을 터치한 후 status=ready를 출력합니다.

따라서 에이전트의 콜드 스타트(cold start)로 인해 작업을 놓치는 일 없이, spawn이 반환되는 즉시 작업을 보낼 수 있습니다. 실행 후 잊어버리는(fire-and-forget) 방식을 원하면 --no-wait를 사용하거나, 대기 시간을 제한하려면 --ready-timeout <secs>를 사용하세요 (기본값 90; 타임아웃 발생 시 status=timeout을 출력하고 종료 코드 3으로 종료하여 호출자가 다시 스폰(re-spawn)할 수 있도록 합니다). Codex는 대기 과정을 건너뜁니다 (Monitor가 없기 때문입니다).

옵션: --project <path> (기본값: 현재 프로젝트), --team <team> (프로젝트에 팀이 하나뿐일 때 자동 해결됨), 그리고 tmux를 사용하지 않는 경로에서 터미널 명령을 재정의하기 위한 --terminal <tmpl> / $AGMSG_TERMINAL / 설정 spawn.terminal ( {cmd} 플레이스홀더는 생성된 부트 스크립트의 경로로 교체됩니다).

macOS의 경우, 기본적으로 open -a를 사용하여 현재 사용 중인 터미널( $TERM_PROGRAM을 통해 Iterm 또는 Terminal 확인)을 엽니다. 이는 단순한 앱 실행 방식이므로, 터미널을 직접 스크립팅할 때 발생하는 자동화/AppleScript 권한 요청 프롬프트를 트리거하지 않습니다.

현재는 claude-code와 codex만 지원됩니다. macOS가 주요 타겟이며, Linux와 Windows는 최선을 다해 지원합니다 (사용 중인 터미널이 처리되지 않는 경우 이슈/PR을 열어주세요). 헤드리스(Headless) 환경 — tmux를 사용하지 않으면서 사용 가능한 터미널도 없는 경우 — 에이전트 CLI는 대화형 터미널이 필요하므로 에러가 발생합니다.

despawn은 spawn의 역작업입니다 — 실행했던 멤버를 깔끔하게 해제합니다.

/agmsg despawn reviewer # graceful: 멤버가 역할을 내려놓고 자신의 팬(pane)을 닫습니다
/agmsg despawn alice --force # force: 워처가 응답할 수 없을 때 여기서 강제로 해제합니다

기본적으로 despawn <name>은 **graceful(우아한 방식)**입니다: <name>에 ctrl:despawn 제어 메시지를 보냅니다.

, 해당 워처(watcher)가 자신의 역할(role)을 해제하고(actas 잠금 및 등록 해제), 자신의 tmux 창을 닫음으로써 에이전트를 종료합니다. 이 과정은 역할이 해제될 때까지 차단(block)되며, --timeout <secs> (기본값 30)까지 대기한 후 status=ok를 출력합니다. 만약 멤버의 워처가 응답하지 않으면 status=timeout을 출력하고 종료 코드 3으로 종료합니다 — 이 경우 --force를 사용하여 재시도하십시오.

--force는 메시지 전송을 건너뛰고 생성(spawn) 시점에 기록된 배치(placement) 정보를 바탕으로 멤버를 강제로 해제합니다. 즉, 멤버의 tmux 창/윈도우를 종료하고 등록을 해제합니다. 워처가 응답할 수 없는 경우 — 즉, 워처가 죽었거나 codex 멤버(Monitor 도구가 없어 우아한 방식(graceful)이 수행할 작업이 없는 경우)일 때 사용하십시오. 수동으로 시작된 멤버(spawn 배치 기록이 없는 경우)는 --force를 사용할 수 없습니다; despawn이 이를 알리며 사용자가 직접 종료하도록 남겨둡니다.

despawn은 지정된 멤버에게만 작동합니다 — despawn을 실행 중인 세션은 절대 종료되지 않으며, 광범위한 구독(broad-subscription) 워처는 다른 역할(role)을 대상으로 하는 ctrl:despawn을 무시합니다.

수신 메시지가 에이전트에 도달하는 방식입니다. 처음 접속 시 프롬프트를 통해 하나를 선택하거나, 나중에 /agmsg mode <name>으로 변경할 수 있습니다.

모드	메커니즘	지연 시간(latency)	대상
monitor (Claude Code 기본값)	SessionStart 훅 → Monitor 도구 → 차단형 SQLite 스트림	~5s	실시간 푸시를 원하는 Claude Code 사용자
turn (Codex / Copilot CLI 기본값)	어시스턴트 턴(turn) 사이에 Stop 훅이 check-inbox.sh를 실행	다음 상호작용 시까지	Codex / Copilot CLI (Monitor 도구 없음); 더 조용한 루프를 원하는 Claude Code 사용자
both	monitor를 주력으로 사용하며, turn을 세션별 안전장치로 사용	~5s; 워처 실패 시 턴 종료 시점으로 폴백(fallback)	이중 안전장치 (belt-and-suspenders)
off	자동 전달 없음	수동 /agmsg만 가능	미니멀리스트

/agmsg mode monitor — 이 프로젝트를 실시간 푸시(Claude Code)로 전환
/agmsg mode turn — 턴 사이 체크 방식으로 전환
/agmsg mode both — monitor를 사용하되 turn을 안전장치로 사용
...

설정은 프로젝트별로 적용됩니다. 각 <project>/.claude/settings.local.json

선택된 모드에 정확히 필요한 훅 (hooks)을 가져옵니다 — 반복적인 set 호출은 멱등성 (idempotent)을 가집니다.

모니터 프라이밍 (Monitor priming): monitor 모드에서는, 수신 에이전트가 이번 세션에서 최소 한 번의 턴 (turn)을 수행하기 전까지는 첫 번째 인바운드 메시지 (inbound message)에 반응하지 않습니다. 만약 방금 새로운 세션을 시작했는데 팀원이 이미 무언가를 보냈다면, 에이전트를 프라이밍 (prime)하기 위해 짧은 메시지(예: "hi")를 보내 넛지 (nudge)를 주세요 — 그 이후의 메시지들은 실시간으로 스트리밍됩니다.

hook on은 이제 mode turn에 대한 얇은 별칭 (thin alias)입니다 (한 줄의 지원 중단 (deprecation) 힌트 포함). 실시간 푸시 (push)로 전환하려면:

/agmsg mode monitor

이 명령은 db/config.yaml을 업데이트하고, 프로젝트의 훅 (hook) 항목을 다시 작성하며, 현재 세션에서 monitor를 활성화하는 AGMSG-DIRECTIVE를 출력합니다 — 에이전트 재시작은 필요하지 않습니다.

/agmsg — 받은 편지함 확인 (모든 팀)
/agmsg history — 메시지 기록
/agmsg team — 팀 멤버 목록
...

$agmsg — 또는 /skills → agmsg

Codex는 mode turn과 mode off만 지원합니다 — 스트리밍을 위한 Monitor 도구가 없습니다.

/agmsg — agmsg 스킬 (skill)을 호출합니다