Skip to content
Back to search

Kyoko

πŸ”¨ 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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kayba-ai--kyoko/badge.svg)](/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)

  1. <img src="docs/assets/kyoko-demo.gif" alt="Kyoko" width="100%" />
  2. # Kyoko
  3. [![GitHub stars](https://img.shields.io/github/stars/kayba-ai/kyoko?style=social)](https://github.com/kayba-ai/kyoko)
  4. [![Kayba Website](https://img.shields.io/badge/kayba.ai-6B8BA8?style=flat&logo=data:image/png;base64,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&logoColor=white)](https://kayba.ai)
  5. [![Discord](https://img.shields.io/discord/1429935408145236131?label=Discord&logo=discord&logoColor=white&color=5865F2)](https://discord.gg/mqCqH7sTyK)
  6. [![Twitter Follow](https://img.shields.io/twitter/follow/kaybaai?style=social)](https://twitter.com/kaybaai)
  7. [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
  8. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
  9. **Kyoko is a fully local system for measuring, debugging, and improving AI
  10. agents.**
  11. **Add telemetry, run your agent.** Kyoko shows where performance breaks across
  12. runs. It groups recurring failures into evidence-backed issues, lets Codex or
  13. Claude Code draft fixes, and only applies changes after checks and evals pass.
  14. **Built around the manual dev workflow.** Inspect traces, understand the
  15. failure, patch the prompt, context, or harness, rerun evals, and decide what
  16. ships. Kyoko makes that workflow repeatable while keeping you in control.
  17. **Local by default.** Traces, issues, proposals, evals, database, and dashboard
  18. stay on your machine.
  19. **Works with your existing coding-agent subscription.** Kyoko can use the Codex
  20. or Claude Code CLI you already have, so there is no separate Kyoko model API key
  21. or hosted service.
  22. <img src="docs/assets/kyoko-dashboard-overview.png" alt="Kyoko dashboard overview" width="100%" />
  23. ## Why Kyoko
  24. - **Finds the failures that repeat across runs.** Kyoko looks across runs, groups recurring problems into evidence-backed issues, and shows where each one happened.
  25. - **Turns issues into fixes.** Accepted issues become proposed changes to your agent context, skills, or harness.
  26. - **Measures whether fixes worked.** Kyoko reruns failing traces, runs deterministic checks, and compares eval results before applying a fix.
  27. - **Keeps the developer in control.** Review every issue, proposal, and apply decision manually, or automate only the parts that pass the gate.
  28. - **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.
  29. - **Runs locally by default.** SQLite, loopback dashboard, local traces, local proposals, and explicit external calls.
  30. - **Connects to real agent stacks.** OTLP/GenAI, Python and TypeScript SDKs, importers, JSON CLI, dashboard, and MCP.
  31. ## The loop
  32. ```text
  33. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  34. β”‚ 1. Analyse β”‚ ───────▢ β”‚ 2. Issues β”‚
  35. β”‚ traces in β”‚ β”‚ recurring β”‚
  36. β”‚ β”‚ β”‚ failures β”‚
  37. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  38. β–² β”‚
  39. β”‚ measure β”‚ accept
  40. β”‚ β–Ό
  41. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  42. β”‚ 4. Evals │◀── gate β”œβ”€β”‚ 3. Proposals β”‚
  43. β”‚ failure rate β”‚ β””β”€β”€β”€β”€β”€β”€β”˜ β”‚ fixes β”‚
  44. β”‚ β”‚ apply β”‚ β”‚
  45. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  46. ```
  47. Kyoko keeps the repair loop explicit. Every step creates something you can
  48. inspect in the dashboard or CLI.
  49. 1. **Analyse:** Kyoko reads real traces from your agent and looks across runs
  50. for repeated behavior: tool mistakes, missing context, policy drift, brittle
  51. routing, bad handoffs, or eval failures.
  52. 2. **Issues:** recurring failures become evidence-backed issues with category,
  53. severity, occurrence count, and links to the spans where they happened.
  54. 3. **Proposals:** accepted issues become concrete fixes to your agent context,
  55. skills, evals, or harness. The fix stays reviewable before it can apply.
  56. 4. **Evals:** Kyoko reruns failing traces, runs deterministic checks, and
  57. compares eval results so the gate can decide whether the fix worked.
  58. The **gate** is the control point. It applies a fix only when checks, replay
  59. evidence, autonomy policy, and human locks allow it.
  60. **Run it your way.** The same loop, the same gate. You pick the autonomy level:
  61. - **Human-in-the-loop:** Kyoko surfaces issues and drafts fixes, and you review
  62. and approve each change before it applies.
  63. - **Fully autonomous:** the policy auto-applies any change that clears replay,
  64. evals, and human locks, and parks anything that doesn't for you to look at.
  65. <img src="docs/assets/kyoko-dashboard-issues.png" alt="Kyoko issues review queue" width="90%" />
  66. ## Quick demo
  67. Try Kyoko without wiring up an agent. The demo creates a local database, loads
  68. bundled fixture runs, and serves the dashboard.
  69. ```bash
  70. pipx install kyoko
  71. kyoko demo --db /tmp/kyoko-demo.db --json
  72. kyoko serve --db /tmp/kyoko-demo.db
  73. ```
  74. Open [http://127.0.0.1:8765](http://127.0.0.1:8765).
  75. Requires Python 3.12 or newer. No live model, framework adapter, or replay
  76. server is needed for the demo.
  77. ## Get started
  78. From the root of your agent project (e.g. the repo of your AI agent, Hermes or
  79. Openclaw), needs Python 3.12+:
  80. ```bash
  81. pipx install kyoko
  82. kyoko project-bootstrap
  83. kyoko serve
  84. ```
  85. Open [http://127.0.0.1:8765](http://127.0.0.1:8765). `pip install kyoko` and
  86. `uv tool install kyoko` work too; see [docs/INSTALL.md](docs/INSTALL.md).
  87. Bootstrap writes a local `.kyoko/` workspace: database, scaffolds, MCP config,
  88. and operator presets. Every later `kyoko` command finds that database
  89. automatically, so no `--db` flags are needed inside your project.
  90. **Then wire up telemetry.** This is the step that makes everything else work:
  91. Kyoko can only find and fix what it can see. The easiest way is to let your
  92. coding agent do the wiring:
  93. ```bash
  94. kyoko install-skill # then run /kyoko-instrument in your coding agent
  95. ```
  96. This installs the bundled `/kyoko-instrument` skill into `.claude/skills/` and
  97. `.agents/skills/`, where Claude Code and Codex pick it up automatically; for
  98. Cursor or other agents, `kyoko install-skill --print` prints the same playbook
  99. to paste in.
  100. The skill finds your agent's entry point, records one real run, and verifies
  101. it shows up in Kyoko.
  102. To connect your agent over MCP instead, or to wire telemetry by hand (Python
  103. or TypeScript SDK, OTLP, importers), see
  104. [Getting Started](docs/GETTING_STARTED.md).
  105. ## What you get
  106. - **Run capture:** Python SDK, TypeScript SDK, generated source adapters,
  107. OTLP/GenAI JSON, Hermes import, and OpenClaw import.
  108. - **Issue queue:** recurring failures grouped into evidence-backed issues with
  109. category, severity, occurrence count, and span links.
  110. - **Fix proposals:** accepted issues become validated `LearningProposal`
  111. records for context, skills, evals, or harness changes.
  112. - **Verification:** bounded replay, deterministic checks, and eval comparison
  113. before a fix can apply.
  114. - **Operator path:** Codex, Claude, OpenClaw, Hermes, or a generic command can
  115. analyze evidence and draft fixes through existing CLI auth.
  116. - **Control surfaces:** local dashboard, JSON-everywhere CLI, and stdio MCP
  117. server, all sharing the same gated apply path.
  118. | Area | Supported paths |
  119. | --- | --- |
  120. | Source telemetry | Python SDK, TypeScript SDK, generated source adapters, OTLP/GenAI JSON, Hermes import, OpenClaw import |
  121. | Replay | External replay commands, managed HTTP replay servers, generated replay scaffolds |
  122. | Operator agents | Codex, Claude Code, OpenClaw, Hermes, generic command adapters, local presets |
  123. | Agent clients | Dashboard, JSON CLI, stdio MCP server |
  124. | Framework scaffolds | Generic Python/TypeScript, LangGraph, Pydantic AI, OpenAI Agents, CrewAI, Hermes, OpenClaw, AI SDK |
  125. See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) and
  126. [examples/README.md](examples/README.md).
  127. ## The gate and local boundary
  128. Every behavior-changing path (operator output, imports, MCP tools, and
  129. `kyoko improve`) flows through one gate:
  130. 1. Validate the structured proposal.
  131. 2. Resolve the evidence it references.
  132. 3. Generate or select checks.
  133. 4. Run bounded replay and deterministic checks.
  134. 5. Evaluate the autonomy policy.
  135. 6. Enforce human locks on protected targets.
  136. 7. Apply context or harness changes **only** if the gate allows it.
  137. Operator agents can analyze evidence and draft fixes; they do not directly
  138. mutate Kyoko state. Context writes update Kyoko-managed skills and delivery
  139. rules. Harness writes create reviewable patch transactions against an explicit
  140. workspace root.
  141. Replay server URLs are loopback-only unless you pass `--allow-remote-server`.
  142. Evidence exported to prompts, MCP, API, or bundles is redacted by default. See
  143. [docs/SECURITY.md](docs/SECURITY.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  144. ## Documentation
  145. - [Getting Started](docs/GETTING_STARTED.md): demo, project bootstrap,
  146. telemetry, inspection, and the repair loop.
  147. - [Install](docs/INSTALL.md): install paths, verification, data location, and
  148. common setup fixes.
  149. - [Integrations](docs/INTEGRATIONS.md): source adapters, replay adapters,
  150. operator agents, MCP, and SDKs.
  151. - [CLI Reference](docs/CLI.md): grouped command reference.
  152. - [Architecture](docs/ARCHITECTURE.md): runtime model, data model, and the gate.
  153. - [Security](docs/SECURITY.md): local data, loopback serving, tokens,
  154. redaction, and write boundaries.
  155. - [Scope](docs/SCOPE.md): what v0 is and is not.
  156. - [Development](docs/DEVELOPMENT.md): tests, dashboard bundle, release smoke,
  157. and contract artifacts.
  158. Specs, schemas, fixtures, and design decisions live under `docs/` as reference
  159. contracts.
  160. ## Contributing
  161. Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
  162. local setup, the test and validation gates, and how to submit a change. To
  163. report a security vulnerability, follow [SECURITY.md](SECURITY.md) rather than
  164. opening a public issue.
  165. ## Repository layout
  166. ```text
  167. kyoko/ Python import package, CLI runtime, dashboard/API, bundled assets
  168. frontend/ React/Vite dashboard source
  169. sdk/typescript/ Dependency-free TypeScript telemetry SDK
  170. examples/ Source and replay hook examples
  171. scripts/ Installer, release smoke, fixture and artifact helpers
  172. tests/ Python unittest suite and CLI contract tests
  173. docs/ User docs plus specs, schemas, fixtures, and decisions
  174. ```
  175. ## License
  176. Apache-2.0. See [LICENSE](LICENSE).
  177. ---
  178. <div align="center">
  179. **Built by [Kayba](https://kayba.ai) and the open-source community.**
  180. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.