Gå til hovedinnhold

Use with Claude

kapi and Claude connect in two directions. In one, you work in Claude and it drives kapi — the assistant writes and translates inside kapi's guardrails. In the other, kapi runs Claude: your local Claude Code sign-in becomes kapi's AI provider, so kapi up and kapi translate run on your Claude subscription with no API key. Start from what you have:

You have…Use
Claude Pro or Max (Claude Code installed)Both directions. Work in Claude via the skill or MCP; run kapi models setup and kapi runs Claude on your subscription — 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 offlineA local model via kapi models ollama, or Kapi Desktop's demo engine (illustrative output, no AI).

Work in Claude​

You describe the outcome; Claude runs kapi. kapi supplies the guardrails — the faithful round-trip, brand voice, terminology, the check gates — and Claude does the writing inside them. All paths need kapi on your PATH (installation); no provider credential is required for attended work — Claude writes, kapi applies and checks, no second model.

You work in…UseHow it drives kapi
Chat — Claude Code, plain-language promptsthe Agent Skill (SKILL.md)Claude runs kapi commands itself and loops until the gates pass
IDE — Claude Desktop, Cursor, Windsurf, VS Codethe MCP server (kapi mcp)structured tools: extract_content, apply_edits, check_file, brand_check
CI — no assistant in the loopthe CLI directlykapi 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 plus two hooks:

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

The Stop hook runs the project gate (kapi check --ship) when Claude tries to finish and keeps it working while a gate fails; the PreToolUse hook denies hand-edits to generated translation targets, steering changes through the source. Both are fail-open outside a project, and both follow one decision protocol.

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. For Claude Code, add .mcp.json at the repository root (Claude Desktop uses claude_desktop_config.json, Copilot .vscode/mcp.json — same shape):

{
  "mcpServers": {
    "kapi": { "command": "kapi", "args": ["mcp"] }
  }
}

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. The exit code is not the channel: Claude Code reads a non-zero exit as a broken hook, so a denial carried that way would be downgraded to a hook error rather than enforced. kapi check --ship keeps its own gate exit code (3) when you run it yourself — the hook drives that gate but is not it.

What the hook foundOn stdoutWhat happens
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 — gates pass, the file is not generated, or there is no kapi projectnothingThe operation proceeds.
The guard could not run at all{"systemMessage":"…"} — plus the same warning on stderr, naming the hookThe operation proceeds: kapi hooks fail open, so a broken guard never blocks work. But the bypass is stated, because a guard that never ran must not look like a guard that passed.

The third row is the one worth knowing about. 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 wire shapes are Claude Code's, and Claude Code versions its own hook schema; kapi does not add a version of its own. What is stable here is the policy in the table: fail open, and never silently.

The loop, whichever door: Claude pulls your brand guide and approved terms first (kapi brand guide, kapi terms lookup), writes through the one write verb (kapi apply — structure preserved, drift-guarded by content hash), then gates out with kapi check until green. Bind the profile and the terms store in a project and this happens automatically; your prompts stay short — "Set kapi up for this project", "Check README.md against our brand voice and fix what fails", "Translate the docs into French and German, then bring them to the ship gate".

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

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 window-limited: a heavy run that exhausts your Claude usage window parks the remainder and reports when it resumes ("Claude subscription limit reached — resumes ~7pm"); the next kapi up picks up exactly the units still pending. For uninterrupted or CI runs use an API key instead — 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​