# claude-wrapper
A type-safe Rust wrapper around the Claude Code CLI.
[](https://crates.io/crates/claude-wrapper)
[](https://docs.rs/claude-wrapper)
[](https://github.com/joshrotenberg/claude-wrapper/actions/workflows/ci.yml)
[](LICENSE-MIT)
## Overview
`claude-wrapper` gives you a builder-pattern interface for the `claude`
CLI. Each subcommand is a typed builder that produces a typed output.
The design follows the same shape as
[`docker-wrapper`](https://crates.io/crates/docker-wrapper) and
[`terraform-wrapper`](https://crates.io/crates/terraform-wrapper).
Features:
- Full coverage of `claude -p` via `QueryCommand`
- Async (tokio) and blocking (`std::thread` + `wait-timeout`) APIs behind feature flags
- Long-lived `DuplexSession` for hosts (IDE backends, daemons, agent servers, chat UIs): one `claude` subprocess held open across turns, mid-turn interrupts, mid-turn permission decisions, broadcast event subscribers
- Transient `Session` for short-lived processes (CLIs, build scripts, batch jobs): subprocess-per-turn with `--resume` continuity, cumulative cost + history, optional `BudgetTracker` hard-stops, streaming
- `Conversation` for host-side history/cost/budget bookkeeping over a `DuplexSession`
- NDJSON streaming events (`stream_query` / `stream_query_sync`)
- Typed tool-permission patterns (`ToolPattern`)
- Read-side introspection of Claude Code's on-disk state without spawning the CLI: session history, agents, skills, custom commands, settings, background jobs, worktrees
- MCP server management: list, get, add, add-json, remove, add-from-desktop, login, logout, serve, reset-project-choices
- Plugin and marketplace subcommands
- Other subcommands: `doctor`, `install`, `update`, `project purge`, `auto-mode`, and `ultrareview` (cloud-hosted multi-agent code review)
- Auth: `status`, `login`, `logout`, `setup-token`
- `McpConfigBuilder` for programmatic `.mcp.json` generation (with optional tempfile backing)
- Retry policy with fixed or exponential backoff
- Opt-in `DangerousClient` for bypass-permissions mode (env-var gated)
- `RawCommand` escape hatch for subcommands not yet wrapped
## Installation
```bash
cargo add claude-wrapper
```
Default features: `["async", "json", "tempfile"]`. To drop `tokio`
entirely for a sync-only build:
```toml
claude-wrapper = { version = "0.13", default-features = false, features = ["json", "sync"] }
```
## Quick start (async)
```rust
use claude_wrapper::{Claude, QueryCommand};
#[tokio::main]
async fn main() -> claude_wrapper::Result<()> {
let claude = Claude::builder().build()?;
let output = QueryCommand::new("explain this error: file not found")
.model("sonnet")
.execute(&claude)
.await?;
println!("{}", output.stdout);
Ok(())
}
```
## Quick start (sync)
Enable the `sync` feature and `use ClaudeCommandSyncExt`:
```rust
use claude_wrapper::{Claude, ClaudeCommandSyncExt, QueryCommand};
fn main() -> claude_wrapper::Result<()> {
let claude = Claude::builder().build()?;
let output = QueryCommand::new("explain this error")
.model("sonnet")
.execute_sync(&claude)?;
println!("{}", output.stdout);
Ok(())
}
```
The sync API uses `std::process::Command` plus `wait-timeout` for the
SIGKILL-on-deadline path, with dedicated reader threads for stdout and
stderr so the child never blocks on pipe-buffer backpressure. It matches
the async version's behaviour feature-for-feature (timeouts, retries,
large-output drain, non-`Send` handlers for streaming).
## Two-layer builder
The `Claude` client holds shared configuration (binary path,
environment, timeout, default retry policy). Command builders hold
per-invocation options and call `execute(&claude)` (or `execute_sync`).
```rust
let claude = Claude::builder()
.env("AWS_REGION", "us-west-2")
.timeout_secs(300)
.retry(RetryPolicy::new().max_attempts(3).exponential())
.build()?;
```
`Claude` options:
- `binary()` -- path to the `claude` binary (auto-detected from PATH by default)
- `working_dir()` / `with_working_dir()` -- working directory for commands
- `env()` / `envs()` -- environment variables applied to every command
- `clear_env()` -- clear inherited child environment before applying `env()` / `envs()`
- `arg()` -- global arg applied before every subcommand
- `timeout_secs()` / `timeout()` -- command timeout (no default)
- `retry()` -- default `RetryPolicy` applied to every command
`Claude` also exposes:
- `cli_version()` / `cli_version_sync()` -- parsed `CliVersion`
- `check_version()` / `check_version_sync()` -- assert a minimum version
### Child environment policy
Children inherit the parent process environment by default for compatibility.
Hosts that need an explicitly constructed environment can opt into clearing it:
```rust
let claude = Claude::builder()
.clear_env()
.env("PATH", "/usr/local/bin:/usr/bin:/bin")
.env("LANG", "C.UTF-8")
.env("CLAUDE_CONFIG_DIR", "/srv/claude/config")
.build()?;
```
`clear_env()` is call-order independent: explicit entries survive whether
`env()` / `envs()` appear before or after it. Every buffered, stdin, timeout,
retry, streaming, sync, and duplex child uses the same policy.
Clearing the environment controls only what the direct Claude CLI child
inherits. It is not operating-system or process isolation. A same-UID child
may still read accessible files or inspect other processes where the OS
permits it. Callers are responsible for choosing the minimal `PATH`, locale,
config-home, credential, proxy, Git, and SSH entries appropriate for their
deployment.
## Command builders
| Query | `QueryCommand` |
| MCP | `McpListCommand`, `McpGetCommand`, `McpAddCommand`, `McpAddJsonCommand`, `McpRemoveCommand`, `McpAddFromDesktopCommand`, `McpLoginCommand`, `McpLogoutCommand`, `McpServeCommand`, `McpResetProjectChoicesCommand` |
| Plugins | `PluginListCommand`, `PluginInstallCommand`, `PluginUninstallCommand`, `PluginEnableCommand`, `PluginDisableCommand`, `PluginUpdateCommand`, `PluginValidateCommand`, `PluginDetailsCommand`, `PluginPruneCommand`, `PluginTagCommand` |
| Marketplace | `MarketplaceListCommand`, `MarketplaceAddCommand`, `MarketplaceRemoveCommand`, `MarketplaceUpdateCommand` |
| Auth | `AuthStatusCommand`, `AuthLoginCommand`, `AuthLogoutCommand`, `SetupTokenCommand` |
| Auto-mode | `AutoModeConfigCommand`, `AutoModeDefaultsCommand`, `AutoModeCritiqueCommand` |
| Lifecycle | `InstallCommand`, `UpdateCommand`, `ProjectPurgeCommand` |
| Review | `UltrareviewCommand` |
| Misc | `VersionCommand`, `DoctorCommand`, `AgentsCommand`, `RawCommand` |
Every builder implements `ClaudeCommand` (`args()`, async `execute`).
With the `sync` feature, `ClaudeCommandSyncExt` provides a blanket
`execute_sync` on every command that returns `CommandOutput`.
`QueryCommand` additionally has inherent `execute_sync` /
`execute_json_sync` that honour the retry policy;
`AuthStatusCommand` has `execute_json_sync`.
## QueryCommand
Full coverage of `claude -p`. The common options:
| `model()` | `--model` | Model alias or full ID |
| `system_prompt()` / `append_system_prompt()` | `--system-prompt` / `--append-system-prompt` | Override or extend the system prompt |
| `output_format()` | `--output-format` | `text`, `json`, `stream-json` |
| `effort()` | `--effort` | `low`, `medium`, `high` |
| `max_turns()` | `--max-turns` | Turn cap |
| `max_budget_usd()` | `--max-budget-usd` | Per-call spend cap (CLI-side) |
| `permission_mode()` | `--permission-mode` | `default`, `acceptEdits`, `dontAsk`, `plan`, `auto` |
| `allowed_tool()` / `allowed_tools()` / `disallowed_tool()` / `disallowed_tools()` | tool filter flags | Allow/deny tool patterns |
| `mcp_config()` / `strict_mcp_config()` | `--mcp-config` / `--strict-mcp-config` | MCP server config |
| `json_schema()` | `--json-schema` | Structured output validation |
| `agent()` / `agents_json()` | `--agent` / `--agents` | Agent or custom agents JSON |
| `no_session_persistence()` | `--no-session-persistence` | Don't save the session to disk |
| `input_format()` / `include_partial_messages()` | `--input-format` / `--include-partial-messages` | Input/streaming shape |
| `settings()` / `fallback_model()` / `add_dir()` / `file()` | various | Misc per-turn knobs |
| `retry()` | (client-side) | Per-command retry override |
Raw session flags (prefer `Session` for multi-turn):
| `continue_session()` | `--continue` |
| `resume()` | `--resume` |
| `session_id()` | `--session-id` |
| `fork_session()` | `--fork-session` |
Bypass-permissions mode is **only** available via
[`DangerousClient`](#dangerous-bypass-mode); see below.
### JSON output
```rust
let result = QueryCommand::new("generate a user struct")
.output_format(OutputFormat::Json)
.json_schema(r#"{"type":"object","properties":{"id":{"type":"integer"}}}"#)
.execute_json(&claude)
.await?;
println!("{}", result.result);
println!("cost: ${:.4}", result.cost_usd.unwrap_or(0.0));
```
### Tool permissions
Use `ToolPattern` for first-class, validated patterns:
```rust
use claude_wrapper::{QueryCommand, ToolPattern};
let cmd = QueryCommand::new("review src/main.rs")
.allowed_tool(ToolPattern::tool("Read"))
.allowed_tool(ToolPattern::tool_with_args("Bash", "git log:*"))
.allowed_tool(ToolPattern::all("Write"))
.allowed_tool(ToolPattern::mcp("my-server", "*"))
.disallowed_tool(ToolPattern::tool_with_args("Bash", "rm*"));
```
Bare strings still work via `From<&str>`:
```rust
let cmd = QueryCommand::new("review").allowed_tools(["Read", "Bash(git log:*)"]);
```
`ToolPattern::parse(s)` validates shape (balanced parens, no comma,
non-empty name) and returns a typed `PatternError` on malformed input.
## Multi-turn conversations
Two shapes for multi-turn work, each suited to a different process
model. Pick `DuplexSession` if you can keep a `claude` subprocess
open for the lifetime of the conversation (IDE backends, daemons,
agent servers, chat UIs). Pick `Session` if your process is
short-lived and conversation continuity is the main thing you need
(CLIs, build scripts, batch jobs, lambdas).
| Process model | one child held open across turns | new subprocess per turn, `--resume` continuity |
| Mid-turn interrupt | yes (`interrupt()`) | no (only `child.kill()` via SIGKILL) |
| Mid-turn permission prompts | yes (`PermissionHandler`) | no |
| Broadcast event subscribers | yes (`subscribe()`) | no (per-turn streaming via `stream_query`) |
| Built-in cost / history tracking | no (TurnResult is per-turn) | yes (`total_cost_usd`, `history`, `BudgetTracker`) |
| Right for | long-running hosts | short-lived processes |
### `DuplexSession` (recommended for long-running hosts)
Holds one `claude` subprocess open in stream-json duplex mode for
the duration of a conversation. User messages go in over stdin,
NDJSON events come back over stdout. Subscribe to the event stream
for token-by-token UI updates, answer permission prompts via an
async callback, and cancel a turn cleanly with `interrupt()`.
```rust
use claude_wrapper::Claude;
use claude_wrapper::duplex::{DuplexOptions, DuplexSession, InboundEvent};
let claude = Claude::builder().build()?;
let session = DuplexSession::spawn(
&claude,
DuplexOptions::default().model("haiku"),
).await?;
let mut events = session.subscribe();
let turn = session.send("what's 2 + 2?").await?;
while let Ok(event) = events.try_recv() {
if let InboundEvent::Assistant(_) = event {
// partial or complete assistant message
}
}
println!("answer: {}", turn.result_text().unwrap_or(""));
session.close().await?;
```
See the [`duplex` module docs](https://docs.rs/claude-wrapper/latest/claude_wrapper/duplex/index.html)
for `interrupt()`, `respond_to_permission()`, and the full surface.
### `Session` (for short-lived processes)
Spawns a transient subprocess per turn and threads `session_id`
across them via `--resume`. Tracks history, cumulative cost, and
integrates with `BudgetTracker` for hard-stop ceilings. The right
fit when each turn can stand on its own and the host process
isn't long-lived.
```rust
use std::sync::Arc;
use claude_wrapper::{Claude, QueryCommand};
use claude_wrapper::session::Session;
let claude = Arc::new(Claude::builder().build()?);
let mut session = Session::new(Arc::clone(&claude));
let first = session.send("what's 2 + 2?").await?;
let second = session
.execute(QueryCommand::new("explain").model("opus"))
.await?;
println!("cost: ${:.4}", session.total_cost_usd());
println!("turns: {}", session.total_turns());
```
Resume an existing session:
```rust
let mut resumed = Session::resume(claude, "sess-abc123");
let next = resumed.send("pick up where we left off").await?;
```
`Session` is `Send + Sync`, holds `Arc<Claude>`, and can move
between tasks or sit in long-lived actor state. Streaming turns
use `Session::stream` / `Session::stream_execute` and capture the
session id from the first event that carries one -- persisted even
if the stream errors partway through.
`Session` is currently async-only. Sync callers compose equivalent
state using `execute_sync` / `execute_json_sync` and `BudgetTracker`.
## Budget tracking
Attach a `BudgetTracker` to a session (or share one across several
sessions) to enforce USD ceilings:
```rust
use claude_wrapper::BudgetTracker;
let budget = BudgetTracker::builder()
.max_usd(5.00)
.warn_at_usd(4.00)
.on_warning(|total| eprintln!("warning: ${total:.2} spent"))
.on_exceeded(|total| eprintln!("budget hit: ${total:.2}"))
.build();
let mut session = Session::new(claude).with_budget(budget.clone());
session.send("hello").await?;
println!("spent: ${:.4}", budget.total_usd());
println!("remaining: ${:.4}", budget.remaining_usd().unwrap());
```
Callbacks fire exactly once at their thresholds. When `max_usd` is
set, `Session::execute` / `Session::stream_execute` short-circuit with
`Error::BudgetExceeded` before dispatching any turn that would run
with the ceiling already hit -- a hard stop, not just a callback.
Clone a tracker across several sessions to share the running total.
`BudgetTracker` is internally `Arc<Mutex<_>>` so clones are cheap and
the total is coherent.
## Streaming NDJSON
```rust
use claude_wrapper::{Claude, QueryCommand, OutputFormat};
use claude_wrapper::streaming::{StreamEvent, stream_query};
let claude = Claude::builder().build()?;
let cmd = QueryCommand::new("explain quicksort")
.output_format(OutputFormat::StreamJson);
stream_query(&claude, &cmd, |event: StreamEvent| {
if event.is_result() {
println!("result: {}", event.result_text().unwrap_or(""));
println!("session: {}", event.session_id().unwrap_or(""));
}
}).await?;
```
Sync: `stream_query_sync`. The handler runs on the caller's thread, so
it can capture non-`Send` state (`Rc<RefCell<_>>`, etc.).
## On-disk introspection
Read Claude Code's on-disk state under `~/.claude` directly, without
spawning the CLI. Each module exposes a root/loader with `list` / `get`
accessors and returns an empty result when the directory is absent.
| `history` | `HistoryRoot` | sessions and transcripts (`projects/<slug>/<id>.jsonl`) |
| `artifacts` | `AgentsRoot` | agent definitions (`agents/<name>.md`) |
| `skills` | `SkillsRoot` | skill definitions (`skills/<name>/SKILL.md`) |
| `commands` | `CommandsRoot` | custom slash commands |
| `settings` | `SettingsLoader` | the four settings layers, merged by precedence |
| `jobs` | `JobsRoot` | background-agent / supervisor state |
| `worktrees` | `WorktreeRoot` | git worktrees for `--worktree` sessions |
```rust
use claude_wrapper::history::HistoryRoot;
let history = HistoryRoot::home()?;
for project in history.list_projects()? {
println!("{} ({} sessions)", project.decoded_path.display(), project.session_count);
}
```
The `history`, `jobs`, and `settings` modules require the `json`
feature (on by default). See the `inspect_state` example for a tour.
## MCP servers
```rust
// List
McpListCommand::new().execute(&claude).await?;
// HTTP
McpAddCommand::new("sentry", "https://mcp.sentry.dev/mcp")
.transport(Transport::Http)
.execute(&claude)
.await?;
// Stdio
McpAddCommand::new("my-tool", "npx")
.server_args(["my-mcp-server"])
.env("API_KEY", "secret")
.execute(&claude)
.await?;
// From JSON
McpAddJsonCommand::new("config.json").execute(&claude).await?;
// Remove
McpRemoveCommand::new("old-server").execute(&claude).await?;
```
### Programmatic `.mcp.json`
```rust
use claude_wrapper::McpConfigBuilder;
McpConfigBuilder::new()
.http_server("hub", "http://127.0.0.1:9090")
.stdio_server("tool", "npx", ["my-server"])
.write_to("/tmp/my-project/.mcp.json")?;
```
With the `tempfile` feature (default), `build_temp()` returns a
`TempMcpConfig` that writes to a temp file and deletes it on drop --
useful for one-shot queries.
## Dangerous: bypass mode
`--permission-mode bypassPermissions` is isolated behind
`DangerousClient`, which requires an env-var acknowledgement at
process start:
```rust
use claude_wrapper::{Claude, QueryCommand};
use claude_wrapper::dangerous::DangerousClient;
// Set CLAUDE_WRAPPER_ALLOW_DANGEROUS=1 at process start
let dangerous = DangerousClient::new(Claude::builder().build()?)?;
let output = dangerous
.query_bypass(QueryCommand::new("do the risky thing"))
.await?;
```
Construction fails with `Error::DangerousNotAllowed` if the env var is
absent. There is no equivalent on plain `Claude` -- the type-level
isolation is deliberate.
## Retry policy
```rust
use std::time::Duration;
use claude_wrapper::RetryPolicy;
let policy = RetryPolicy::new()
.max_attempts(3)
.initial_backoff(Duration::from_secs(1))
.exponential()
.retry_on_timeout(true)
.retry_on_exit_codes([1, 2]);
let claude = Claude::builder().retry(policy).build()?;
```
Retry wraps every `QueryCommand::execute` and `execute_sync` (other
commands don't retry). A per-command override is available via
`QueryCommand::retry(policy)`.
## Error handling
```rust
use claude_wrapper::Error;
match QueryCommand::new("test").execute(&claude).await {
Ok(output) => println!("{}", output.stdout),
Err(Error::CommandFailed { stderr, exit_code, .. }) => {
eprintln!("Command failed (exit {}): {}", exit_code, stderr);
}
Err(Error::Timeout { .. }) => eprintln!("Command timed out"),
Err(Error::BudgetExceeded { total_usd, max_usd }) => {
eprintln!("Budget ${:.2} / ${:.2}", total_usd, max_usd);
}
Err(Error::VersionMismatch { found, minimum }) => {
eprintln!("Claude CLI {} < required {}", found, minimum);
}
Err(e) => eprintln!("Other error: {}", e),
}
```
## Escape hatch: RawCommand
For subcommands not yet wrapped:
```rust
let output = RawCommand::new("custom-subcommand")
.arg("--unsupported-flag")
.arg("value")
.execute(&claude)
.await?;
```
## Cargo features
| `async` | yes | tokio-backed async API. Disabling drops tokio from the runtime dep tree. |
| `json` | yes | JSON output parsing (`execute_json`, `StreamEvent`, `Session`, `stream_query`). |
| `tempfile` | yes | `TempMcpConfig` for one-shot MCP config files. |
| `sync` | no | Blocking API: `*_sync` methods on `exec`, `retry`, each command builder, and `Claude`. Pulls in `wait-timeout`. |
Sync-only build with no tokio:
```toml
claude-wrapper = { version = "0.13", default-features = false, features = ["json", "sync"] }
```
## Examples
```bash
cargo run --example oneshot # Single query
cargo run --example stream_query # Streaming NDJSON
cargo run --example json_output # Structured JSON response
cargo run --example mcp_config # MCP config generation
cargo run --example health_check # CLI diagnostics
cargo run --example agent_worker # Agent worker setup
cargo run --example supervised_worker # Restart loop with budget tracking
cargo run --example duplex_chat # Interactive multi-turn chat (DuplexSession)
cargo run --example duplex_interrupt # Cancel an in-flight turn
cargo run --example duplex_http_service # One DuplexSession behind HTTP routes
cargo run --example inspect_state --features json # Read on-disk state (no CLI)
```
Most examples use the async API (`--features async`, on by default);
`inspect_state` is read-only and needs just `--features json`.
## Testing
```bash
# Unit + doc tests
cargo test --lib --all-features
cargo test --doc --all-features
# Integration tests against the bundled fake-claude.sh (no real CLI needed)
cargo test --test fake_claude --all-features
cargo test --test fake_claude_sync --all-features
# Sync-only build + tests (no tokio)
cargo test --test fake_claude_sync \
--no-default-features --features "json,sync"
# Integration tests against a real `claude` binary (requires auth)
cargo test --test integration -- --ignored
```
## License
MIT OR Apache-2.0