kyoko 0.1.1

Local-first repair loop for debugging and improving AI agents.

Kyoko

Kyoko is a fully local system for debugging and improving agents with measured, gated fixes.

Kyoko captures what your agent actually did, finds recurring failures, turns them into evidence-backed issues, drafts fixes, and tests them by rerunning the failing trace, running deterministic checks, and comparing eval results before applying them.

It is built for the way developers already debug agents: inspect the run, understand the failure, decide what to fix, test the change, then ship it. You can review every step manually, or automate the parts that pass the gate.

Everything stays local by default: traces, issues, proposals, evals, database, and dashboard. For analysis and fix drafting, Kyoko can use the coding-agent CLI you already have, like Codex or Claude Code, so there is no separate Kyoko model API key or hosted service.

Why Kyoko

• Finds the failures that repeat across runs. Kyoko looks across runs, groups recurring problems into evidence-backed issues, and shows where each one happened.
• Turns issues into fixes. Accepted issues become proposed changes to your agent context, skills, or harness.
• Measures whether fixes worked. Kyoko reruns failing traces, runs deterministic checks, and compares eval results before applying a fix.
• Keeps the developer in control. Review every issue, proposal, and apply decision manually, or automate only the parts that pass the gate.
• Uses the tools you already have. Codex, Claude Code, OpenClaw, Hermes, or a generic command can analyze evidence and draft fixes through existing CLI auth.
• Runs locally by default. SQLite, loopback dashboard, local traces, local proposals, and explicit external calls.
• Connects to real agent stacks. OTLP/GenAI, Python and TypeScript SDKs, importers, JSON CLI, dashboard, and MCP.

The loop

        ┌─────────────────┐           ┌─────────────────┐
        │  1. Analyse     │ ───────▶ │  2. Issues      │
        │  traces in      │           │  recurring      │
        │                 │           │  failures       │
        └─────────────────┘           └─────────────────┘
                 ▲                            │
                 │ measure                    │ accept
                 │                            ▼
        ┌─────────────────┐  ┌──────┐ ┌─────────────────┐
        │  4. Evals       │◀─┤ gate ├─│  3. Proposals   │
        │  failure rate   │  └──────┘ │  fixes          │
        │                 │   apply   │                 │
        └─────────────────┘           └─────────────────┘

Kyoko keeps the repair loop explicit. Every step creates something you can inspect in the dashboard or CLI.

1. Analyse: Kyoko reads real traces from your agent and looks across runs for repeated behavior: tool mistakes, missing context, policy drift, brittle routing, bad handoffs, or eval failures.
2. Issues: recurring failures become evidence-backed issues with category, severity, occurrence count, and links to the spans where they happened.
3. Proposals: accepted issues become concrete fixes to your agent context, skills, evals, or harness. The fix stays reviewable before it can apply.
4. Evals: Kyoko reruns failing traces, runs deterministic checks, and compares eval results so the gate can decide whether the fix worked.

The gate is the control point. It applies a fix only when checks, replay evidence, autonomy policy, and human locks allow it.

Run it your way. The same loop, the same gate. You pick the autonomy level:

• Human-in-the-loop: Kyoko surfaces issues and drafts fixes, and you review and approve each change before it applies.
• Fully autonomous: the policy auto-applies any change that clears replay, evals, and human locks, and parks anything that doesn't for you to look at.

Quick demo

Try Kyoko without wiring up an agent. The demo creates a local database, loads bundled fixture runs, and serves the dashboard.

pipx install kyoko
kyoko demo --db /tmp/kyoko-demo.db --json
kyoko serve --db /tmp/kyoko-demo.db

Open http://127.0.0.1:8765.

Requires Python 3.12 or newer. No live model, framework adapter, or replay server is needed for the demo.

Install options

pipx install kyoko

pip install kyoko and uv tool install kyoko work too.

To run from source:

git clone https://github.com/kayba-ai/kyoko.git
cd kyoko
python3 -m pip install -e .

See docs/INSTALL.md for uv, editable installs, the installer script, upgrades, and common setup fixes.

Use it in your project

Bootstrap Kyoko from the root of an agent project:

kyoko project-bootstrap \
  --project-dir . \
  --profile-name my-agent \
  --source-framework generic-python \
  --replay-framework generic-python \
  --mcp-target codex

project-bootstrap writes a local .kyoko/ workspace: database, source/replay scaffolds, MCP config, operator presets, and .kyoko/NEXT_STEPS.md.

Then check readiness and start the dashboard:

kyoko doctor --db .kyoko/kyoko.db --safe-smokes --json
kyoko serve --db .kyoko/kyoko.db

Then bring your agent's telemetry into Kyoko. The easiest way is to let your coding agent wire it for you:

kyoko install-skill   # then run /kyoko-instrument in Claude Code, Cursor, or Codex

The /kyoko-instrument skill finds your agent's entry point, records one real run, and verifies it shows up in Kyoko. You can also point telemetry at Kyoko by hand with the Python or TypeScript SDK, a generated adapter, or an importer. See Getting Started for the full walkthrough.

What you get

• Run capture: Python SDK, TypeScript SDK, generated source adapters, OTLP/GenAI JSON, Hermes import, and OpenClaw import.
• Issue queue: recurring failures grouped into evidence-backed issues with category, severity, occurrence count, and span links.
• Fix proposals: accepted issues become validated LearningProposal records for context, skills, evals, or harness changes.
• Verification: bounded replay, deterministic checks, and eval comparison before a fix can apply.
• Operator path: Codex, Claude, OpenClaw, Hermes, or a generic command can analyze evidence and draft fixes through existing CLI auth.
• Control surfaces: local dashboard, JSON-everywhere CLI, and stdio MCP server, all sharing the same gated apply path.

Area	Supported paths
Source telemetry	Python SDK, TypeScript SDK, generated source adapters, OTLP/GenAI JSON, Hermes import, OpenClaw import
Replay	External replay commands, managed HTTP replay servers, generated replay scaffolds
Operator agents	Codex, Claude Code, OpenClaw, Hermes, generic command adapters, local presets
Agent clients	Dashboard, JSON CLI, stdio MCP server
Framework scaffolds	Generic Python/TypeScript, LangGraph, Pydantic AI, OpenAI Agents, CrewAI, Hermes, OpenClaw, AI SDK

See docs/INTEGRATIONS.md and examples/README.md.

The gate and local boundary

Every behavior-changing path (operator output, imports, MCP tools, and kyoko improve) flows through one gate:

1. Validate the structured proposal.
2. Resolve the evidence it references.
3. Generate or select checks.
4. Run bounded replay and deterministic checks.
5. Evaluate the autonomy policy.
6. Enforce human locks on protected targets.
7. Apply context or harness changes only if the gate allows it.

Operator agents can analyze evidence and draft fixes; they do not directly mutate Kyoko state. Context writes update Kyoko-managed skills and delivery rules. Harness writes create reviewable patch transactions against an explicit workspace root.

Replay server URLs are loopback-only unless you pass --allow-remote-server. Evidence exported to prompts, MCP, API, or bundles is redacted by default. See docs/SECURITY.md and docs/ARCHITECTURE.md.

Documentation

• Getting Started: demo, project bootstrap, telemetry, inspection, and the repair loop.
• Install: install paths, verification, data location, and common setup fixes.
• Integrations: source adapters, replay adapters, operator agents, MCP, and SDKs.
• CLI Reference: grouped command reference.
• Architecture: runtime model, data model, and the gate.
• Security: local data, loopback serving, tokens, redaction, and write boundaries.
• Scope: what v0 is and is not.
• Development: tests, dashboard bundle, release smoke, and contract artifacts.

Specs, schemas, fixtures, and design decisions live under docs/ as reference contracts.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for local setup, the test and validation gates, and how to submit a change. To report a security vulnerability, follow SECURITY.md rather than opening a public issue.

Repository layout

kyoko/              Python import package, CLI runtime, dashboard/API, bundled assets
frontend/           React/Vite dashboard source
sdk/typescript/     Dependency-free TypeScript telemetry SDK
examples/           Source and replay hook examples
scripts/            Installer, release smoke, fixture and artifact helpers
tests/              Python unittest suite and CLI contract tests
docs/               User docs plus specs, schemas, fixtures, and decisions

License

Apache-2.0. See LICENSE.

---

Built by Kayba and the open-source community.