swnotmetal/Project-Koma

Miko: required Skill checks for Claude Code and Codex
> **Your coding agent says it read the Skill, but did it really?**
>
> Miko intercepts file edits at the Hook layer. If your agent hasn't read the required Skill first, Miko rejects the edit and provides a clear, observable recovery path. It runs locally, zero-dependency, makes no LLM calls, and is free and open source.
Who needs this?
- You use **Claude Code** or **Codex CLI**, wrote project Skills/instructions, but aren't sure if the agent follows them.
- You want a **hard check** before file edits instead of relying solely on prompt instructions.
- You want Skill loading and checks to be **observable, rejectable, and recoverable**.
How Miko differs
Unlike static Skill linters or security scanners, Miko works at the **runtime Hook layer**—intercepting the agent's actual file edit tool calls in real time rather than statically analyzing Skill files.
Scope
**Miko is an extremely lightweight tool.** It checks a small set of observable events and blocks only the actions that fail them. It is not a security boundary, a compliance system, or proof that a model understood anything.
**Start every conversation by telling your agent to load the Skills it needs.** Miko is the backstop for when the agent forgets, not a replacement for saying what you want. Clearer instructions mean fewer pauses.
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.
中文版
▶ Try Miko's guided terminal replay — plus Gate, Scout & Core, no signup.
---
Miko for Claude Code and Codex
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.
> **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. VS Code Copilot now has one verified live enforcement cycle on the
Local harness, but that host does not render Miko's status text in the chat UI,
so Miko asks the agent to relay it. 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.