claude-batch-toolkit

Anthropic Batch API (또는 Vertex AI)로 긴급하지 않은 작업(non-urgent work)을 50% 비용으로 Claude Code에서 직접 전송할 수 있습니다.

코드 리뷰, 문서화, 아키텍처 분석, 리팩토링 계획, 보안 감사 등 약 1시간 정도 기다릴 수 있는 모든 작업을 Claude Opus를 통해 반값으로 처리합니다. Anthropic API와 직접 연결하거나 Google Cloud의 Vertex AI를 통해 사용할 수 있습니다.

설치 (Install)

git clone [email protected]:s2-streamstore/claude-batch-toolkit.git
cd claude-batch-toolkit
./install.sh --api-key sk-ant-your-key-here

설치 스크립트는 변경할 모든 항목의 매니페스트(manifest)를 보여주고 진행 전에 확인을 요청합니다.

설치 옵션 (Install Options)

제거 (Uninstall)

./uninstall.sh

이 스크립트는 제거할 항목을 보여주고 확인을 요청하며, 결과를 ~/.claude/batches/results/에 보존합니다. 결과를 함께 제거하려면 --purge-data를 사용하십시오.

설치 스크립트를 실행하고 싶지 않거나 제한된 환경에서 설치해야 하는 경우, 다음 단계를 따라 각 구성 요소를 수동으로 설정할 수 있습니다.

전제 조건 (Prerequisites)

전제 조건 확인:

command -v uv && echo 

```bash
cp mcp/claude_batch_mcp.py ~/.claude/mcp/claude_batch_mcp.py

Step 3: 스킬 파일 설치 (Install the skill file)

cp skills/batchy/SKILL.md ~/.claude/skills/batchy/SKILL.md

Step 4 (선택 사항): 상태 표시줄 스크립트 설치 (Install the statusline script)

Claude Code 상태 표시줄에 배치 작업 카운트를 원하지 않으면 이 단계를 건너뛰세요. 다른 모든 것은 이것 없이 작동합니다.

cp statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

Step 5: API 키 설정 (Set up your API key)

툴킷은 ~/.claude/env에서 ANTHROPIC_API_KEY를 읽습니다. 이 파일은 반드시 모드 600이어야 합니다.

만약 ~/.claude/env가 아직 존재하지 않는 경우:

echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' > ~/.claude/env
chmod 600 ~/.claude/env

만약 ~/.claude/env가 이미 존재하는 경우, 에디터로 열고 ANTHROPIC_API_KEY 라인을 추가하거나 (또는 대체하고) chmod 600 ~/.claude/env를 실행하여 권한을 확인하세요.

Step 6: ~/.claude.json에 MCP 서버 등록 (Register the MCP server in ~/.claude.json)

Claude Code는 ~/.claude.json을 통해 MCP 서버를 발견합니다. 여기에 mcpServers 키 아래에 claude-batch 항목을 추가해야 합니다.

만약 ~/.claude.json이 아직 존재하지 않는 경우:

API_KEY=$(grep ANTHROPIC_API_KEY ~/.claude/env | cut -d'"' -f2)

jq -n --arg home "$HOME" --arg key "$API_KEY" '{ 
... 

만약 ~/.claude.json이 이미 존재하는 경우 — 병합하세요 (덮어쓰지 마세요):

API_KEY=$(grep ANTHROPIC_API_KEY ~/.claude/env | cut -d'"' -f2)

jq --arg home "$HOME" --arg key "$API_KEY" ' 
... 

또는 수동으로 편집하세요 — args의 경로는 절대 경로여야 합니다 (자신의 경로는 echo $HOME을 사용하세요).

Step 7 (선택 사항): ~/.claude/settings.json에서 상태 표시줄 구성 (Configure the statusline in ~/.claude/settings.json)

Step 4를 건너뛰었다면 이 단계를 건너뛰세요. statusLine 값은 단순 문자열이 아니라 **객체(object)**여야 합니다.

만약 ~/.claude/settings.json이 아직 존재하지 않는 경우:

jq -n --arg cmd "bash $HOME/.claude/statusline.sh" '{

```bash
jq --arg cmd "bash $HOME/.claude/statusline.sh" '
  .statusLine = {"type": "command", "command": $cmd}
' ~/.claude/settings.json > ~/.claude/settings.json.tmp \
...

경고: 이 명령어는 기존의 statusLine을 덮어씁니다. 사용자 지정 statusline이 있는 경우, 배치 스크립트를 수동으로 통합해야 합니다.

Step 8: 작업 레지스트리 초기화 (Initialize the jobs registry)

if [ ! -f ~/.claude/batches/jobs.json ]; then
  echo '{"version": 1, "jobs": {}}' | jq '.' > ~/.claude/batches/jobs.json
  echo "jobs.json을 생성했습니다" 
...

Step 9: 스모크 테스트 (Smoke test)

source ~/.claude/env
uv run ~/.claude/mcp/claude_batch_mcp.py list --base-dir ~/.claude/batches

예상 결과: 비어 있는 목록 또는 작업이 없음을 보여주는 JSON. 첫 실행 시 uv가 종속성을 해결하는 동안 잠시 시간이 걸릴 수 있습니다.

statusline을 설치한 경우:

echo '{}' | bash ~/.claude/statusline.sh

설치 확인 (Verify Installation)

echo "=== 파일 확인 ==="
[ -f ~/.claude/mcp/claude_batch_mcp.py ] && echo "ok MCP 서버"     || echo "MISSING MCP 서버"
[ -f ~/.claude/skills/batchy/SKILL.md ]  && echo "ok Skill 파일"     || echo "MISSING Skill 파일"
...

수동 제거 (Manual Uninstall)

Step 1: 툴킷 파일 제거 (Remove toolkit files)

rm -f ~/.claude/mcp/claude_batch_mcp.py
rm -f ~/.claude/skills/batchy/SKILL.md
rm -f ~/.claude/statusline.sh
...

Step 2: ~/.claude.json에서 MCP 항목 제거 (Remove MCP entry from ~/.claude.json)

jq 'del(.mcpServers["claude-batch"])' ~/.claude.json > ~/.claude.json.tmp \
  && mv ~/.claude.json.tmp ~/.claude.json

Step 3: ~/.claude/settings.json에서 statusline 제거 (Remove statusline from ~/.claude/settings.json) (설치한 경우)

jq 'del(.statusLine)' ~/.claude/settings.json > ~/.claude/settings.json.tmp \
  && mv ~/.claude/settings.json.tmp ~/.claude/settings.json

Step 4: API 키 제거 (Remove API key) (선택 사항)

grep -v '^export ANTHROPIC_API_KEY=' ~/.claude/env > ~/.claude/env.tmp \
  && mv ~/.claude/env.tmp ~/.claude/env && chmod 600 ~/.claude/env
[ ! -s ~/.claude/env ] && rm -f ~/.claude/env

Step 5: 작업 데이터 제거 (Remove jobs data) (선택 사항)

rm -f ~/.claude/batches/jobs.json
rm -f ~/.claude/batches/.poll_cache
rm -f ~/.claude/batches/.poll.lock
...

왜 /batchy인가?

원래 이 기능은 /batch라는 이름이었지만, Claude Code가 다른 의미를 가진 내장 /batch 명령어를 도입하면서(#4) 충돌을 피하기 위해 이름을 /batchy로 변경했습니다. 기존 설치본은 ./install.sh를 다시 실행할 때 자동으로 마이그레이션됩니다.

사용법

배치에 작업 제출하기

Claude Code에서는 다음과 같이 말하면 됩니다:

/batchy Review this codebase for security issues

/batchy Generate comprehensive tests for src/auth/

/batchy Write API documentation for all public endpoints

Claude는 관련 컨텍스트를 모두 모으고, 자체 포함된 프롬프트를 작성한 후, 이를 Batch API에 제출하고 작업 ID를 알려줍니다.

결과 확인하기

/batchy check

/batchy status

/batchy list

결과는 상태 표시줄에 자동으로 나타납니다. 작업이 완료되면 Claude가 디스크에서 결과를 읽어와 제시합니다.

직접 CLI 사용하기

MCP 서버는 독립적인 CLI로도 작동합니다:

# 작업을 제출하려면
uv run ~/.claude/mcp/claude_batch_mcp.py submit --packet-path prompt.md --label "security-review"

...

작동 방식

┌─────────────────────────────────────────────────────────────────┐
│ Claude Code 세션
│                                                                 │
...

상태 표시줄 + 캐시된 폴러 (Cached Poller)

상태 표시줄만이 유일하게 움직이는 부분입니다. 데몬(daemons)도, 백그라운드 서비스도, launchd/systemd도 없습니다.

Assistant 메시지가 도착함
        │
        ▼
...

Vertex AI (선택 사항)

Anthropic API를 직접 사용하는 대신 Google Cloud를 통해 배치 처리를 원할 때 Vertex AI를 대체 백엔드로 사용할 수 있습니다. 두 백엔드 모두 동일한 50% 할인된 배치를 제공합니다.

사전 요구 사항

1. Vertex AI API가 활성화된 GCP 프로젝트
2. 사용 지역에서 claude-opus-4-6 (또는 다른 Claude 모델)을 사용할 수 있어야 함
3. 배치 입력/출력을 위한 지원되는 지역의 GCS 버킷
4. 애플리케이션 기본 자격 증명(Application Default Credentials) 구성:

gcloud auth application-default login

환경 변수

Vertex용 MCP 설정

Vertex를 사용할 때는 ANTHROPIC_API_KEY가 필요하지 않습니다. 대신 ~/.claude.json을 사용하여 Vertex 환경 변수를 구성하세요:

{
  "mcpServers": {
    "claude-batch": {
...

Anthropic과 Vertex 자격 증명을 모두 설정하여 두 백엔드를 모두 사용할 수 있습니다.

백엔드 자동 선택

send_to_batch를 `backend:

백그라운드 상태 라인 폴러(statusline.sh)는 Anthropic API만 폴링합니다. Vertex AI 작업은 백그라운드에서 폴링되지 않으며, /batchy check를 실행할 때(이는 batch_poll_once를 호출함) 상태가 업데이트됩니다. 이는 Vertex 폴링이 가벼운 curl+jq 상태 라인 스크립트가 처리할 수 없는 Google 인증 자격 증명을 필요로 하기 때문입니다.

자세한 내용은 Vertex AI Claude 배치 문서를 참조하십시오.

파일 위치 (File Locations)

~/.claude/
├── env                          # ANTHROPIC_API_KEY (mode 600)
├── settings.json                # statusLine 설정
...

비용 참고 (Cost Reference)

(백만 토큰당 입력/출력 (Input / Output per million tokens))

일반적인 처리 시간: 1시간 미만. 최대: 24시간.

문제 해결 (Troubleshooting)

"MCP server not responding" ("MCP 서버 응답 없음")

# MCP 서버 직접 테스트
uv run ~/.claude/mcp/claude_batch_mcp.py list

...

"No batch info in status bar" ("상태 표시줄에 배치 정보 없음")

# statusline 설정 확인
jq '.statusLine' ~/.claude/settings.json

...

"Job stuck in pending" ("작업이 보류 상태에 갇힘")

# 수동 폴링
uv run ~/.claude/mcp/claude_batch_mcp.py poll

...

"Vertex batch submit failed (403)" 또는 인증 오류

# 애플리케이션 기본 자격 증명 새로 고침
gcloud auth application-default login

...

"Permission denied on env file" ("env 파일 권한 거부")

chmod 600 ~/.claude/env

아키텍처 (Architecture)

아키텍처 (Architecture)

• MCP Server (claude_batch_mcp.py): uv로 실행되는 Python 스크립트입니다. send_to_batch, batch_status, batch_fetch, batch_list, batch_poll_once 도구를 노출합니다. CLI 역할도 수행합니다.
• Skill (SKILL.md): Claude Code에게 배치(batch) 도구의 사용 방법과 시점을 가르칩니다. /batchy로 호출됩니다. 자동으로 로드됩니다.
• Status Line (statusline.sh): Claude Code 상태 표시줄에 배치 작업 수를 렌더링하고 curl+jq를 통해 백그라운드 폴링(polling)을 트리거하는 Bash 스크립트입니다.
• Jobs Registry (jobs.json): 제출된 모든 배치 작업, 해당 상태 및 결과 경로를 추적하는 JSON 파일입니다.

라이선스 (License)

MIT