Chidori: Durable, Replayable TypeScript Agents on a Rust Runtime

The problem Chidori picks: non-deterministic, expensive, long-running agents

The README frames the target user bluntly. Agents are non-deterministic, expensive and long-running, and that combination is what makes them painful: a bug surfaces three runs deep and cannot be reproduced, every debugging cycle re-bills the same tokens, a crash halfway through a multi-step run loses everything, and waiting for a human approval means keeping a process alive for hours. Chidori's answer is not an orchestration layer on top of that chaos. It removes the chaos at the source by forcing every side effect through one boundary.

The audience is engineers already writing agent logic in TypeScript. The README is explicit that agents are plain async TypeScript, not a graph and not a DSL: native async control flow, if/for/try, type-safe inputs, real imports, full editor tooling. If you have been putting retry logic, caching and checkpointing around an agent by hand, this project is aimed at you. If you want a visual graph editor or a YAML pipeline, it is not.

How the host call boundary makes replay byte-identical

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 everything. The README describes the payoff as a call log that can be logged, cached, replayed, paused on and resumed from.

That single mechanism produces four behaviours. Replay re-runs the same code against the call log, so every prompt, tool and HTTP call returns its recorded result instantly with zero tokens spent. Checkpointing happens at every host safepoint, so killing the process mid-run and resuming in a brand-new process works by replaying the call log to the pause point and continuing live. chidori.input() and named signals suspend a run to disk, so a human can answer minutes or days later. And a recorded run can be committed to git as a test that asserts the agent has not drifted.

The determinism claim is enforced by runtime policy: a fixed clock and seeded randomness. That is a stronger statement than most frameworks make. It also means any nondeterminism you introduce outside the host call boundary, such as reading the system clock through a path the runtime does not intercept, is a real risk to the guarantee. The README does not enumerate what is intercepted beyond LLM calls, tool calls and HTTP requests.

The runtime itself is one Rust binary with an embedded pure-Rust JavaScript engine. There is no Node, no Deno and no V8, and the SDKs talk to it over HTTP with no native bindings. Structural prompt caching is built in: stable prefixes are auto-marked for the provider cache, which the README puts at roughly 10% of base input rate on Anthropic, and replay pays nothing at all.

Installing the chidori binary and running a first agent

The thing you install is the runtime, a single self-contained binary. The README notes there is nothing else to install: no Node, no Python, no Rust toolchain, no native bindings. The fastest path is the prebuilt binary script, which 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.

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

After that, confirm the binary is on your PATH and reports a version.

chidori --version

If you already have cargo, the crate builds from source and needs a stable Rust toolchain 1.95 or newer. The binary lands in ~/.cargo/bin.

cargo install chidori

A checkout also gets you the bundled examples/ directory, which the README uses in its step 4. The repo pins its toolchain via rust-toolchain.toml, so cargo picks it up automatically, and the release build lands at ./target/release/chidori.

git clone https://github.com/ThousandBirdsInc/chidori
cd chidori
cargo build --release

One naming trap is worth stating plainly because the README calls it out. The chidori binary is the runtime. The npm package @1kbirds/chidori and the PyPI package chidori are SDKs, thin optional clients for driving the runtime over HTTP from a TypeScript or Python app. Installing the SDK does not give you the runtime. The repository layout backs this up: crates/ holds chidori, chidori-js, chidori-wasm and test262-runner, while sdk/ sits alongside it. The README does not document the CLI flags for running an agent beyond the cargo run -- run agents/my_agent.ts form quoted in Cargo.toml.

Where Chidori is the wrong tool

The overhead is the point, so it is also the cost. Every LLM call, tool call and HTTP request becomes a recorded host call, and every host call is a safepoint. For an agent that makes one model call and returns, you are paying for a call log, a checkpointing path and a replay engine that will never be used. A plain script with an HTTP client is smaller and easier to reason about.

The second constraint is language. Agent logic is TypeScript. Python appears in the repository as an SDK client (examples/sdk_demo.py, the PyPI package), which drives the runtime over HTTP rather than authoring agents in Python. If your team writes agents in Python or Go and does not want to maintain a TypeScript layer, this is a mismatch.

The third is the replay guarantee itself. Byte-identical replay depends on runtime policy intercepting everything that matters. The README describes a fixed clock and seeded randomness, but it does not publish an exhaustive list of what the runtime intercepts, and it does not document a rollback path for a run whose checkpoint is corrupt or whose call log no longer matches the code. If you edit an agent's logic, the recorded call log is a record of the old logic. The README does not say how replay behaves when the code and the log diverge, and that is the question to settle before you make replay part of CI.

Chidori against Temporal and LangGraph

The closest comparison in kind is a durable execution engine such as Temporal. Temporal also checkpoints workflow state and resumes after a crash, but it does so by requiring you to model work as workflows and activities, and it runs a server and workers as separate infrastructure. Chidori's difference is that durability is not a wrapper you opt into: every await chidori.* is a durable, replayable safepoint, and the runtime is a single binary rather than a cluster you operate. What Temporal gives you that Chidori's README does not claim is a mature operational story for many concurrent workflows across a fleet.

The other comparison is an LLM orchestration library such as LangGraph. Those give you a graph of nodes and edges, plus tracing and retries around model calls. Chidori rejects the graph as the programming model: control flow is ordinary TypeScript, and the value it adds is the recorded call log underneath, not the topology on top. If you want to see and edit the shape of your agent as a diagram, a graph framework fits better. If you want your existing async functions to become resumable without restructuring them into nodes, Chidori is the more direct fit.

A smaller, more honest comparison is to your own code. Caching LLM responses and writing a JSON checkpoint file yourself is not hard for a linear agent. Chidori's advantage appears when the agent branches, calls tools, pauses for input and has to resume in a new process, because that is where hand-rolled checkpointing tends to grow a state machine you did not want.

Maintenance, releases and the Apache-2.0 licence

The last push to the default branch was on 2026-09-10, and the repository is not archived. Recent releases are v3.6.0 on 2026-07-07, v3.7.0 on 2026-07-29 and v3.8.1 on 2026-08-30. The cadence over that window is roughly monthly, with patch releases between. That is the extent of what the release list supports; it says nothing about how many people work on the project or how quickly a reported bug gets fixed.

Upgrade cost is shaped by the architecture. The runtime is a single binary, so upgrading is replacing that binary or re-running cargo install chidori. The SDKs version separately on npm and PyPI, which means a runtime upgrade and an SDK upgrade are two moves, and the README does not state a compatibility policy between them. If you commit recorded runs as tests, as the README suggests, those fixtures are tied to the behaviour of the runtime that produced them, so a runtime upgrade is the moment to re-run them.

The licence is Apache-2.0, declared in the workspace Cargo.toml and shown in the README badge. That is a permissive licence with an explicit patent grant, which is generally the easy case for commercial use. It is not legal advice, and if you redistribute the binary or embed the crates you should read the licence text and your own obligations rather than take this paragraph as a clearance.

Editorial conclusion

Adopt Chidori if you write async TypeScript agents that call LLMs and tools, and you need reproducible debugging, cheap regression tests, or runs that wait days for a human answer without holding a process open. Do not adopt it if your agents are short, cheap, single-shot calls, or if you need a language other than TypeScript for agent logic today. Before committing, verify the three things the README leaves open: how a run is checkpointed and resumed in a new process, what the SQLite-backed SDK actually gives you over the raw binary, and what happens to a run when a host call fails mid-flight.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. ThousandBirdsInc/chidori on GitHub