프로젝트 소개

claude-print는 Claude Code의 대화형 터미널 UI를 감싸는 명령줄 래퍼입니다. 이 도구의 목적은 명확하고 좁습니다. Anthropic은 헤드리스 모드(`claude -p`, SDK/파이프 경로)를 별도의 Agent SDK 크레딧 풀을 통해 라우팅하는 반면, 대화형 TUI만 무제한 구독으로 청구합니다. README에 따르면 청구 경로는 `claude` 바이너리 내부의 `isatty` 체크에 의해 결정됩니다. TTY 출력은 세션을 `cc_entrypoint=cli`로 태그하고, 파이프는 `cc_entrypoint=sdk-cli`로 태그합니다. claude-print는 PTY를 할당하여 TUI를 구동함으로써 `claude -p` 출력과 와이어 호환성을 유지하는 동시에 구독 기반으로 청구되도록 하는 것을 목표로 합니다. README에 설명된 작동 방식은 다음과 같습니다: - `isatty`가 true를 반환하도록 PTY 하에서 `claude`를 실행합니다. - 일회성 프로젝트 신뢰 대화 상자를 감시하고 확인 키 입력을 자동으로 전송합니다. - 브래킷 붙여넣기(bracketed-paste) 이스케이프 시퀀스를 사용하여 프롬프트를 주입하므로, TUI는 이를 셸 해석 없이 사용자 입력으로 처리합니다. - FIFO에 기록하는 임시 Claude Code Stop 훅을 설치하며, 프로세스는 해당 읽기 작업에서 블록됩니다. - JSONL 세션 트랜스크립트를 읽어 어시스턴트 턴을 추출하고 요청된 형식으로 출력합니다. 입력은 위치 인자, `--input-file` 또는 non-TTY stdin을 통해 제공될 수 있으며, 이들은 상호 배타적입니다. 출력 형식은 `text`(기본값), `json`(result, session_id, num_turns, duration_ms, cost_usd, claude_version 및 입력/출력/캐시 토큰 수가 포함된 usage 객체 필드를 가진 단일 행 객체), `stream-json`(트랜스크립트 이벤트의 실시간 JSONL 재생)이 있습니다. 문서화된 플래그에는 `--model`, `--max-turns`, `--allowedTools`/`--disallowedTools`, `--dangerously-skip-permissions`, 여러 타임아웃 설정(wall-clock, first-output, stream-json, Stop hook), `--claude-binary`, `--config`, `--no-inherit-hooks`, `--verbose`, `--check`, `--version` 및 `--help`가 포함됩니다. 종료 코드는 성공(0), 어시스턴트 오류(1), 내부 오류(2), 입력 오류(4), 타임아웃(124) 및 SIGINT(130)로 정의되어 있습니다. 설정은 `$XDG_CONFIG_HOME/claude-print/config.toml` 또는 `~/.config/claude-print/config.toml`에 선택적으로 TOML 파일로 저장하며, `--config`로 덮어쓸 수 있습니다. 문서화된 키는 `model`, `inherit_hooks`, `max_turns`, `timeout_secs`이며 각각 선택 사항입니다. 유효성 검사 결과, 파일이 없으면 기본값으로 돌아가지만, 읽을 수 없거나 형식이 잘못되었거나 범위를 벗어난 설정은 경고 후 계속하는 대신 상태 코드 2로 종료됩니다. 설치는 `sh install.sh`를 통해 수행되며, GitHub Releases에서 사전 빌드된 정적 musl 바이너리를 다운로드하고 `--check`를 실행하며, 선택적으로 NEEDLE 플릿 디스패치를 위해 어댑터 YAML을 `~/.needle/agents/`에 복사합니다. Cargo를 이용한 소스 빌드 방법도 문서화되어 있습니다. x86_64 Linux만 지원하며, aarch64/ARM 및 Windows ConPTY는 명시적으로 범위 외입니다. README에는 `entrypoint` 필드를 검사하는 청구 확인 스크립트와 일일 카나리 서비스/타이머에 대한 내용도 포함되어 있습니다. 명시된 제한 사항은 다음과 같습니다. Linux 전용 PTY 할당, `claude` 바이너리가 이미 설치 및 인증되어 있어야 함, 호출당 하나의 프롬프트만 가능하며 멀티 턴 세션 모드 불가, 직접적인 HTTP 호출 대비 약 2~5초의 시작 지연 시간이 발생합니다. 중요한 운영 요구 사항은 `HOME`이 비어 있지 않고 실제로 존재하며 쓰기 가능한 디렉토리로 설정되어야 한다는 점입니다. 이 도구는 의도적으로 `/root`를 추측하거나 passwd 데이터베이스를 참조하지 않으며, 현재 빌드는 세션 시작, `--check` 및 `--version` 전에 이 계약을 강제합니다. 문제 해결 노트에는 `/dev/ptmx` 누락, Stop 훅 미작동, 트랜스크립트 경쟁 상태(race conditions)에 대한 내용이 다뤄집니다.