Claudraband – Claude Code를 프로그래밍 방식으로 제어하는 Power User 도구

Who Should Read

Claude Code를 일회성 명령이 아닌 지속적인 세션 기반 자동화 워크플로우에 활용하고 싶은 개발자. 특히 CI/CD나 헤드리스 환경에서 Claude Code를 원격으로 제어하거나 에디터 플러그인과 연동하고 싶은 경우에 유용하다.

Core Mechanics

• Claudraband는 Claude Code의 TUI(터미널 UI)를 제어 가능한 터미널로 감싸서, 세션을 유지하고 나중에 재개하거나 외부에서 프롬프트를 주입할 수 있게 해준다.
• 핵심 기능은 크게 네 가지다: 재개 가능한 비대화형 워크플로우, HTTP 데몬을 통한 원격/헤드리스 세션 제어, ACP(에이전트 통신 프로토콜) 서버를 통한 에디터 연동, TypeScript 라이브러리를 통한 커스텀 도구 통합.
• 세션 재개 기능이 핵심인데, `cband continue <session-id> '질문'` 형식으로 이전 Claude Code 세션의 컨텍스트를 유지한 채 새로운 프롬프트를 보낼 수 있다. 기존 `claude -p`에 세션 지원이 추가된 개념.
• 로컬에서는 tmux를 백엔드로 사용해 세션을 관리한다. tmux가 설치돼 있어야 1등 시민(first-class) 워크플로우를 사용할 수 있다.
• Claude Code SDK를 대체하는 게 아니라, 개인적이고 애드혹(임시) 사용에 특화된 도구다. OAuth를 건드리지 않고 Claude Code TUI를 우회하지도 않으며, 반드시 Claude Code로 인증한 후 실제 Claude Code 세션을 통해 동작한다.
• 설치는 npm/bun으로 간단하게 할 수 있고, 패키지 안에 `@anthropic-ai/claude-code@2.1.96`이 번들되어 있다. 다른 버전을 쓰고 싶으면 `CLAUDRABAND_CLAUDE_PATH` 환경변수로 오버라이드할 수 있다.
• 아직 실험적(Experimental) 단계로, Claude Code와 ACP 클라이언트가 변화함에 따라 프로젝트도 계속 변하고 있다고 명시하고 있다.

Evidence

• Claude Code에만 의존한다는 점에서 Anthropic 종속(lock-in) 문제를 심화시킨다는 비판이 있었다. Gemini CLI, Codex, OpenCode도 지원하는 좀 더 범용적인 도구가 필요하다는 의견이 제기됐다.
• Claude Channels를 이용하면 프롬프트 주입과 응답 추출이 쉬워질 수 있다는 의견이 있었지만, 설계가 잘 안 돼 있고 `/clear` 같은 슬래시 명령은 결국 터미널 인터페이스를 통해야만 한다는 한계도 지적됐다.
• 구독 기반 사용 시 Anthropic의 서비스 약관(ToS)과 충돌하지 않는지에 대한 우려가 댓글에서 제기됐다. 공식 TUI를 우회하지 않는다고 명시하고 있지만 자동화된 사용이 약관 위반인지 불명확하다.
• README에 라이선스가 명시되지 않았다는 지적이 있었다. 실제로 repo에 MIT 라이선스 파일이 있지만 README에서 눈에 띄지 않아 혼란을 야기했다.

How to Apply

• Claude Code를 이용한 코드 리뷰나 분석 작업을 반복적으로 수행하는 경우, `cband 'staged diff를 리뷰해줘'`로 세션을 시작하고 `cband continue <session-id> '계속해줘'`로 이전 컨텍스트를 유지하며 후속 작업을 이어갈 수 있다. 매번 새 세션을 여는 것보다 훨씬 효율적이다.
• 헤드리스 서버나 CI 환경에서 Claude Code를 자동화해야 한다면 HTTP 데몬 모드를 활용하면 된다. 데몬을 띄워두고 REST API 형태로 세션을 제어할 수 있어 스크립트나 다른 서비스와 연동하기 좋다.
• 자체 에디터 플러그인이나 개발 도구에 Claude Code를 통합하고 싶다면 ACP(에이전트 통신 프로토콜) 서버 기능을 이용하거나, TypeScript 라이브러리를 직접 import해서 커스텀 워크플로우를 코드로 구성할 수 있다.
• 일회성으로 빠르게 테스트해보고 싶다면 `npx @halfwhey/claudraband 'staged diff를 리뷰해줘'` 또는 `bunx @halfwhey/claudraband '...'`로 설치 없이 바로 실행해볼 수 있다.

Code Example

# 일회성 실행
npx @halfwhey/claudraband "review the staged diff"
bunx @halfwhey/claudraband "review the staged diff"

# 전역 설치
npm install -g @halfwhey/claudraband

# 로컬 세션 시작
cband "audit the last commit and tell me what looks risky"

# 세션 목록 확인
cband sessions

# 세션 재개 (이전 컨텍스트 유지)
cband continue <session-id> "keep going"
cband continue <session-id> --select 2

# 커스텀 Claude Code 바이너리 경로 지정
export CLAUDRABAND_CLAUDE_PATH=/path/to/claude-code

Terminology

관련 논문

• adamsreview: Claude Code용 멀티 에이전트 PR 코드 리뷰 파이프라인

  Claude Code에서 최대 7개의 병렬 서브 에이전트가 각각 다른 관점으로 PR을 리뷰하고, 자동 수정까지 해주는 오픈소스 플러그인이다. 기존 /review나 CodeRabbit보다 실제 버그를 더 많이 잡는다고 주장하지만 커뮤니티에서는 복잡도와 실효성에 대한 회의론도 나왔다.

• Claude를 User Space IP Stack으로 써서 Ping에 응답시키면 얼마나 빠를까?

  Claude Code에게 IP 패킷을 직접 파싱하고 ICMP echo reply를 구성하도록 시켜서 실제로 ping에 응답하게 만든 실험으로, 'Markdown이 곧 코드이고 LLM이 프로세서'라는 아이디어를 네트워크 스택 수준까지 밀어붙인 재미있는 사례다.

• AI Agent를 위한 Git: re_gent

  AI 코딩 에이전트(Claude Code 등)가 수행한 모든 툴 호출을 자동으로 추적하고, 어떤 프롬프트가 어느 코드 줄을 작성했는지 blame까지 가능한 버전 관리 도구다.

• Agent-Native CLI를 위한 설계 원칙 10가지

  AI 에이전트가 CLI 도구를 더 잘 사용할 수 있도록 설계하는 원칙들을 정리한 글로, 에이전트가 CLI를 도구로 활용하는 빈도가 높아지면서 이 설계 방식이 실용적으로 중요해지고 있다.

• Agent-harness-kit: MCP 기반 멀티 에이전트 워크플로우 오케스트레이션 프레임워크

  여러 AI 에이전트가 서로 역할을 나눠 협업할 수 있도록 조율하는 scaffolding 도구로, Vite처럼 설정 없이 빠르게 멀티 에이전트 파이프라인을 구성할 수 있다.

• Tilde.run – AI Agent를 위한 트랜잭션 기반 버전 관리 파일시스템 샌드박스

  AI 에이전트가 실제 프로덕션 데이터를 건드려도 롤백할 수 있는 격리된 샌드박스 환경을 제공하는 도구로, GitHub/S3/Google Drive를 하나의 버전 관리 파일시스템으로 묶어준다.

Related Resources

• Claudraband GitHub 저장소
• npm 패키지 @halfwhey/claudraband