Back to search
Kyoko
SkillGitHub
π¨ Kyoko is the all-in-one, fully local tool for debugging and improving your AI agents.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/kayba-ai--kyoko)HTML
<a href="/listings/kayba-ai--kyoko"><img src="/api/listings/kayba-ai--kyoko/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 234 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <img src="docs/assets/kyoko-demo.gif" alt="Kyoko" width="100%" />
- # Kyoko
- [](https://github.com/kayba-ai/kyoko)
- [](https://kayba.ai)
- [](https://discord.gg/mqCqH7sTyK)
- [](https://twitter.com/kaybaai)
- [](https://www.python.org/downloads/)
- [](LICENSE)
- **Kyoko is a fully local system for measuring, debugging, and improving AI
- agents.**
- **Add telemetry, run your agent.** Kyoko shows where performance breaks across
- runs. It groups recurring failures into evidence-backed issues, lets Codex or
- Claude Code draft fixes, and only applies changes after checks and evals pass.
- **Built around the manual dev workflow.** Inspect traces, understand the
- failure, patch the prompt, context, or harness, rerun evals, and decide what
- ships. Kyoko makes that workflow repeatable while keeping you in control.
- **Local by default.** Traces, issues, proposals, evals, database, and dashboard
- stay on your machine.
- **Works with your existing coding-agent subscription.** Kyoko can use the Codex
- or Claude Code CLI you already have, so there is no separate Kyoko model API key
- or hosted service.
- <img src="docs/assets/kyoko-dashboard-overview.png" alt="Kyoko dashboard overview" width="100%" />
- ## 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
- ```text
- βββββββββββββββββββ βββββββββββββββββββ
- β 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.
- <img src="docs/assets/kyoko-dashboard-issues.png" alt="Kyoko issues review queue" width="90%" />
- ## Quick demo
- Try Kyoko without wiring up an agent. The demo creates a local database, loads
- bundled fixture runs, and serves the dashboard.
- ```bash
- 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](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.
- ## Get started
- From the root of your agent project (e.g. the repo of your AI agent, Hermes or
- Openclaw), needs Python 3.12+:
- ```bash
- pipx install kyoko
- kyoko project-bootstrap
- kyoko serve
- ```
- Open [http://127.0.0.1:8765](http://127.0.0.1:8765). `pip install kyoko` and
- `uv tool install kyoko` work too; see [docs/INSTALL.md](docs/INSTALL.md).
- Bootstrap writes a local `.kyoko/` workspace: database, scaffolds, MCP config,
- and operator presets. Every later `kyoko` command finds that database
- automatically, so no `--db` flags are needed inside your project.
- **Then wire up telemetry.** This is the step that makes everything else work:
- Kyoko can only find and fix what it can see. The easiest way is to let your
- coding agent do the wiring:
- ```bash
- kyoko install-skill # then run /kyoko-instrument in your coding agent
- ```
- This installs the bundled `/kyoko-instrument` skill into `.claude/skills/` and
- `.agents/skills/`, where Claude Code and Codex pick it up automatically; for
- Cursor or other agents, `kyoko install-skill --print` prints the same playbook
- to paste in.
- The skill finds your agent's entry point, records one real run, and verifies
- it shows up in Kyoko.
- To connect your agent over MCP instead, or to wire telemetry by hand (Python
- or TypeScript SDK, OTLP, importers), see
- [Getting Started](docs/GETTING_STARTED.md).
- ## 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](docs/INTEGRATIONS.md) and
- [examples/README.md](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](docs/SECURITY.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
- ## Documentation
- - [Getting Started](docs/GETTING_STARTED.md): demo, project bootstrap,
- telemetry, inspection, and the repair loop.
- - [Install](docs/INSTALL.md): install paths, verification, data location, and
- common setup fixes.
- - [Integrations](docs/INTEGRATIONS.md): source adapters, replay adapters,
- operator agents, MCP, and SDKs.
- - [CLI Reference](docs/CLI.md): grouped command reference.
- - [Architecture](docs/ARCHITECTURE.md): runtime model, data model, and the gate.
- - [Security](docs/SECURITY.md): local data, loopback serving, tokens,
- redaction, and write boundaries.
- - [Scope](docs/SCOPE.md): what v0 is and is not.
- - [Development](docs/DEVELOPMENT.md): 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](CONTRIBUTING.md) for
- local setup, the test and validation gates, and how to submit a change. To
- report a security vulnerability, follow [SECURITY.md](SECURITY.md) rather than
- opening a public issue.
- ## Repository layout
- ```text
- 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](LICENSE).
- ---
- <div align="center">
- **Built by [Kayba](https://kayba.ai) and the open-source community.**
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.