에이전트를 늘리면 인간이 전달자 역할을 하게 된다

구현을 Claude Code에, 리뷰를 Codex에 맡기는 구성에서는 구현 결과를 복사하여 리뷰 측에 붙여넣고, 돌아온 지적 사항을 다시 구현 측으로 돌려보내는 왕복 과정이 발생합니다. 에이전트들은 병렬로 작동하더라도, 그 사이를 잇는 작업은 자동화되어 있지 않습니다.

agmsg는 이러한 전달 사항을 CLI 에이전트끼리 직접 송수신할 수 있도록 하는 도구입니다. 여러 화면과 상태를 통합하는 herdr와는 달리, agmsg는 에이전트 간의 통신을 담당합니다.

agmsg란

agmsg는 Claude Code, Codex, Gemini CLI, GitHub Copilot CLI 등의 세션을 공유 로컬 SQLite 데이터베이스로 연결하는 메시징 도구입니다. Bash와 SQLite만으로 구현되었으며, 메시지의 저장과 송수신 자체에는 전용 서버도, 브로커도, 네트워크 연결도 사용하지 않습니다.

다만 완전히 프로세스가 없는 것은 아닙니다. 도착한 시점에 받는 monitor를 선택하면, 수신 측에 프로세스가 상주하게 됩니다. Codex에서는 더욱이 agmsg가 관리하는 수신 역할을 백그라운드에서 실행합니다.

송신 시에는 SQLite에 메시지를 추가하고, 수신 측은 자신에게 지정된 행을 읽어옵니다.

상호작용은 하나의 파일에 대한 읽기/쓰기뿐. 동일한 머신 내에서 완결됨

SEND: 상대방에게 지정된 행을 SQLite에 추가 작성 -
RECEIVE: 자신에게 지정된 행을 SQLite에서 읽음

저장할 수 있는 것은 텍스트뿐입니다. 긴 결과물은 파일로 내보내고, 그 요약과 파일 경로, 커밋의 SHA, Issue 번호 등을 메시지로 전달하는 방법이 공식적으로 안내되어 있습니다. 메시지는 세션을 종료해도 남기 때문에 나중에 이력을 다시 읽어볼 수 있습니다.

네트워크를 사용하지 않기 때문에, 다른 머신에 있는 에이전트를 직접 연결하는 용도로는 적합하지 않습니다.

MCP나 서브 에이전트(Sub-agent)와는 역할이 다르다

비슷한 용어와 혼동하기 쉬우므로, 연결 대상을 기준으로 정리합니다.

spawn으로 새로운 에이전트를 기동할 수 있지만, 기동된 대상은 독립된 에이전트입니다. 호출 측이 관리하는 서브 에이전트와는 달리, 대등한 멤버로서 팀에 합류합니다.

설치

필요한 명령어는 bash와 sqlite3입니다. macOS에는 표준으로 포함되어 있지만, 최소 구성의 Linux 환경에서는 SQLite를 추가해야 할 수도 있습니다.

가장 빠른 설치 방법은 npx입니다.

npx agmsg

실행하면 호출에 사용할 명령어 이름을 한 번 묻습니다. 그대로 Enter를 누르면 기본값인 agmsg로 설정되며 설치가 진행됩니다.

agmsg 본체는 ~/.agents/skills/agmsg/에 배치됩니다. 실체는 이 한 곳뿐이며, 각 에이전트는 이곳을 참조합니다. 인스톨러는 이와 함께 사용 중인 각 에이전트의 설정 디렉토리에 명령어와 스킬을 등록합니다.

Codex만은 설정 파일의 수정이 필요하므로, ~/.codex/config.toml을 백업한 뒤 메시지 저장소(db/), 팀 정보(teams/), 실행 상태(run/)를 쓰기 가능한 폴더로 추가합니다. Codex에는 쓸 수 있는 폴더를 제한하는 메커니즘이 있어, 이를 거치지 않으면 팀 참여나 메시지 저장이 실패합니다.

Claude Code에서는 플러그인 구조를 통해 제작자의 marketplace를 추가하여 도입할 수도 있습니다.

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

팀에 참여하기

처음에는 프로젝트 내에서 agmsg 명령어를 호출합니다. 에이전트에 따라 진입부 표기가 다릅니다.

# Claude Code / GitHub Copilot CLI
/agmsg
# Codex / Gemini CLI / Antigravity / OpenCode
...

팀 이름과 해당 팀 내에서 사용할 에이전트 이름을 등록합니다. 팀은 프로젝트에 귀속되므로, 동일한 리포지토리에서 동작하는 구현 담당자와 리뷰 담당자를 같은 팀에 참여시킵니다.

등록 후에는 수신 방법을 선택합니다. 모드는 4가지가 있습니다.

여기까지는 모든 에이전트 공통이며, 이후부터 갈라집니다. monitor는 상주하는 감시 프로세스가 수신하므로 작업 중에도 개입합니다. turn은 입력하지 않는 한 움직이지 않으며, 방치하는 동안에는 수신함에서 대기합니다. 규칙 파일 (Rule file) 방식의 turn은 에이전트가 지시문을 읽고 따르는 것을 전제로 하므로, 읽지 않을 수도 있습니다. off는 자동으로 수신하지 않고 수동으로 수신함을 확인합니다.

송수신 자체는 어떤 에이전트라도 가능하지만, 수신 방식은 통일되어 있지 않습니다. 선택할 수 있는 모드와 그 이면의 메커니즘이 에이전트마다 다릅니다.

monitor를 선택할 수 있는 것은 Claude Code와 Codex뿐이며, both는 Claude Code만 가능합니다. 그 외에는 turn이 실질적인 기본값(Default)이 됩니다. 서로 다른 벤더를 같은 팀에 넣을 수 있다는 것과, 모두가 동일한 수신 방식을 사용할 수 있다는 것은 별개라고 생각해야 합니다.

규칙 파일 방식은 전달되지 않을 수 있다

규칙 파일 방식으로 설치되는 것은 .cursor/rules/agmsg.mdc 또는 .agent/rules/agmsg.md이며, 내용은 다음과 같은 지시문입니다.

## PostToolUse
After each tool call, automatically check the agmsg inbox for unread messages.

메커니즘으로서 발화(Trigger)되는 것이 아니라, 에이전트가 읽고 따르는 것을 전제로 합니다. 따라서 동일한 turn이라도 후크 (Hook) 방식은 실행이 보장되지만, 규칙 파일 방식은 보장되지 않습니다. 실제로 파일 읽기를 포함한 작업을 지시해도 규칙이 실행되지 않고 메시지가 미독 상태로 남기도 합니다.

Cursor만 취급이 다르다

동일한 규칙 파일 방식이라도 Cursor에 배치되는 파일에는 상단에 지정이 붙습니다.

---
alwaysApply: true
---
...

이 지정이 있는 규칙은 매 요청마다 반드시 읽힙니다. 지정이 없는 Antigravity나 OpenCode에서는 애초에 규칙이 모델의 눈에 들어갈 보장이 없습니다. 실제로 테스트해 보면 Cursor만 자동으로 수신함을 읽고, 나머지는 미독 상태로 남았습니다.

Cursor는 추가로 .cursor/hooks.json이라는 실제 후크에도 대응합니다. 이곳으로 옮기면 지시문이 아닌 메커니즘으로서 발화하기 때문에 더욱 확실해집니다.

Antigravity처럼 후크를 가지지 않는 에이전트는 메시지가 전달되지 않을 것을 전제로 구성합니다. 상대의 응답이 필요한 처리를 에이전트에게 전적으로 맡기지 않고, $agmsg를 통한 수동 수신함 확인 단계를 거칩니다.

rulesync로 설정을 관리하는 경우

agmsg는 각 도구의 설정 디렉토리에 직접 쓰기 때문에 rulesync와 충돌합니다. delete: true를 설정해 두었다면, rulesync generate를 실행하는 시점에 agmsg의 배포 설정이 삭제됩니다.

대처 방법은 도구마다 다르며, rulesync로 통합할 수 있는 것, 통합할 수 없는 것, 통합하면 상태가 악화되는 것으로 나뉩니다. 자세한 내용은 별도의 기사에 정리해 두었습니다.

turn은 답장할 때마다 수신함을 읽는다
Codex의 turn

그러면 답장을 다 쓸 때마다 후크 (hook)가 수신함을 확인합니다. 표시 상태는 수신함의 상태에 따라 달라집니다.

blocked는 실패가 아닙니다. Codex의 Stop 후크 (hook)는 턴 (turn)을 종료해도 되는지를 판정하는 메커니즘이며, agmsg는 새로운 메시지가 있을 때만 "종료하지 않음"이라고 응답하고, 그 이유란에 메시지 본문을 실어 보냅니다. 이것이 대화에 개입하는 방식입니다.

개입의 기점은 어디까지나 답장의 종료입니다. Codex에 아무것도 입력하지 않으면 후크 (hook)는 동작하지 않으므로, 도착한 메시지는 그대로 수신함에서 대기합니다.

monitor는 기동 방법을 교체한다

Codex의 monitor는 codex 명령의 기동 처리를 agmsg 측의 수신구로 교체하는 방식입니다. 오랫동안 베타 (beta)로 안내되어 왔으나, 버전 1.1.11 시점에서는 일반적인 선택지로 취급되고 있습니다. 다만 공식 문서에는 여전히 알려진 제한 사항이 기재되어 있으므로, 후술할 확인 방법을 준비해 두는 것이 안전합니다.

활성화하면 셸 함수 (shell function)가 표시되므로, 이를 ~/.zshrc 등에 추가합니다.

codex() {
~/.agents/skills/agmsg/scripts/drivers/types/codex/codex-shim.sh "$@"
}

수신 역할은 Codex가 첫 번째 턴 (turn)을 마친 시점에 동작하기 시작합니다. 동작 여부는 다음 명령으로 확인할 수 있습니다.

~/.agents/skills/agmsg/scripts/delivery.sh status codex "$(pwd)"

Codex bridge: <팀>/<이름> alive라고 표시되면 성립된 것입니다.

not running 상태라면, 우선 셸 함수 (shell function)를 반영했는지, Codex를 재기동했는지, 첫 번째 턴 (turn)을 마쳤는지 확인합니다. 그래도 변하지 않는다면, 후크 (hook)가 신뢰됨 (trusted) 상태로 활성화되어 있는지, Node.js를 사용할 수 있는지, agmsg의 저장 위치에 쓸 권한이 있는지도 확인 대상입니다. 로그는 ~/.agents/skills/agmsg/run/의 codex-bridge.*.log에서 확인할 수 있습니다.

배포 모드를 변경하면 Codex 측에서 활성화한다

배포 모드를 전환하면 프로젝트의 .codex/hooks.json이 다시 작성됩니다. Codex는 후크 (hook)의 내용이 바뀌면 재확인을 요구하기 때문에, 전환만 해서는 동작하지 않습니다.

Codex의 후크 (hook) 설정 화면에서 대상 후크 (hook)가 다음 두 가지 조건을 모두 만족하는 상태로 만듭니다.

• Trust가 Trusted로 되어 있음
• 후크 (hook) 스위치가 [x] (활성화) 상태임

신뢰됨 (trusted) 상태라도 스위치가 꺼져 있으면 실행되지 않습니다. 설정은 올바른데 수신함을 확인하러 가지 않는다면 이 부분을 확인하십시오.

메시지를 송수신한다

주요 조작은 Claude Code의 표기법을 기준으로 다음과 같습니다. Codex에서는 맨 앞에 $agmsg를 붙여 호출합니다.

예를 들어 구현 역할에서 리뷰 역할로 요청할 때는 다음과 같이 보냅니다.

/agmsg send reviewer 현재 변경 사항의 차이(diff)를 확인하고, 중요도 순으로 개선점을 반환해 주세요. 완료되면 DONE이라고 답장해 주세요.

agmsg는 메시지를 전달할 뿐, 대화를 언제 멈출지 또는 동일한 파일을 동시에 건드리지 않도록 어떻게 조정할지까지는 결정하지 않습니다. 최대 왕복 횟수나 DONE과 같은 종료 조건을 첫 번째 요청에 포함해야 합니다.

구현 역할과 리뷰 역할을 연결한다

리뷰를 왕복시키려면 역할과 정지 조건을 먼저 결정합니다.

• 구현 역할이 변경을 완료하고, 차이(diff)가 있는 위치와 확인 항목을 리뷰 역할에게 보냅니다.
• 리뷰 역할이 차이(diff)를 읽고, 지적 사항 또는 DONE을 반환합니다.
• 구현 역할이 지적 사항을 수정하고, 재리뷰를 요청합니다.
• 최대 왕복 횟수에 도달하거나, 리뷰 역할이 DONE을 반환하는 시점에서 멈춥니다.

메시지 본문에 커다란 차이(diff)를 붙여넣을 필요는 없습니다. 동일한 리포지토리 (repository)를 열고 있다면, 대상 파일, 브랜치 이름, 커밋의 SHA를 보내면 수신 측에서 직접 차이(diff)를 읽을 수 있습니다.

양측이 monitor 모드로 동작하고 있다면, 이 왕복 과정은 입력 없이 진행됩니다. Claude Code (cc)와 Codex로 3회 왕복시킨 결과는 다음과 같습니다.

소요 시간은 약 1분이며, 그동안 키보드에는 손을 대지 않았습니다. 2번 결과는 ls src/content/posts/*.mdx | wc -l로도 같은 값이 나오며, 다른 방법으로 동일한 답에 도달했습니다.

2회차와 3회차 왕복. 사람의 입력을 거치지 않고 요청, 응답, 명령어 확인까지 진행됨

역할을 늘리기

actas는 현재 세션이 사용하는 역할을 전환합니다. 동일한 프로젝트 내에서 아키텍처 리뷰어 역할과 요구사항 확인 역할 역할을 서로 다른 이름으로 취급할 때 사용합니다.

/agmsg actas tech-lead

spawn은 다른 터미널에서 새로운 에이전트를 실행합니다. 첫 번째 지시를 동시에 전달하려면 --boot-prompt를 사용합니다.

/agmsg spawn codex reviewer --boot-prompt "차이점(diff)을 리뷰하고, 완료되면 DONE이라고 답장해 주세요"

실행을 위해서는 대상 에이전트 CLI와 tmux 또는 새로운 터미널을 열 수 있는 환경이 필요합니다. 화면이 없는 환경이나 에이전트의 종류에 따라 실행할 수 없으므로, 공식 README의 지원 현황을 확인하십시오.

agmsg로 무엇이 바뀌는가

서로 다른 벤더의 CLI를 동일한 팀으로 구성할 수 있습니다. Claude Code와 Codex처럼 명령어 체계가 다른 에이전트라도 동일한 저장소를 공유할 수 있습니다.

메시지 이력이 세션을 넘어 유지됩니다. 새로운 세션은 history를 통해 과거의 요청과 응답을 다시 읽을 수 있습니다.

통신을 위한 서버 운영 부담이 늘어나지 않습니다. 로컬 Bash 스크립트와 SQLite만으로 동작하며, MCP 서버나 중계용 브로커(broker)를 별도로 구축할 필요가 없습니다. monitor에서 사용하는 수신 측 프로세스는 agmsg가 실행과 정지를 관리합니다.

사용 전 확인 사항

• 메시지는 짧은 텍스트용이며, 파일 자체를 전송하지는 않습니다.
• 다른 머신 간의 통신에는 사용할 수 없습니다.
• 발언 순서, 누가 어떤 파일을 수정할지, 최대 왕복 횟수는 프롬프트(prompt)나 운영 측에서 결정합니다.
• 전송 모드(delivery mode)의 지원 현황과 메커니즘은 에이전트마다 다릅니다.
• Codex의 monitor는 셸 함수(shell function) 추가와 재시작을 전제로 합니다. 전송 모드를 전환하면 Codex 측에서 훅(hook)을 신뢰하고 스위치를 활성화합니다.
• 규칙 파일(rule file) 방식의 에이전트는 turn 모드에서도 수신함을 읽지 않을 수 있습니다. 쓰기 권한이 있는 폴더를 제한하고 있다면, agmsg의 저장 위치가 제한에 걸리지 않았는지 확인하십시오.

요약

agmsg는 서로 다른 벤더의 CLI 에이전트를 하나의 로컬 SQLite 파일로 연결하는 메시징 도구입니다. 송신은 자신 이외의 대상에게 보낼 행을 추가하는 것이고, 수신은 자신에게 온 행을 읽는 방식이기에 그 핵심에 전용 서버도, 브로커도, 네트워크 통신도 사용하지 않습니다. monitor를 선택하면 수신 측에 프로세스가 상주하지만, 그 실행과 정지 역시 agmsg가 담당합니다.

실제로 사용할 때의 차이점은 수신 방법입니다. Claude Code와 Codex는 monitor를 통해 메시지가 도착한 시점에 수신할 수 있으며, 양측이 모두 monitor 모드라면 사람의 입력 없이 왕복이 진행됩니다. 반면, 규칙 파일 방식의 에이전트는 지시문을 따를지 여부가 모델에 달려 있어, turn으로 설정하더라도 수신함을 읽지 않을 수 있습니다. 사용하는 에이전트가 어떤 방식인지 미리 확인해 두면, 메시지가 도달하지 않을 때 원인을 찾는 수고를 덜 수 있습니다.

agmsg가 담당하는 것은 메시지 전달뿐입니다. 대화를 언제 멈출지, 누가 어떤 파일을 다룰지는 결정해 주지 않으므로, 최대 왕복 횟수나 종료 신호를 첫 번째 요청에 포함해 두십시오. actas로 역할을 전환하고 spawn으로 독립된 에이전트를 늘릴 수 있지만, 이들을 어떤 역할로 움직이게 할지 설계하는 것은 사용하는 사람의 몫입니다.

Discussion