Letterbox

📌 내부 프로덕션 사용을 위해 제작됨. 수개월간의 일일 AI 개발을 통해 검증된 아키텍처. 참조 구현으로 오픈소스화되었습니다.

쉽게 말하면: 터미널에서 AI 코딩 어시스턴트를 사용한다면, 보통 한 번에 하나씩만 작업하게 됩니다 — 두 개를 협업시키려면 직접 창 사이에서 메시지를 복사-붙여넣기해야 하죠. Letterbox를 사용하면 두 어시스턴트(예: Claude와 Gemini, 또는 Gemini와 Mistral의 Vibe)가 직접 서로 대화하고 함께 작업을 처리할 수 있습니다. 핸즈프리로요.

결과: 한 에이전트가 계획을 세우는 동안 다른 에이전트가 검토하거나, 둘이 작업을 분담할 수 있습니다 — 모든 메시지를 직접 중계하는 대신, 지켜보는 동안 스스로 협업합니다.

두 AI 에이전트가 서로 다른 터미널에서 실시간으로 대화할 수 있게 해주는 작은 파일 기반 통신 프로토콜.

Letterbox는 두 터미널 코딩 에이전트 — Claude Code, Gemini CLI, Antigravity, 또는 Mistral의 Vibe — 가 공유 디렉토리를 통해 메시지 파일을 주고받으며 실시간 대화를 할 수 있게 해줍니다. 한 에이전트가 말하면 📬 알림이 상대방 터미널에 주입되어 깨어나 읽고 답하게 됩니다. 네트워크도, 서버도, 공유 메모리도 없습니다: 폴더 안의 JSON 파일과 OS의 원자적 이름 변경(atomic-rename)만 있을 뿐입니다. 내부 계획 루프를 위해 만들어진 메시징 레이어로, 2026년에 독립형 버전 관리 도구로 분리되었습니다. 두 CLI 에이전트가 창 사이에서 복사-붙여넣기 없이 협업하길 원한 적이 있다면, 이 도구가 바로 그 목적에 맞습니다. 작성자의 재량에 따라 가끔 업데이트됩니다(런처가 새 버전이 나왔을 때 알려줍니다) — 하지만 지원되지 않습니다: 로드맵도, 기능 요청도, 커뮤니티 프로젝트도 아닙니다.

브리지는 진정한 크로스-하네스입니다: 한쪽에 Claude, 다른 쪽에 Gemini가 같은 채널을 통해 대화하는 것이 실제로 검증되었습니다. 유일한 단점은 설정입니다 — Claude는 자동으로 연결되지만, Gemini와 Antigravity는 자체 설정에서 letterbox를 로드합니다. 설정 섹션에서 두 경우를 모두 다룹니다.

왜 만들어졌나

저는 매일 두 명의 AI 협업자 — Claude와 Gemini — 와 함께 일합니다. 각각은 실행되는 터미널 하네스(Claude Code, Gemini CLI, Antigravity CLI, 그리고 이제 Mistral의 Vibe) 안에 살고 있습니다. Letterbox는 이들이 저를 통하지 않고 서로 대화하게 만드는 방법입니다.

이는 두 가지 모드로 이루어집니다. 때로는 수동입니다: 브레인스토밍 중에 다른 모델을 대화에 끌어들이고 싶을 때입니다. 때로는 자동입니다 — 계획 루프에서 Claude가 계획을 초안하고 각 계획은 내장 단계로 검토를 위해 Gemini로 라우팅됩니다. Letterbox는 두 경우 모두 동일한 방식으로 전달합니다.

설계상 하네스에 구애받지 않습니다 — Claude Code ↔ Gemini CLI ↔ Antigravity CLI ↔ Vibe 어떤 조합이든 가능하며, 같은 모델 쌍도 잘 작동합니다: 두 개의 Claude 탭, 또는 두 개의 Gemini 탭이 하나의 채널로 대화합니다.

Related MCP server: claude-intercom

무엇인가

각 letterbox <harness> 실행은 하나의 터미널 안에서 두 개의 조정된 프로세스를 실행합니다:

  letterbox claude --channel demo --as alice
        │
        ├─ PTY-Parent  (the foreground letterbox process)
        │    • spawns the harness CLI as a PTY child
        │    • watches the channel directory for peer writes
        │    • injects 📬 notifications into the PTY on arrival
        │
        └─ the harness spawns:
             └─ letterbox mcp  (stdio MCP server, agent-spawned)
                  • send_message / check_messages / acknowledge
                  • check_latest_message / channel_info / list_channels

  Both sides coordinate ONLY through the filesystem:

        ~/.letterbox/channels/demo/
          msg-*.json           ← one file per message
          .read/alice.json     ← per-agent read markers
          .read/bob.json

데몬도, IPC도, 백그라운드 서비스도 없습니다. 파일시스템 자체가 조정 매체입니다 — PTY-Parent의 watcher가 새 msg-*.json이 나타나는 것을 보고 알림을 렌더링합니다; 채널 디렉토리는 영구적이고, 검사 가능하며, cat으로 볼 수 있습니다. 크래시 복구는 메모리에 중요한 것이 없기 때문에 사소합니다.

에이전트가 letterbox 도구를 얻는 방식은 하네스마다 다르며, 이것이 한 번만 설정하면 되는 유일한 것입니다:

• Claude Code는 실행 플래그를 받으므로, letterbox가 자동으로 연결합니다 — 임시 MCP 구성을 생성하고 --mcp-config를 claude에 전달합니다. 설정할 것이 없습니다.

• Gemini CLI와 Antigravity는 해당 플래그를 받지 않습니다; 자체 설정 파일에서 MCP 서버를 로드합니다. 채널에 구애받지 않는 한 줄의 letterbox 항목을 한 번 추가하면, 런처가 각 세션에 채널과 정체성을 환경 변수로 전달합니다 — 채널별로 설정을 편집할 필요가 없습니다.

• Vibe는 ~/.vibe/config.toml에서 MCP 서버를 로드합니다. MCP 하위 프로세스는 축소된 환경만 상속하므로, Vibe 자체 프로세스 환경에서 LETTERBOX_CHANNEL / LETTERBOX_SENDER를 중계하는 일회성 브리지 스크립트가 필요합니다. 일단 설정되면 모든 채널이 Gemini와 정확히 동일하게 작동합니다. Vibe 설정 섹션을 참조하세요.

대상 사용자

• 한 머신에서 자율적인 AI↔AI 대화를 원하는 터미널 코딩 에이전트 사용자 — 창 사이의 복사-붙여넣기를 관리할 필요 없이.

• 파일을 진실의 원천으로 여기는 사람 — 감사 가능하고, grep 가능하며, 불투명한 프로토콜도, 마법도 없습니다.

대상이 아닌 사용자

• 호스팅 또는 네트워크 채팅 서비스를 원하는 사람 — 메시지 프로토콜은 파일시스템 로컬이며 네트워크에 절대 닿지 않습니다. (런처는 시작 시 한 번의 선택적, 최선 노력(best-effort) 버전 확인을 수행합니다; LETTERBOX_NO_UPDATE_CHECK=1로 비활성화할 수 있습니다.)

• 다중 사용자 플랫폼을 원하는 사람 — 한 머신의 에이전트 간 지점 간(point-to-point) 브리지이지, 다수 사용자 허브가 아닙니다 (2인용 설계 참조).

• Windows 네이티브 사용자 — v1은 POSIX 전용입니다 (지원하지 않는 것 참조).

• 지원되는 제품을 원하는 사람 — letterbox는 버전 관리되며 작성자의 재량에 따라 가끔 업데이트됩니다(런처가 새 버전이 나왔을 때 알려줍니다), 하지만 로드맵도, SLA도, 기능 요청을 받거나 유지보수를 계속할 의무도 없습니다. 있는 그대로 사용하세요; 도움이 된다면 새 버전을 받으세요.

2인용 설계

Letterbox는 본질적으로 양방향 브리지입니다 — 한 피어가 한 피어와 대화하는 것이 설계되고 최적화된 용도입니다. 세 개 이상의 에이전트도 채널을 공유할 수 있습니다: 지시적 주소 지정(send_message(to="<label>"))과 participants 목록으로 작동 가능하며, 같은 채널의 브로드캐스트는 모두에게 도달합니다. 하지만 공유 채널은 브로드캐스트 버스입니다 — 모든 메시지가 모든 참가자를 깨웁니다. 오케스트레이션(턴 테이킹, 지정된 코디네이터, 또는 누가 언제 말할지에 대한 규칙) 없이는, N-way 룸은 모델의 메시지/사용량 한도를 놀라울 정도로 빠르게 소진시키는 알림 폭풍이 됩니다. 세 개 이상을 원한다면, 직접 지휘자를 가져오세요. 기반은 누가 방에 있는지 정직하게 알려줍니다; 예절은 당신의 몫입니다.

설치

Letterbox는 소스에서 설치됩니다(휠 빌드 가능; 현재 PyPI에 게시되지 않음). 저장소 루트에서:

pip install -e .          # or: pip install -e ".[dev]" for the test extras

이렇게 하면 letterbox 명령이 PATH에 추가됩니다. 명령은 이름으로 해석되어야 합니다 — 각 에이전트가 letterbox mcp를 직접 실행하므로 — 이는 중요한 사항입니다. 확인:

which letterbox           # note this absolute path; Gemini/Antigravity setup needs it

또한 실행할 하네스(claude, gemini, antigravity, 또는 vibe)가 설치되어 있고, PATH에 있으며, 로그인되어 있어야 합니다. Letterbox가 대신 실행해 줍니다.

업데이트

Letterbox는 버전 관리됩니다(letterbox.__version__, 단일 진실의 원천); PyPI 릴리스가 없으므로 git main HEAD가 곧 릴리스입니다. 사람이 보는 실행에서 CLI는 최선 노력 확인을 한 번 수행하고(하루 최대 한 번, ~/.cache/letterbox/에 캐시됨) 새 버전이 있으면 한 줄 알림을 출력합니다. 업데이트하려면:

pip install --upgrade "git+https://github.com/dovahkiin-v/letterbox"

이것이 letterbox가 수행하는 유일한 네트워크 호출입니다 — 메시징 프로토콜은 완전히 로컬로 유지됩니다. 짧은 타임아웃으로 실행되며 완전히 실패-무음(fail-silent)입니다: GitHub에 도달할 수 없으면 아무것도 출력하지 않고 실행을 지연시키지 않습니다. letterbox mcp(에이전트의 stdio 서버)에서는 절대 실행되지 않습니다. LETTERBOX_NO_UPDATE_CHECK=1로 완전히 비활성화하세요.

하네스별 설정

하네스당 한 번만 하면 됩니다. 사용하지 않을 하네스는 건너뛰세요.

Claude Code — 할 일 없음

Letterbox가 Claude를 자동으로 연결합니다: 실행 시 임시 MCP 구성(모드 0600)을 작성하고 --mcp-config <path>를 claude에 전달합니다. letterbox 도구는 해당 세션에만 나타나며 다른 곳에는 없습니다. 편집할 설정 파일이 없습니다.

Gemini CLI — 두 가지 일회성 단계

1. MCP 서버 등록 — ~/.gemini/settings.json에 (파일이 없으면 생성). 위의 which letterbox에서 얻은 설치된 letterbox의 절대 경로를 사용하고, ["mcp"]만 전달하세요 — 채널도, 정체성도 없이:

{
  "mcpServers": {
    "letterbox": {
      "command": "/absolute/path/to/letterbox",
      "args": ["mcp"]
    }
  }
}

이 항목은 의도적으로 채널에 구애받지 않습니다. 런처가 LETTERBOX_CHANNEL, LETTERBOX_SENDER, LETTERBOX_INSTANCE_ID를 실행 시 Gemini의 환경으로 내보내고, MCP 서버가 이를 읽습니다 — 따라서 동일한 단일 항목이 모든 채널에 적용되며 다시 편집할 필요가 없습니다. (이는 Forge 오케스트레이터가 환경 변수를 통해 채널을 전달하는 방식과 동일합니다.)

2. 실행 폴더를 신뢰하세요. Gemini는 대화형 "이 폴더를 신뢰하시겠습니까?" 프롬프트 없이는 신뢰되지 않은 디렉토리에서 실행을 거부합니다 — 그리고 차단형 TUI 프롬프트는 자동화를 중단시킬 수 있습니다. 실행 디렉토리(또는 상위 디렉토리)를 ~/.gemini/trustedFolders.json에 미리 신뢰하세요:

{
  "/home/you/projects": "TRUST_PARENT"
}

TRUST_FOLDER는 정확히 해당 디렉토리를 신뢰합니다; TRUST_PARENT는 해당 디렉토리와 그 아래 모든 것을 신뢰하므로, 하나의 항목으로 모든 프로젝트 폴더를 커버합니다. (팁: 이를 피하려고 Gemini의 --skip-trust 플래그를 사용하지 마세요 — 이미 신뢰된 디렉토리에서도 크래시를 일으키는 워크스페이스 시스템 프롬프트 조회를 강제합니다. 대신 폴더를 신뢰하세요.)

Antigravity (agy)

letterbox agy … 로 실행하세요 (긴 형식 letterbox antigravity …도 작동합니다 — agy는 바이너리 이름과 일치하는 별칭일 뿐입니다). Antigravity는 Gemini와 동일한 환경 변수를 통해 실행별 채널과 정체성을 받습니다; 다른 점은 MCP 서버를 등록하는 방식입니다. agy는 플러그인에서 MCP 서버를 로드하므로, letterbox를 작은 로컬 플러그인(두 개의 JSON 파일이 있는 디렉토리)으로 설치합니다:

# 1. Build the plugin (one directory, two files). Use the absolute
#    `letterbox` path from `which letterbox`.
mkdir -p ~/.letterbox/agy-plugin/letterbox
cat > ~/.letterbox/agy-plugin/letterbox/plugin.json <<'JSON'
{ "name": "letterbox", "version": "1.0.0",
  "description": "Letterbox file-based AI-to-AI comms bridge." }
JSON
cat > ~/.letterbox/agy-plugin/letterbox/mcp_config.json <<'JSON'
{ "mcpServers": { "letterbox": {
    "command": "/absolute/path/to/letterbox", "args": ["mcp"] } } }
JSON

# 2. Install it (and confirm).
agy plugin install ~/.letterbox/agy-plugin/letterbox
agy plugin list

mcp_config.json은 Gemini의 설정 항목과 같은 이유로 채널에 구애받지 않습니다 — 런처가 실행 시 환경으로 채널과 정체성을 전달합니다. Gemini와 마찬가지로 agy도 폴더 신뢰를 확인합니다: ~/.gemini/antigravity-cli/settings.json의 trustedWorkspaces 목록을 존중하므로, 아직 없다면 실행 디렉토리를 거기에 추가하세요.

상태: PTY 레이어(알림 + 메시지 전달, 양방향)는 실제로 검증되었으며, 위의 플러그인 설치는 도구를 깔끔하게 연결합니다. agy에서의 전체 도구 왕복은 최근에 작동하며 가볍게 테스트되었습니다 — Antigravity를 세 가지 중 가장 최신으로 취급하고 이상한 점이 있으면 보고하세요.

Vibe (Mistral)

letterbox vibe … 로 실행하세요. Vibe는 ~/.vibe/config.toml에서 MCP 서버를 로드하지만, MCP 하위 프로세스는 축소된 환경(HOME, PATH, SHELL, TERM, USER, LOGNAME)만 상속합니다 — 따라서 LETTERBOX_CHANNEL 등이 일반 상속으로 도달하지 않습니다. 작은 일회성 브리지 스크립트가 생성 시 /proc을 통해 Vibe의 프로세스에서 이를 읽어 해결합니다. 그 후에는 모든 채널이 Gemini와 정확히 동일하게 작동합니다 — 채널별 구성 편집이 없습니다.

1. 브리지 스크립트 설치 (letterbox와 함께 제공):

cp "$(python3 -c 'import letterbox.data, pathlib; print(pathlib.Path(letterbox.data.__file__).parent / "vibe-mcp-bridge.sh")')" \
   ~/.letterbox/vibe-mcp-bridge.sh
chmod +x ~/.letterbox/vibe-mcp-bridge.sh

2. ~/.vibe/config.toml에 등록. 기존 letterbox 항목을 다음으로 교체:

[[mcp_servers]]
name = "letterbox"
transport = "stdio"
command = "/home/YOU/.letterbox/vibe-mcp-bridge.sh"
args = []

실제 홈 경로를 사용하세요(~ 아님 — Vibe가 확장하지 않을 수 있습니다). 항목은 의도적으로 채널에 구애받지 않습니다: 브리지 스크립트는 Gemini가 환경에서 읽는 것과 정확히 동일하게, 런타임에 Vibe의 프로세스 환경에서 채널과 정체성을 읽습니다.

3. 완료. 모든 채널이 작동합니다:

letterbox vibe --channel blueberry-fields --as mistral

Vibe는 또한 --yolo(자동 승인)로 실행되어 주입된 알림이 도구별 프롬프트에서 차단되지 않고 깨어날 수 있습니다.

참고: 브리지 스크립트는 /proc/$PPID/environ을 사용하여 Vibe의 환경을 읽습니다 — Linux 전용이며, 이는 letterbox의 POSIX 전용 입장과 일치합니다. macOS 지원은 다른 메커니즘(ps -p $PPID -Ewww)이 필요합니다; 현재는 제공되지 않습니다.

상태: 📬 웨이크 주입(wake injection)이 정상 동작함이 확인되었습니다(STEP 0에서 Vibe의 ChatTextArea가 Enter를 제출로 오버라이드한다는 것을 검증했으므로, 표준 PTY 주입 경로가 적용됩니다). Vibe를 네 가지 중 가장 최신으로 취급하고 이상한 점이 있으면 보고하세요.

빠른 시작

두 개의 터미널을 열고 각각 서로 다른 정체성으로 같은 채널을 가리키세요. 설정 파일이 없으면 letterbox의 기본값이 공유 전역 상태 디렉터리(~/.letterbox)를 제공합니다.

진정한 크로스-하네스 브리지 — Claude가 Gemini와 대화합니다(Gemini 설정을 먼저 완료하세요):

# Terminal 1
letterbox claude --channel demo --as claude

# Terminal 2
letterbox gemini --channel demo --as gemini

또는 더 단순하게 하려면 같은 하네스 두 개를 사용하세요:

# Terminal 1
letterbox claude --channel demo --as alice

# Terminal 2
letterbox claude --channel demo --as bob

두 세션 모두 시작되어 조용히 대기합니다. 이제 터미널 1에서 에이전트를 깨워 보세요 — 예를 들어, "피어에게 메시지를 보내세요." 그 시점부터 각 📬 알림이 상대 에이전트를 깨워 읽고 답하게 합니다: 그 핸드오프가 바로 이 도구의 핵심입니다. --as <label> 이름은 대화 기록을 읽기 쉽게 만들기 위한 것이며, 내부적으로 메시지 필터링은 라벨이 아닌 실행별 인스턴스 ID를 사용합니다.

솔직한 메모 몇 가지:

• letterbox mcp를 직접 실행할 일은 없습니다. 이 하위 명령은 stdio MCP 서버로, 하네스가 생성합니다 — 에이전트를 위한 것이지 여러분을 위한 것이 아닙니다. 터미널에서 직접 실행하면 그렇게 알려주고 종료됩니다.

• 실행 인자는 기본적으로 자율적입니다. Claude 어댑터는 --dangerously-skip-permissions로, Gemini 어댑터는 --yolo로 실행됩니다. 주입된 메시지는 작업별 승인 프롬프트에 막혀 있는 에이전트를 깨울 수 없기 때문입니다. 그런 트레이드오프가 마음에 들지 않는다면 letterbox는 적합한 도구가 아닙니다 — letterbox.toml에서 인자를 재정의하거나 사용을 중단하세요.

전체 내레이션 워크스루(핫도그가 샌드위치인지 토론하는 두 Claude)는 examples/two-claudes-debating/ 아래의 샘플 프로젝트를 참조하세요.

브리지 상태 파악하기

설정이 연결된 하네스는 모든 세션에서 letterbox를 로드하므로, 에이전트가 활성 브리지 없이 letterbox 도구를 사용할 수 있습니다 — 예를 들어, letterbox를 통해 실행하지 않은 일반 Gemini 세션 같은 경우입니다. Letterbox는 이를 차분하게 처리하고 에이전트가 확인할 수 있는 방법을 제공합니다:

• 일반 세션은 휴면 상태이지, 고장이 아닙니다. 채널이 없어도 MCP 서버는 여전히 연결됩니다(하네스는 차분한 "연결됨"을 표시). 하지만 메시징 도구는 조용히 유지됩니다 — 실제로 호출될 때만 명확하고 실행 가능한 메시지와 함께 실패하며, 스스로 실패하지 않습니다. 의도적인 일반 세션은 절대 스팸을 받지 않습니다. 진짜 잘못 구성된 브리지는 에이전트가 대화를 시도하는 순간 드러납니다.

• channel_info는 에이전트의 브리지 오라클입니다. 이를 호출하면 서버 측에서 답합니다: 브리지가 활성화되어 있는가? 어떤 채널에서, 누구로? 피어는 누구인가(가장 최근 메시지에서 관찰), 읽지 않은 메시지는 몇 개인가, 마지막으로 말한 때는 언제인가? 상황이 불확실한 에이전트는 보내기 전에 물어볼 수 있습니다 — *"피어가 90초 전에 마지막으로 말함"*은 *"한 번도 말한 적 없음"*과는 매우 다르게 읽힙니다.

채널 보기 및 목록 확인

어느 터미널에서든 원시 대화를 보거나 존재하는 채널을 확인할 수 있습니다:

letterbox tail --channel demo --follow   # stream messages as JSON, one per line
letterbox list-channels                  # list channels with last-activity

기본값에 의존하는 대신 시작용 letterbox.toml을 생성하려면:

letterbox init --channel demo            # writes ./letterbox.toml (project-local)
letterbox init --global                  # writes ~/.letterbox/config.toml instead

운영

• 읽기는 따라잡기를 의미하며, 받은 편지함은 스스로 비워집니다. check_messages는 읽지 않은 피어 메시지를 반환하고 진행하면서 해당 에이전트의 읽기 마커를 전진시킵니다 — 따라서 연속 호출이 백로그를 페이지 단위로 넘기고, 비워진 받은 편지함은 수동 정리 없이 비워진 상태로 유지됩니다. check_latest_message는 일반적인 "방금 뭐라고 했지?" 상황을 위한 비전진 엿보기이며, acknowledge는 명시적인 단일 메시지 제어를 위한 것입니다.

• 재시작은 재생이 아니라 새 시작입니다. 실행 시 에이전트의 읽기 마커는 이미 디스크에 있는 가장 최신 메시지에 맞춰지므로, 참여 이후 도착한 메시지만 볼 수 있습니다 — 이전 세션의 채널 전체 기록이 쏟아지지 않습니다. 기록은 여전히 존재하며 필요 시 접근할 수 있습니다(since_id 커서가 있는 check_messages). 강제로 밀어넣지 않을 뿐입니다.

• 보존은 수동입니다. 메시지는 직접 정리할 때까지 채널 디렉터리에 남아 있습니다. 자동 삭제는 없습니다(통신 인프라에서 갑작스러운 삭제는 용납할 수 없습니다). 에이전트별 .read/ 마커가 읽기 상태를 추적합니다 — 마커를 전진시킬 뿐, 파일을 건드리지 않으며, 피어의 보기에 영향을 주지 않습니다.

• 실질적 상한: 채널당 미정리 메시지 약 10,000개. 그 이상이 되면 check_messages와 list-channels에서 눈에 띄는 지연이 발생할 수 있습니다. 그 지점 이상에서는 정리하세요.

• letterbox prune은 공간을 회수하는 안전한 방법입니다. 기본적으로 드라이런(dry-run) 입니다 — 어떤 일이 일어날지 출력만 하고 아무것도 건드리지 않습니다. --yes-i-am-sure는 일치하는 파일을 되돌릴 수 있는 cold/ 하위 디렉터리로 이동합니다. --delete --yes-i-am-sure(이중 게이트)는 영구 삭제합니다. 이것이 letterbox에서 유일한 파괴적 명령입니다.

letterbox prune --channel demo --keep-last 100                   # preview (dry run)
letterbox prune --channel demo --keep-last 100 --yes-i-am-sure   # move to cold/
letterbox prune --help                                           # all selection rules

채널은 그냥 폴더이므로 rm -rf ~/.letterbox/channels/demo도 작동합니다 — letterbox는 아무것도 잠그지 않습니다.

보안 모델

전체 위협 모델은 docs/PROTOCOL.md에 있습니다. 요약하면:

• 채널의 피어 에이전트는 신뢰할 수 없습니다. 피어의 메시지 본문에는 프롬프트 주입 페이로드, ANSI 이스케이프, 셸 메타문자가 포함될 수 있습니다. Letterbox는 양쪽 모두를 신뢰할 수 없는 것으로 취급합니다.

• 알림은 신뢰할 수 있는 컨텍스트에서만 렌더링됩니다. 📬 알림 템플릿은 감시자의 자체 구성과 관찰에서 가져온 변수({channel}, {sender}, {message_id}, {timestamp})만 대체합니다 — 피어의 메시지 페이로드에서 가져온 것은 절대 없습니다. 악의적인 피어는 자신의 파일에 무엇이든 쓸 수 있지만, 그 어떤 것도 주입된 알림에 도달하지 않습니다. 메시지 본문은 에이전트가 check_messages를 명시적으로 호출할 때만 표시됩니다. channel_info의 피어 필드도 마찬가지입니다: 트래픽에서 관찰된 정보 제공용이며, 알림에 절대 사용되지 않습니다.

• 실행 경로가 없습니다. Letterbox는 메시지 본문이나 메타데이터 필드를 exec, eval, 셸 실행하지 않습니다. 하위 프로세스는 argv 목록으로 생성되며(shell=True 절대 사용 안 함), letterbox.toml에 구성된 하네스를 실행할 때만 사용됩니다.

• 경로 안전성. 채널 이름과 메시지 ID는 파일 시스템 작업 전에 엄격한 패턴으로 검증됩니다 — ../etc 또는 슬래시가 포함된 것은 거부됩니다.

• 파일 시스템 권한. ~/.letterbox/와 채널 디렉터리는 0700(사용자 전용)으로 생성됩니다. 생성된 MCP 구성은 0600입니다.

letterbox가 방어하지 않는 것: 손상된 로컬 사용자 계정(파일 시스템 권한이 유일한 장벽), 소비 하네스 자체의 프롬프트 주입 취약점, 또는 크로스 머신 동기화(NFS, syncthing)로 도입되는 신뢰 경계. 저장 데이터 암호화나 네트워크 신뢰 계층이 아닙니다 — 이는 설계상 범위 밖입니다.

범위와 반-범위

letterbox가 의도적으로 하지 않는 일은 공백이 아니라 핵심입니다:

• LLM 호출 없음. Letterbox는 언어 모델을 호출하지 않고, 토큰을 소비하지 않으며, API 키를 보유하지 않습니다. 알림 템플릿은 렌더링된 텍스트이지 프롬프트가 아닙니다.

• 텔레메트리, 메트릭, 분석 없음. 수집되는 것, 대시보드, 사용 추적이 없습니다.

• 전화 집(phone-home), 자동 업데이트, 버전 확인 없음. Letterbox는 어떤 서버에도 접촉하지 않습니다. 첫 실행은 조용합니다.

• 네트워크 없음. 파일 시스템 로컬입니다. 크로스 머신 사용은 파일 시스템 동기화의 몫이지 letterbox의 몫이 아닙니다.

이 반-범위 덕분에 letterbox는 작고, 비활성적이며, 감사 가능하고, 내구성이 있습니다.

접근성

• 기본적으로 일반 텍스트(--format=plain) — 파이프 및 화면 판독기 친화적입니다. tail은 jq용으로 메시지 JSON을 stdout에 출력합니다. 구조화/컬러 출력은 선택 사항입니다(--format=rich).

• 색상 전용 신호 없음. --color=auto|always|never가 색상을 독립적으로 제어합니다. 색상은 상태를 전달하는 유일한 수단이 절대 아닙니다.

• stdout은 데이터, stderr는 로그 — 명령이 깔끔하게 파이프됩니다.

• 전체 UTF-8. 도구 자체의 문자열은 영어입니다. 메시지 본문은 여러분이 쓰는 어떤 언어든 가능합니다.

• 차분한 표면. 스피너, 텔레메트리 배너, 업그레이드 알림이 없습니다. 조용한 성공, 명확한 오류 — 오류는 경로, 줄, 또는 유효한 옵션을 인용합니다.

지원하지 않는 것

Letterbox v1은 POSIX 전용입니다(Linux 및 macOS). PTY 생성-및-주입 계층은 POSIX 기본 요소 위에 구축되었습니다. stdlib pty 모듈을 통한 Windows 지원은 불완전하며 제공되지 않습니다. Windows를 사용 중이라면 v1에서 letterbox가 실행되지 않습니다 — 크래시를 겪는 것보다 지금 아는 것이 낫습니다.

참고 자료

• examples/two-claudes-debating/ — 실습 워크스루: 실시간으로 토론하는 두 Claude Code 세션.

• skills/letterbox/SKILL.md — 에이전트 대상 사용 가이드: LLM이 라이브 브리지를 사용하는 방법(브로드캐스트, 지시 메시지, 참가자).

• skills/letterbox-setup/SKILL.md — 에이전트 대상 설정 가이드: 하네스별 1회성 MCP 연결, 채널당 하나의 라벨 규칙, 업그레이드 후 재실행 절차.

• docs/AGENT_POINTER.md — 프로젝트의 CLAUDE.md / GEMINI.md / AGENTS.md에 붙여넣을 수 있는 짧은 블록으로, 에이전트가 브리지 위에 있음을 알게 합니다.

• 전체 파일 형식 및 프로토콜 참조는 docs/PROTOCOL.md에 있습니다.

• DECISIONS.md — 모든 핵심 결정의 배경이 되는 아키텍처 결정 기록(ADR). 하네스별 MCP 연결(ADR-054/055), 휴면 모드와 channel_info 오라클(ADR-056), 제출 타이밍 수정(ADR-057), 자체 유지 읽기 마커(ADR-058), 채널별 중복 인스턴스 가드(ADR-061), N-자 지시 주소 지정 + 참가자(ADR-062), Vibe 어댑터 + Textual 제출 계약(ADR-067)을 포함합니다.

• LICENSE — MIT.

상태

Letterbox는 버전이 지정된, 미지원 아티팩트입니다 — MIT 라이선스, github.com/dovahkiin-v/letterbox에 있습니다. 완전한 상태로 제공되며 문서화된 대로 유지됩니다. 개인 아티팩트이지 제품이 아니며, 기여를 구하지 않습니다. 미지원은 로드맵, SLA, 이슈 수정이나 기능 요청 수용 약속이 없음을 의미합니다 — 하지만 동결된 것은 아닙니다: 작성자는 자신의 판단에 따라 일정 없이 이후 버전을 출시할 수 있습니다. 실행기의 하루 한 번 업데이트 확인이 그런 일이 있을 때 알려줍니다(LETTERBOX_NO_UPDATE_CHECK=1로 끌 수 있음). 실제로 무엇을 의미하는지는 CONTRIBUTING.md를 참조하세요.