Skip to main content

Crate hive_claude

Crate hive_claude 

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

§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, Clone handle that can cancel a RunningClaude from anywhere — signals the process group directly, no interaction with whatever (if anything) is currently polling RunningClaude::wait, so it fires immediately regardless of where/whether that’s running. Deliberately not Copy, 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, use crate::InfiniteSession instead.
Config
Everything needed to build one headless claude --print invocation, minus the Attach target (passed separately to crate::Claude::run).
InfiniteSession
A named claude session that outlives the model’s context window by compacting itself. Bundles the three things a durable session needs:
NeverCompact
A policy that never compacts. Turns run until the session overflows and the reactive path in crate::InfiniteSession::run takes over.
NoopSink
A Sink that discards everything. Useful for fire-and-forget runs where only the returned crate::Result matters.
PercentPolicy
Compact once the context reaches percent of the model window.
Progress
What InfiniteSession::run did, beyond streaming the turn to the sink.
RunningClaude
A claude run already in progress (Claude::spawn). Cancel it via RunningClaude::cancel_handle, or drive it to completion with RunningClaude::wait.
SessionStore
On-disk claude session store scoped to one working directory.
Telemetry
Everything the driver tracks from one turn’s stream-json output.
TokenUsage
Token counts from one usage block. All in tokens; missing fields read 0.
Usage
The compaction signal: the live context size and the window it’s measured against. Derived from Telemetry via Telemetry::usage.

Enums§

Attach
How a run attaches to a claude session — the low-level session flag. Kept separate from Config so one config can drive resume + create + /compact of the same logical session. For a self-managing durable session, prefer crate::InfiniteSession over hand-picking an Attach.
Error
Why a claude run did not complete cleanly. A normal, finished turn is Ok(()); everything else is one of these variants.

Traits§

CompactionPolicy
Decides, after a completed turn, whether an crate::InfiniteSession should 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.