aannoo/hcom

코딩 에이전트들을 서로 연결하세요

hcom

은 에이전트들이 터미널을 가로질러 서로 메시지를 보내고, 관찰하며, 생성(spawn)할 수 있도록 지원하는 CLI입니다. Claude Code, Gemini, Codex, OpenCode와 통합되지만, 기존 사용 방식은 전혀 바꾸지 않습니다.

파이프라인을 조정하거나, 서로의 하위 에이전트(subagents)로서 다양한 AI CLI를 실행하거나, 단순히 복사-붙여넣기 대신 사용하는 용도로 활용하세요.

단일 Rust 바이너리로 구성되어 있으며, 백그라운드 서비스가 필요 없습니다. hcom을 앞에 붙여 에이전트를 시작한 다음, 평소처럼 프롬프트를 입력하세요.

hcom-video.mp4

brew install aannoo/hcom/hcom

기타 설치 옵션

# macOS, Linux, Android (Termux), 및 WSL을 위한 셸 설치 프로그램
curl -fsSL https://github.com/aannoo/hcom/releases/latest/download/hcom-installer.sh | sh

# PyPI 사용 시
uv tool install hcom # 또는: pip install hcom

터미널 1:

hcom claude # codex / gemini / opencode

터미널 2:

hcom codex

프롬프트:

다른 에이전트에게 가장 좋아하는 케이크가 무엇인지 물어봐

claude가 수행한 내용을 검토하고 수정 사항을 보내줘

gemini를 3개 생성(spawn)하여 작업을 분할하고 결과를 수집해

버그 조사를 위해 자신을 포크(fork)하고 결과를 보고해

TUI 열기:

hcom

메시지(Message): 의도(intent), 응답, 핸드오프(handoffs)를 위한 묶음 컨텍스트(bundled context)를 실시간으로 서로 주고받습니다.

관찰(Observe): 대화 기록(transcripts), 파일 수정, 터미널 화면, 명령 이력을 서로 관찰합니다.

생성(Spawn), 포크(fork), 재개(resume), 종료(kill): 어떤 터미널 에뮬레이터나 헤드리스(headless) 환경에서도 서로를 생성, 포크, 재개, 종료할 수 있습니다.

훅(Hooks)은 활동을 로컬 SQLite 데이터베이스에 기록하고 거기서 메시지를 전달합니다.

에이전트(agent) → 훅(hooks) → DB → 훅(hooks) → 다른 에이전트(other agent)

메시지는 턴 중간(도구 호출(tool calls) 사이에 주입됨)에 도착하거나 유휴(idle) 상태인 에이전트를 즉시 깨웁니다.

각 에이전트는 쿼리 가능한 식별자(identity)를 가집니다:

이름 (name)
상태 (status: active, blocked, listening)
받은 편지함 (inbox)
실시간 터미널 화면 (live terminal screen)
구조화된 청크(chunks) 형태의 대화 기록 (transcript)
모든 상태 변경, 파일 수정, 도구 호출의 이벤트 로그 (event log)

훅(Hooks)은 첫 실행 시 ~/ 아래의 설정 디렉토리(또는 HCOM_DIR)에 저장됩니다. hcom을 사용하지 않는다면 훅은 아무런 동작도 하지 않습니다.

훅이 없더라도, hcom start를 실행함으로써 다른 어떤 AI 도구든 참여할 수 있습니다. 어떤 프로세스든 hcom send를 통해 에이전트를 깨울 수 있습니다.

모든 에이전트는 사용자가 직접 보고, 스크롤하고, 중단할 수 있는 실제 터미널 (terminal)에서 실행됩니다. 어떤 에뮬레이터(emulator)든 실행(spawning)에 사용할 수 있습니다. kitty, wezterm, tmux, zellij, waveterm, cmux 또한 hcom kill을 통한 창 닫기를 지원합니다.

사용자 정의 터미널 열기/닫기 설정을 구성하려면, 에이전트에게 다음을 실행하도록 명령하십시오:

hcom config terminal --info

MQTT 릴레이 (relay)를 통해 여러 기기에 걸쳐 에이전트를 연결하십시오.

hcom relay new # 토큰(token) 획득
hcom relay connect <token> # 각 장치에서 실행

hcom relay status # 연결 상태 확인
hcom relay off|on # 토글 (toggle)

릴레이 보안 (Relay Security)

릴레이 페이로드 (payloads)은 종단간 암호화 (end-to-end encrypted)됩니다. 브로커 (Brokers)는 데이터를 볼 수 없습니다.
참여 토큰 (join token)을 SSH 키나 API 키와 같이 취급하십시오.
토큰이 유출되었을 가능성이 있다면, hcom relay off --all을 실행하여 모든 장치의 연결을 해제하십시오. 더 나은 보안을 위해 --broker 및 --password를 사용하여 개인용/사용자 정의/자체 호스팅 브로커를 사용하십시오.

hcom relay는 한 운영자의 장치들을 위한 하나의 신뢰 도메인 (trust domain)입니다. 멤버십은 전체 또는 전무 (all-or-nothing) 방식입니다. 범위가 지정된 역할 (scoped roles), 읽기 전용 피어 (read-only peers), 또는 장치별 권한은 존재하지 않습니다.

릴레이 페이로드는 XChaCha20-Poly1305와 함께 공유 PSK (Pre-Shared Key)를 사용합니다. 이 암호화는 각 페이로드를 릴레이, 토픽 (topic), 그리고 타임스탬프 (timestamp)에 결합합니다. 재전송 방지 장치 (replay guard)는 신선도 윈도우 (freshness window) 내의 중복된 엔벨로프 (envelopes)를 폐기합니다.

브로커와 네트워크 관찰자는 PSK 없이는 페이로드를 읽거나 위조할 수 없습니다. 다만 토픽 이름, 타이밍, 메시지 크기, 연결 패턴과 같은 메타데이터 (metadata)는 여전히 확인할 수 있습니다.

참여 토큰에는 릴레이 ID, 브로커 URL, 그리고 원시 PSK가 포함되어 있습니다. hcom은 서버에 이를 검증하도록 요청하지 않습니다. 토큰에는 만료 기간, 범위, 또는 폐기 목록 (revocation list)이 없습니다.

공용 브로커 (public brokers)에서 토큰이 유출되면 공격자가 릴레이에 대한 완전한 제어권을 갖게 됩니다. 공격자는 캡처된 트래픽을 복호화하고, 인증된 릴레이 트래픽을 게시하며, 대기 중인 에이전트에 텍스트를 보내고, 등록된 장치에서 에이전트를 실행하거나, 실행 중인 에이전트를 종료하고, 원격 릴레이 RPC를 사용할 수 있습니다. 만약 해당 에이전트들이 도구 (tools)를 실행할 수 있다면, 이를 릴레이 내의 모든 등록된 장치에 대한 셸 접속 (shell access)으로 간주해야 합니다.

--password를 사용하는 개인 브로커의 경우

, 토큰이 여전히 PSK (Pre-Shared Key)를 유출하므로, 캡처된 트래픽은 여전히 노출됩니다. 하지만 공격자가 브로커 비밀번호를 함께 가지고 있지 않는 한, 토큰만으로는 메시지를 발행(publish)할 수 없습니다. 브로커 측의 액세스 제어 (access control)가 중요하거나, 트래픽의 메타데이터 형태 자체가 민감한 경우에는 개인 브로커를 사용하십시오. --password는 브로커 액세스 제어 수단이지, 또 다른 계층의 메시지 암호화가 아닙니다.

순방향 비밀성 (Forward secrecy). 유출된 PSK는 이전에 캡처된 트래픽을 복호화할 수 있습니다.
릴레이 (relay) 내부의 장치별 귀속 (Per-device attribution). 송신자 신원은 라우팅 메타데이터 (routing metadata)일 뿐, 권한 부여 (authorization)가 아닙니다. 등록된 모든 장치는 완전한 권한을 가지고 통신합니다.
인증된 피어 (peer)로부터의 프롬프트 인젝션 (Prompt injection). 등록 (Enrollment)은 완전한 신뢰를 의미합니다. 피어는 단순히 메시지를 보내는 것을 넘어, RPC를 통해 에이전트 (agent)를 실행, 종료 및 제어할 수 있습니다. 셸 접속 (shell access)을 허용할 수 있는 장치만 등록하십시오.
로컬 OS 침해 (Local OS compromise). hcom은 로컬 사용자 계정과 ~/.hcom/config.toml을 신뢰합니다. 동일한 계정 내의 다른 사용자나 파일 시스템 접근 권한을 가진 멀웨어로부터는 방어하지 못합니다.

PSK는 ~/.hcom/config.toml에 저장됩니다. Unix에서 hcom은 해당 파일을 0600 모드로 작성합니다.

hcom은 PSK를 환경 변수 (environment variables)에 두지 않습니다. 원격 config_get 및 config_set은 relay_psk, relay_token, relay_id 및 브로커 URL을 거부합니다. hcom relay status는 짧은 지문 (fingerprint)만을 보여주므로, 두 장치가 키를 직접 출력하지 않고도 동일한 키를 공유하는지 확인할 수 있습니다.

해당 파일을 읽을 수 있는 사람(동일한 OS 계정의 다른 사용자, 멀웨어, 또는 권한을 보존하지 않고 작성된 백업 등)은 전체 PSK를 갖게 됩니다.

hcom relay off --all을 실행하십시오. 이 명령은 도달 가능한 모든 신뢰할 수 있는 피어에게 릴레이 비활성화를 요청한 다음 로컬에서 릴레이를 비활성화하여, 에이전트가 공격자의 메시지에 반응하는 것을 중단시킵니다. 이는 최선의 노력에 기반한 피해 통제 (damage control)일 뿐, 격리 (containment)는 아닙니다. 공격자의 장치는 이 요청을 무시할 수 있습니다.

PSK는 취소 (revoke)할 수 없습니다. 통지할 서버도 없고 업데이트할 블랙리스트 (denylist)도 없습니다. PSK를 가진 사람은 당신이 사용을 중단할 때까지 기존 릴레이를 계속 사용할 수 있습니다.

유출 발생 후에도 릴레이 (relay)를 계속 사용하려면, hcom relay new 명령어로 새로운 릴레이를 생성하십시오.

그리고 모든 신뢰할 수 있는 장치 (device)를 새로운 토큰 (token)으로 이동시키십시오. 로테이션 (Rotation)을 수행하면 relay_id도 변경되므로, 기존 브로커 토픽 (broker topics)에 유지되던 상태 (state)는 고아 (orphaned) 상태가 됩니다.

hcom status # 진단 (diagnostics)
hcom reset all # 초기화 및 아카이브 (archive): 데이터베이스 (database) + 훅 (hooks) + 설정 (config)

hcom hooks remove # 모든 hcom 훅 (hooks)을 안전하게 제거
brew uninstall hcom # 또는: rm $(which hcom)

도구 (Tools)

도구 (Tool)	메시지 전달 (Message delivery)	연결 (Connect)
Claude Code	자동 (automatic)	`hcom claude`
...	`hcom start` (도구 내부에서 실행)

hcom r <session_id> # hcom 외부에서 시작된 세션 (session) 재개
hcom f <session_id> # hcom 내에서 세션 포크 (Fork)

프린트 모드 (print mode)에서의 분리된 백그라운드 프로세스 (Detached background processes)는 계속 살아있습니다. TUI를 통해 관리하십시오.

hcom claude -p 'say hi in hcom'

서브에이전트 (subagents)의 경우, hcom claude를 실행한 후 다음과 같이 프롬프트 (prompt)를 입력하십시오:

run 2x task tool and get them to talk to each other in hcom

CLI

셸 (shell)에서 입력할 수 있는 명령어들입니다. 에이전트 (Agents)는 실행 시 hcom CLI 입문서 (primer, 약 700 토큰)를 통해 학습한 자체 명령어를 실행합니다. 전체 플래그 (flags)를 확인하려면 hcom <command> --help를 사용하십시오.

hcom [N] claude|gemini|codex|opencode # N개의 에이전트 실행
hcom r <name|session_id> # 에이전트 재개
hcom f <name|session_id> # 세션 포크
...

hcom 실행 플래그 (launch flags):

플래그 (Flag)	목적 (Purpose)
`--tag <name>`	그룹 라벨 (Group label) — 에이전트는 `@tag`로 호출될 수 있음
`--terminal <preset>`	창이 열리는 위치: `default` (자동 감지), `kitty`, `wezterm`, `tmux`, `cmux`, `iterm` 등
`--dir <path>`	에이전트가 실행되는 디렉토리 (Directory)
`--headless`	터미널 창 없이 백그라운드에서 실행
`--device <name>`	원격 장치 (remote device)에서 생성 (릴레이를 통해)
`--hcom-prompt <text>`	초기 사용자 프롬프트 (Initial user prompt)
`--hcom-system-prompt <text>`	시스템 프롬프트 (system prompt)에 추가

그 외의 모든 것은 도구로 전달됩니다: --model sonnet, --yolo 등.

hcom # TUI 대시보드 (dashboard)
hcom send -b @luna -- hey # 에이전트에게 일회성 메시지 전송
hcom list # 모든 활성 에이전트 표시
...

hcom run docs --cli

모든 명령에 대해.

설정 (Config)

설정은 ~/.hcom/config.toml에 저장됩니다.

. 우선순위: 기본값 (defaults) < config.toml < 환경 변수 (env vars).

hcom config # 소스와 함께 모든 값 표시
hcom config <key> # 가져오기
hcom config <key> <value> # 설정하기
...

키 (Key)	목적 (Purpose)
`tag`	그룹 레이블 (Group label) — 실행된 에이전트는 `tag-name`이 됩니다
`hints`	에이전트가 받는 모든 메시지에 추가되는 텍스트
`notes`	부트스트랩 (bootstrap, 실행 시 1회)에 추가되는 텍스트
`auto_approve`	안전한 hcom 명령(send/list/events/…)을 자동 승인 (Auto-approve)
(이벤트 구독 프리셋: `collision`, `created`, `stopped`, `blocked`)
`name_export`	인스턴스 이름을 사용자 정의 환경 변수 (custom env var)로 내보내기
`terminal`	새로운 에이전트 창이 열리는 위치 (`hcom config terminal --info`)
`timeout`	헤드리스/바닐라 Claude (headless/vanilla Claude)의 유휴 시간 제한 (초 단위)
`subagent_timeout`	Claude 서브 에이전트 (subagents)의 Keep-alive 시간 (초 단위)
`claude_args` / `gemini_args` / `codex_args` / `opencode_args`	도구에 전달되는 기본 인자 (Default args)

hcom config tag mycrew # 전역 (global)
hcom config -i luna hints "respond in JSON" # 에이전트별 (per-agent)
HCOM_TAG=dev hcom 3 claude # 실행 시 환경 변수 (per-launch env)

export HCOM_DIR="$PWD/.hcom" # 상태(state)와 훅(hooks)을 이 폴더로 격리
hcom hooks remove && rm -rf "$HCOM_DIR"

각 키에 대한 전체 참조를 확인하려면:

hcom config <key> --info를 실행하거나

hcom run docs --config를 실행하세요.

실행되는 모든 에이전트에 전달할 외부 환경 변수를 설정하려면:

~/.hcom/env를 편집하세요.

워크플로 스크립트 (Workflow Scripts)

멀티 에이전트 패턴을 위한 번들 및 사용자 스크립트 (~/.hcom/scripts/)가 포함되어 있습니다:

hcom run # 사용 가능한 스크립트 목록 표시
hcom run debate "topic" # 하나 실행
hcom run docs # 에이전트에게 새로운 워크플로 생성을 위해 이를 실행하도록 지시

에이전트에게 실행을 지시하세요:

** hcom run confess** — 에이전트(또는 백그라운드 클론)가 정직한 자기 평가(honesty self-eval)를 작성합니다. 생성된 캘리브레이터(calibrator)가 대상의 트랜스크립트(transcript)를 독립적으로 읽습니다. 판사(judge)가 두 보고서를 비교하고 hcom 메시지를 통해 판결을 보냅니다.

** hcom run debate** — 판사(judge)가 생성되어 기존 에이전트(agents)들과 토론(debate)을 설정합니다. 모든 에이전트가 서로의 논거를 볼 수 있는 공유 스레드에서 라운드를 조정하며, 워크스페이스 파일과 트랜스크립트(transcripts)의 공유 컨텍스트(context)를 가집니다.

커스텀 스크립트(Custom scripts): *.sh 또는 *.py 파일을 ~/.hcom/scripts/ 디렉토리에 넣으세요.

— 자동으로 검색되며, 동일한 이름의 번들(bundled) 스크립트를 덮어씁니다. 에이전트에게 스크립트 작성을 요청하세요; hcom run docs --scripts가 작성 가이드입니다.

빌드 (Build)

# 필수 요구사항: Rust 1.88+
git clone https://github.com/aannoo/hcom.git
cd hcom
...

두 가지 옵션이 있습니다:

심볼릭 링크 (Symlink) — 간단하며, 개발 빌드(dev build)가 전역(global)으로 적용됩니다.

ln -sf $(pwd)/target/debug/hcom ~/.cargo/bin/hcom

dev_root — hcom이 어떻게 설치되었는지(brew, pip 등)와 상관없이 작동하며, debug/release 중 더 최신 것을 자동으로 선택합니다:

hcom config dev_root $(pwd)
hcom config dev_root --unset # 되돌리기
hcom status # 로컬 빌드 실행

동시 작업용 워크트리(worktrees)를 사용하는 경우, 각각을 고유한 DB로 범위를 지정하세요:

HCOM_DIR=$PWD/.hcom HCOM_DEV_ROOT=$PWD hcom claude

이슈(Issues)와 PR(Pull Requests)을 환영합니다. 코드베이스는 Rust로 작성되었습니다.

cargo build && cargo test
hcom config dev_root $(pwd)
hcom status