Context Vault

acpx — ACP 헤드리스 CLI 클라이언트

4 min read

acpx — ACP 헤드리스 CLI 클라이언트

AI 에이전트가 PTY 스크래핑 없이 ACP(Agent Client Protocol)를 통해 코딩 에이전트와 구조적으로 통신할 수 있는 헤드리스 CLI 클라이언트. ⭐ 1.9k, MIT 라이선스.

핵심 기능

  • 지속 세션: repo별 다중 턴 대화, 호출 간 상태 유지
  • 이름 지정 세션: 동일 repo에서 병렬 워크스트림 (-s backend, -s frontend)
  • 프롬프트 큐잉: 실행 중인 프롬프트가 있어도 대기열에 추가
  • 협력적 취소: cancel 명령으로 ACP session/cancel 전송 (세션 상태 유지)
  • Fire-and-forget: --no-wait로 프롬프트 큐잉 후 즉시 반환
  • 정형 출력: thinking, tool calls, diffs를 타입화된 ACP 메시지로 출력 (ANSI 스크래핑 불필요)
  • Crash 재연결: 에이전트 프로세스 종료 감지 후 세션 자동 재로드
  • Flows: TypeScript 기반 멀티스텝 워크플로우 실행

지원 에이전트

명령어에이전트URL
acpx piPi Coding Agenthttps://github.com/mariozechner/pi
acpx openclawOpenClaw ACP bridgehttps://github.com/openclaw/openclaw
acpx codexCodex CLIhttps://codex.openai.com
acpx claudeClaude Codehttps://claude.ai/code

사용법

# 설치
npm install -g acpx@latest
 
# 기본 사용
acpx codex "fix the failing tests"
acpx claude "refactor auth middleware"
 
# 네임드 세션 (병렬 작업)
acpx codex -s api 'implement token pagination'
acpx codex -s docs 'rewrite API docs'
 
# Fire-and-forget
acpx codex --no-wait 'draft test migration plan'
 
# Flow 실행 (멀티스텝 워크플로우)
acpx flow run ./my-flow.ts --input-file ./flow-input.json
 
# JSON 출력 (자동화용)
acpx --format json codex exec 'review this PR' | jq '.type'

Claude Code에서 ACP CLI를 서브 에이전트로 사용하는 방법

방법 1: Claude Code 네이티브 서브에이전트

.claude/agents/ 디렉토리에 마크다운 파일로 정의하면 자동 위임. ACP 불필요.

방법 2: acpx로 다른 ACP 에이전트 호출

Claude Code의 Bash 도구에서 npx acpx codex "task" 또는 npx acpx claude "task" 형태로 호출.

# Claude Code의 커스텀 서브에이전트에서
npx acpx@latest codex "fix the failing tests"
npx acpx@latest claude "refactor the auth module"

방법 3: invoke-opencode-acp 스킬

Claude Code 스킬로 설치하면 ACP 프로토콜로 OpenCode를 서브에이전트로 위임. 토큰 50~90% 절약.

node ~/.claude/skills/invoke-opencode-acp/acp_client.cjs "$PWD" "task description"

핵심 구분

  • MCP: 도구 연결 (Tool connection)
  • ACP: 에이전트 간 통신 (Agent-to-agent communication)

멀티에이전트 오케스트레이션 설계 시 두 프로토콜의 역할을 명확히 구분하는 것이 중요.

설정

// ~/.acpx/config.json 또는 <cwd>/.acpxrc.json
{
  "defaultAgent": "codex",
  "defaultPermissions": "approve-all",
  "authPolicy": "skip",
  "ttl": 300,
  "timeout": null,
  "format": "text"
}

참고

  • 알파 단계 — CLI/런타임 인터페이스 변경 가능
  • ACP 스펙 커버리지: ACP Spec Coverage Roadmap
  • Node.js 기반, MIT 라이선스

그래프 뷰