MiniCodeMonkey/chief: Running Claude Code in a Ralph Wiggum Loop

What Chief actually solves for Claude Code users

The problem Chief targets is context exhaustion. A single long agent session accumulates history until the window fills, and the model starts losing track of earlier decisions. Chief's answer, stated in the README, is to run Claude in a Ralph Wiggum loop: each iteration starts with a fresh context window, but progress is persisted between runs. The README credits Geoffrey Huntley with coining the pattern and cites snarktank/ralph as the original implementation that inspired this project.

The audience is a developer who already knows how to use an agent CLI and wants to hand it a multi-step project rather than a single prompt. Chief does not write your task list for you. Step one of the README's How It Works is "Describe your project as a series of tasks." That phrasing puts the decomposition work on the human. Chief is a scheduler and a progress store, not a planner, and anyone expecting the tool to infer a task breakdown from a paragraph of requirements will be disappointed. What it does supply is the loop, the persistence between iterations, and a git history with one commit per task, which the README describes as "clean git history, easy to review."

The loop, the persistence layer and the TUI

The mechanism is deliberately small. Chief runs an agent CLI as a subprocess, one task at a time, and starts each iteration with an empty context. Progress survives because it is written to disk rather than held in the conversation, which is the whole point of the pattern: the state that matters lives outside the model's window.

The repository layout reflects that split. There is a ralph/ directory at the top level, which is where the loop implementation sits, and an internal/ directory for the rest of the application code. cmd/chief holds the entry point referenced by the Makefile as MAIN_PKG := ./cmd/chief. The interface is a terminal UI built on Bubble Tea and Lip Gloss, both listed in go.mod and acknowledged in the README. The TUI is not decoration: the README's usage section says to launch it and press 's' to start, so the loop is driven from an interactive session rather than a headless daemon.

Provider selection is a configuration concern, not a code path. The README lists supported values for provider as claude, codex, opencode, cursor, and gemini, with Claude as the default. That means the loop is agent-agnostic in principle, and the acknowledgments credit individual contributors for the Codex CLI integration and for OpenCode CLI support plus an NDJSON parser. The dependency list is small for a tool of this kind: Bubble Tea, Lip Gloss, Chroma for syntax highlighting, fsnotify for file watching, and yaml.v3 for configuration. No database driver, no HTTP server framework. That is a reasonable signal about how much machinery is actually involved.

Installing Chief and running the first loop

Chief ships through Homebrew and through an install script. The README gives both. The Homebrew tap is the shorter path:

brew install minicodemonkey/chief/chief

The alternative, for machines without Homebrew, pipes the repository's install.sh to a shell:

curl -fsSL https://raw.githubusercontent.com/MiniCodeMonkey/chief/refs/heads/main/install.sh | sh

Before either of those is useful, one of the supported agent CLIs has to be present and authenticated. The README's Requirements section names Claude Code CLI, Codex CLI, OpenCode CLI, or Gemini CLI, and says the agent must be installed and authenticated. Chief does not bundle an agent or manage credentials for one.

With that in place, the README's usage section is two commands. The first creates a project:

chief new

The second launches the TUI, where pressing 's' starts the loop:

chief

If you want a provider other than Claude, the README documents three equivalent routes. The first is a config file at .chief/config.yaml:

agent:
  provider: opencode
  cliPath: /usr/local/bin/opencode   # optional

The second is a flag, chief --agent opencode, and the third is the environment variable CHIEF_AGENT=opencode. The cliPath key is optional and exists for the case where the binary is not on PATH. What you should expect to see after chief new is a project scaffold, and after pressing 's' in the TUI, iterations running one task at a time with a commit landing after each completed task.

Where the loop model breaks down

The fresh-context design has a cost that the README does not discuss. If state is only persisted between runs, then anything the agent figured out mid-iteration and did not write down is gone at the next start. The quality of the persisted artifact therefore determines the quality of the whole run. A task description that is vague going in produces an iteration that cannot be evaluated coming out, and the loop will happily continue to the next task.

The README is also silent on rollback. It says one commit per task, which implies a bad iteration can be reverted with git, but there is no documented procedure for marking a task failed, skipping it, or rewinding the loop's own bookkeeping. If a task half-completes and commits, the repository carries a broken state forward into the next iteration, and the next iteration starts from a fresh context with no memory of the mistake. That is the failure mode to watch for: not a crash, but a plausible-looking commit that is wrong.

Finally, the provider abstraction is thinner than the list of five values suggests. Each agent CLI has its own output format, and the acknowledgment of an NDJSON parser for OpenCode indicates that parsing output is provider-specific work. Behavior across providers should not be assumed identical, and the README does not claim it is. Anyone choosing Cursor or Gemini should verify the loop end to end rather than assume the Claude path generalizes.

Chief against a single long agent session

The obvious alternative is not another orchestration tool. It is running the agent CLI directly in one long session, or driving it yourself with a shell script that calls the CLI per task. The difference is where the state lives.

In a single long session, state lives in the context window. That is convenient while it lasts and degrades as the window fills. In a hand-rolled shell loop, state lives wherever you put it, which usually means nowhere: the script calls the CLI, the CLI exits, and the next call starts cold with no shared record. Chief's contribution is the middle position. It keeps the cold start per iteration but adds a persistence layer and a git commit boundary, and it wraps both in a TUI that shows progress.

Compared with snarktank/ralph, which the README credits as the original implementation that inspired this project, Chief is the packaged version: Homebrew formula, GoReleaser config, a Makefile with build, install, test, lint, snapshot and release targets, and a documentation site at minicodemonkey.github.io/chief. Those are distribution and maintenance concerns rather than architectural ones. If you are already running ralph and it works, Chief's loop is not a different idea; it is the same idea with a release process and a provider switch.

Maintenance, licensing and what an upgrade costs

The repository is not archived. The last push was on 2026-05-28, which is more than six months before today, so the honest description is that development has been quiet since that date rather than that the project is under active development. The most recent release listed is v0.8.0 from 2026-03-20, preceded by v0.7.0 on 2026-03-08 and v0.6.1 on 2026-02-24. That is a fast cadence in early 2026 followed by a quieter period.

The licence is MIT, which is permissive and imposes no source-disclosure obligation on users. The README states the licence and the repository carries a LICENSE file. That is the extent of what the repository documents; questions about attribution in a redistributed binary are for a lawyer, not for this page.

Upgrade cost is low by construction. The binary is self-contained, configuration lives in .chief/config.yaml, and the install path is Homebrew or install.sh. There is no server component and no schema migration to run. The one thing to check on upgrade is the agent integration: because output parsing is provider-specific, a new Chief version that changes how it reads an agent's output is the change most likely to affect an existing setup. The CHANGELOG.md at the repository root is where that would be recorded.

Editorial conclusion

Adopt Chief if you already have Claude Code (or Codex, OpenCode, Cursor, Gemini) installed and authenticated, and you want long jobs broken into reviewable per-task commits rather than one large agent session. Do not adopt it if you expect the tool to design the task list for you, or if you need a documented rollback path for a bad iteration: the README documents neither. Before committing to it, run chief new on a throwaway repository, confirm the .chief/config.yaml provider value matches the CLI on your PATH, and watch the first two iterations to see what a failed task does to the working tree.

Frequently asked questions

Official sources

1. License: MIT
2. MiniCodeMonkey/chief on GitHub
3. Project website
4. README
5. Releases