Claude Code와 Codex가 하나의 짧은 메시지 스트림으로 서로의 진행 상황을 알 수 있게 하는, 작고 이식 가능한 CLI와 공식 훅 설치 도구입니다.
Agent Broadcast는 공유된 Redis Stream에 상태 메시지를 기록하고 최근 메시지를 다시 보여 줍니다. 두 도구가 같은 Redis와 스트림 이름을 사용하면, 어느 쪽에서 보낸 메시지든 다른 쪽에서 바로 확인할 수 있습니다.
영문 문서는 README.en.md에서 볼 수 있습니다.
여러 AI 코딩 세션을 함께 쓸 때는 “누가 무엇을 하고 있는지”를 짧고 명확하게 알리는 통로가 필요합니다. Agent Broadcast는 다음만 담당합니다.
- Codex 또는 Claude Code에서 한 줄 메시지를 같은 Redis Stream에 발행
- 다른 터미널에서 최신 메시지를 시간 역순으로 조회
agent,node,topic, 익명 세션 ID, 프로젝트 이름 메타데이터를 함께 기록- Claude Code/Codex 공식 훅에서 다른 세션의 최근 활동을 자동으로 전달
- 1,000개까지만 유지해 Stream이 끝없이 커지지 않도록 제한
수동 명령은 명령에 직접 적은 메시지만 전송합니다. 자동 훅은 정해진 생명주기 메시지만 전송하며 프롬프트, 전체 작업 경로, transcript, 파일 내용, 도구 입력·결과, API 키를 전송하지 않습니다.
Docker가 있다면 로컬 전용 Redis를 한 번 실행하세요. 127.0.0.1에만 연결하므로 외부 인터넷에 열리지 않습니다.
docker run --name agent-broadcast-redis --rm -p 127.0.0.1:6379:6379 redis:7-alpineDocker가 없다면 조직에서 제공하는 Redis에 바로 연결하지 말고, 먼저 SSH 또는 VPN으로 만든 로컬 터널을 사용하세요. 이 도구는 URL에 비밀번호를 넣지 않도록 의도적으로 막습니다.
Rust가 설치되어 있다면 저장소를 받은 뒤 다음을 실행합니다.
cargo install --path . --locked설치 없이 시험하려면 아래 모든 agent-broadcast를 cargo run --으로 바꾸면 됩니다.
$env:AGENT_BROADCAST_REDIS_URL = "redis://127.0.0.1:6379/0"
$env:AGENT_BROADCAST_STREAM = "agent:broadcast"
agent-broadcast doctorOK endpoint=...가 보이면 주소와 설정 형식이 올바른 것입니다. doctor는 Redis에 메시지를 쓰지 않습니다.
agent-broadcast broadcast "README 초안을 작성 중입니다" `
--topic docs --agent codex --node laptop-a다른 터미널(또는 다른 컴퓨터에서 같은 Redis 터널을 사용한 터미널)에서 실행합니다.
agent-broadcast recent
agent-broadcast broadcast "검토를 시작합니다" `
--topic docs --agent claude-code --node laptop-bCodex 터미널에서 다시 agent-broadcast recent를 실행하면 두 메시지가 최신순으로 보입니다.
수동 송수신을 확인한 다음, 두 제품의 사용자 설정에 기본 훅을 한 번에 설치합니다.
agent-broadcast hooks install all제품별 설치도 가능합니다.
agent-broadcast hooks install claude
agent-broadcast hooks install codex설치기는 기존 JSON 설정을 파싱해 Agent Broadcast 항목만 병합합니다. 기존 훅과 다른 설정은 유지하고, 최초 변경 전에 같은 폴더에 *.agent-broadcast.bak 백업을 만듭니다. 같은 명령을 반복해도 훅이 중복되지 않습니다.
기본 설치 이벤트는 다음 네 가지입니다.
| 이벤트 | Redis에 보내는 내용 | 에이전트에 돌려주는 내용 |
|---|---|---|
SessionStart |
session started |
같은 프로젝트의 다른 세션 최근 활동 |
UserPromptSubmit |
work turn started |
같은 프로젝트의 다른 세션 최근 활동 |
Stop |
turn completed |
없음 |
SessionEnd |
session ended |
없음 |
프롬프트 내용은 읽거나 전송하지 않습니다. session_id는 원문 대신 로컬에서 만든 해시형 짧은 식별자로 바꾸고, cwd는 마지막 프로젝트 폴더 이름만 사용합니다. 에이전트 컨텍스트에 넣기 전에는 전용 topic·제품명·세션 형식·고정 생명주기 메시지를 다시 검사해 임의 Redis 문장을 제외합니다. 훅이 보여 주는 충돌 정보는 주의 신호이지 분산 파일 잠금이 아닙니다. 겹치는 파일을 편집하기 전에는 상대 세션과 작업 범위를 조정해야 합니다.
도구 사용 시점까지 보고 싶다면 선택적으로 활동 훅을 추가합니다. 이 옵션도 도구 입력·파일 경로·결과는 보내지 않고 tool_name만 보냅니다.
agent-broadcast hooks install all --activity프로젝트 설정에만 설치하려면 저장소 루트에서 --scope project를 사용합니다. 기본값은 사용자 범위입니다.
agent-broadcast hooks install all --scope project설치 후 Claude Code 또는 Codex를 다시 시작하고 각각 /hooks에서 전체 명령과 출처를 검토하세요. Codex 프로젝트 훅은 신뢰된 프로젝트에서만 실행되며, 설치한 훅의 신뢰 확인이 요청될 수 있습니다.
제거할 때도 Agent Broadcast가 관리하는 항목만 삭제합니다.
agent-broadcast hooks uninstall all훅 규격은 각 제품의 공식 문서를 따릅니다: Claude Code Hooks, Codex Hooks.
agent-broadcast broadcast <message> [--topic <topic>] [--agent <name>] [--node <name>] [--stream <stream>]
agent-broadcast recent [--count <1-100>] [--stream <stream>]
agent-broadcast doctor
agent-broadcast hooks install [claude|codex|all] [--scope user|project] [--activity]
agent-broadcast hooks uninstall [claude|codex|all] [--scope user|project]
예시:
# 현재 작업을 알리기
agent-broadcast broadcast "테스트를 실행합니다" --topic test --agent codex --node desktop
# 최근 20개 확인
agent-broadcast recent --count 20
# 프로젝트별로 Stream을 분리하기
$env:AGENT_BROADCAST_STREAM = "my-team:release"
agent-broadcast broadcast "배포 검토 준비 완료" --topic release --agent claude-code --node ci-runner--agent와 --node를 생략하면 실행 환경에서 가능한 값을 감지합니다. 협업 로그를 읽기 쉽게 하려면 처음에는 명시적으로 적는 편을 권합니다.
| 환경변수 | 기본값 | 설명 |
|---|---|---|
AGENT_BROADCAST_REDIS_URL |
redis://127.0.0.1:6379/0 |
Redis 주소. 사용자명·비밀번호·쿼리 문자열은 허용하지 않습니다. |
AGENT_BROADCAST_STREAM |
agent:broadcast |
공유할 Redis Stream 이름 |
AGENT_BROADCAST_NODE |
컴퓨터 이름 | 보낼 때 사용할 노드 이름 |
AGENT_BROADCAST_PROJECT |
현재 폴더 이름 | 훅이 공유할 안전한 프로젝트 표시명 |
AGENT_BROADCAST_HOOK_TIMEOUT_MS |
400 |
훅의 Redis 연결·읽기·쓰기 제한 시간(50~5,000ms) |
AGENT_BROADCAST_HOOK_DEBUG |
꺼짐 | 1이면 fail-open 오류를 stderr에 표시 |
아닙니다. 한 도구만 사용해도 메모·상태 알림 용도로 쓸 수 있습니다. 두 도구가 같은 Redis URL과 Stream 이름을 사용하면 자연스럽게 서로의 메시지를 봅니다.
아닙니다. 두 제품의 API나 로그인 정보에 접근하지 않습니다. Redis에 연결하는 로컬 CLI일 뿐입니다.
수동 명령은 broadcast 뒤에 직접 입력한 메시지를 저장합니다. 자동 훅은 위 표의 고정 생명주기 메시지와 agent, node, 익명 세션 ID, 프로젝트 폴더 이름만 저장합니다. 프롬프트와 코드 전문은 저장하지 않습니다. 수동 메시지에도 민감한 내용·개인정보·토큰을 넣지 마세요.
안 됩니다. Redis는 기본적으로 127.0.0.1에만 바인딩하고, 원격 협업은 VPN 또는 SSH 터널을 통해 로컬 포트로 연결하세요. 이 공개판은 비밀번호를 URL에 넣는 방식도 받지 않습니다.
가능합니다. 이제 agent-broadcast hooks install all이 Claude Code의 ~/.claude/settings.json과 Codex의 ~/.codex/hooks.json에 안전한 기본 훅을 병합합니다. 먼저 수동 명령으로 전달 경로를 확인한 뒤 설치하세요.
아닙니다. 자동 훅은 오류가 나도 항상 성공 종료하는 fail-open 방식입니다. Redis 작업은 기본 400ms 제한이며, 실패 시 에이전트의 원래 작업은 계속됩니다. 공유 정보가 빠질 수 있으므로 중요한 동시작업에서는 doctor와 recent로 연결 상태를 별도 확인하세요.
두 터미널에서 agent-broadcast doctor를 실행해 Redis 주소·DB 번호·Stream 이름이 같은지 확인하세요. 그 다음 Redis 프로세스 또는 터널이 실제로 열려 있는지 확인합니다. recent --count 100으로 조회 범위도 넓힐 수 있습니다.
Codex terminal ── broadcast ──┐
├── Redis Stream ── recent ── Claude Code terminal
Claude Code terminal ──────────┘
- Rust 네이티브 단일 바이너리이며 별도 훅 스크립트가 필요 없습니다. JSON 설정 병합에는
serde_json만 사용하고 Redis Streams에 필요한 RESP2는 직접 구현합니다. - 네트워크 연결·읽기·쓰기에 3초 제한을 둡니다.
- 자동 훅은 더 짧은 400ms 제한과 fail-open 동작을 사용합니다.
- 메시지는 공백만으로 된 값과 1,024자 초과 값을 거부합니다.
- Stream은
MAXLEN ~ 1000으로 추가되어 오래된 메시지가 자동 정리됩니다. - Redis 인증/TLS는 이 CLI가 아닌 안전한 로컬 터널 또는 프록시 계층에서 처리합니다.
cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release테스트에는 Redis 프로토콜, 기존 설정 보존·멱등 설치·안전한 제거, 훅 fail-open, 프롬프트·전체 경로 비전송, 실제 CLI ↔ 모의 Redis 서버 종단간 테스트가 포함됩니다.
MIT License로 공개합니다. 보안 문제는 공개 이슈에 민감정보를 올리지 말고 SECURITY.md의 안내를 따라 비공개로 신고해 주세요.