Use with Claude

An assistant connected to a kapi project writes to the project's rules. It reads the terms and voice that apply to a file before it writes, checks each file it changes, and notes what it sees for a person to decide about. Connect one with Connect on the Assistants page in Kapi Desktop, or run kapi connect in the project's folder. Both write the same files.

kapi can also run Claude itself, through your Claude Code sign-in; see Let kapi run Claude.

Connect an assistant

$ kapi connect
Claude Code   connected · rules, MCP server, skill
  .mcp.json            created
  .claude/skills/kapi  created
  Edit hook            pending: in Claude Code, /plugin marketplace add neokapi/claude-plugins, then /plugin install kapi@neokapi-plugins
  Stop hook            pending: in Claude Code, /plugin marketplace add neokapi/claude-plugins, then /plugin install kapi@neokapi-plugins
Cursor        connected · rules, MCP server
  .cursor/mcp.json     created
VS Code       not connected: no .vscode/ folder here (kapi connect vscode adds it)
Codex         not connected: no .codex/ folder here (kapi connect codex adds it)

Project
  kapi.yaml            created
  AGENTS.md            created
  CLAUDE.md            updated (Writing rules section)

See what an assistant reads for a file: kapi context <path> --explain

That run was in a folder with a .cursor/ directory, a CLAUDE.md of its own and no recipe. kapi connect connects Claude Code and each assistant whose folder the project keeps, and lists the others. Each line says what happened: created, updated or kept for a file; deleted, or removed the section, for a rules file in a folder that has no rules of its own any more. A folder with no recipe gets the one kapi init writes. A second run keeps every file as it is.

• kapi connect --dry-run lists the same files with what it would do, and writes none of them.
• kapi connect codex connects one assistant: claude, cursor, vscode, codex or agents. Any other name exits with status 1 and lists these.
• kapi connect --json gives the assistants and the files as data.

kapi init writes the same files when it creates a project, so a project made with kapi init is already connected to Claude Code. Run kapi connect in a project an earlier kapi created to bring its wiring up to date.

When the assistant reads the rules

An assistant on a kapi project meets the rules as it starts, before it writes and after it edits.

As it starts, it reads the Writing rules section of CLAUDE.md, the file Claude Code reads, or of AGENTS.md, which most other agents read: the voice, what to write and what not, and the kapi check line. A folder whose rules differ from the root's gets files of its own, so a rename kept for help/ is stated in help/CLAUDE.md, and api/CLAUDE.md says the old name is correct there. kapi rewrites the section when the rules change and leaves the rest of each file as you wrote it; a CLAUDE.md that imports @AGENTS.md gets no section of its own. See rules files for agents.

Before it writes a file the section does not cover, it asks kapi context <path>, or context_read through the MCP server. kapi context <path> --explain prints what it reads there.

After it edits, it runs kapi check on each file it changed, or check_file, and fixes what fails. The kapi Claude Code plugin makes both checks automatic:

• The edit hook runs after each edit and checks the one file the edit wrote, as kapi check <file> does. A failing finding (a name, a spelling, a word rule) comes back to Claude beside the edit's result, with the fix when the rule names one, so Claude corrects the file before it reports done.
• The Stop hook runs the project gate (kapi check --ship) when Claude tries to finish, and keeps it working while a gate fails.

kapi connect reports both hooks as pending until the plugin is installed and enabled, with the two commands that install it.

As it works, the assistant notes what the files keep to and what you change in its drafts, with the file and sentence each came from. Each note arrives as a suggestion: checks report it and none fails on it until you keep it with kapi rules. A note holds only in the files where the assistant saw it until you widen it. See Growing context.

What kapi connect writes

Agent	What it gets
Claude Code	.mcp.json with the kapi server, and the kapi skill in .claude/skills/kapi/SKILL.md
Cursor	.cursor/mcp.json with the kapi server
VS Code	.vscode/mcp.json with the kapi server
Codex	.codex/config.toml with the kapi server, read once you trust the repository
Any SKILL.md-aware tool	the kapi skill in .agents/skills/kapi/SKILL.md

Every agent also gets the rules files. The skill says how to read what applies to a file, note what it sees and what you change, check edits, and report the session, with the CLI and MCP form of each. kapi help <topic> prints the longer guides from your installed binary.

Claude Code is wired every time. The others are wired when the project already keeps their directory, so neither command adds a directory for an editor you do not use. Name one with kapi connect <assistant>, or choose with kapi init --agents:

kapi init --agents claude-code,cursor   # exactly these
kapi init --agents all                  # every agent kapi knows
kapi init --agents none                 # write no agent configuration

kapi init --no-rules-files leaves out the rules files.

Everything it writes is inside the project. The MCP entry holds a command only, with no shell, environment or credential. An entry called kapi that you wrote or changed is left exactly as it is. An entry exactly as kapi wrote it follows the recipe, so after you add target languages, running kapi connect again adds the translation tools. A skill directory an earlier kapi filled with reference files is cleared of the files kapi wrote there, and any file of yours in it stays.

Claude Code asks you to approve a project MCP server the first time you open the project, so review .mcp.json before you say yes, the way you would any file a repository ships.

Set it up by hand

These are the pieces kapi connect writes, for a client it does not configure or a setup you want to control yourself. All of them need kapi on your PATH (installation), and none needs a provider credential for attended work: Claude writes, kapi applies and checks.

You work in…	Use	How it reaches kapi
Chat (Claude Code, plain-language prompts)	the Agent Skill (SKILL.md)	Claude runs kapi commands itself and loops until the checks pass
IDE (Claude Desktop, Cursor, Windsurf, VS Code)	the MCP server (kapi mcp)	context_read for a file the rules files do not cover, context_note for what it notices, and check_file; --tools adds more sets
CI (no assistant in the loop)	the CLI directly	kapi check / kapi check --ship exit non-zero, failing the build

Install the Agent Skill (Claude Code and any SKILL.md-aware tool)

Claude Code: the plugin bundles the skill, the edit hook and the Stop hook above, and a PreToolUse hook:

/plugin marketplace add neokapi/claude-plugins
/plugin install kapi@neokapi-plugins

The PreToolUse hook denies hand-edits to generated translation targets, steering changes through the source. Every hook is fail-open outside a project, and all follow one decision protocol. kapi connect reads the project's .claude/settings.json and .claude/settings.local.json, then your own Claude Code settings (settings.json in $CLAUDE_CONFIG_DIR, or in ~/.claude), and reports the hooks as kept once one of them enables the plugin, or kept (enabled for your user) when only your own settings do.

Copilot, Cursor, Windsurf, VS Code, Codex: SKILL.md is an open standard:

npx skills add neokapi/agent-skills --skill kapi     # add -a <tool> for a specific tool
npx skills update kapi                               # refresh later

Install the MCP server (Claude Desktop, Claude Code, Cursor, and the rest)

Your client launches kapi mcp as a stdio subprocess. Claude Code and Cursor read the server list under mcpServers; VS Code reads it under servers. Claude Desktop uses claude_desktop_config.json with the same shape as Claude Code's:

{
  "mcpServers": {
    "kapi": {
      "type": "stdio",
      "command": "kapi",
      "args": ["mcp", "--project", "kapi.yaml"]
    }
  }
}

--project names the project the server answers for. Without it, the server binds whichever project sits above the directory your client started it in. The writing tools include read_blocks, apply_edits and describe_format, which read a file's blocks, write edits back with the file's structure and inline codes kept, and say what a format supports. For a project that declares target languages, kapi connect and kapi init add "--tools", "writing,translation" to the arguments, so the agent also gets the translation tools beside the writing ones.

See MCP server for every client's configuration and the full tool list.

The hook decision protocol

A kapi hook states its verdict as JSON on stdout and always exits 0. Claude Code reads a non-zero exit as a broken hook, so a denial sent as an exit code would count as a hook error and not be enforced. kapi check --ship keeps its own gate exit code (3) when you run it yourself; the hook drives that gate without replacing it.

What the hook found	On stdout	What happens
The edited file has a failing finding	{"decision":"block","reason":"…"} (PostToolUse)	The edit stands. Claude reads the reason beside the edit's result: one line per finding, the fix when the rule names one, and the kapi check <file> command to run.
A gate fails / the file is a generated target	{"decision":"block","reason":"…"} (Stop) · {"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"…"}} (PreToolUse)	Claude keeps working, or the edit is refused. The reason names the findings, or the source and locale to change instead.
Nothing to report (the file or the gates pass, the file is not generated or not read by the project, or there is no kapi project)	nothing	The operation proceeds.
The guard could not run at all	{"systemMessage":"…"} plus the same warning on stderr, naming the hook	The operation proceeds: kapi hooks fail open, so a broken guard never blocks work. The notice states the bypass, so you can tell a guard that never ran from one that passed.

An unreadable, empty, or malformed hook payload; a session directory kapi cannot enter; a recipe that will not load because it needs a plugin you have not installed: each of those leaves the guard installed but inert. The notice says which hook, and what stopped it.

The JSON shapes are Claude Code's, and Claude Code versions its own hook schema. kapi adds no version of its own. The policy in the table stays fixed: a hook fails open and reports the bypass.

Let kapi run Claude

For unattended runs (kapi up across every locale, kapi translate without you in the loop) kapi needs a provider of its own. If Claude Code is signed in on your machine, that provider can be your Claude subscription:

kapi models setup     # detects the Claude Code CLI ("uses your Claude subscription"): one confirm, no key

You have…	Use
Claude Pro or Max (Claude Code installed)	kapi models setup, and kapi runs Claude on your subscription with no key.
An API key (Anthropic, OpenAI, Gemini)	kapi models setup finds keys already in your environment, or stores one in the OS keychain, and verifies it with a test call.
Nothing, or offline	A local model via kapi models ollama, or Kapi Desktop's demo engine (illustrative output, no AI).

Setup verifies the choice with a small test call and writes the default provider to the global config, shared with Kapi Desktop, whose first-open Connect your AI card offers the same detected sign-in as a one-click button. kapi models list shows it under Detected, alongside Ollama models and any cloud keys.

Subscription use is limited by your Claude usage window. A heavy run that uses up the window holds back the remainder and reports when it resumes ("Claude subscription limit reached; resumes ~7pm"). The next kapi up picks up exactly the blocks still pending. For uninterrupted runs, use an API key. Subscription auth is bound to your personal sign-in and its usage window, so CI should always use a key (a provider env var, or kapi credentials add). See Ship gates & CI.

Next

• Content governance for AI: the guardrails that make agent output pass.
• Bulk rewrite with an agent: a repo-wide sweep, gated.
• Choose a model: every provider kapi can run.