Meta Agent Tools
PT

Back to the catalog

kkachi

Portable Top-1 greedy loop engine for coding agents.

Open source Open in the app JSON README (API)

About

Portable Top-1 greedy loop engine for coding agents.

Details

Kind
Plugins
Topic
No topic detected
Publisher
jaichangpark
Origin
gemini
Category
ferramentas
Version
0.1.0
Forks
1
Last push
2026-02-21T13:43:54Z
Repository state
ativo
Language
Python
License
Apache-2.0
Added
2026-08-30 14:13:39
Updated
2026-08-30 14:13:39
Origin id
jaichangpark/kkachi

README

# Kkachi

Portable Top-1 greedy loop engine for coding agents.

Kkachi keeps selection logic in one Python core and provides thin integrations for:

- Gemini CLI extension
- OpenCode project/global runtime
- Generic shell loop for Codex, Claude Code, or any agent runner

Language docs:

- [Korean](README.ko.md)
- [Japanese](README.ja.md)
- [Chinese (Simplified)](README.zh-cn.md)

## Agent Compatibility and Install Matrix

| Agent | Support Level | Install | Notes |
| --- | --- | --- | --- |
| Gemini CLI | Native extension | `bash scripts/install_gemini.sh` | Slash commands + `AfterAgent` hook |
| OpenCode | Native integration | `bash scripts/install_opencode.sh` | Project/global install supported |
| Codex | Supported via loop + skill | `bash scripts/install_skills.sh --target codex` | Uses local scripts/prompts and optional Codex skill |
| Claude Code | Supported via loop + skill | `bash scripts/install_skills.sh --target claude` | Uses local scripts/prompts and optional Claude skill |
| Any shell-capable coding agent | Portable loop | No special installer required | Run `scripts/setup.sh -> next.sh -> mark.sh` |

## Skills Support

Yes. This repo now includes a reusable skill package:

- `skills/kkachi/SKILL.md`

Install skill pack:

```bash
# install for both Codex + Claude
bash scripts/install_skills.sh --target all

# only Codex
bash scripts/install_skills.sh --target codex

# only Claude Code
bash scripts/install_skills.sh --target claude
```

Uninstall skill pack:

```bash
bash scripts/uninstall_skills.sh --target all
```

Manual install (without script):

- Copy `skills/kkachi/` to `~/.codex/skills/kkachi`
- Copy `skills/kkachi/` to `~/.claude/skills/kkachi`

## One-line Value

Ship more by forcing one validated next step at a time.

## Why Teams Adopt Kkachi

- Deterministic and explainable task choice (`rank`, `select`, `explain`)
- Safe execution contract (exactly one task per iteration)
- Cross-agent portability (Gemini + OpenCode + generic shell)
- File-based state you can inspect and version (`.kkachi/`, `.gemini/kkachi/`)
- Built-in operational modes for different delivery phases

## Best-fit Use Cases

| Use case | Recommended mode | Why it works |
| --- | --- | --- |
| Startup feature shipping | `kkachi-ship-fast` | Pushes visible progress and quick wins |
| CI instability / regression days | `kkachi-stabilize` or `kkachi-incident` | Stronger fail-first and risk controls |
| Dependency bottlenecks | `kkachi-unblock` | Prioritizes tasks that unlock more work |
| Unknown requirements / investigation | `kkachi-discover` | Increases information gain with exploration |
| Refactor / debt cleanup sprint | `kkachi-debt-burn` | Balances debt reduction with change safety |

## Why Kkachi

Kkachi enforces one simple contract per iteration:

1. Rank pending tasks.
2. Pick exactly one Top-1 task.
3. Execute and verify.
4. Mark success/fail.

This prevents multi-task drift and makes progress measurable in files (`tasks.json`, loop state JSON).

## Core Scoring Policy

Default score formula:

```text
score =
  + 5 * fail_first
  + 4 * priority
  + 3 * kkachi-unblock
  + 2 * quick_win
  + 2 * impact
  + 1 * info_gain
  - 3 * risk
  - 2 * effort
  - 4 * failures
```

Definitions:

- `fail_first`: `1` only when `--tests-failing` is on and task `kind == "fix"`.
- `quick_win`: `1` when `effort <= 2` and `risk <= 2`.
- `failures`: prior failed attempts for that task.

Tie-break order:

1. Lower `effort`
2. Lower `risk`
3. Higher `priority`
4. Lexicographic `id`

Exploration:

- Epsilon-greedy is supported (`--epsilon`).
- During exploration, selection is random from ranks 2..3 (when available).

## Built-in Modes

Modes live under `modes/*.json`.

```bash
python3 kkachi_greedy.py modes
python3 kkachi_greedy.py modes --json
```

| Mode | Goal | Default epsilon |
| --- | --- | --- |
| `kkachi-ship-fast` | Maximize visible delivery speed / quick wins | `0.05` |
| `kkachi-stabilize` | Reliability first, reduce breakage and risk | `0.0` |
| `kkachi-unblock` | Resolve dependency bottlenecks | `0.05` |
| `kkachi-discover` | Maximize information gain under uncertainty | `0.2` |
| `kkachi-debt-burn` | Reduce technical debt with risk control | `0.02` |
| `kkachi-incident` | Incident / outage / CI emergency mode | `0.0` |

### Mode Deep Dive

| Mode | Primary objective | Dominant positive terms | Strong penalties | When to use | Avoid when |
| --- | --- | --- | --- | --- | --- |
| `kkachi-ship-fast` | Maximize visible output per turn | `priority=4`, `quick_win=4`, `impact=4` | `effort=3`, `risk=2` | Early feature sprint, demo week, MVP push | Critical outage where reliability must dominate |
| `kkachi-stabilize` | Reduce breakage and repeated failures | `fail_bonus=8`, `kkachi-unblock=3` | `risk=6`, `failure_penalty=6` | Flaky CI, regression cleanup, release hardening | You need exploratory discovery speed |
| `kkachi-unblock` | Unlock downstream work quickly | `kkachi-unblock=8` | Moderate `risk=2`, `effort=2` | Dependency bottlenecks, blocked team queues | Independent tasks with no dependency graph |
| `kkachi-discover` | Buy information under uncertainty | `info_gain=7`, `impact=2` | Low `effort=1`, `risk=2` | Root-cause analysis, unknown requirements, research spikes | Strict deterministic delivery windows |
| `kkachi-debt-burn` | Burn debt with controlled blast radius | `quick_win=3`, `priority=3` | `effort=4`, `risk=4`, `failure_penalty=4` | Refactor weeks, quality initiatives, cleanup periods | Aggressive feature expansion targets |
| `kkachi-incident` | Fast kkachi-incident containment and service restore | `fail_bonus=10`, `priority=5`, `kkachi-unblock=4` | `risk=5`, `failure_penalty=6` | Production outage, broken CI/CD, emergency fixes | Normal roadmap work where exploration is valuable |

Practical notes:

- `kkachi-incident` is most effective with `--tests-failing`, because fix tasks get the largest fail-first bonus.
- `kkachi-discover` intentionally uses the highest default exploration (`epsilon=0.2`).
- `kkachi-stabilize` and `kkachi-incident` set `epsilon=0.0` to keep behavior deterministic during high-risk periods.
- `kkachi-debt-burn` strongly discourages long/high-risk tasks unless payoff is clear.

Mode-specific ranking examples:

```bash
python3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi --json
python3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-stabilize --json
python3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-unblock --json
python3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-discover --json
python3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-debt-burn --json
python3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-incident --tests-failing --json
```

Mode resolution order:

1. `--mode-file` (explicit custom mode JSON)
2. `--mode` + `--mode-dir`
3. No mode (base defaults)

Weight merge order:

1. Base `Weights` defaults
2. Mode `weights` override
3. `--weights-file` (or config file) override

## Requirements

- `python3` (tested in CI with 3.11)
- `jq`
- `bash`

Optional (integration-specific):

- `gemini` CLI for Gemini extension install
- OpenCode runtime for `/kkachi-*` commands

## Quick Start (Local Loop)

Initialize:

```bash
bash scripts/init.sh
bash scripts/doctor.sh .kkachi/tasks.json .kkachi/config.json
```

Inspect ranking:

```bash
python3 kkachi_greedy.py rank .kkachi/tasks.json \
  --weights-file .kkachi/config.json \
  --mode kkachi \
  --json
```

Run one iteration:

```bash
bash scripts/setup.sh "Implement feature X with tests"
bash scripts/status.sh
TASK_ID=$(bash scripts/next.sh)
bash scripts/render_step_prompt.sh
# Work and verify...
bash scripts/mark.sh "$TASK_ID" success
```

Check completion:

```bash
python3 kkachi_greedy.py pending .kkachi/tasks.json
```

## Cross-Agent Usage (Codex / Claude Code / OpenCode)

Shared loop files:

- `.kkachi/tasks.json`
- `.kkachi/config.json`
- `.gemini/kkachi/state.json` (active loop state)

Common flow:

1. `bash scripts/setup.sh "<goal prompt>" ...`
2. `bash scripts/status.sh`
3. `TASK_ID=$(bash scripts/next.sh)`
4. Execute only `TASK_ID`
5. Verify
6. `bash scripts/mark.sh "$TASK_ID" success|fail`
7. Repeat

Reference: `docs/CROSS_CLI.md`.

## Task JSON Schema

Task file must be a JSON array.

Each task object supports:

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | string | required | Must be unique |
| `title` | string | `id` | Display text |
| `priority` | int | `1` | `>= 0` |
| `impact` | int | `1` | `>= 0` |
| `effort` | int | `1` | `>= 0` |
| `risk` | int | `1` | `>= 0` |
| `kkachi-unblock` | int | `0` | `>= 0` |
| `info_gain` | int | `0` | `>= 0` |
| `kind` | string | `feature` | Use `fix` for fail-first bonus |
| `status` | string | `pending` | One of `pending`, `done`, `blocked` |
| `failures` | int | `0` | `>= 0` |

Validation (`doctor`) checks:

- Duplicate task IDs
- Invalid statuses
- Negative numeric values
- Invalid runtime/mode/weights payloads

## Config and Weights

Example config: `examples/config.json`:

- Loop settings:
  - `tests_failing`
  - `seed`
  - `block_after`
  - `max_iterations`
  - `completion_promise`
  - `mode`
- Weight overrides:
  - Either top-level weight keys or nested `weights` object

`scripts/setup.sh` behavior:

- Creates missing task/config files from `examples/`.
- Reads config values.
- CLI flags override config values.
- Persists state to `.gemini/kkachi/state.json`.

## CLI Reference (`kkachi_greedy.py`)

### `rank`

Rank pending tasks, show Top-1 selection.

```bash
python3 kkachi_greedy.py rank <tasks.json> [options]
```

Options:

- `--tests-failing`
- `--epsilon <0..1>`
- `--seed <int>`
- `--weights-file <path>`
- `--mode <name>`
- `--mode-file <path>`
- `--mode-dir <path>`
- `--json`

### `select`

Print selected task ID (or JSON payload).

```bash
python3 kkachi_greedy.py select <tasks.json> [options]
```

Behavior:

- Exit code `1` when no pending tasks.

### `pending`

Print count of `pending` tasks.

```bash
python3 kkachi_greedy.py pending <tasks.json>
```

### `apply`

Apply one execution result.

```bash
python3 kkachi_greedy.py apply <tasks.json> <task_id> \
  --result success|fail \
  [--block-after 3]
```

Behavior:

- `success`: status -> `done`
- `fail`: increments `failures`; status -> `blocked` when `failures >= block_after`

### `loop`

Simulated greedy loop (for testing policy behavior).

```bash
python3 kkachi_greedy.py loop <tasks.json> [options]
```

Loop-specific options:

- `--max-steps <int>` (default `20`)
- `--auto-success-rate <0..1>` (default `1.0`)
- `--write` to persist updates

### `explain`

Explain score breakdown for one task.

```bash
python3 kkachi_greedy.py explain <tasks.json> <task_id> [options]
```

Output includes:

- task payload
- effective weights
- selected mode
- per-term scoring breakdown

### `doctor`

Validate tasks and runtime inputs.

```bash
python3 kkachi_greedy.py doctor <tasks.json> [options]
python3 kkachi_greedy.py doctor <tasks.json> --json
```

Behavior:

- Exit code `0` when valid
- Exit code `2` on validation/runtime issues

### `modes`

List available modes.

```bash
python3 kkachi_greedy.py modes [--mode-dir <path>] [--json]
```

## Runtime Script Reference (`scripts/`)

| Script | Purpose |
| --- | --- |
| `init.sh` | Create task/config files from `examples/` and run `doctor` |
| `setup.sh` | Initialize active loop state from prompt + config + flags |
| `status.sh` | Print iteration/status summary and current Top-1 |
| `next.sh` | Select next Top-1 task (`select`) |
| `render_step_prompt.sh` | Print one-step contract prompt for agent handoff |
| `mark.sh` | Apply `success|fail` to a selected task |
| `doctor.sh` | Wrapper around Python `doctor` + dependency checks |
| `cancel.sh` | Stop loop and remove `.gemini/kkachi/state.json` |
| `install_gemini.sh` | Install extension and optionally patch `~/.gemini/settings.json` |
| `uninstall_gemini.sh` | Uninstall extension and clean settings include path |
| `install_opencode.sh` | Install OpenCode runtime/commands/rules (project or global) |
| `uninstall_opencode.sh` | Remove OpenCode runtime/commands/rules and config reference |
| `install_skills.sh` | Install `skills/kkachi` into Codex/Claude skill directories |
| `uninstall_skills.sh` | Remove installed Codex/Claude skill directories |

## Gemini CLI Extension

Extension metadata:

- `gemini-extension.json`
- `commands/kkachi/*.toml`
- `hooks/hooks.json`
- `hooks/stop-hook.sh`

Install:

```bash
bash scripts/install_gemini.sh
```

Manual:

```bash
gemini extensions install <repo-url> --auto-update
```

Commands:

- `/kkachi:init`
- `/kkachi:loop "<goal prompt>" [options]`
- `/kkachi:status`
- `/kkachi:modes`
- `/kkachi:cancel`
- `/kkachi:help`

`/kkachi:loop` options:

- `--tasks-file <path>`
- `--config-file <path>`
- `--weights-file <path>`
- `--mode <name>`
- `--mode-file <path>`
- `--mode-dir <path>`
- `--max-iterations <n>`
- `--completion-promise <text>`
- `--tests-failing`
- `--epsilon <0..1>`
- `--seed <int>`
- `--block-after <n>`

Hook behavior (`AfterAgent`):

- Continues loop while pending tasks exist and max iterations not reached.
- Stops when:
  - no pending tasks
  - completion promise appears (`<promise>...</promise>`)
  - prompt mismatch
  - max iterations reached
- On continue, denies current continuation and requests fresh context (`clearContext: true`).

Uninstall:

```bash
bash scripts/uninstall_gemini.sh
```

## OpenCode Integration

Installer generates runtime from templates in `integrations/opencode/template/`.

Project install:

```bash
bash scripts/install_opencode.sh
```

Global install:

```bash
bash scripts/install_opencode.sh --global
```

Installed artifacts:

- `.opencode/kkachi/kkachi_greedy.py`
- `.opencode/kkachi/scripts/*.sh`
- `.opencode/kkachi/examples/*.json`
- `.opencode/kkachi/modes/*.json`
- `.opencode/commands/kkachi-{init,loop,status,modes,cancel}.md`
- `.opencode/plugins/kkachi-idle.ts`
- `.opencode/rules/kkachi.md`
- `opencode.json` merged with `instructions` entry

OpenCode commands:

- `/kkachi-init`
- `/kkachi-loop`
- `/kkachi-status`
- `/kkachi-modes`
- `/kkachi-cancel`

Uninstall:

```bash
bash scripts/uninstall_opencode.sh
bash scripts/uninstall_opencode.sh --global
```

## Agent Prompt Contracts

Reusable iteration contracts:

- `prompts/codex.md`
- `prompts/claude_code.md`
- `prompts/opencode.md`

Agent instruction snippets:

- `agents/codex/AGENTS.md`
- `agents/claude_code/CLAUDE.md`
- `agents/opencode/AGENTS.md`

All enforce:

- one selected task per iteration
- verification before marking
- exactly one mark operation ends the iteration

## Repository Layout

```text
.
├─ kkachi_greedy.py                 # core policy engine + CLI
├─ modes/                           # mode presets
├─ examples/                        # sample tasks/config
├─ scripts/                         # runtime/install wrappers
├─ commands/kkachi/                 # Gemini slash command templates
├─ hooks/                           # Gemini loop control hook
├─ integrations/opencode/template/  # OpenCode template assets
├─ agents/                          # agent-specific instruction snippets
├─ prompts/                         # copy/paste loop prompts
├─ docs/                            # installation and cross-cli docs
├─ tests/test_kkachi_greedy.py      # unit tests
└─ .github/workflows/ci.yml         # CI pipeline
```

## Development and CI

Local checks:

```bash
python3 -m unittest kkachi-discover -s tests -p "test_*.py"
bash -n hooks/stop-hook.sh scripts/*.sh
python3 kkachi_greedy.py doctor examples/tasks.json --weights-file examples/config.json
python3 kkachi_greedy.py modes
python3 kkachi_greedy.py explain examples/tasks.json CI-01 --weights-file examples/config.json
```

CI (`.github/workflows/ci.yml`) runs:

- unit tests
- shell parse checks
- sample data validation (`doctor`, `modes`, `explain`)

## Troubleshooting

- `Unknown mode '<name>'`: run `python3 kkachi_greedy.py modes`.
- `invalid status` / duplicate IDs: run `python3 kkachi_greedy.py doctor <tasks.json> --json`.
- `jq is required`: install `jq` for shell wrappers.
- Loop not advancing in Gemini: check `.gemini/kkachi/state.json`, completion promise, and max iterations.

## Additional Docs

- Installation variants: `docs/INSTALL.md`
- Cross-agent workflow: `docs/CROSS_CLI.md`
- Contribution rules: `CONTRIBUTING.md`
- 10k star growth playbook: `docs/GROWTH_10K_STARS.md`
- Technical report draft (arXiv): `paper/main.tex`

More