Koma

Verify what coding agents actually did. Protect the AI apps they build.

Koma is a TypeScript toolkit for observable AI boundaries. Miko checks coding-agent Skills, tool actions, and completion evidence against local Agent Specs. Gate, Scout, and Core protect prompt input, perimeter resources, and retrieval.

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

Building an LLM endpoint instead? Start with npm install koma-gate.

中文版

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

---

Featured Alpha: 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.

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

Miko README → · 10-second web replay → · DeepSeek Harness adapter →

---

Four Boundaries

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.

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.

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

---

Quick Start

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 →

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

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

Each package works standalone. Stack them: Gate filters → Scout throttles → Core stores.

MCP servers — expose Koma to AI agents directly:

• 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 AI coding agent?

Tell it:

"Add Koma to protect this AI endpoint. Use koma-gate for prompt injection, koma-scout for perimeter abuse, and koma-core for protected RAG retrieval. Each works standalone."

For a coding-agent repository, install Miko and run npx koma-miko init --host claude; then edit the generated miko.json to name the Skills, paths, and completion evidence that matter to the project.

Koma is designed for both human and agent discoverability — including two MCP servers. See llms.txt.

---

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.
• Fail-open by default. A broken optional guard does not take down the app; security-first deployments can set failOpen: false.
• CodeQL on every push. Targets OWASP LLM01.
• MIT licensed.

→ Security policy · Known limitations · Comparison with alternatives · 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