claude-code-agent
Run Claude Code from Rust. Each Session keeps one claude process running, so you can send prompts, watch Claude work, approve or block its tools, and give it tools written in Rust.
You need the Claude Code CLI 2.1.329 or newer, installed and logged in. Session::spawn refuses an older version.
Install
[]
= "0.7"
= { = "1", = ["full"] }
= "0.1"
Add features = ["macros"] to turn Rust functions into tools with #[claude_tool].
Quick start
use ;
use StreamExt;
async
close() ends the claude process and everything it started.
Choosing the model and limits
Set these in SessionOptions before spawning:
| Option | What it does |
|---|---|
model, fallback_model |
Which model to use, and which to fall back to |
effort, thinking |
How hard the model thinks |
permission_mode |
Default, AcceptEdits, BypassPermissions, Plan, DontAsk or Auto |
max_turns, max_budget_usd |
Stop a prompt after this many turns or this much spend |
tools, allowed_tools, disallowed_tools, add_dirs |
Which tools Claude has and which folders it may use |
resume, fork_session, continue_conversation |
Continue an earlier conversation |
cwd, env, settings, setting_sources |
Working folder, environment and Claude Code settings |
persist_session: false |
Don't save the conversation to disk |
include_partial: true |
Receive text as it is typed, in small pieces |
extra_args |
Any other claude flag |
Change them mid-session with set_model, set_effort and set_permission_mode.
What a prompt sends back
agent.prompt(...) returns a stream of AgentEvents for that prompt:
| Event | Meaning |
|---|---|
Text, Thinking |
What Claude writes and thinks |
ToolUse |
Claude calls a tool |
ToolResult |
The tool's result; structured holds the full output, such as Bash's stdout and stderr |
Subagent |
An event from a subagent Claude started |
System, Other |
Everything else the CLI reports, such as retries and rate limits |
Done(TurnResult) |
Finished: the answer, cost, tokens and number of turns |
Error(TurnError) |
Failed; kind says why: MaxTurns, MaxBudget, Api, Cancelled, … |
To get the answer as JSON, set Initialize::json_schema. The value arrives in TurnResult::structured_output (see examples/structured_output.rs).
Claude sometimes starts a new turn by itself, for example when a background command finishes. agent.watch() streams every turn, including those (see examples/watch.rs).
Stopping a prompt
Drop the stream to cancel its prompt. A prompt still waiting in line is removed; a running one is stopped. Other prompts keep going.
session.interrupt()stops whatever is running.session.interrupt_all()also removes every waiting prompt.UserMessage::with_priority(Priority::Now)stops the running prompt and starts yours right away.
Approving tools and hooks
Decide which tools Claude may use with can_use_tool, and react to what Claude does with hooks. Both are set before spawning:
use ;
use ;
let mut hooks = new;
// Block every Bash command
hooks.on;
// Give every subagent extra instructions
hooks.on;
let opts = SessionOptions ;
HookEventKind has every Claude Code hook. These fire for Rust hooks: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, UserPromptSubmit, SessionStart, Stop, SubagentStart, SubagentStop, PreCompact, PostCompact and MessageDisplay. CwdChanged and FileChanged only reach shell hooks in your settings.
Tools written in Rust
With the macros feature, a Rust function becomes a tool Claude can call. It runs inside your program:
use ;
/// Search files matching a glob pattern
async
let opts = SessionOptions ;
Claude sees the tool as mcp__files__search_files. The doc comment becomes its description, and the arguments are read from the call with serde. An Err is shown to Claude as a failed call. Your tools are allowed to run without asking.
Other MCP servers (stdio, HTTP or SSE) go in Initialize::mcp_servers. Add or change servers mid-session with session.set_mcp_servers(...).
Questions from the CLI
Sometimes Claude Code needs a decision from your user before it can go on. Without a handler it doesn't ask and picks a safe default. To ask your user yourself, list the questions your app can show and answer them in on_user_dialog:
use ;
let opts = SessionOptions ;
let init = Initialize ;
| Question | When Claude Code asks | Answers | With no handler |
|---|---|---|---|
refusal_fallback_prompt |
The model refused and fallback_model is set |
"retry_fallback" tries the fallback model; "edit_prompt" stops |
The prompt ends with the refusal |
auto_mode_server_fallback |
In auto mode, checking tool calls starts to cost extra API requests | "continue" pays and goes on; "interrupt" blocks the tool call |
The checks run and are billed |
fable_overage_consent_prompt |
Your plan reached its Fable usage limit | See question.payload; an answer can turn on overage billing |
Not asked |
UserDialogResponse::cancelled() means your user closed the question without choosing.
Running many prompts at once
A SessionPool keeps claude processes warm and hands them out:
use ;
let pool = new;
pool.warm.await; // start 2 processes now
let session = pool.acquire.await?; // waits while all 4 are in use
let mut stream = new.prompt.await?;
// A session with its own model
let fast = pool.acquire_with.await?;
Dropping a pooled session returns it. Before the next task gets it, its conversation is cleared and its model, effort and permission mode are reset.
Testing without the CLI
Record a live session once, then replay it in tests with no process and no API cost:
let opts = SessionOptions ;
// ... run the session ...
let session = replay.await?;
More
- Compacting:
claude_code_agent::compaction::compact(&agent, Some("keep file paths"))shrinks the conversation to save context. - Images and documents: send them as prompt content with
UserMessage::blocks. - Tracing: spans
claude.turn,claude.hookandclaude.toolwork with anytracingsubscriber. - CLI output:
on_stderrreceives every line the CLI writes to stderr. - Code Mode:
code_mode: truegives Claude aREPLtool where it writes JavaScript that calls its tools. Anthropic doesn't support this; the CLI only allows it interactively, so the SDK runs a patched copy of the CLI (built on first use, cached in~/.cache/claude-code-agent/). Your installedclaudeis not changed. SeeDESIGN.md.
Runnable programs for each feature are in examples/.
Limitations
- A Claude Code update can break Code Mode until the SDK is updated; spawning then fails with a
CodeModeError(AnchorCount,PatternInvalidorReplacementTooShort). A CLI older than the SDK supports fails withSessionError::UnsupportedCliVersioninstead. close()and dropping a session end the CLI, its hooks and its Bash tools. A process a hook or tool detached that outlived it ((cmd &),nohup cmd &) is out of reach.- Tools from servers added with
set_mcp_serversstill need permission (permission_modeorcan_use_tool). session.mcp_callandmcp_read_resourcework only with external MCP servers.set_system_promptworks only on your account's default model; useset_model_and_system_promptotherwise.UserMessage::with_timestampis ignored by Claude Code 2.1.329.- The SDK doesn't handle login; the CLI uses its own.
Development
Release: bump version in both Cargo.toml files (and the dependency on claude-code-agent-macros), push to main, then push the matching tag:
&&
.github/workflows/release.yml runs the tests on Linux, macOS and Windows, then publishes both crates to crates.io. No token is stored; crates.io trusts the workflow directly.
After a Claude Code update, run python3 -I scripts/cli-parity.py to list new CLI flags and requests the SDK doesn't support yet. Deliberate gaps and their reasons are in scripts/cli-parity-ignore.txt.
To read the CLI's own source, run python3 -I scripts/decompile-claude.py. It unpacks the installed claude binary into target/claude-src/<version>/; DESIGN.md cites those files as chunk-*.js:line.
License
MIT