Traces you can run, not just read.
Kitaru (来る, "to arrive") is replay-based evals for AI agents. It turns your agent's production traces into a regression suite: record or import every run, replay it against your next change, and see what improved and what broke before you ship. Open source, self-hosted, Python and TypeScript. From the team behind ZenML.
Docs · Get Started · Roadmap · Community
🎯 Why
Your agent has already been tested thousands of times, in production. Every one of those runs is sitting in a trace store as a transcript you can read but not run. So you change a prompt, swap a model, refactor a tool, and find out whether it broke from an angry user.
Kitaru makes those traces runnable:
- Every run is a recording. Wrap your agent once, or import the traces you already collect from Langfuse, LangSmith, Braintrust, or Logfire. Your trace store stays your system of record.
- Replay is re-execution. Your real code runs again, tool calls answered from the recording, so no card gets refunded twice. Unchanged, the replay reproduces the original; forked, the diff you see is your change.
- Improvement is measured, not vibed. Your coding assistant interviews you over the sessions that matter, your judgments calibrate evaluators, and experiments replay a frozen cohort against your change: what improved, what regressed, before it ships. The cohort that caught a failure becomes the regression gate that keeps it caught.
⚡ Get started
1. Install and log in. The local server (FastAPI + Postgres) provisions itself in Docker:
uv add "kitaru[cli,worker,mcp]" kitaru-pydantic-ai # or: pip install
kitaru login --local # or: kitaru login <your-team-url>
2. Make your coding assistant Kitaru-capable. This is the intended way to drive it: skills teach it the method, the MCP server gives it bounded operations.
npx skills add zenml-io/kitaru-skills
{
"mcpServers": {
"kitaru": {
"command": "uv",
"args": ["run", "kitaru-mcp", "--server", "http://localhost:8000", "--mode", "standard"]
}
}
}
3. Get an agent with traces. The fastest way to feel the loop is the template: a ready PydanticAI agent with checked-in Langfuse traces to investigate.
git clone https://github.com/zenml-io/kitaru-template
cd kitaru-template # its README has the setup and import commands
Already have an agent in production? Import its traces from Langfuse, LangSmith, Braintrust, or Logfire, or record with an adapter: one wrapper, no rewrite.
4. Drive results. Open the repo (the template or your own agent) in Claude Code, Codex, or Cursor and ask:
Use kitaru-investigation to investigate this agent and help me test one meaningful improvement. Show me the recorded evidence before asking for a judgment, and ask before creating resources or starting paid replay.
The assistant sweeps the sessions with the built-in deterministic evaluators, interviews you over the ones that matter, drafts the evaluator, runs the experiment, and reports what improved and what regressed. You judge; it does the legwork. The tutorial walks the same loop on the template, step by step.
🔌 Languages and frameworks
Python and TypeScript SDKs, one server. Adapters:
| Framework | Language | Package |
|---|---|---|
| PydanticAI | Python | kitaru-pydantic-ai |
| LangGraph (also LangChain agents, Deep Agents) | Python | kitaru-langgraph |
| OpenAI Agents SDK | Python | kitaru-openai-agents |
| Mastra | TypeScript | @zenml-io/kitaru-mastra |
| Vercel AI SDK | TypeScript | @zenml-io/kitaru-vercel-ai |
Anything else still works: import your traces, write a one-page custom importer (an agent skill drafts it), or build a small adapter.
🔒 Self-hosted, by design
One server on your infrastructure (Docker image and Helm chart included), and no user code executes on it. Replays, imports, and evaluations run on workers in your environment: your virtualenv, your credentials, your network. Traces never have to leave your systems. Apache 2.0, no mandatory SaaS control plane.
📚 Learn more
| Resource | Description |
|---|---|
| Documentation | Concepts, guides, and the quickstart |
| Quickstart | From an agent in production to your first replay-backed decision |
| Set up your coding agent | Install the MCP server and the agent skills |
| Kitaru template | A ready agent and traces to try the method on |
| Import your traces | Langfuse, LangSmith, Braintrust, Logfire, or any format |
| Build a regression suite | Production traffic as your test suite, gated in CI |
| Deploy Kitaru | Self-host for your team |
🤝 Contributing
We welcome contributions! See CONTRIBUTING.md for development setup, code style, and how to submit changes. The default branch is develop; all PRs should target it.
💬 Community and support
- Slack community: ask questions, share ideas
- Report a bug: goes straight to GitHub issues
- support@kitaru.ai: when email is easier
Hit something broken? Any of the three reaches a human; an issue with a session ID attached gets fixed fastest.
📄 License
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file kitaru-0.22.0.tar.gz.
File metadata
- Download URL: kitaru-0.22.0.tar.gz
- Upload date:
- Size: 4.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
29640832cef45521875a69f8a1181b8d57f222532afc6346f15b92e228ff2c55
|
|
| MD5 |
87a5ade3ffb7682ebcf98dceb92a5214
|
|
| BLAKE2b-256 |
cd9002a9598df1fd80b8fd5209583899c83b5ea58bcadff1d8f0bd0200fd42e5
|
Provenance
The following attestation bundles were made for kitaru-0.22.0.tar.gz:
Publisher:
release.yml on zenml-io/kitaru
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
kitaru-0.22.0.tar.gz -
Subject digest:
29640832cef45521875a69f8a1181b8d57f222532afc6346f15b92e228ff2c55 - Sigstore transparency entry: 2501192371
- Sigstore integration time:
-
Permalink:
zenml-io/kitaru@e314ba89aefdd0c081e381e8a2b5b8070712741d -
Branch / Tag:
refs/tags/python/kitaru/v0.22.0 - Owner: https://github.com/zenml-io
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@e314ba89aefdd0c081e381e8a2b5b8070712741d -
Trigger Event:
push
-
Statement type:
File details
Details for the file kitaru-0.22.0-py3-none-any.whl.
File metadata
- Download URL: kitaru-0.22.0-py3-none-any.whl
- Upload date:
- Size: 2.7 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c00c3a98466835f075a147c0d793061cbf74bd77d03eb8206c923f1b6af40ca5
|
|
| MD5 |
9d8037b11cb8557047d2aca4032fa3bd
|
|
| BLAKE2b-256 |
ba3d010b3e1bccae1732f99bd4d53fbff71c9b91f15d1715b4e63934c63a50a9
|
Provenance
The following attestation bundles were made for kitaru-0.22.0-py3-none-any.whl:
Publisher:
release.yml on zenml-io/kitaru
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
kitaru-0.22.0-py3-none-any.whl -
Subject digest:
c00c3a98466835f075a147c0d793061cbf74bd77d03eb8206c923f1b6af40ca5 - Sigstore transparency entry: 2501192383
- Sigstore integration time:
-
Permalink:
zenml-io/kitaru@e314ba89aefdd0c081e381e8a2b5b8070712741d -
Branch / Tag:
refs/tags/python/kitaru/v0.22.0 - Owner: https://github.com/zenml-io
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@e314ba89aefdd0c081e381e8a2b5b8070712741d -
Trigger Event:
push
-
Statement type:
