{
  "markdown": "# Koma\n\n### Miko: required Skill checks for Claude Code and Codex\n\nKeep reminding your coding agent to read a required Skill before editing?\n**Miko** checks for observable Skill reads before protected edits. When evidence\nis missing, it pauses the action and tells the agent what to load before retrying.\nIt runs locally, makes no LLM calls, and is free and open source.\n\nThe current focus is **Claude Code and Codex CLI**. Miko is part of Koma;\nthe separate **Gate, Scout, and Core** packages cover AI application input,\nrequest limits, and retrieval. You do not need them to use Miko.\n\n```bash\nnpm install -D koma-miko@alpha\nnpx koma-miko init --host claude\n```\n\nEdit the generated `miko.json` to name your project's Skills and protected paths,\nthen start a new Claude Code session.\n**Using Codex?** Follow the [Codex setup and one-time Hook review](./packages/koma-miko/README.md#codex-setup).\nCodex CLI is a Technical Preview; Desktop requires prior CLI activation.\n\n<p align=\"center\">\n  <img src=\"logo/logobanner.png\" alt=\"Koma\" width=\"600\" />\n</p>\n\n<p align=\"center\">\n  <img alt=\"License\" src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" />\n  <img alt=\"CI\" src=\"https://github.com/swnotmetal/Project-Koma/actions/workflows/ci.yml/badge.svg\" />\n  <a href=\"https://www.npmjs.com/package/koma-miko\"><img alt=\"koma-miko\" src=\"https://img.shields.io/npm/v/koma-miko/alpha?label=koma-miko%20alpha&color=C25E38&style=flat-square\" /></a>\n  <a href=\"https://www.npmjs.com/package/koma-gate\"><img alt=\"koma-gate\" src=\"https://img.shields.io/npm/v/koma-gate?label=koma-gate&color=3178c6&style=flat-square\" /></a>\n  <a href=\"https://www.npmjs.com/package/koma-scout\"><img alt=\"koma-scout\" src=\"https://img.shields.io/npm/v/koma-scout?label=koma-scout&color=3178c6&style=flat-square\" /></a>\n  <a href=\"https://www.npmjs.com/package/koma-core\"><img alt=\"koma-core\" src=\"https://img.shields.io/npm/v/koma-core?label=koma-core&color=3178c6&style=flat-square\" /></a>\n  <br />\n  <a href=\"https://koma-demo.swbuilds.workers.dev\"><img alt=\"Miko live demo\" src=\"https://img.shields.io/badge/Miko_demo-10--sec_replay-C25E38?style=flat-square\" /></a>\n  <img alt=\"Gate benchmark\" src=\"https://img.shields.io/badge/Gate_eval-98.8%25_recall_0%25_FPR-6e3abe?style=flat-square\" />\n  <img alt=\"koma-gate downloads\" src=\"https://img.shields.io/npm/dt/koma-gate?label=gate%20downloads&color=blue&style=flat-square\" />\n  <a href=\"https://glama.ai/mcp/servers/swnotmetal/Project-Koma\"><img alt=\"MCP server\" src=\"https://glama.ai/mcp/servers/swnotmetal/Project-Koma/badges/score.svg\" /></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"./README.zh-CN.md\">中文版</a>\n</p>\n\n<p align=\"center\">\n  <strong>▶ <a href=\"https://koma-demo.swbuilds.workers.dev\">Try Miko's guided terminal replay</a></strong> — plus Gate, Scout &amp; Core, no signup.\n</p>\n\n---\n\n### Miko for Claude Code and Codex\n\n<p align=\"center\">\n  <img src=\"packages/koma-miko/assets/miko-lockup.png\" alt=\"Koma Miko\" width=\"420\" />\n</p>\n\nCoding agents can say they loaded a required Skill or ran a test. Miko does not\ntreat that claim as evidence. At supported local host Hooks, it compares\nobserved Skill loads, reference reads, tool actions, and completion checks with\na project-owned `miko.json`.\n\nIf an agent tries to edit before satisfying the spec, Miko can return a denial\nand a short recovery instruction. It cannot inspect hidden model context, prove\nthat a model understood a Skill, or verify events the host never exposes.\nIn Claude CLI guided mode, a genuine scope exception opens one visible Miko\nchoice: allow that exact retry once, or keep the current boundary.\n\n```bash\nnpx --yes koma-miko@alpha demo       # deterministic; no API key\nnpx --yes koma-miko@alpha probe --host claude  # isolated adapter check; no model\nnpx koma-miko init --host claude     # after local installation\n```\n\n> **Codex CLI is a Technical Preview; Codex Desktop requires prior CLI\n> activation.** The CLI requires a one-time `/hooks` review before project\n> Hooks run. Miko promotes `enforce` on Codex because the current Hook API\n> cannot open a native `REVIEW` choice; review therefore degrades to a\n> recoverable pause/deny. Desktop-only onboarding is not a supported alpha\n> path. An offline `probe` proves adapter logic, not live Hook activation.\n\n[Miko README →](./packages/koma-miko/README.md) ·\n[Current host support →](./packages/koma-miko/README.md#host-support) ·\n[10-second web replay →](https://koma-demo.swbuilds.workers.dev)\n\n[Miko replay GIF](./docs/assets/miko-terminal-demo.gif) ·\n[Still image](./docs/assets/miko-terminal-demo-poster.png) — browser simulation, not a live host recording.\n\nClaude Code is the primary alpha workflow. Codex CLI has a verified narrow\nrecovery flow with the activation limits above. Gemini is outside active\ndevelopment; Copilot adapter work is paused pending a real tester. Existing\nadapters and their dated results remain available in the\n[adapter documentation](./packages/koma-miko/README.md#other-adapters).\n\n**Why use Miko instead of writing a Hook?** A small native Hook is enough for a\nsingle fixed check. Miko packages project Specs, observed-read tracking,\npost-compaction reload requirements, recovery messages, and completion evidence\nso you can maintain those checks together. Neither approach proves the model\nunderstood the instructions. See [when Miko helps](./packages/koma-miko/README.md#when-to-use-miko).\n\n---\n\n### Four Boundaries\n\n| Boundary | Failure mode | What Koma checks | Package |\n|---|---|---|---|\n| Coding agent | Required Skill or completion check skipped | Host-observed preparation, action scope, and evidence | `koma-miko@alpha` |\n| User → LLM | Prompt injection / jailbreak | Semantic scope before the application model | `koma-gate` |\n| Request perimeter | Audio abuse / flooding | Validation, rate limits, and geo rules | `koma-scout` |\n| Retrieval | Data enumeration / scraping | Split index from content; token-gate retrieval | `koma-core` |\n\nDifferent attacks cross different boundaries. Koma provides a small primitive for each one.\n\n---\n\n### What Koma Is — and Isn't\n\n**Is**: small composable packages · usable independently · explicit failure\nmodes · deterministic checks where the host exposes evidence\n\n**Isn't**: a model · an agent framework · proof that a model understood its\ninstructions · a replacement for authorization · a complete security boundary\nby itself\n\n---\n\n### Benchmarks\n\n#### Miko alpha evaluation\n\nMiko is deterministic, so its useful numbers are verifier cost and end-to-end\nHook behavior—not a generic score for model intelligence.\n\n| Signal | Observed result |\n|---|---|\n| Offline host conformance | Claude, Codex, Gemini, and VS Code Copilot each reproduce `DENY → observed Skill → ALLOW`; ledger fixtures reject prompt/code/tool-response persistence |\n| Local verifier scale | 1,000 Agent Specs: **1.34 ms p95** per action; 10,001 indexed evidence events: **0.0041 ms p95**; restore 1,000 evidence events: **1.52 ms p95** |\n| Claude Code live + hand-test | One 100-Skill / ~20k-context run passed. A natural Chinese request drove a three-file rewrite through 3 Agent Specs and 28 observed events. Separate Haiku 4.5 runs verified visible `Allow once` and `Keep current scope` policy-exception paths |\n| Codex CLI Technical Preview | Fixed live recovery completed `DENY → Skill/reference → edit → COMPLETE`; an interactive CLI 0.152.0 hand-test visibly rendered Miko active, recovered, and COMPLETE. Desktop also enforced after CLI activation, but onboarding and completion visibility remain unsuitable as a primary path |\n| DeepSeek Harness smoke | **3/3** narrow packed-artifact recovery runs passed; 19.425 s mean model phase |\n\nThe scale row is a 2026-08-27 reference run on Node 24.19 / Windows; rerun it\nwith `npm run eval:scale -w koma-miko`. Context tokens never enter the verifier.\nThe paid samples are deliberately small and **do not establish general model,\nlong-context, or editor reliability**. See the\n[scale record](./docs/evals/miko-scale-alpha.md),\n[Claude record](./docs/evals/miko-claude-haiku-alpha.md),\n[host-adapter record](./docs/evals/miko-host-adapters-alpha.md), and\n[DSH record](./docs/evals/miko-dsh-alpha.md).\n\n#### Koma Gate live-model benchmark\n\nI threw **1,769 real prompt-injection attacks** at Koma Gate in fail-closed mode, using real providers — not mock adapters.\n\n| Provider | Recall | Precision | False Positives |\n|----------|:------:|:---------:|:---:|\n| DeepSeek (deepseek-chat) | **98.8%** | **100%** | **0** |\n| Google (gemini-2.5-flash) | 96.2% | **100%** | **0** |\n\n**Chinese attack set**: 100% recall · 100% precision · 0% FPR across 8 categories.\n\n> **Can you break it?** [Open an issue](https://github.com/swnotmetal/Project-Koma/issues) with an attack Koma misses. → [Full methodology](./BENCHMARKS.md)\n\n---\n\n### Application-side quick start: Gate\n\n```ts\nimport { createGeneralKnowledgeGuard } from 'koma-gate';\n\nconst guard = createGeneralKnowledgeGuard({\n  llm: { apiKey: process.env.GEMINI_API_KEY },\n});\n\napp.post('/api/chat', guard.middleware(), async (req, res) => {\n  // Only in-scope requests reach your model\n  res.json({ reply: await chat(req.body.message) });\n});\n```\n\n```bash\ngit clone https://github.com/swnotmetal/Project-Koma\ncd Project-Koma && node demo/server.js\ncurl http://localhost:8080/self-test\n```\n\n---\n\n### Application-Side Packages\n\n**`koma-gate`** — Prompt injection firewall. LLM-based scope classifier that blocks jailbreaks, off-topic requests, and instruction overrides. Supports OpenAI, Anthropic, Google, DeepSeek, and local Ollama models. [README →](./packages/koma-gate/README.md)\n\n[Try Gate in the browser demo →](https://koma-demo.swbuilds.workers.dev)\n\n**`koma-scout`** — Perimeter protection. Rate limiting, audio upload validation, geo allowlisting. Cheap checks before expensive AI work. [README →](./packages/koma-scout/README.md)\n\n<img src=\"logo/scout-diagram.svg\" alt=\"Koma Scout perimeter checks\" width=\"480\" />\n\n**`koma-core`** — Protected RAG storage. Public search index, private content, opaque HKDF-derived tokens. *Discovery is not authorization.* [README →](./packages/koma-core/README.md)\n\n<img src=\"logo/core-diagram.svg\" alt=\"Koma Core split-store\" width=\"480\" />\n\nEach package works standalone. A typical application checks cheap request limits\nwith Scout before Gate classification, then uses Core where protected retrieval\nis needed. See the [architecture map](./ARCHITECTURE_MAP.md).\n\n**Application-side MCP servers** — these belong to Gate and Core, not Miko:\n\n- `koma-gate-mcp` — `classify_input` tool for prompt-injection checks. [README →](./packages/koma-gate-mcp/README.md)\n- `koma-core-mcp` — `search_docs` + `retrieve_doc` for protected RAG retrieval. [README →](./packages/koma-core-mcp/README.md)\n\n```json\n{\n  \"mcpServers\": {\n    \"koma-gate\": { \"command\": \"npx\", \"args\": [\"-y\", \"koma-gate-mcp\"] },\n    \"koma-core\": { \"command\": \"npx\", \"args\": [\"-y\", \"koma-core-mcp\"] }\n  }\n}\n```\n\n---\n\n### Using an agent to set up Miko?\n\nTell it:\n\n> \"Read the Miko README, then help me configure koma-miko for my existing Skills and protected paths. Use the setup for my host and explain any activation step I must complete.\"\n\nFor a coding-agent repository, install Miko and run\n`npx koma-miko init --host claude` or follow the\n[Codex setup](./packages/koma-miko/README.md#codex-setup). Edit the generated\n`miko.json` to name the Skills, paths, and completion evidence that matter to\nthe project. Miko does not install the Skills themselves.\n\nSee [llms.txt](./llms.txt) for documentation entry points. Miko uses host Hooks;\nit does not require an MCP server.\n\n---\n\n### Trust & Safety\n\n- **Minimal dependency surface.** Miko, Gate, and Core have no third-party runtime dependencies; Scout declares Express as a peer.\n- **No model-output execution.** Miko observes host events; Gate, Scout, and Core classify, rate-limit, or store. None executes generated code.\n- **Package-specific failure behavior.** Gate defaults to fail-open and can use\n  `failOpen: false`. Miko follows each Agent Spec's mode; an enforce-mode\n  missing-evidence check denies the applicable action.\n- **CodeQL on every push.** Targets OWASP LLM01.\n- **MIT licensed.**\n\n→ [Security policy](./SECURITY.md) · [Known limitations](./SECURITY-HARDENING.md) · [Contributing](./CONTRIBUTING.md)\n\n---\n\nKoma comes from Komainu (\"狛犬\"), the stone guardian lions of Japanese Shinto shrines. Three deployed defense layers, each standalone, plus the Miko alpha agent-contract boundary. Patterns distilled from production, not papers.\n\n[License](./LICENSE)\n",
  "bytes": 12563,
  "sha": "8d6ebfdb0566977fab6d7ed99a5caed28290fae82b7e920ad2166c3990485961",
  "repo_slug": "swnotmetal/project-koma",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_swnotmetal_koma_gate_mcp_1a827e42/readme"
}