Expand description
hive-claude — a small, reusable async driver for headless
claude --print (Claude Code CLI) sessions.
It spawns the CLI, streams and classifies its stream-json output, and
reports the result as a Result<(), Error>: a clean turn is Ok(()), and
every non-completion state — both recognized sentinels (rate-limit,
prompt-too-long, …) and hard failures (spawn, non-zero exit) — is a variant
of the single Error enum, so callers branch with one match. The crate
also locates and archives on-disk sessions by title (SessionStore). It
knows only about the Claude Code CLI — no application types, hard-coded
watermarks, or logging. Callers wire streaming output through a Sink.
Two layers:
Claude::run— the low-level driver: one turn, oneAttachtarget.InfiniteSession— a durable session (name +SessionStore+CompactionPolicy) that keeps itself alive across the context window by compacting reactively (on overflow) and proactively (per policy — e.g.PercentPolicy). This is the one you usually want.
§Example
use hive_claude::{Attach, Claude, Config, Error, NoopSink};
let config = Config {
model: Some("haiku".into()),
..Default::default()
};
match Claude::run(&config, &Attach::Resume("my-session".into()), "hello", &NoopSink).await {
Ok(()) => {}
Err(Error::PromptTooLong) => { /* caller compacts + retries */ }
Err(Error::RateLimited) => { /* caller parks + retries */ }
Err(other) => eprintln!("claude: {other}"),
}Re-exports§
pub use serde_json;
Structs§
- Cancel
- A cheap,
Clonehandle that can cancel aRunningClaudefrom anywhere — signals the process group directly, no interaction with whatever (if anything) is currently pollingRunningClaude::wait, so it fires immediately regardless of where/whether that’s running. Deliberately notCopy, to leave room to grow non-trivially-copyable internals later without an API break. - Claude
- The low-level driver entry point. A namespace for the run function — there
is nothing to construct; call
Claude::run(…)directly. For a durable, self-compacting session, usecrate::InfiniteSessioninstead. - Config
- Everything needed to build one headless
claude --printinvocation, minus theAttachtarget (passed separately tocrate::Claude::run). - Infinite
Session - A named claude session that outlives the model’s context window by compacting itself. Bundles the three things a durable session needs:
- Never
Compact - A policy that never compacts. Turns run until the session overflows and the
reactive path in
crate::InfiniteSession::runtakes over. - Noop
Sink - A
Sinkthat discards everything. Useful for fire-and-forget runs where only the returnedcrate::Resultmatters. - Percent
Policy - Compact once the context reaches
percentof the model window. - Progress
- What
InfiniteSession::rundid, beyond streaming the turn to the sink. - Running
Claude - A claude run already in progress (
Claude::spawn). Cancel it viaRunningClaude::cancel_handle, or drive it to completion withRunningClaude::wait. - Session
Store - On-disk claude session store scoped to one working directory.
- Telemetry
- Everything the driver tracks from one turn’s stream-json output.
- Token
Usage - Token counts from one
usageblock. All in tokens; missing fields read0. - Usage
- The compaction signal: the live context size and the window it’s measured
against. Derived from
TelemetryviaTelemetry::usage.
Enums§
- Attach
- How a run attaches to a claude session — the low-level session flag. Kept
separate from
Configso one config can drive resume + create +/compactof the same logical session. For a self-managing durable session, prefercrate::InfiniteSessionover hand-picking anAttach. - Error
- Why a claude run did not complete cleanly. A normal, finished turn is
Ok(()); everything else is one of these variants.
Traits§
- Compaction
Policy - Decides, after a completed turn, whether an
crate::InfiniteSessionshould proactively compact — and what to say in the optional checkpoint turn that runs first. Injected by the caller so the driver stays free of any app-specific policy. - Sink
- Consumer callbacks for a claude run’s output streams. Every method has a no-op default, so an implementor overrides only what it needs.
Type Aliases§
- Result
- Convenience alias for results from this crate.