kunchi 0.1.1

A simple coding harness with planner-implementor-validator orchestration

kunchi

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

Install from PyPI:

pip install kunchi

CLI

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

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):

kunchi-demo "Build a demo feature"

Python API

Fake agents (default) — no external dependencies:

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:

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:

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:

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:

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 — architecture, agents, validators, and extension points
• Roadmap — milestones and planned work
• Contributing — development setup and manual testing

License

MIT — see LICENSE.