anthropics / anthropics/claude-agent-sdk-python
Feature request: opt out of the bundled CLI (slim install + force external `claude`)
- 主要语言
- Python
- 星标
- 8.1k
- 派生
- 1.3k
- PR 合并指标
- PR 指标待抓取
描述
### 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
贡献指南
这个仓库没有索引到贡献指南
评估
这个 Issue 还没有评估数据。