Skip to main content

5. Editor setup (MCP)

This is where Kleio gets useful: your editor's agent can call kleio_capture, kleio_decide, and kleio_checkpoint directly while you work, and it reads guidance from AGENTS.md and skill files about when to do so.

What kleio init does​

From the root of any git repo:

kleio init

It detects your editor (Cursor, Claude Code, Windsurf, Codex, OpenCode, Copilot, or generic) and drops in:

  • An MCP server registration so the editor's agent can call Kleio tools.
  • An AGENTS.md (or editor-specific equivalent) explaining when to log decisions vs. checkpoints vs. work items.
  • Skill / rule files teaching the agent the right call shape.
  • A .cursor/hooks.json (Cursor) so captures fire automatically on certain events.

If a file already exists, kleio init writes a sidecar (e.g. AGENTS.kleio.md, .cursor/mcp.kleio.json.example) so nothing of yours gets overwritten silently. Pass --force-overwrite only if you want to replace an existing file.

Pick a profile explicitly​

kleio init defaults to whichever editor it detects in the repo. To override:

kleio init --tool=cursor              # Cursor only
kleio init --tool=claude              # Claude Code only
kleio init --tool=cursor,claude       # both
kleio init --tool=generic             # AGENTS.md only, no editor-specific config
kleio init -i                         # interactive wizard (recommended for first install)

For CI or scripted bootstrap:

kleio init --non-interactive --yes-new-only --tool=cursor

MCP configuration​

If you want to wire MCP yourself instead of using kleio init, here's the config block. Path varies per editor:

  • Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
  • Claude Code: ~/.claude/mcp.json
  • Windsurf: ~/.codeium/windsurf/mcp_config.json
  • Codex / OpenCode / Copilot: see each editor's MCP docs
{
  "mcpServers": {
    "kleio": {
      "command": "kleio",
      "args": ["mcp"]
    }
  }
}

That's it. The kleio binary speaks MCP over stdio when invoked with the mcp subcommand and uses the credentials written by kleio login (in ~/.kleio/environments/production.yaml).

The MCP process hot-reloads ~/.kleio/config.yaml about every 30 seconds, so re-running kleio login or kleio workspace select does not require restarting your editor.

Available MCP tools​

ToolPurpose
kleio_captureCapture a work-item signal with file/line/repo context.
kleio_decideLog a decision (content + rationale + confidence + alternatives).
kleio_checkpointLog a meaningful implementation slice (validation status, files touched).
kleio_backlog_listList backlog items with filters.
kleio_backlog_showShow one backlog item.
kleio_backlog_prioritizeUpdate urgency / importance / status.
kleio_askQuery workspace memory (RAG over captures, decisions, checkpoints).

The full schemas for each tool are documented in the kleio-cli README and surfaced to your agent automatically by the MCP server.

Verify the editor wiring​

  1. Restart your editor so it picks up the MCP registration.
  2. In a new chat, ask the agent: "Log a decision in Kleio that we picked Postgres over MySQL because of pgvector support, with high confidence and one alternative."
  3. The agent should call kleio_decide and report back the new decision ID.
  4. Refresh app.kleio.build — the decision is there with the rationale and alternative attached.

If the agent doesn't see the tools, check that:

  • The editor was restarted after kleio init wrote the MCP config.
  • kleio status succeeds in the same shell environment your editor uses.
  • For project-scoped configs (e.g. .cursor/mcp.json), you opened the editor inside that project root.

You're done​

The full loop is live: humans and agents capture work and decisions, the GitHub App ingests commits and PRs, and the workspace at app.kleio.build reflects all of it.

What to do next: