claude-wrapper：Claude Code CLI 的类型安全 Rust 封装库

A type-safe Rust wrapper around the Claude Code CLI.

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 and 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

cargo add claude-wrapper

Default features: ["async", "json", "tempfile"]. To drop tokio entirely for a sync-only build:

claude-wrapper = { version = "0.13", default-features = false, features = ["json", "sync"] }

Quick start (async)

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:

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).

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
• process_group() -- isolate each child in its own Unix process group (enabled by default)
• kill_grace() -- optional SIGTERM grace before SIGKILL on awaited shutdown paths
• output_limit() -- byte ceiling on captured stdout and stderr (no default)

Claude also exposes:

• cli_version() / cli_version_sync() -- parsed CliVersion
• check_version() / check_version_sync() -- assert a minimum version

Awaited cancellation

QueryCommand::execute_cancellable and execute_json_cancellable accept any future that resolves to (). When it resolves, the wrapper terminates the owned process group and reaps the direct child before returning Error::Cancelled. A configured timeout uses the same settlement path.

Dropping an ordinary execute future still triggers immediate process-group cleanup, but a destructor cannot wait for reaping. Use the cancellable methods when the caller needs terminal settlement before it records a run as stopped.

Bounded output capture

A buffered run reads the child's stdout and stderr to EOF, so peak memory is whatever the CLI decides to print. output_limit() sets a ceiling:

let claude = Claude::builder()
    .output_limit(4 * 1024 * 1024)
    .build()?;

The ceiling applies to each stream independently, so the pair holds at most twice the configured bytes. Reaching it terminates the child's process group (honoring kill_grace), reaps the direct child, and returns Error::OutputLimitExceeded { stream, limit_bytes } naming which stream ran over. It is not a truncated success: a caller can tell a complete answer from one that exceeded what it agreed to hold. Output captured before the ceiling tripped is logged at warn rather than returned.

There is no default ceiling. With output_limit() unset, capture behavior is unchanged.

This bounds the buffered paths (execute, execute_json, and their cancellable and blocking forms). Streaming runs deliver events as they arrive and are unaffected.

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:

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

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:

Raw session flags (prefer Session for multi-turn):

Bypass-permissions mode is only available via DangerousClient; see below.

JSON output

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:

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>:

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).

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().

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 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.

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:

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:

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

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?;

Use stream_query_cancellable when a host has an explicit stop signal. It returns only after the owned process group has been terminated and the direct child reaped. Streaming also honors QueryCommand::prompt_via_stdin(true), so sensitive prompts do not need to appear in process arguments.

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.

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

// 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

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:

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

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

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:

let output = RawCommand::new("custom-subcommand")
    .arg("--unsupported-flag")
    .arg("value")
    .execute(&claude)
    .await?;

Cargo features

Sync-only build with no tokio:

claude-wrapper = { version = "0.13", default-features = false, features = ["json", "sync"] }

Examples

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

# 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