Metadata-Version: 2.4
Name: kagura-engineer
Version: 0.7.0
Summary: Autonomous memory-grounded coding harness over Claude Code or Codex
Project-URL: Homepage, https://github.com/kagura-ai/kagura-engineer
Project-URL: Repository, https://github.com/kagura-ai/kagura-engineer
Project-URL: Issues, https://github.com/kagura-ai/kagura-engineer/issues
Project-URL: Changelog, https://github.com/kagura-ai/kagura-engineer/blob/main/CHANGELOG.md
Author-email: Kagura AI <dev@kagura-ai.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agent,autonomous-agent,claude-code,codex,coding-agent,developer-tools,harness,kagura,llm,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: kagura-brain<0.5,>=0.4.1
Requires-Dist: kagura-memory<0.38,>=0.37
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: review
Requires-Dist: kagura-code-reviewer; extra == 'review'
Description-Content-Type: text/markdown

# kagura-engineer

[![PyPI](https://img.shields.io/pypi/v/kagura-engineer.svg)](https://pypi.org/project/kagura-engineer/)
[![Python](https://img.shields.io/pypi/pyversions/kagura-engineer.svg)](https://pypi.org/project/kagura-engineer/)
[![License](https://img.shields.io/pypi/l/kagura-engineer.svg)](https://github.com/kagura-ai/kagura-engineer/blob/main/LICENSE)

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`](https://github.com/kagura-ai/kagura-brain)
using Claude Code (the default) or Codex. Grounding comes from
[Kagura Memory Cloud](https://github.com/kagura-ai/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](https://github.com/kagura-ai/kagura-engineer/blob/main/CHANGELOG.md)
before upgrading.

## Install

Requires **Python ≥ 3.11**.

```bash
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`](https://github.com/kagura-ai/kagura-code-reviewer).
Install both together, or `review` degrades to a clean FAIL gate:

```bash
uv tool install "kagura-engineer[review]"
```

## Quick start

```bash
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

| Command | What it does |
|---|---|
| `init` | Scaffold a commented, git-ignored `repo.yaml` |
| `doctor` | Check the dependency chain; `--exec-probe` also live-tests headless permissions |
| `setup` | Install missing dependencies and bootstrap authentication |
| `run <issue>` | Drive one GitHub issue to a pull request |
| `review [ref]` | Review a branch or PR and gate on the verdict; `--fix` runs the auto-fix loop |
| `eval <issues…>` | A/B the memory-grounded loop against an ungrounded control arm |

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](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/commands.md).

## Configuration

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

```yaml
profile: dev
memory_backend: local
```

A Cloud-backed config adds the workspace, context, and agent identity. Every
field is documented in the
[configuration reference](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/configuration.md).

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](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/headless-permissions.md),
and verify with `kagura-engineer doctor --exec-probe`.

## Documentation

| Page | Contents |
|---|---|
| [Commands](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/commands.md) | Every command, flag, and exit code |
| [Configuration](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/configuration.md) | `repo.yaml` fields, memory backends, task fidelity, brain auth |
| [Headless permissions](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/headless-permissions.md) | Allowlist and workspace trust for unattended runs |
| [Development](https://github.com/kagura-ai/kagura-engineer/blob/main/docs/development.md) | Layout, tests, release process |
| [Changelog](https://github.com/kagura-ai/kagura-engineer/blob/main/CHANGELOG.md) | Shipped and breaking changes by release |

`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`](https://github.com/kagura-ai/kagura-plugins) marketplace.

## Related repositories

| Repo | Role |
|---|---|
| [`kagura-brain`](https://github.com/kagura-ai/kagura-brain) | Headless launcher seam for the Claude/Codex actor |
| [`memory-cloud`](https://github.com/kagura-ai/memory-cloud) | Persistent memory service and MCP server |
| [`kagura-memory-python-sdk`](https://github.com/kagura-ai/kagura-memory-python-sdk) | Memory SDK used by the Cloud client and MCP setup |
| [`kagura-code-reviewer`](https://github.com/kagura-ai/kagura-code-reviewer) | Standalone reviewer invoked by `review` |
| [`kagura-plugins`](https://github.com/kagura-ai/kagura-plugins) | Public Claude Code plugin marketplace |

## License

[Apache License 2.0](https://github.com/kagura-ai/kagura-engineer/blob/main/LICENSE)
— © 2026 Kagura AI. See
[NOTICE](https://github.com/kagura-ai/kagura-engineer/blob/main/NOTICE) for
attribution.
