Kagura Brain
kagura-ai/kagura-brain
Camada neutra de provedores para agentes CLI de código com MCP integrado
Ver no GitHubCamada de abstração para agentes de IA headless via CLI, centralizando o lançamento de agentes de código, gerenciamento de credenciais por subscription e normalização de saídas. Suporta múltiplos provedores (Claude, Codex) com adaptadores plugáveis e roteamento automático.
Instalação
npx convez-ai kagura-ai/kagura-brain1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Orquestrar agentes de código Claude/Codex sem replicar lógica de inicialização
- Gerenciar credenciais de subscription e stripped de variáveis de ambiente
- Rotear dinamicamente entre múltiplos backends (Claude, Codex, Ollama)
- Integrar MCP servers com controle granular de permissões e sandbox
Veredito

Ferramenta especializada para quem constrói agentes CLI multi-provider em Python. Resolve problemas reais de abstração e segurança de credenciais, mas curva de aprendizado steep — use se realmente precisar orquestrar múltiplos backends de IA em escala.
README
A tradução para o português deste README ainda está na fila.
kagura-brain
The provider-neutral "brain" layer shared by Kagura's CLI-brain harnesses
(kagura-engineer, kagura-planner, kagura-code-reviewer).
These tools run a headless CLI coding agent as their brain. They were each re-implementing the same seams: launching the agent, stripping stale provider credentials so subscription auth wins, parsing exit codes and sentinel markers, and normalizing output. This package centralizes those seams.
Two adapters ship today — Claude Code (claude -p) and Codex CLI
(codex exec) — as thin siblings over one shared launcher core (core._run +
verdict + extract_block). Each strips its provider's credential/endpoint
overrides from the child env so the CLI's subscription login wins:
claude deny-sets ANTHROPIC_*; codex prefix-scrubs OPENAI_*/CODEX_*
(including OPENAI_BASE_URL and CODEX_HOME).
from kagura_brain import claude, codex
claude.invoke("…prompt…", mcp_config=".mcp.json") # claude -p
codex.invoke("…prompt…", sandbox="read-only") # codex exec
MCP / approval differs by provider. Claude takes per-call --mcp-config /
--allowedTools (see claude.mcp_args). Codex manages MCP servers persistently
via codex mcp / ~/.codex/config.toml (no per-call flag), and its sandbox /
approval is opt-in: pass sandbox= (read-only | workspace-write |
danger-full-access) or bypass_approvals=True — neither is loosened by default.
BYO endpoint (opt-in)
By default both adapters strip the provider's endpoint/credential env so the
subscription login wins. To deliberately route at a caller-chosen
endpoint (Ollama Cloud / any compatible gateway), pass endpoint + api_key
together — they are injected after the scrub, so only these explicit
values reach the child while an ambient *_BASE_URL override stays stripped
(#2):
# Codex → Ollama Cloud (OpenAI-compatible). "ollama-cloud" is an alias for
# codex.OLLAMA_CLOUD_ENDPOINT ("https://ollama.com/v1").
codex.invoke("…prompt…", endpoint="ollama-cloud", api_key="…")
# Codex → a LOCAL ollama/lmstudio backend (no endpoint/key needed):
codex.invoke("…prompt…", local_provider="ollama")
# Claude → a caller-supplied Anthropic-compatible gateway (no Ollama preset:
# Ollama Cloud is OpenAI-, not Anthropic-, compatible):
claude.invoke("…prompt…", endpoint="https://my-gateway/v1", api_key="…")
Supplying only one of endpoint/api_key raises ValueError; a non-https
endpoint emits a UserWarning (prompt + code context goes off-box). With none
of these set, the default subscription-auth path is byte-for-byte unchanged.
Provider-neutral selector
When a consumer supports more than one backend, select confines the
claude/codex dispatch — and the per-provider MCP wiring — to the library, so
each consumer no longer re-encodes it
(#14):
import os
from kagura_brain import select, BRAIN_API_KEY_ENV
# "claude" (default) and "codex" are both supports_mcp=True.
handle = select(cfg.backend, endpoint=cfg.endpoint, api_key=os.environ.get(BRAIN_API_KEY_ENV))
handle.invoke("…prompt…", cwd=repo, mcp_config=".mcp.json", allowed_tools=MEMORY_TOOLS)
# Same mcp_config/allowed_tools to both; the adapter owns the mechanism:
# claude → --mcp-config/--allowedTools per call; codex → translates the .mcp.json
# into -c mcp_servers.* overrides and ignores allowed_tools (no codex analog).
# endpoint/api_key forward to both.
select takes primitives, never a consumer's Config, and never reads the
env itself — the library owns only the standard name BRAIN_API_KEY_ENV
("KAGURA_BRAIN_API_KEY"); the consumer reads it and passes api_key= in. An
unknown backend raises ValueError.
Why a separate package (not folded into the memory SDK)
Harness-support code splits cleanly along two axes:
| Axis | Belongs in | Examples |
|---|---|---|
| memory | kagura-memory-python-sdk | sync client facade, .mcp.json setup, auth resolution, recall |
| brain | this package | CLI-agent launcher (claude -p + codex exec), subscription-auth hygiene, verdict contract, doctor primitives |
Pushing CLI-agent spawning into a memory SDK would invert the layers ("memory spawns the agent"). So the brain axis lives here, and this package depends on no memory package — the two support libs are mutually independent.
kagura-engineer kagura-planner kagura-code-reviewer
\ | /
`--> kagura-brain + kagura-memory-python-sdk <--'
(brain axis) (memory axis)
Install
pip install kagura-brain
# or: uv add kagura-brain
Requires Python 3.11+. It has no Python runtime dependencies (stdlib-only) — and by design depends on no memory package (see the axis split above).
Prerequisites: the provider CLIs
kagura-brain is a launcher — it drives the provider CLIs as subprocesses, so
each adapter needs its own CLI installed and on PATH. These are external
tools, not pip dependencies; install only the one(s) you use:
| Adapter | Needs | Auth (default path) |
|---|---|---|
claude.invoke() | Claude Code CLI (claude) — see docs | signed in to your Claude subscription (the adapter strips ANTHROPIC_* so the subscription login wins) |
codex.invoke() | Codex CLI (codex) — see docs | codex login (ChatGPT subscription; the adapter strips OPENAI_*/CODEX_*). Verified against Codex 0.133.0 (codex._CODEX_VERIFIED_VERSION) |
The CLI binary is required even in BYO-endpoint mode —
only the auth source changes: instead of the subscription login, the
caller-supplied endpoint + api_key (or, for Codex, a local
--oss --local-provider backend) are used. No subscription login is needed for
the BYO path, but claude / codex must still be installed.
doctor primitives to check CLI launchability are planned (see Status).
Status
Public surface is built incrementally under TDD, one consumer migration per PR:
-
core— shared seam:BrainResult,_run(subprocess + env-scrub + timeout + utf-8 decode),as_text,extract_block -
claude.invoke()— headlessclaude -plauncher (ANTHROPIC_*/CLAUDE_*deny-set,---guarded prompt,mcp_args, opt-in BYOendpoint/api_key) -
codex.invoke()— headlesscodex execlauncher (OPENAI_*/CODEX_*prefix scrub,---guarded prompt, opt-in sandbox, BYOendpoint/api_key+local_provider) -
verdict—PROCEEDset + exit-code map (contract only); see the exit-code contract for the canonical gate vocabulary vs reviewer-internal codes -
doctor— provider-neutral check primitives (check_binary,check_auth,check_endpoint,aggregate) + presence-onlyclaude.check()/codex.check()wrappers -
select— provider-neutralBrainHandleselector over the adapters (supports_mcpcapability; per-provider MCP wiring confined to the library — claude per-call flags, codex-c mcp_servers.*;BRAIN_API_KEY_ENVname)
Development
uv sync --extra dev
uv run pytest # tests
uv run ruff check . # lint
uv run ruff format . # format
uv run mypy # type check
See CONTRIBUTING.md for the full workflow and CHANGELOG.md for release history.