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:

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:

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

Rank pending tasks.
Pick exactly one Top-1 task.
Execute and verify.
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:

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:

Lower effort
Lower risk
Higher priority
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.

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:

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:

--mode-file (explicit custom mode JSON)
--mode + --mode-dir
No mode (base defaults)

Weight merge order:

Base Weights defaults
Mode weights override
--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 scripts/init.sh
bash scripts/doctor.sh .kkachi/tasks.json .kkachi/config.json

Inspect ranking:

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

Run one iteration:

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:

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:

bash scripts/setup.sh "<goal prompt>" ...
bash scripts/status.sh
TASK_ID=$(bash scripts/next.sh)
Execute only TASK_ID
Verify
bash scripts/mark.sh "$TASK_ID" success|fail
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.

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

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

Behavior:

Exit code 1 when no pending tasks.

`pending`

Print count of pending tasks.

python3 kkachi_greedy.py pending <tasks.json>

`apply`

Apply one execution result.

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

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.

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.

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.

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
`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 scripts/install_gemini.sh

Manual:

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 scripts/uninstall_gemini.sh

OpenCode Integration

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

Project install:

bash scripts/install_opencode.sh

Global install:

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

.
├─ 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:

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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
agents		agents
commands/kkachi		commands/kkachi
docs		docs
examples		examples
hooks		hooks
integrations/opencode		integrations/opencode
modes		modes
paper		paper
prompts		prompts
scripts		scripts
skills/kkachi		skills/kkachi
tests		tests
.DS_Store		.DS_Store
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.ko.md		README.ko.md
README.md		README.md
README.zh-cn.md		README.zh-cn.md
gemini-extension.json		gemini-extension.json
kkachi_greedy.py		kkachi_greedy.py
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Kkachi

Agent Compatibility and Install Matrix

Skills Support

One-line Value

Why Teams Adopt Kkachi

Best-fit Use Cases

Why Kkachi

Core Scoring Policy

Built-in Modes

Mode Deep Dive

Requirements

Quick Start (Local Loop)

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

Task JSON Schema

Config and Weights

CLI Reference (kkachi_greedy.py)

rank

select

pending

apply

loop

explain

doctor

modes

Runtime Script Reference (scripts/)

Gemini CLI Extension

OpenCode Integration

Agent Prompt Contracts

Repository Layout

Development and CI

Troubleshooting

Additional Docs

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

CLI Reference (`kkachi_greedy.py`)

`rank`

`select`

`pending`

`apply`

`loop`

`explain`

`doctor`

`modes`

Runtime Script Reference (`scripts/`)

Packages