Skip to content

Integrating mokata with other AI tools

mokata is Claude-Code-first — start with the pip-first path, pip install mokata → mokata setup claude (a one-click Claude Code plugin is planned but not yet available; see Using mokata in Claude Code). But the engine is harness-agnostic: what setup wires is just a bundle of three portable artifacts (prompt templates, the mokata-mcp server, and hook scripts), so you can wire those into another harness or share a governed stack across a team. The paths below go from highest-fidelity (a real harness integration) down to the lowest common denominator (raw CLI), so reach for them in that order. (mokata never supplies the LLM — your harness does; see How mokata uses an LLM: harness vs CLI.)

1. Wire mokata into your harness (the setup model)

The best integration mirrors what mokata setup claude does: point your harness at the three artifacts — the prompt templates (templates/commands/*.md), the mokata-mcp MCP server, and the hook scripts — using that harness's own command/MCP/hook conventions. For Claude Code this is one command (mokata setup claude); the same one-command wiring now covers Cursor, GitHub Copilot, Windsurf, Gemini CLI, Codex, and Aider — each mapped to that agent's native command/MCP surface, degrading clearly where an agent lacks a capability. See Use mokata with other AI agents. This gives the LLM the full structured workflow, not just shell access.

2. The CLI works anywhere (lowest common denominator)

The mokata CLI is a dependency-light Python tool (no required runtime deps; jsonschema optional). It runs in any terminal, script, or CI, independent of Claude Code. Any AI tool that can run shell commands can therefore call mokata — e.g. have your assistant run mokata query callers foo, mokata preview, or mokata doctor and read the output. Use this when a full harness integration isn't available — the CLI is the engine's mechanics (it has no LLM of its own).

3. Orchestrate external MCP servers (H4)

mokata has an MCP registry + discovery layer: drop a .mokata/mcp.json listing the MCP servers you use ({name, provides, command}), and mokata mcp enumerates them and maps them to stack roles/capabilities. mokata then orchestrates those servers through its own gates and audit trail. Discovery is pluggable and degrades cleanly — with no config present, the registry is empty and nothing errors.

mokata ships mokata-mcp — its own operations as native Claude Code tools — and orchestrates the external MCP servers it discovers and routes to (H4).

4. Cross-harness portability (the harness boundary)

mokata's engine runs through a thin harness boundary (mokata harness) so the pipeline isn't tied to one host. The reference implementation targets Claude Code; the boundary defines how commands, hooks, context injection, and subagents map to a harness. On a harness that lacks a capability (e.g. a host without subagents), mokata degrades with a clear message instead of failing — so the same workflow runs, just with fewer features. This is what lets mokata extend to tools like Codex or OpenCode without rebuilding the engine per host.

5. Shareable stack manifests (team adoption)

A mokata stack — which tools are wired, the profile, toggles, trust dials — is a committed, reviewable manifest. Share it so a teammate adopts the same governed setup in one step:

mokata export team-stack.json        # publish your stack
mokata import team-stack.json --yes  # validate + apply on another repo (human-gated)

Imports are validated before they apply (an invalid manifest is rejected, nothing written), and applying is human-gated — so sharing a stack never silently reconfigures someone's repo. See Share a stack.

What stays true everywhere

No matter the integration path, mokata's guarantees hold: local-first (nothing leaves the machine unless you wire an external tool), every durable write human-gated (a write tool call returns a proposal id and commits nothing; a human mints the approval out-of-band with mokata approve <id>), and a full audit trail of every gate decision and tool call. Adopted external tools are treated as untrusted input — their output is gated on the way in, never trusted on sight.

One limit, stated plainly: the PreToolUse hooks — the secret-guard and the run-state gate-guard — are wired only on Claude Code, the one harness that declares the hooks capability. Elsewhere the durable-write protections above still hold (they live in mokata's own WriteGate, not the hook), but the four run-state gates (approach-approval, spec-persisted, no-code-without-failing-test, spec-scope) enforce nothing. See Use mokata with other AI agents.