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

관련 논문

• 중요할 때 기억하라: Long-Horizon 에이전트를 위한 Proactive Memory Agent

  LLM 에이전트가 긴 작업 중 중요한 정보를 잊어버리는 문제를 별도의 메모리 에이전트가 '적절한 타이밍에' 끼어들어 해결하는 방법

• WebSwarm: 깊고 넓은 웹 검색을 위한 재귀적 Multi-Agent Orchestration

  복잡한 웹 검색을 재귀적으로 분해하고 각 노드에 적합한 검색 모드를 동적으로 할당하는 멀티에이전트 프레임워크

• 웹 앱을 리버스 엔지니어링해서 AI Agent 도구로 자동 변환하기

  로그인된 웹 앱의 API 호출을 브라우저에서 감시해 자동으로 MCP 도구로 변환하는 에이전트를 만들었다. 소스 코드나 공식 API 문서 없이도 Jira, Spotify 같은 서비스에 AI 어시스턴트를 붙일 수 있다.

• FableCut – AI 에이전트가 조작할 수 있는 브라우저 기반 비디오 에디터 (zero deps)

  타임라인 전체를 JSON 파일 하나로 표현하고 MCP/REST로 AI 에이전트가 직접 편집할 수 있는 브라우저 비디오 에디터로, Claude 같은 AI가 프롬프트 하나로 영상을 자동 컷편집하고 결과를 실시간으로 UI에 반영해준다.

• 노이즈 가득한 실행 로그에서 근본 원인 찾기: Agent 최적화를 위한 구조적 Trajectory 분석과 인과 추출

  Agent 실패 로그를 인과 그래프로 분석해 진짜 근본 원인만 골라내고, 해당 모듈 프롬프트만 정밀하게 수정하는 자동 최적화 프레임워크

• Microsoft, AI 에이전트를 위한 시각화 언어 Flint 공개

  Microsoft가 LLM/AI 에이전트가 차트를 쉽게 생성할 수 있도록 설계된 고수준 시각화 DSL(도메인 특화 언어) Flint를 오픈소스로 공개했다. 에이전트가 복잡한 시각적 세부사항 대신 의미론적 명세만 다루면 되도록 추상화 계층을 제공하는 게 핵심이다.

• 크게 생각하고, 작게 검색하라: Hierarchical Search Agent에서 모델 용량은 어디에 집중해야 하는가?

Related Resources

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