claude-print

claude-print is a command-line wrapper around Claude Code's interactive terminal UI. Its purpose is narrow and explicit: Anthropic routes headless mode (`claude -p`, the SDK/pipe path) through a separate Agent SDK credit pool, while only the interactive TUI is billed against an unlimited subscription. The README states the billing path is decided by an `isatty` check inside the `claude` binary — TTY output tags the session `cc_entrypoint=cli`, a pipe tags it `cc_entrypoint=sdk-cli`. claude-print allocates a PTY, drives the TUI through it, and aims to stay wire-compatible with `claude -p` output while billing against the subscription. How it works, per the README: - Spawns `claude` under a PTY so `isatty` returns true. - Watches for the one-time project trust dialog and sends the confirmation keypress automatically. - Injects the prompt using bracketed-paste escape sequences, so the TUI treats it as user input without shell interpretation. - Installs a temporary Claude Code Stop hook that writes to a FIFO; the process blocks on that read. - Reads the JSONL session transcript, extracts the assistant turn, and emits it in the requested format. Input can come from a positional argument, `--input-file`, or non-TTY stdin; these are mutually exclusive. Output formats are `text` (default), `json` (a single-line object with fields such as result, session_id, num_turns, duration_ms, cost_usd, claude_version and a usage object with input/output/cache token counts) and `stream-json` (real-time JSONL replay of transcript events). Documented flags include `--model`, `--max-turns`, `--allowedTools`/`--disallowedTools`, `--dangerously-skip-permissions`, several timeout knobs (wall-clock, first-output, stream-json, Stop hook), `--claude-binary`, `--config`, `--no-inherit-hooks`, `--verbose`, `--check`, `--version` and `--help`. Exit codes are documented for success (0), assistant error (1), internal error (2), input error (4), timeout (124) and SIGINT (130). Configuration is optional TOML at `$XDG_CONFIG_HOME/claude-print/config.toml` or `~/.config/claude-print/config.toml`, overridable with `--config`. Documented keys are `model`, `inherit_hooks`, `max_turns` and `timeout_secs`, each optional, with validation: a missing file falls back to defaults, but an unreadable, malformed or out-of-range config exits with status 2 rather than warning and continuing. Installation is `sh install.sh`, which downloads a pre-built static musl binary from GitHub Releases, runs `--check`, and optionally copies an adapter YAML into `~/.needle/agents/` for NEEDLE fleet dispatch. Building from source with Cargo is also documented. Only x86_64 Linux is supported; aarch64/ARM and Windows ConPTY are explicitly out of scope. The README also documents billing-verification scripts that inspect the latest transcript for the `entrypoint` field and a daily canary service/timer. Stated limitations: Linux-only PTY allocation, the `claude` binary must already be installed and authenticated, one prompt per invocation with no multi-turn session mode, and roughly 2–5 seconds of startup latency compared with a direct HTTP call. A prominent operational requirement is that `HOME` must be set to a non-empty, existing and writable directory; the tool deliberately does not guess `/root` or consult the passwd database, and current builds enforce this contract before session startup, `--check` and `--version`. Troubleshooting notes cover missing `/dev/ptmx`, Stop hooks not firing, and transcript race conditions.