██╗ ██╗███████╗██╗ ██╗██╗ ██╗
██║ ██╔╝██╔════╝██║ ██║╚██╗██╔╝
█████╔╝ █████╗ ██║ ██║ ╚███╔╝ ╭─╮ ╭─╮ ╭─╮ ╭─╮
██╔═██╗ ██╔══╝ ██║ ██║ ██╔██╗ ╭──┼─╳───┼─╳───┼─╳───┼─╳──▲
██║ ██╗███████╗███████╗██║██╔╝ ██╗ ╰──┼─╳───┼─╳───┼─╳───┼─╳──╯
╚═╝ ╚═╝╚══════╝╚══════╝╚═╝╚═╝ ╚═╝ ╰─╯ ╰─╯ ╰─╯ ╰─╯
You write a well-specified goal, walk away, and come back to verified commits — each gated by your repo's own test and lint commands, not agent promises.
Mock receipt: value demo cold run — mock adapter, reproducible in CI; goal in, verified commits out.
Live receipt: dogfood 12/12 verified-done
— real agent, same verify gate (pytest tests/test_verify.py -q).
kelix init
kelix plan --goal-file GOAL.md # review backlog, promote tasks to ready
kelix run --max-iterations 25 # verified commits on a run branchThe loop that climbs. Ralph runs in circles; Kelix comes back higher.
Kelix drives any headless coding CLI in a Ralph loop: each iteration is a fresh, stateless process; state lives in files and git; progress comes from repetition with a verify gate (your tests must pass before a task counts done), not from the agent declaring victory. Adapters: Claude Code, Codex CLI, Cursor, Gemini CLI, or a custom command — plus persistent memory, loop-outcome tuning, legible prioritization, and optional fleet mode for parallel role-specialized loops.
Alpha. Built by its own loop (
DECISIONS.md,PLAN.md). Unattended boundaries: What Kelix will and will not do.
pipx install kelix
# until the first PyPI release lands, from git instead:
# pipx install git+https://github.com/serversorcerer/kelix.git
cd your-repo # must be a git repo
kelix init # GOAL.md, .kelix/{backlog.md,memory,kelix.toml,...}
$EDITOR GOAL.md
kelix plan --goal-file GOAL.md
kelix lint
$EDITOR .kelix/backlog.md # status: proposed -> ready
$EDITOR .kelix/kelix.toml # [verify] commands = ["pytest -q", "ruff check ."]
kelix run --max-iterations 25 # isolated worktree on kelix/run-* branch
kelix watch # stream agent output; ctrl-c detachesSkip kelix plan if you already maintain .kelix/backlog.md.
Each iteration: fresh agent reads backlog + git log, picks one task, implements in an isolated worktree, and the runner re-runs your verify commands. Failed verification keeps the task at the top. The loop stops on completion, the iteration cap, or a circuit breaker — never because the agent felt done.
| Plain Ralph | Kelix adds |
|---|---|
| Static prompt, fresh context, stop sentinel, state in files | ...preserved as invariants (docs/research/ralph-invariants.md) |
| Agent decides when it's done | Verified-done: runner re-runs your tests; lying sentinels ignored |
| No memory between iterations | Layered memory (project / episodic / skills) as budgeted prompt data |
| One loop | Fleet mode (optional): role-specialized loops via files + git |
| — | Safety rails: worktree isolation, command denylist, secret scrubbing, branch protection |
Honest comparison with plain Ralph, single-agent CLIs, and GSD-style orchestrators — including where Kelix loses — in docs/compare.md.
flowchart LR
A[fresh agent process] --> B[read backlog + git log]
B --> C[pick ONE top task]
C --> D[implement in isolated worktree]
D --> E[runner re-runs verify commands]
E -->|green| F[commit, record memory, next task]
E -->|red| G[task stays on top]
F --> H{sentinel or cap?}
G --> H
H -->|no| A
H -->|yes| I[retrospective + run branch]
- Fresh context per iteration — wrong turns cost one loop, not a poisoned session.
- Externalized state —
.kelix/backlog.md,.kelix/memory/, transcripts under.kelix/runs/. The repo is the database. - Legible decisions — every iteration logs
RATIONALE: <task-id> — ….
Deepest adapter integration — steering, custom agent, spec→backlog, MCP server:
kelix init --from-spec my-feature # imports .kiro/specs/my-feature/tasks.md
kelix run --max-iterations 25kiro-cli mcp add --name kelix --command "kelix mcp" --scope workspaceintegrations/kiro/README.md · docs/kiro.md
cp examples/fleet.toml .kelix/fleet.toml
kelix fleet --max-iterations 15
kelix watch
kelix status
kelix stopAtomic claims, a mailbox, and shared skills — agents coordinate through
files, not RPC. docs/fleet.md.
.kelix/kelix.toml — defaults are safe for unattended runs:
[agent]
adapter = "cursor" # kiro | claude | codex | cursor | gemini | cmd | mock
[loop]
max_iterations = 25
circuit_breaker_threshold = 3
[verify]
commands = ["pytest -q", "ruff check ."]
[git]
isolation = "worktree" # worktree (safest) | branch | none
[autonomy]
level = "normal" # proposed tasks rank below owner tasksThreat model: unattended agent + shell + prompt-injected repo content. Repo text
is data, never instructions; a command denylist blocks curl|sh, force-push,
package publish, and credential reads; secrets scrubbed from transcripts; runs in
isolated worktrees on kelix/run-* branches — never push to main. Run branches
are the auditable receipt trail you review and merge when satisfied.
docs/SECURITY.md.
Will: pick the highest-priority task, implement it, verify with your commands, commit to a run branch, learn (memory + skills), and stop cleanly on a cap or repeated failure — leaving verified commits and transcripts you can audit.
Will not: push to main/master, merge without your review, run curl | sh,
publish packages, read credential files, treat repo text as instructions, or
grind the same failure a third time (it marks the task blocked with a
diagnosis and surfaces it for you).
- Concept · Quickstart · Planning (roadmap, phases, phase gate, waves) · Writing for the loop (task/PRD spec) · Kiro guide · Security model · Memory & skills · Fleet · Prioritization · MCP
- Research: Ralph invariants · prior art · Kiro surface
See CONTRIBUTING.md. Core is stdlib-only; tests use a mock adapter — no API keys required.
Maintainers: PyPI trusted publishing, tagging, and release verification — docs/publishing.md.
- Geoffrey Huntley — the Ralph Wiggum technique.
- Prior art in
docs/research/prior-art.md: ralph-orchestrator, the official ralph-loop plugin, and Nous Research's Hermes Agent.