Pickle Rick for Gemini CLI: A Hook-Driven Agent Loop for Iterative Coding

The problem Pickle Rick targets: single-pass agents that stop too early

Most CLI coding agents are single-pass. You give a prompt, the model works, and it declares itself finished. If the tests still fail, you re-prompt by hand, usually with less context than the agent had in its own files. Pickle Rick exists to remove that manual re-prompting. The README frames the technique as "continuous AI agent loops," borrowed from what it calls the "Ralph Wiggum" technique, summarized as "Ralph is a Bash loop": a construct that repeatedly feeds an AI agent a prompt so it can improve its own work until done. The intended user is someone with a well-defined task and an automatic pass/fail signal. The README lists exactly that: getting tests to pass, greenfield projects you can walk away from, tasks with automatic verification such as tests or linters. It also lists the inverse: tasks needing human judgment or design decisions, one-shot operations, tasks with unclear success criteria, and production debugging, for which it points you at targeted debugging instead. That is a narrower audience than the persona suggests.

How the loop works: an AfterAgent hook that blocks exit and re-feeds the prompt

The mechanism is not an external shell loop. The README states the loop happens inside your current session, implemented by an AfterAgent hook whose handler lives at extension/hooks/handlers/stop-hook.js. The sequence it describes is: you run /pickle once with a task and a completion promise, the agent works, the agent tries to exit, the hook blocks that exit, and the hook feeds the same prompt back. The prompt never changes between iterations, which the README says is deliberate to keep focus. State persists through files, not through conversation memory: each iteration sees modified files and git history, and the agent improves by reading its own past work. Around that core, the extension layers a six-phase lifecycle: PRD, Breakdown, Research, Plan, Implement, Refactor. Each phase maps to a named skill such as prd-drafter, ticket-manager, code-researcher, implementation-planner, and load-pickle-persona, which the README says activates the persona. The loop is therefore two things at once: a control-flow trick and a process scaffold. The control-flow trick is the interesting part; the scaffold is the part that consumes tokens.

Installation and the two config blocks that decide whether it works

Installation is one command: gemini extensions install https://github.com/galz10/pickle-rick-extension. Prerequisites are Gemini CLI version greater than 0.25.0-preview.0, Agent Skills and Hooks enabled, and Node.js, which the README says is required for orchestration and hooks. Enabling is manual and the README treats it as mandatory. In .gemini/settings.json you set tools.enableHooks to true and experimental.skills to true. Separately, you must add the extension data directory to context.includeDirectories, as "~/.gemini/extensions/pickle-rick". The README is direct about the consequence of skipping that second block: without it the agent is "blind" to its own progress between iterations, because it cannot read or write the sessions directory where PRDs, tickets, research, and plans live. That directory is ~/.gemini/extensions/pickle-rick/sessions, and it is also where you inspect what the agent did. Note the README's own numbering bug: the two configuration steps are both labeled "2". The install command is stated; the README does not document an uninstall path.

Running a session: commands, flags, and the termination conditions

The entry point is /pickle with a task string, for example /pickle "Refactor the authentication module". Termination is governed by several flags with defaults: --max-iterations (default 5), --max-time in minutes (default 60), --worker-timeout in seconds (default 1200, with the README also stating individual workers have a 20m timeout), --name for a custom session directory slug, and --completion-promise, which stops the loop only when the agent emits a matching <promise>TEXT</promise> tag. The README's warning is unambiguous: the loop continues until the task is complete, max-iterations is reached, max-time expires, or the completion promise is fulfilled. A separate /pickle-prd command drafts requirements interactively before the loop starts, and /pickle --resume continues an existing session, defaulting to the latest one for the current working directory. Control commands are /eat-pickle to stop or cancel, /add-to-pickle-jar to queue a task, /pickle-jar-open to execute queued tasks, and /send-to-morty, which the README marks internal and describes as spawning Morty instances from the manager. The default of five iterations is low enough that a genuinely iterative task will often hit the cap before the promise fires; the promise flag, not the iteration cap, is what you should treat as the real stopping condition.

Where Pickle Rick is the wrong tool

The README's own warning is the strongest limitation and it is not boilerplate: this is described as a fun side project and experimental demonstration, involving autonomous code modification and shell execution, and the agent may behave unexpectedly and consume a significant number of tokens. Three failure modes follow from the design rather than from bugs. First, cost is unbounded in the direction that matters: the loop re-feeds an identical prompt, so every iteration re-sends the same instruction plus whatever the agent reads from disk, and the only hard ceilings are iteration count and wall-clock time. Second, the completion promise is a string match on model output. An agent that writes <promise>DONE</promise> into a file, or emits it prematurely, ends the loop without the task being finished. Third, the persistence model depends on that includeDirectories entry being correct; if the path is wrong the agent cannot see its own prior work, and the loop degrades into the same prompt repeated with no accumulating state, which is the worst possible version of this design. The README also rules out production debugging and design-decision work, and those exclusions are worth taking literally rather than as modesty.

Comparison with plain Gemini CLI and with external bash loops

The README positions Pickle Rick against the technique it is based on. An external bash loop that invokes an agent repeatedly has the same core idea, but each invocation starts a fresh process: conversation state is gone, and continuity comes only from files on disk. Pickle Rick's AfterAgent hook keeps the loop inside one session, so the agent's context survives across iterations rather than being rebuilt from the filesystem each time. That is the actual difference in approach, and it is a real one, though it cuts both ways: a long-lived session accumulates context that a fresh process would not. Against plain Gemini CLI without the extension, the difference is process rather than mechanism. Stock Gemini CLI gives you a single conversational turn sequence with no enforced phases and no exit interception. Pickle Rick adds the six-phase lifecycle, the skill set, and the session directory that holds PRDs, tickets, research, and plans as artifacts you can read afterward. If you already drive iteration with your own wrapper script and you do not want a persona or a phase structure, the stock CLI plus your script is the simpler arrangement, and you keep control of the stopping condition instead of delegating it to a promise tag.

Maintenance, licensing, and what the repository does not tell you

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements to retain notices and state changes; that is a general description of the licence text, not legal advice, and you should read the LICENSE file in the repository before redistributing a modified version. The extension is not archived and the last push recorded is 2026-05-14. No releases were retrieved, so there is no versioned artifact to pin: installation pulls from the main branch of the git URL, which means an upgrade is whatever lands on main between your install and your next install. That is the real maintenance cost here, and it is not small. A change to extension/hooks/handlers/stop-hook.js changes loop behaviour directly, and you have no release boundary to test against. The README does not document an uninstall command, a migration path between versions, or how session directories should be cleaned up, and the sessions directory will accumulate PRDs, tickets, research, and plans with no documented retention policy. Before depending on this, read stop-hook.js to confirm how exit is blocked and how the promise is matched, and check whether your Gemini CLI version still satisfies the greater than 0.25.0-preview.0 requirement, since the extension depends on hooks and skills that the README treats as experimental configuration.

Editorial conclusion

Adopt Pickle Rick only for well-defined tasks with automatic verification (test suites, linters) on branches you can discard, and only after you have set enableHooks and experimental.skills in .gemini/settings.json and added ~/.gemini/extensions/pickle-rick to includeDirectories. Do not use it for production debugging or design work where success cannot be expressed as a check. Before a long run, verify the loop actually terminates by starting with a small --max-iterations value and confirming that the sessions directory under ~/.gemini/extensions/pickle-rick/sessions receives files between iterations.

Official sources

1. galdawave/pickle-rick-extension on GitHub
2. Issues
3. License: Apache-2.0
4. README