kunchi 0.1.0

A simple coding harness with planner-implementor-validator orchestration

kunchi

A Simple Coding Harness (Python)

Multi-agent orchestration: planner → implementor → sequential validators, with output contracts and retry loops.

Quick start

pip install kunchi
# or for development:
pip install -e ".[dev]"
pytest
python3 -m kunchi.examples.demo "Build a demo feature"

The demo uses fake agents (no external CLIs) to exercise the full harness flow.

CLI (recommended for real repos)

pip install -e ".[dev]"
cd /path/to/your/repo
kunchi init --template cursor    # writes .kunchi/profile.yaml
export CURSOR_API_KEY=...        # for cursor template
kunchi run "Your goal"
kunchi run "Your goal" --monitor   # compact progress lines 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. See docs/ROADMAP.md.

See docs/MANUAL_TESTING.md for manual smoke tests. Development progress and a good enough to start checklist are in docs/ROADMAP.md. Runnable scripts are in src/kunchi/examples/manual/:

python3 -m kunchi.examples.manual.harness_fake
python3 -m kunchi.examples.manual.cli_runner
python3 -m kunchi.examples.manual.cli_agent_fake_binary

hello()

kunchi exports a small public hello() helper (see src/kunchi/hello.py). It returns the string "hello".

from kunchi import hello

hello()  # "hello"

Agent backends

Fake agents (default) — no external dependencies:

from kunchi import Harness, default_harness_config

harness = Harness(default_harness_config())

Cursor CLI — requires the agent binary on PATH; tasks require summary + git_commit and run ruff / pytest shell validators before Cursor review:

from kunchi.harness import Harness, default_cursor_harness_config

harness = Harness(default_cursor_harness_config(workspace_path="/path/to/repo"))

Profiles bundle fixed output contracts and validators; register custom ones or load from a dict:

from kunchi.harness import harness_config_from_profile
from kunchi.profiles import ProfileRegistry, load_profile

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

# Dynamic / file-based (same shape a planner could emit later):
from pathlib import Path

from kunchi.harness import harness_config_from_profile_file
from kunchi.profiles import ProfileRegistry, load_profile, load_profile_file

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

profile = load_profile_file(Path("my-profile.json"))
registry = ProfileRegistry.default()
registry.register(profile)
harness = Harness(harness_config_from_profile(profile.name, ".", registry=registry))

# Or in one step:
harness = Harness(harness_config_from_profile_file("my-profile.yaml", "/path/to/repo"))

Or configure agents explicitly:

from kunchi import Harness, HarnessConfig
from kunchi.models.agent import AgentRole, AgentSpec
from kunchi.models.context import WorkspaceConfig

config = HarnessConfig(
    planner=AgentSpec(id="planner", role=AgentRole.PLANNER, config={"cli": "cursor"}),
    workspace=WorkspaceConfig(path="."),
    default_validators=[
        AgentSpec(id="lint", role=AgentRole.VALIDATOR, config={"cli": "shell", "command": "ruff check ."}),
    ],
)
harness = Harness(config)

Extending integrations

External system adapters live under src/kunchi/providers/:

• Agent clients (providers/agents/) — implement AgentClient and register in AgentClientRegistry (Cursor is built in)
• VCS backends (providers/vcs/) — implement VCSBackend and register in VCSRegistry (git is built in; hg is stubbed)

See docs/DESIGN.md sections 9 and 17 for details.

Persist plan state to disk (resume / inspect after a run):

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

# After an interrupt or partial run, continue from persisted state:
report = await harness.resume(report.plan_id)

# List saved plans:
summaries = await harness.list_plans()