kagura-engineer

kagura-engineer

Part of the Kagura Memory Cloud offering. Licensed under Apache-2.0 — © 2026 Kagura AI.

An autonomous coding harness over Claude Code and Kagura Memory Cloud.

The long-term goal is a memory-backed actor that executes real, resumable coding tasks (see Roadmap). Shipping today: doctor and setup stand up the environment, and run / review drive GitHub issues to PRs through a memory-grounded loop. It's an early 0.x harness, not a finished actor. Memory Cloud is the recommended backbone (free to start), with an offline SQLite fallback for the basic loop.

---

Install

Requires Python ≥ 3.11.

As a tool (recommended)

Published on PyPI. uv will also fetch a suitable Python for you.

# uv (also bootstraps Python 3.11 if needed)
uv tool install kagura-engineer

# or pipx
pipx install kagura-engineer

# or plain pip
pip install kagura-engineer

The review command shells out to the separate kagura-code-reviewer console script. Pull it in alongside the harness with the review extra:

uv tool install "kagura-engineer[review]"

(kagura-engineer setup can also bootstrap it later; without it, review degrades to a clean FAIL gate.)

To install straight from the repository instead — e.g. an unreleased commit:

uv tool install git+ssh://[email protected]/kagura-ai/kagura-engineer.git

Pin a version with a tag: pip install kagura-engineer==0.1.0.

For development (from a checkout)

pip install -e ".[dev]"     # editable install + pytest

Either way, this exposes the kagura-engineer CLI (entry point kagura_engineer.cli:app).

As a Claude Code plugin

This repo also ships a thin skill-plugin wrapper (.claude-plugin/ + skills/) so the harness is installable and discoverable from inside Claude Code. The skills (kagura-engineer:doctor, :setup, :run, :review, :eval) are thin — they shell out to the CLI installed above and surface its output; no harness logic is duplicated. Install the CLI first, then add the plugin from this repo as a marketplace source.

It is referenced by the umbrella kagura-plugins marketplace (rule: reference, don't vendor — the plugin lives here and kagura-plugins/marketplace.json points at it), where kagura-engineer takes its place as a Tier-2 Harness: multi-phase, stateful/resumable, repo-mutating, PR-creating, and HITL-gated.

---

Configuration

Every command reads a repo.yaml (override with --config / -c):

profile: coding                                   # required
memory_cloud_url: https://memory.kagura-ai.com    # required for cloud backend
workspace_id: ws_xxxxxxxx                          # required for cloud backend — Memory Cloud scope
context_id: 00000000-0000-0000-0000-000000000000  # required for cloud backend — context within the workspace
ollama_url: http://localhost:11434                 # optional (default shown)
memory_backend: cloud                              # optional: cloud | local (default: cloud)
local_memory_path: .kagura/memory.db               # optional (used only when backend=local)
memory_mcp_config: .mcp.json                       # optional: override the auto-discovered <repo>/.mcp.json
review:
  models: [qwen2.5-coder:7b, haiku]               # optional (default: [])
  max_loops: 3                                      # optional (default: 3)
  code_review: auto                                 # optional: auto | always | never (default: auto)
  effort: medium                                    # optional: low | medium | high (default: medium)

workspace_id → context_id → memory is the Memory Cloud filter hierarchy. A missing required field, unparseable YAML, or an unreadable file fails with a clean error and exit code 2. With memory_backend: local the three Cloud-only fields may be omitted — an offline repo.yaml is just profile + memory_backend: local.

Memory backend. Memory Cloud is the recommended default and is free to start. Authenticate with either of two equivalent credentials — run honours both, env-first:

• export KAGURA_API_KEY=... — a workspace API key. Explicit and CI-friendly.
• kagura auth login — installs the kagura CLI and writes an OAuth profile to ~/.kagura/credentials.json. Used automatically when KAGURA_API_KEY is unset.