kagura-brain

kagura-brain is the provider-neutral Python launcher for the CLI coding agents used as brains by Kagura harnesses. It gives consumers one tested seam for running Claude Code (claude -p) or Codex CLI (codex exec), keeping provider credentials, subprocess behavior, MCP wiring, and verdict handling out of each harness.

from kagura_brain import select

brain = select("claude")  # or "codex"
result = brain.invoke("Reply with exactly: PONG")

if not result.ok:
    raise RuntimeError(result.detail())

print(result.stdout)

What it provides

• Two CLI adapters: Claude Code and Codex share one subprocess, timeout, output, and result contract.
• Subscription-auth hygiene: inherited provider credentials and endpoint overrides are removed before launch so the CLI's own login wins.
• Explicit alternate backends: callers can opt into a compatible gateway; Codex can also select local Ollama or LM Studio backends.
• Provider-neutral selection: select() keeps backend dispatch and MCP translation inside the library.
• Safe gate semantics: the verdict module normalizes proceed/halt decisions; unknown or missing verdicts halt.
• Preflight primitives: lightweight checks cover binaries, auth commands, endpoints, and aggregate reports.

Backend summary

Neither adapter loosens permissions by default. Full-bypass options are explicit, and the Codex bypass also disables its sandbox. See Provider configuration before using an unattended mode.

Install

pip install kagura-brain
# or
uv add kagura-brain

Requirements:

• Python 3.11+
• claude and/or codex installed and available on PATH
• the selected CLI signed in, unless an explicit alternate backend is used

The Python package is stdlib-only at runtime and deliberately has no dependency on kagura-memory.

For setup, authentication, result handling, and first examples, read Getting started.

Architecture at a glance

Kagura's reusable harness support is split along two independent axes:

kagura-engineer   kagura-planner   kagura-code-reviewer
        \                |                /
         +---- kagura-brain  +  kagura-memory ----+
               brain axis        memory axis

kagura-brain launches the coding agent. kagura-memory supplies durable context. Keeping them independent avoids the inverted dependency "memory spawns the agent". The full module and launch-flow description is in Architecture.

Documentation

Current release

Version 0.6.1 supports Python 3.11-3.13. The Codex adapter's environment and configuration assumptions were last audited against Codex CLI 0.145.0; the subprocess suite remains mocked, so releases also require the documented real-CLI smoke test.

Development

uv sync --extra dev
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy
uv run pytest tests/ -v

Coverage must remain at or above 90%. See CONTRIBUTING.md for the complete workflow.

License

Apache-2.0. See LICENSE and NOTICE.