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). - Cost-efficient prompting — structural prompt caching re-bills stable prefixes at the cached rate, and replay pays zero tokens.

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. No API key? Try the bundled examples

From a checkout of the repo (the build-from-source option in step 0), several examples run with no provider key at all:

chidori demo                                              # interactive picker
chidori run examples/agents/hello.ts --input name=Colton  # no LLM calls
chidori run examples/agents/tool_use.ts \
  --input query=chidori --tools examples/tools            # local TS tool, no LLM

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

export LITELLM_API_URL=http://localhost:4401/v1

export LITELLM_API_KEY=sk-litellm-master-key

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

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 under .chidori/runs/).

⚖️ 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.