Metadata-Version: 2.4
Name: kunchi
Version: 0.1.1
Summary: A simple coding harness with planner-implementor-validator orchestration
Project-URL: Homepage, https://github.com/Hudsone/kunchi
Project-URL: Repository, https://github.com/Hudsone/kunchi
Project-URL: Issues, https://github.com/Hudsone/kunchi/issues
Project-URL: Documentation, https://github.com/Hudsone/kunchi/blob/main/docs/ROADMAP.md
Author-email: Hsiwei Chang <hudsone@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: coding-agent,cursor,harness,orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Build Tools
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# kunchi

Multi-agent coding harness for Python: **planner → implementor → validators**, with output contracts and retry loops.

Install from PyPI:

```bash
pip install kunchi
```

## CLI

Initialize a project, then run a goal in your repository:

```bash
cd /path/to/your/repo
kunchi init --template cursor    # writes .kunchi/profile.yaml
export CURSOR_API_KEY=...        # required for the cursor template
kunchi run "Your goal"
kunchi run "Your goal" --monitor   # compact progress on stderr
kunchi run "Your goal" --trace     # verbose debug trace on stdout
kunchi plans
kunchi resume PLAN_ID
```

Use `kunchi init --template fake` to try the flow without Cursor or other external agent CLIs.

Try the bundled demo (fake agents, no external dependencies):

```bash
kunchi-demo "Build a demo feature"
```

## Python API

**Fake agents** (default) — no external dependencies:

```python
from kunchi import Harness, default_harness_config

harness = Harness(default_harness_config())
report = await harness.run("Build feature")
```

**Cursor CLI** — requires the `agent` binary on `PATH`:

```python
from kunchi.harness import Harness, default_cursor_harness_config

harness = Harness(default_cursor_harness_config(workspace_path="/path/to/repo"))
report = await harness.run("Build feature")
```

**Profiles** — bundle output contracts and validators:

```python
from kunchi.harness import Harness, harness_config_from_profile

harness = Harness(harness_config_from_profile("cursor", "/path/to/repo"))
```

Load a custom profile from YAML or JSON:

```python
from kunchi.harness import Harness, harness_config_from_profile_file

harness = Harness(harness_config_from_profile_file("my-profile.yaml", "/path/to/repo"))
```

**Persist and resume plans:**

```python
from kunchi import Harness, default_harness_config
from kunchi.state import FilePlanStore

harness = Harness(default_harness_config(), plan_store=FilePlanStore(".kunchi/plans"))
report = await harness.run("Build feature")
report = await harness.resume(report.plan_id)
summaries = await harness.list_plans()
```

## Documentation

- [Design](https://github.com/Hudsone/kunchi/blob/main/docs/DESIGN.md) — architecture, agents, validators, and extension points
- [Roadmap](https://github.com/Hudsone/kunchi/blob/main/docs/ROADMAP.md) — milestones and planned work
- [Contributing](https://github.com/Hudsone/kunchi/blob/main/CONTRIBUTING.md) — development setup and manual testing

## License

MIT — see [LICENSE](LICENSE).
