chidori

Chidori

The agent framework where every run is durable, replayable, and resumable by default.

Write agents as plain async TypeScript. Every side effect — every LLM call, tool call, and HTTP request — flows through the runtime as a recorded host call. So any run can be checkpointed to disk, replayed for byte-identical output with zero LLM calls, and resumed from any pause — even in a new process after a crash. One Rust binary, an embedded pure-Rust JavaScript engine, and TypeScript + Python SDKs. No Node, no DSL, no native bindings.

Why Chidori · ⚡️ Quick Start · What You Can Build · ⚖️ Compare · Docs · Discord

## Why Chidori **Agents are non-deterministic, expensive, and long-running.** That combination is what makes them miserable to build: - A bug surfaces three runs deep — and you can't reproduce it. - Every debugging cycle re-bills the same tokens. - A crash halfway through a multi-step run loses everything. - ⏳ "Wait for a human to approve" means keeping a process alive for hours. Most frameworks layer orchestration *on top of* this chaos. **Chidori removes it at the source.** The trick is a single boundary. Every side effect an agent performs — every LLM call, tool call, and HTTP request — flows through the runtime as a recorded **host call**. Agents never touch the world directly, so the runtime sees (and records) *everything*:

Once the runtime sees every side effect, it can log it, cache it, replay it, pause on it, and resume from it. That one mechanism is what turns each of the four problems above into a feature: - **Replay any run with zero LLM calls.** The call log is a deterministic record. Re-run the exact same code against it — for tests, for debugging, for recovery — and every prompt, tool, and HTTP call returns its recorded result instantly. No tokens spent, identical output. - **Survive crashes and restarts.** Runs are checkpointed at every host safepoint. Kill the process mid-run and resume exactly where it left off — in a brand-new process — by replaying the call log to the pause point and continuing live. - ‍⚖️ **Pause for humans without holding a process open.** `chidori.input()` and named [signals](./docs/signals.md) suspend the run to disk. A human (or another agent) answers minutes or days later and the run picks up exactly where it stopped. - **Check in a checkpoint as a test.** Commit a recorded run to git and assert the agent's behavior hasn't drifted — a full integration test that costs $0 and runs in milliseconds. The payoff: you get the durability guarantees of a workflow engine *and* LLM-native primitives, while writing nothing but ordinary `async`/`await` TypeScript. ### What makes it different - **Agents are plain TypeScript — not a graph or a DSL.** Native async control flow, `if`/`for`/`try`, type-safe inputs, real imports, and full editor tooling. If you can write a function, you can write an agent. - **Durability is the default, not a wrapper.** You don't annotate steps or define activities. Every `await chidori.*` *is* a durable, replayable safepoint. - **Replay costs zero tokens and is byte-identical.** Determinism is enforced by runtime policy (fixed clock, seeded randomness), so a replay isn't an approximation — it's the same run. - **One Rust binary, no runtime dependencies.** An embedded pure-Rust JavaScript engine runs your agents — no Node, no Deno, no V8. SDKs talk to it over HTTP with no native bindings. - **Structural prompt caching built in.** Stable prefixes are auto-marked for the provider cache (~10% of base input rate on Anthropic), and replay pays nothing at all. ## ⚡️ Quick Start ### 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: ```bash 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](https://github.com/ThousandBirdsInc/chidori/releases/latest), 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. Other ways to install (build from source, contributors) **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`: ```bash 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: ```bash git clone https://github.com/ThousandBirdsInc/chidori cd chidori cargo build --release # binary at ./target/release/chidori ``` > **Which package is which?** The thing you install here is the **runtime** (the > `chidori` binary). The [npm](https://www.npmjs.com/package/@1kbirds/chidori) and > [PyPI](https://pypi.org/project/chidori/) 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. ### 1. Chat with the Chidori docs (30 seconds) The fastest way to feel what Chidori does: scaffold an agent that answers questions from a local docs folder, and chat with it. ```bash chidori model-login # sign in with OpenRouter — no API key to set up chidori init my-agent --template docs cd my-agent chidori chat agent.ts ``` `chidori model-login` opens your browser, signs you in with OpenRouter, and saves a key to `~/.chidori/credentials.json` — the zero-setup way to try things out. Prefer your own provider key? Set `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`) instead; explicit keys always take precedence over the OpenRouter fallback. Then ask it things like *"What is a host call?"* or *"How do I write a tool?"*. The scaffold is a complete, readable project: a ~50-line `agent.ts`, a `docs/chidori.md` knowledge file, and a README. The agent reads the Markdown under `docs/` with `chidori.workspace.read(...)` and answers from it. **What it touches:** only the files in this project folder. Chidori scopes the workspace to the project directory — the agent can't read elsewhere on your machine — and the only thing sent to the model is your question plus the bundled docs. Drop your own `.md` files into `docs/` to chat with those instead. Every turn is a recorded host call, so replaying the whole conversation costs zero tokens. Two other starters ship too — `--template chat` (a plain assistant) and `--template worker` (an autonomous tool-using loop); omit `--template` to pick interactively. ### 2. Write your own agent An agent is a plain TypeScript file: import the `chidori` host object and the `run` definer from the virtual `chidori:agent` module and register your handler. Every model call is a recorded host call: ```ts // summarizer.ts /// import { chidori, run } from "chidori:agent"; run(async (input: { document: string }) => { const summary = await chidori.prompt("Summarize in 3 bullets:\n" + input.document); const actionItems = await chidori.prompt("Extract action items:\n" + summary); return { summary, actionItems }; }); ``` That's a complete, durable agent. Both prompts are recorded; replay returns them for free. `chidori:agent` is a **virtual** module the runtime injects at execution time — there is no npm package behind it, so the runtime needs nothing installed. The `/// ` line is what gives your editor and `tsc` its types: they ship in the [`@1kbirds/chidori`](https://www.npmjs.com/package/@1kbirds/chidori) npm package (`npm install -D @1kbirds/chidori`, or add `"types": ["@1kbirds/chidori/agent-env"]` to your `tsconfig.json` instead of the per-file directive). See the [TypeScript SDK README](./sdk/typescript/README.md) for the full story. ### 3. Run it ```bash # The OpenRouter sign-in from step 1 is all you need. Prefer your own key? # 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): ```bash export CHIDORI_OPENAI_COMPAT_URL=https://api.deepseek.com # /v1 optional export CHIDORI_OPENAI_COMPAT_KEY=sk-... chidori run summarizer.ts --model deepseek-chat \ --input document="Rust is a systems programming language..." ``` `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`: ```bash chidori run my_agent.ts --trusted ``` Re-run the same agent with `chidori resume summarizer.ts ` 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 --trusted`. ### 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: ```bash chidori demo # interactive picker ``` Several examples need **no provider at all** (pure compute and local tools), so they run with zero setup: ```bash 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](./docs/running-modes.md) for the approval model.) For