anthropics / anthropics/claude-agent-sdk-python

Feature request: opt out of the bundled CLI (slim install + force external `claude`)

Aberta
#1,144 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
8.1k
Forks
1.3k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

### Summary

Provide a supported way to **not use the bundled CLI** — both at install time (a packaging extra that skips shipping `_bundled/`) and at runtime (an env var / option that forces resolution to an external `claude`). Today the bundled binary is mandatory: it's baked into the wheel and it takes priority over a system `claude`, so users who already have a CLI on `PATH` pay for a copy they never run.

### Motivation

**1. Size.** On SDK `0.2.123` the `_bundled/` directory is **~253 MB** — the single largest thing most installs pull in. For anyone who already manages `claude` separately (npm global, mise/asdf, distro package, container base image), that 253 MB is pure dead weight: downloaded on every `pip install` / `uv tool upgrade`, never executed. This is a regression in spirit from #349, which was closed by switching to a native binary — the "ink bloat" went away but the on-disk footprint went *up*.

**2. Correctness / control.** Several open issues stem specifically from the bundled binary, and an opt-out would give affected users a clean workaround:
- #926 — bundled `claude` hangs when stdout isn't a TTY (pipe / cron / launchd / Docker)
- #922 — `_bundled/claude` protocol-incompatible in container env (silent `initialize` timeout)
- #952 / #1034 / #1068 — bundled CLI drops inbound TRACEPARENT / OTel `trace_id` / thinking blocks

Users who pin a known-good external CLI can't reliably do so today, because…

**3. Surprising precedence.** In `_internal/transport/subprocess_cli.py`, `_find_cli()` checks `_find_bundled_cli()` **before** `shutil.which("claude")`. So a system `claude` on `PATH` is silently shadowed by the bundled copy unless the caller passes `ClaudeAgentOptions(cli_path=...)` explicitly. "I installed my own claude on PATH" does not do what most users expect.

### Proposed solution

Any one of these would solve it; ideally the first two together:

1. **Packaging extra to skip the bundle.** Publish the CLI as an optional component so `pip install claude-agent-sdk` (or an explicit `claude-agent-sdk[no-cli]` / a `claude-agent-sdk[bundled]` opt-*in*) can install without `_bundled/`. When absent, resolution simply falls through to `PATH`.
2. **Runtime opt-out env var**, e.g. `CLAUDE_AGENT_SDK_NO_BUNDLE=1` (mirroring the existing `CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK`), that makes `_find_cli()` skip `_find_bundled_cli()` and go straight to `PATH` / known locations.
3. **Optional precedence flip / documentation**: let callers prefer a `PATH` `claude` over the bundled one (an env or option), and document the current order explicitly.

### Workaround today

`ClaudeAgentOptions(cli_path=...)` bypasses the bundled binary at runtime, and deleting `_bundled/` reclaims the 253 MB — but the delete is undone by the next `pip install` / `uv tool upgrade`, so there's no durable slim install.

### Environment
- `claude-agent-sdk` 0.2.123 (Python), Linux x86_64
- `_bundled/` measured at ~253 MB

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.