0. Install

Chidori is one self-contained binary — the runtime that runs your agents. There's nothing else to install: no Node, no Python, no Rust toolchain, no native bindings. The fastest way to get it is the prebuilt binary:

curl -fsSL https://raw.githubusercontent.com/ThousandBirdsInc/chidori/main/scripts/install.sh | sh

This downloads the right binary for macOS (Apple Silicon or Intel) or Linux (x86_64 or arm64) from the latest GitHub release, puts it in ~/.chidori/bin, and prints a one-line PATH tweak if needed. Check it with chidori --version. Prefer to grab the tarball by hand? Every release page lists one per platform.

<details> <summary>Other ways to install (build from source, contributors)</summary>

From crates.io — builds the binary from source, so you need a stable Rust toolchain (1.95 or newer). Slower than the prebuilt binary, but handy if you already have cargo:

cargo install chidori   # binary lands in ~/.cargo/bin

From a checkout — also gets you the bundled examples/ used in step 4. The repo pins its toolchain via rust-toolchain.toml, so cargo picks it up automatically:

git clone https://github.com/ThousandBirdsInc/chidori
cd chidori
cargo build --release   # binary at ./target/release/chidori

</details>

Which package is which? The thing you install here is the runtime (the chidori binary). The npm and PyPI packages are the SDKs — thin, optional clients for driving the runtime over HTTP from a TypeScript or Python app. You don't need them to write or run agents (you author those in plain .ts files the runtime executes directly); reach for an SDK only when you want to embed Chidori in an existing service. npm i @1kbirds/chidori does not install the runtime.

🧰 What You Can Build

- Conversational chat assistants — chidori.conversation() owns a multi-turn dialogue: chat.say(message) per turn, or chat.loop() for an interactive input()-driven session. Every turn is durable and prefix-cached, so the whole conversation replays for $0. Or run chidori chat (optionally through an agent file) for a built-in REPL. See Core concepts. - Autonomous tool-using agents — a worker that loops (think → call a tool → observe → repeat) until the task is done, via context.respond() and toolResult(...). Scaffold one with chidori init --template worker; see examples/agents/worker.ts. - Durable, resumable agents — runs survive crashes and restarts and resume exactly where they paused. See How replay works. - Deterministic tests & free debugging — check in a checkpoint and replay it with zero LLM calls to assert behavior or step through a failure locally with breakpoints. - Human-in-the-loop workflows — pause for approval or input with chidori.input(...), persist the checkpoint, resume hours later in a new process. - Multiplayer & event-driven agents — react to webhooks, or pause on named signals until a human or another agent delivers a payload. - Branching exploration — fork a run into per-strategy sub-runs and compare every outcome (branching execution). - Implementation history — every source version a run or branch ever executed is recorded as a git-like commit chain alongside the journal: chidori history shows which code produced which recorded calls, prints any stored version, and diffs any two (source history). - Supervised multi-agent processes — spawn agent modules as concurrent, addressable actors with durable mailboxes, message passing, supervision trees, and runtime-owned restart policies — including restart-with-history, which replays an actor's completed work and retries only the failing call. - Detached durable agents — spawn long-lived, named agent processes that outlive the run that started them: they hibernate at listen points holding zero threads and zero memory, wake on a mailbox delivery or a durable chidori.alarm(ms) deadline, and survive server restarts (the fleet re-arms from a durable registry at boot). - Replicated run storage — mirror every run's journal to any S3-compatible bucket (S3/R2/GCS/MinIO), SQLite, or a Cloudflare Durable Object per run (CHIDORI_RUN_STORE), hydrate runs back after machine loss, gate side effects on journal durability (CHIDORI_DURABILITY=strict), and time-travel with chidori resume --until-seq. - Cost-efficient prompting — structural prompt caching re-bills stable prefixes at the cached rate, and replay pays zero tokens. - Agents that learn across sessions — persist distilled lessons and preferences in chidori.memory, a namespaced key-value store anchored to the agent's directory, and render reusable prompt templates (Jinja with strict undefined-variable checking) instead of concatenating strings. - npm packages without Node — chidori add zod installs straight from the npm registry into a content-addressed cache (SHA-512 verified, hardlinked node_modules, merge-friendly JSONL lockfile, no install scripts ever), and agents just import { z } from "zod". The engine is not Node, so the compatible set is pure-ESM, native-free packages using only the shimmed builtins — chidori add warns when a package falls outside it. See package management. - Self-improving agents / harness engineering — the same durability machinery is a substrate for the self-improvement loop: mine failures from traces, fork a controlled experiment from the failure's exact anchored state with chidori.branch, validate against golden cases whose fixtures are checkpoints (replayed byte-for-byte at $0), and regression-guard the win by committing the checkpoint. See the runnable self-harness-loop demo and Observing runs with Tael.

Agents reach all of this through a fixed set of host functions on the chidori object — see Core concepts for the full list and llm.txt for the complete API reference.

⚡️ Quick Start

4. Try the bundled examples

From a checkout of the repo (the build-from-source option in step 0), chidori demo is an interactive picker of runnable examples. The LLM-backed ones use whatever provider you've configured — or prompt you to sign in with OpenRouter on the spot (chidori model-login) if you have no key set:

chidori demo                                              # interactive picker

Several examples need no provider at all (pure compute and local tools), so they run with zero setup:

chidori run examples/agents/hello.ts --input name=Colton  # no LLM calls
chidori run examples/agents/tool_use.ts \
  --input query=chidori                                   # defineTool, no LLM

(The second example defines its tool inline with defineTool and calls it — no directory, no --tools. See Running modes for the approval model.)

For a guided walkthrough — inspecting a run, the demo picker, and the human-in-the-loop pause/resume loop — see Getting Started.

export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY=...

chidori run summarizer.ts \ --input document="Rust is a systems programming language..."

**Any OpenAI-compatible provider (DeepSeek, Groq, Ollama, vLLM, LiteLLM…).**
Point Chidori at any endpoint that speaks the OpenAI chat-completions
protocol, and pick the model with `--model` (or the `CHIDORI_MODEL` env var —
prompts that don't set `model` in code default to `claude-sonnet-4-6`
otherwise):

`OPENAI_BASE_URL` (alongside `OPENAI_API_KEY`) works too, and
`LITELLM_API_URL`/`LITELLM_API_KEY` remain as legacy aliases of the
`CHIDORI_OPENAI_COMPAT_*` pair.

`chidori run` **asks before powerful effects by default**: tool calls, network
access (`chidori.fetch`), and workspace writes pause for a one-keypress
approval at the terminal (LLM prompts and pure compute never ask). That's the
safe default for running code you didn't write; for your own agents, in
scripts, or in CI — where there is no terminal to ask at, so gated effects
fail closed — pass `--trusted`:

Re-run the same agent with chidori resume summarizer.ts <run_id> to replay it byte-for-byte with zero model calls (the run id is printed when the run starts, and lives under .chidori/runs/). The run's model travels with it — a --model deepseek-chat run resumes under deepseek-chat with no extra flags — and crash recovery of a trusted, tool-using run mirrors run's flags: chidori resume my_agent.ts <run_id> --trusted.

⚖️ How Chidori Compares

Chidori sits where LLM agent frameworks and durable execution engines meet — and brings the strengths of both without their usual trade-offs.

Reach for Chidori when your agents are long-running, expensive, or human-gated — and you want them to be as testable and debuggable as ordinary code.