kagura-engineer

An autonomous, memory-grounded coding harness. It drives a GitHub issue to a pull request, and reviews pull requests.

The actor runs through kagura-brain using Claude Code (the default) or Codex. Grounding comes from Kagura Memory Cloud or an offline SQLite store, so each run starts with what previous runs learned.

This is a 0.x project: minor releases may include breaking changes. Check the changelog before upgrading.

Install

Requires Python ≥ 3.11.

uv tool install kagura-engineer     # uv can also fetch a suitable Python
pipx install kagura-engineer
pip install kagura-engineer

The standalone review command invokes kagura-code-reviewer. Install both together, or review degrades to a clean FAIL gate:

uv tool install "kagura-engineer[review]"

Quick start

kagura-engineer init        # scaffold a git-ignored repo.yaml
kagura-engineer doctor      # check the dependency chain
kagura-engineer setup       # install what's missing, bootstrap auth
kagura-engineer run 42      # drive issue #42 to a pull request

run verifies the environment, recalls relevant memory, isolates a git worktree, drives start → implement → ship with a gate between each phase, and opens a pull request — checkpointing as it goes, so a blocked run resumes by re-running the same command.

Beyond Python, a run expects git, gh, the brain CLI (claude or codex), and the gh-issue-driven plugin; ollama is used by the reviewer. kagura-engineer doctor reports exactly which of these are missing, and setup installs what it can.

Commands

Exit codes are consistent across the operational commands: 0 success, 1 hard failure, 2 blocked or resumable. Full behaviour, flags, and exit codes are in the command reference.

Configuration

kagura-engineer init writes a commented repo.yaml. A minimal offline config is two lines:

profile: dev
memory_backend: local

A Cloud-backed config adds the workspace, context, and agent identity. Every field is documented in the configuration reference.

Headless runs need Claude Code permissions granted up front — an unattended claude -p has no human to answer a permission prompt, so a missing grant shows up as a red-halted run. See headless permissions, and verify with kagura-engineer doctor --exec-probe.

Documentation

kagura-engineer <command> --help is authoritative for the version you have installed.

As a Claude Code plugin

The repository also ships a thin Claude Code skill-plugin wrapper. Its skills shell out to the installed CLI; the harness logic stays in the Python package. Install the CLI first, then add this repository as a marketplace source. The plugin is also referenced by the public kagura-plugins marketplace.

Related repositories

License

Apache License 2.0 — © 2026 Kagura AI. See NOTICE for attribution.