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

Related Resources

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