hive_claude/lib.rs
1//! `hive-claude` — a small, reusable async driver for headless
2//! `claude --print` (Claude Code CLI) sessions.
3//!
4//! It spawns the CLI, streams and classifies its `stream-json` output, and
5//! reports the result as a `Result<(), Error>`: a clean turn is `Ok(())`, and
6//! every non-completion state — both recognized sentinels (rate-limit,
7//! prompt-too-long, …) and hard failures (spawn, non-zero exit) — is a variant
8//! of the single [`Error`] enum, so callers branch with one `match`. The crate
9//! also locates and archives on-disk sessions by title ([`SessionStore`]). It
10//! knows only about the Claude Code CLI — no application types, hard-coded
11//! watermarks, or logging. Callers wire streaming output through a [`Sink`].
12//!
13//! Two layers:
14//!
15//! - [`Claude::run`] — the low-level driver: one turn, one [`Attach`] target.
16//! - [`InfiniteSession`] — a durable session (name + [`SessionStore`] +
17//! [`CompactionPolicy`]) that keeps itself alive across the context window by
18//! compacting reactively (on overflow) and proactively (per policy — e.g.
19//! [`PercentPolicy`]). This is the one you usually want.
20//!
21//! # Example
22//!
23//! ```no_run
24//! # async fn ex() {
25//! use hive_claude::{Attach, Claude, Config, Error, NoopSink};
26//!
27//! let config = Config {
28//! model: Some("haiku".into()),
29//! ..Default::default()
30//! };
31//! match Claude::run(&config, &Attach::Resume("my-session".into()), "hello", &NoopSink).await {
32//! Ok(()) => {}
33//! Err(Error::PromptTooLong) => { /* caller compacts + retries */ }
34//! Err(Error::RateLimited) => { /* caller parks + retries */ }
35//! Err(other) => eprintln!("claude: {other}"),
36//! }
37//! # }
38//! ```
39// The crate-level `//!` overview above is the rustdoc entry point — it belongs
40// in source, not docs/, so the comment-block length lint should not flag it.
41// lint:allow-long-comment
42
43mod classify;
44mod config;
45mod driver;
46mod error;
47mod policy;
48mod session;
49mod sink;
50mod store;
51mod telemetry;
52
53/// Re-exported because [`Sink::on_event`] hands out a [`serde_json::Value`]:
54/// implementing a sink needs the same `serde_json` this crate was built
55/// against, without depending on it separately.
56pub use serde_json;
57
58pub use config::{Attach, Config};
59pub use driver::{Cancel, Claude, RunningClaude};
60pub use error::{Error, Result};
61pub use policy::{CompactionPolicy, NeverCompact, PercentPolicy};
62pub use session::{InfiniteSession, Progress};
63pub use sink::{NoopSink, Sink};
64pub use store::SessionStore;
65pub use telemetry::{Telemetry, TokenUsage, Usage};