kitaru

Traces you can run, not just read.

Kitaru (来る, "to arrive") gives you replay-based evals for AI agents. Record or import production runs as sessions, replay them against your next model, prompt, or code change, and see what improved and what broke before you ship. Open source, self-hosted, Python and TypeScript. From the team behind ZenML.

Docs · Guided Tour · Get Started · Roadmap · Community

🎯 Why

Your agent has already been tested thousands of times in production. Most of that evidence is sitting in a trace store as something you can read but not run. Then you change a prompt, swap a model, or refactor a tool, and the first strong signal comes from a user who found the regression.

Kitaru turns that history into something you can test:

Every run becomes a session. Wrap your agent once, or import the traces you already collect from Langfuse, LangSmith, Braintrust, Logfire, or Arize Phoenix. Your trace store stays your system of record.
Replay re-executes your code. Your real agent runs again, with tool calls answered from the recording, so no card gets refunded twice. An unchanged replay gives you the faithful baseline; a forked replay shows the effect of one change.
Evaluation starts with human judgment. Your coding assistant reviews the sessions that matter, interviews you against the evidence, and pins your answers to exact trace locations. Those judgments calibrate evaluators, cohorts freeze the population, and experiments replay the cohort against your change before it ships.

⚡ Get started

1. Install and log in. The local server is FastAPI + Postgres, and kitaru login --local provisions it with 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 Kitaru: skills teach the method, and the MCP server gives your assistant 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.

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, Logfire, or Arize Phoenix, or record with an adapter: one wrapper, no rewrite.

4. Let your assistant drive the loop. Open the repo in Claude Code, Codex, or Cursor. On the template, take the guided tour:

Use kitaru-guided-tour to walk me through Kitaru on the returns-agent template. I am new; explain each step as we go, and ask before anything paid or live.

On your own agent, run the investigation:

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 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 handles the investigation work. The tutorial walks the same loop on the template, step by step.

🔌 Languages and frameworks

Python and TypeScript SDKs talk to the same server. Adapters ship for:

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 with help from an agent skill, or build a small adapter.

🔒 Self-hosted, by design

One server runs on your infrastructure, with 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 checked-in traces to try the method on
Import your traces	Langfuse, LangSmith, Braintrust, Logfire, Arize Phoenix, or any format
Build a regression suite	Replay production traffic against a change and gate it 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

Apache 2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kitaru-0.22.2.tar.gz (4.3 MB view details)

Uploaded Aug 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

kitaru-0.22.2-py3-none-any.whl (2.7 MB view details)

Uploaded Aug 20, 2026 Python 3

File details

Details for the file kitaru-0.22.2.tar.gz.

File metadata

Download URL: kitaru-0.22.2.tar.gz
Upload date: Aug 20, 2026
Size: 4.3 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for kitaru-0.22.2.tar.gz
Algorithm	Hash digest
SHA256	`b73c9ad0198f42e363d6b60a75337b4be9141ec3fd9c320f1321f77079d7c630`
MD5	`b06836b4fbc8ce63ef1cab6f35738a66`
BLAKE2b-256	`ab0fc59845fc53caaa9349486924196ba7e180d306d2aa939470c593e8c2ff6b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for kitaru-0.22.2.tar.gz:

Publisher: release.yml on zenml-io/kitaru

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: kitaru-0.22.2.tar.gz
- Subject digest: b73c9ad0198f42e363d6b60a75337b4be9141ec3fd9c320f1321f77079d7c630
- Sigstore transparency entry: 2532897803
- Sigstore integration time: Aug 20, 2026
Source repository:
- Permalink: zenml-io/kitaru@241099ae4ab122eb8260a7de4c060f169c1fad47
- Branch / Tag: refs/tags/python/kitaru/v0.22.2
- Owner: https://github.com/zenml-io
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@241099ae4ab122eb8260a7de4c060f169c1fad47
- Trigger Event: push