Koma

September 3, 2026 · View on GitHub

Miko: required Skill checks for Claude Code and Codex

Keep reminding your coding agent to read a required Skill before editing? Miko checks for observable Skill reads before protected edits. When evidence is missing, it pauses the action and tells the agent what to load before retrying. It runs locally, makes no LLM calls, and is free and open source.

The current focus is Claude Code and Codex CLI. Miko is part of Koma; the separate Gate, Scout, and Core packages cover AI application input, request limits, and retrieval. You do not need them to use Miko.

npm install -D koma-miko@alpha
npx koma-miko init --host claude

Edit the generated miko.json to name your project's Skills and protected paths, then start a new Claude Code session. Using Codex? Follow the Codex setup and one-time Hook review. Codex CLI is a Technical Preview; Desktop requires prior CLI activation.

Koma

License CI koma-miko koma-gate koma-scout koma-core
Miko live demo Gate benchmark koma-gate downloads MCP server

中文版

▶ Try Miko's guided terminal replay — plus Gate, Scout & Core, no signup.

Miko for Claude Code and Codex

Koma Miko

Coding agents can say they loaded a required Skill or ran a test. Miko does not treat that claim as evidence. At supported local host Hooks, it compares observed Skill loads, reference reads, tool actions, and completion checks with a project-owned miko.json.

If an agent tries to edit before satisfying the spec, Miko can return a denial and a short recovery instruction. It cannot inspect hidden model context, prove that a model understood a Skill, or verify events the host never exposes. In Claude CLI guided mode, a genuine scope exception opens one visible Miko choice: allow that exact retry once, or keep the current boundary.

npx --yes koma-miko@alpha demo       # deterministic; no API key
npx --yes koma-miko@alpha probe --host claude  # isolated adapter check; no model
npx koma-miko init --host claude     # after local installation

Codex CLI is a Technical Preview; Codex Desktop requires prior CLI activation. The CLI requires a one-time /hooks review before project Hooks run. Miko promotes enforce on Codex because the current Hook API cannot open a native REVIEW choice; review therefore degrades to a recoverable pause/deny. Desktop-only onboarding is not a supported alpha path. An offline probe proves adapter logic, not live Hook activation.

Miko README → · Current host support → · 10-second web replay →

Miko replay GIF · Still image — browser simulation, not a live host recording.

Claude Code is the primary alpha workflow. Codex CLI has a verified narrow recovery flow with the activation limits above. Gemini is outside active development; Copilot adapter work is paused pending a real tester. Existing adapters and their dated results remain available in the adapter documentation.

Why use Miko instead of writing a Hook? A small native Hook is enough for a single fixed check. Miko packages project Specs, observed-read tracking, post-compaction reload requirements, recovery messages, and completion evidence so you can maintain those checks together. Neither approach proves the model understood the instructions. See when Miko helps.

Four Boundaries

BoundaryFailure modeWhat Koma checksPackage
Coding agentRequired Skill or completion check skippedHost-observed preparation, action scope, and evidencekoma-miko@alpha
User → LLMPrompt injection / jailbreakSemantic scope before the application modelkoma-gate
Request perimeterAudio abuse / floodingValidation, rate limits, and geo ruleskoma-scout
RetrievalData enumeration / scrapingSplit index from content; token-gate retrievalkoma-core

Different attacks cross different boundaries. Koma provides a small primitive for each one.

What Koma Is — and Isn't

Is: small composable packages · usable independently · explicit failure modes · deterministic checks where the host exposes evidence

Isn't: a model · an agent framework · proof that a model understood its instructions · a replacement for authorization · a complete security boundary by itself

Benchmarks

Miko alpha evaluation

Miko is deterministic, so its useful numbers are verifier cost and end-to-end Hook behavior—not a generic score for model intelligence.

SignalObserved result
Offline host conformanceClaude, Codex, Gemini, and VS Code Copilot each reproduce DENY → observed Skill → ALLOW; ledger fixtures reject prompt/code/tool-response persistence
Local verifier scale1,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
Claude Code live + hand-testOne 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
Codex CLI Technical PreviewFixed 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
DeepSeek Harness smoke3/3 narrow packed-artifact recovery runs passed; 19.425 s mean model phase

The scale row is a 2026-08-27 reference run on Node 24.19 / Windows; rerun it with npm run eval:scale -w koma-miko. Context tokens never enter the verifier. The paid samples are deliberately small and do not establish general model, long-context, or editor reliability. See the scale record, Claude record, host-adapter record, and DSH record.

Koma Gate live-model benchmark

I threw 1,769 real prompt-injection attacks at Koma Gate in fail-closed mode, using real providers — not mock adapters.

ProviderRecallPrecisionFalse Positives
DeepSeek (deepseek-chat)98.8%100%0
Google (gemini-2.5-flash)96.2%100%0

Chinese attack set: 100% recall · 100% precision · 0% FPR across 8 categories.

Can you break it? Open an issue with an attack Koma misses. → Full methodology

Application-side quick start: Gate

import { createGeneralKnowledgeGuard } from 'koma-gate';

const guard = createGeneralKnowledgeGuard({
  llm: { apiKey: process.env.GEMINI_API_KEY },
});

app.post('/api/chat', guard.middleware(), async (req, res) => {
  // Only in-scope requests reach your model
  res.json({ reply: await chat(req.body.message) });
});

git clone https://github.com/swnotmetal/Project-Koma
cd Project-Koma && node demo/server.js
curl http://localhost:8080/self-test

Application-Side Packages

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 →

Try Gate in the browser demo →

koma-scout — Perimeter protection. Rate limiting, audio upload validation, geo allowlisting. Cheap checks before expensive AI work. README →

Koma Scout perimeter checks

koma-core — Protected RAG storage. Public search index, private content, opaque HKDF-derived tokens. Discovery is not authorization. README →

Koma Core split-store

Each package works standalone. A typical application checks cheap request limits with Scout before Gate classification, then uses Core where protected retrieval is needed. See the architecture map.

Application-side MCP servers — these belong to Gate and Core, not Miko:

  • koma-gate-mcp — classify_input tool for prompt-injection checks. README →
  • koma-core-mcp — search_docs + retrieve_doc for protected RAG retrieval. README →
{
  "mcpServers": {
    "koma-gate": { "command": "npx", "args": ["-y", "koma-gate-mcp"] },
    "koma-core": { "command": "npx", "args": ["-y", "koma-core-mcp"] }
  }
}

Using an agent to set up Miko?

Tell it:

"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."

For a coding-agent repository, install Miko and run npx koma-miko init --host claude or follow the Codex setup. Edit the generated miko.json to name the Skills, paths, and completion evidence that matter to the project. Miko does not install the Skills themselves.

See llms.txt for documentation entry points. Miko uses host Hooks; it does not require an MCP server.

Trust & Safety

  • Minimal dependency surface. Miko, Gate, and Core have no third-party runtime dependencies; Scout declares Express as a peer.
  • No model-output execution. Miko observes host events; Gate, Scout, and Core classify, rate-limit, or store. None executes generated code.
  • Package-specific failure behavior. Gate defaults to fail-open and can use failOpen: false. Miko follows each Agent Spec's mode; an enforce-mode missing-evidence check denies the applicable action.
  • CodeQL on every push. Targets OWASP LLM01.
  • MIT licensed.

→ Security policy · Known limitations · Contributing

Koma 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.

License