Pickle Rick

📋 Requirements

• Node.js 18+
• Claude Code CLI (claude) — v2.1.49+
• jq (for install.sh, uninstall.sh, uninstall-hooks.sh)
• rsync (for install.sh)
• tmux (optional — for /pickle-tmux, /szechuan-sauce, /anatomy-park, /pickle-pipeline)
• Zellij >= 0.40.0 (optional — for /pickle-zellij)
• Graphite CLI (gt) (optional — for /council-of-ricks)
• GitHub CLI (gh) authed (optional — required only for /council-of-ricks auto-publish; the review itself works without it)
• Codex plugin (optional — required for --backend codex on /pickle, /pickle-tmux, /pickle-microverse, /anatomy-park, /szechuan-sauce, and for /council-of-ricks Phase C adversarial review. Without it, --backend codex spawns fail and Council's Phase C is skipped — Claude-backed runs and non-Codex Council rounds are unaffected. Install: /plugin install openai-codex or npm i -g @openai/codex-cli + codex setup)
• macOS or Linux (Windows not supported)

---

How to Build Things with Pickle Rick

Two ways to drive every step: just describe what you want (Rick routes to the right skill) or invoke the slash command yourself (explicit control). Same artifacts either way.

Fire and forget — for one-shot autopilot from goal to shipped code, hand the whole thing to /pickle-pipeline "<goal>" (build → citadel → anatomy-park → szechuan-sauce, sequential, with auto-refine when prose triggers it) or /cronenberg "<goal>" (meta-router that picks the right metaphor + cleanup chain for the task). Skip the step-by-step below.

1. Install

git clone https://github.com/gregorydickson/pickle-rick-claude.git
cd pickle-rick-claude
bash install.sh

Deploy Lockdown Operations

install.sh refuses source versions older than the deployed runtime unless rollback is explicit. Supported deploy flags:

Release closer flows must run bin/release-gate.sh --pre-tag <tag> before publishing and bin/release-gate.sh --post-tag <tag> after the release exists. Exit codes are: 10 pre-tag package version mismatch, 11 jq parse failed, 12 tag or tagged package missing, 20 release download failed, 21 downloaded tarball package version mismatch, and 22 GitHub release API error.

Use bin/purge-update-cache.js [--dry-run] to remove poisoned updater cache state before or during a release. Updater cache lives at ~/.claude/pickle-rick/update-check.json, and install audit entries live at ~/.claude/pickle-rick/deploy-audit.log.

Gate-baseline activity events are baseline_recapture_attempted, baseline_recapture_succeeded, and baseline_recapture_failed. Deploy audit-log event types are DOWNGRADE, CACHE_PURGE, and INSTALL_BYPASS_ACTIVE_SESSION.

4. Uninstall

Two uninstall paths depending on how much you want to remove.

Remove hooks only — disables automatic behavior (Stop loop enforcement, commit logging, config protection) but keeps extension files and slash commands available for manual use:

bash uninstall-hooks.sh

Settings are backed up to ~/.claude/backups/settings.json.pickle-uninstall-hooks.<timestamp> before modification. Run bash install.sh to re-enable hooks later — install.sh is idempotent, safe to re-run any time. Third-party hooks in settings.json (GitNexus, RTK, etc.) are never touched.

What still works without hooks:

• One-shot utilities and reporters (never needed hooks) — /pickle-prd, /pickle-refine-prd, /pickle-dot, /pickle-dot-patterns, /pickle-metrics, /pickle-status, /pickle-standup, /help-pickle, /attract.
• Detached-runner commands (bootstrap a separate process that runs independently inside tmux/zellij) — /pickle-tmux, /pickle-zellij, /pickle-jar-open, /pickle-microverse, /szechuan-sauce, /anatomy-park, /pickle-pipeline. These launch mux-runner.js / jar-runner.js / microverse-runner.js / pipeline-runner.js inside the multiplexer; the runner spawns its own claude -p subprocesses and drives iteration via Node.js, not via the Stop hook. In tmux mode the Stop hook is a pass-through anyway.

What needs hooks — in-session loops where the Stop hook is the iteration driver for the same Claude session: /pickle (interactive mode), /council-of-ricks, /portal-gun, /project-mayhem, /pickle-retry. Without hooks these run the first step and stop.

Full uninstall — removes hooks, extension scripts at ~/.claude/pickle-rick/, and all pickle-rick slash commands at ~/.claude/commands/:

bash uninstall.sh

Preserved after full uninstall (delete manually if desired): - Session history at ~/.local/share/pickle-rick/sessions/ - Activity logs at ~/.local/share/pickle-rick/activity/ - Settings backups at ~/.claude/backups/ - Project-local CLAUDE.md files — remove the appended persona block manually

Third-party hooks in settings.json (GitNexus, RTK, etc.) are never touched.

---

⚡ Quick Start

Step 4 (Optional): Metric-Driven Refinement

Just ask:

"Push test coverage to 90%"

If you can define a measurable goal — test coverage, response time, bundle size, extraction accuracy — the Microverse grinds toward it. Each cycle: make one change, measure, keep or revert. Failed approaches are tracked so it never repeats a dead end.

```bash

Step 5 (Optional): Cleanup

Four options for polishing the result.

Full Pipeline — chains build, Citadel conformance audit, deep review, and deslop in a single tmux session. No manual intervention between phases. When refinement is mentioned in the request (or --refine is passed), the skill auto-runs /pickle-refine-prd first.

"Run the full pipeline to build the caching layer"

```bash

🪠 Plumbus — DAG Shaping Loop

<p align="center"> <img src="images/plumbus.jpg" alt="Plumbus — iterative DAG shaping loop" width="100%" /> </p>

"Everybody has a plumbus in their home, Morty. First they take the dinglebop, smooth it out with a bunch of schleem..."

The same convergence loop applied to a single attractor .dot pipeline. Runs the attractor validator as a hard gate, walks every edge, and converges against the pickle-dot-patterns rubric (DAG validity, Tier 1 mandatory patterns, anti-patterns). Use it after /pickle-dot generates a graph you want hardened before /attract.

/plumbus pipeline.dot                         # Shape a DAG into a proper plumbus
/plumbus --dry-run pipeline.dot               # Catalog violations only
/plumbus --focus "fan-out safety" pipeline.dot
/plumbus --no-validator pipeline.dot          # Pattern-only (no attractor repo)

When to use which: Szechuan Sauce asks "is this code well-designed?" — Anatomy Park asks "is this code correct?" — Plumbus asks "will this DAG actually run without deadlocking?"

Generative Audit Frames

Plumbus runs six analysis frames during the first iteration Edge Walk (Override 6). Each frame produces findings in gap_analysis.md under ## Generative Findings, using a three-severity model (pre_verification_severity / post_verification_severity / rendered_severity).

Kill-switch: set PLUMBUS_GENERATIVE_AUDIT=off to skip Override 6 entirely (no analyzer invocation, no ## Generative Findings written). Any other value (including absent) runs the audit normally.

---

🚀 Command & Flag Reference

Every slash command and flag — including command-scoped families and the †/Codex/Teams notes — lives in COMMANDS.md.

---

Under the hood: See internals.md for the 8-phase ticket lifecycle, manager/worker model, stop-hook loop, context clearing, state schema, settings reference, and every internal system that makes this thing run.

---

then follow the workflow above — start with a PRD

```

Other Workflows

Slash-command alternative:

/pickle-microverse --metric "npm run coverage:score" --task "hit 90% test coverage" /pickle-microverse --metric "node perf-test.js" --task "reduce p99 latency" --direction lower /pickle-microverse --goal "error messages are user-friendly and actionable" --task "improve UX"

<a id="backends"></a>**Backends** — `/pickle`, `/pickle-tmux`, `/szechuan-sauce`, `/anatomy-park`, and `/pickle-microverse` accept `--backend codex` to route spawns through `codex exec`, or `--backend hermes` to route spawns through `hermes chat -q ... -Q --ignore-rules --ignore-user-config`. The choice is persisted in `state.json` and survives resume; omit the flag to keep the default `claude` backend. Set `PICKLE_BACKEND=codex` or `PICKLE_BACKEND=hermes` for a session-independent alternative that persists across commands. Precedence: CLI flag > env var > session state > default `claude`. **Incompatible with `--teams`** — agent-teams mode is claude-harness-native; setup rejects non-claude backends at session creation and on `--resume`.

For codex-backed runs, keep `/pickle` for short interactive work and prefer `/pickle-tmux` for longer sessions. The safe workaround is tmux-direct: the shell/tmux pane owns `mux-runner`, and `codex exec` is only a child spawned by mux-runner. Avoid the risky arrangement where a long-lived codex session becomes the parent of mux-runner and supervises the whole pipeline.

`/council-of-ricks` integrates Codex differently — its Phase C runs an adversarial Codex subagent by default (`--no-codex` to disable, `--codex-timeout <sec>` to tune). See the Council of Ricks section below.

**Reasoning effort** *(codex backend)* — append `--effort <low|medium|high>` to opt into a non-default reasoning effort. Pickle threads it through to `codex exec` as `-c reasoning.effort=<level>` before the prompt separator. Omit the flag to inherit whatever your local `codex` CLI / `~/.codex/config.toml` is set at — Pickle does not override the default. Persisted in `state.json` and survives `--resume`. Claude path is a no-op (no public reasoning-effort flag for `claude -p`); refinement displays the level for visibility but does not pass it (claude-only).

<a id="agent-teams"></a>**Agent Teams mode** *(v1.55+, claude backend only)* — `/pickle --teams` switches Phase 3 from spawning per-ticket `claude -p` subprocesses to spawning subagents on a harness-native team. Each ticket runs as a `morty-implementer` agent (`Agent` tool with `team_name` + `subagent_type`) that signals completion via `TaskUpdate(status="completed")` instead of the legacy `<promise>I AM DONE</promise>` token + log-size check. Manager-side validation switches to a strict all-of artifact check (`validate-teams-ticket.js`): every required prefix (`research_*.md`, `plan_*.md`, `conformance_*.md`, `code_review_*.md`) must have a matching file or the ticket is marked Failed. The flag is persisted in `state.json` and survives resume.

Subagent definitions live at ~/.claude/agents/morty-implementer.md (8-phase implementation lifecycle) and ~/.claude/agents/morty-reviewer.md (4-phase review lifecycle). Both are deployed by install.sh. v1 always dispatches morty-implementer; review-group dispatch via morty-reviewer is a follow-up — see the PRD for the v1 boundary. Legacy subprocess path is untouched and remains the default — passing no --teams flag preserves byte-for-byte v1.54 behavior.

When NOT to use: codex backend (rejected at setup), /pickle-tmux / /pickle-zellij / /pickle-microverse / /pickle-pipeline (out of scope for v1; legacy spawn only). When to use: epics where you want clean bidirectional comms with the worker, native completion notifications, and the strictest artifact gate available.

Slash-command alternative:

/pickle-pipeline "build the caching layer" # No refinement (no trigger) /pickle-pipeline "refine the prd then build the caching layer" # Auto-inferred from prose /pickle-pipeline --refine "build the caching layer" # Explicit force, prose silent /pickle-pipeline --no-refine "refine the prd first then ship X" # Suppress auto-inferred refinement /pickle-pipeline --skip-anatomy "refactor auth" # Skip deep review /pickle-pipeline --target src/services "add retry logic" # Scope review phases

The auto-refine trigger fires on `refine-prd` / `prd refinement`, on `refine`/`refinement`/`decompose` near `prd` or `first` (within 40 chars), or on workflow ordering like `refine then build`. Bare `refine the dropdown UX` won't trigger — use `--refine` to force, `--no-refine` to suppress. Refinement always uses the `claude` backend regardless of `--backend` (refinement is planning, not implementation). Fails fast if no `prd.md` exists in cwd or session — run `/pickle-prd` first.

**Citadel** — audits the implemented branch against the PRD before deeper review phases. It reads PRD acceptance criteria, interface contracts, changed files, trap-door notes, and sibling phase artifacts when present. Findings are grouped by audit surface: PRD coverage, endpoint contract drift, trap-door enforcement, sibling route divergence, state-machine drift, frontend prop drift, cross-phase findings, and diff hygiene.

Slash-command alternative:

/citadel --prd prd.md --diff main..HEAD /citadel --prd prd.md --strict --report /tmp/citadel_report.json

Citadel writes a versioned JSON report with `schema: "1.0"`. Standalone runs use `--report <path>` when supplied; `/pickle-pipeline` writes `<session>/citadel_report.json` and passes that report to anatomy-park and szechuan-sauce. `--strict` makes High findings fail the phase; without it, only Critical findings halt the pipeline.

**Resume hardening** *(v1.56+)* — pipeline pre-flight excludes `prds/` and `docs/` from the clean-tree check by default, so doc churn during a long-running epic doesn't block resume. Override the list per-session via `pipeline.json.ignore_dirty_paths` (set `[]` to opt out entirely). The pickle phase pins its own `command_template` on entry — a stale `state.command_template` from a prior phase no longer misroutes resumed workers to the wrong skill prompt.

**Szechuan Sauce** — hunts coding principle violations (KISS, DRY, SOLID, security, style) and fixes them one at a time until zero remain. Great for post-feature polish before merging.

Slash-command alternative:

/szechuan-sauce src/services/ # Deslop a directory /szechuan-sauce --dry-run src/ # Catalog violations without fixing /szechuan-sauce --focus "error handling" src/ # Narrow the review

**Anatomy Park** — traces data flows through subsystems looking for runtime bugs: data corruption, timezone issues, rounding errors, schema drift. Catalogs "trap doors" (files that keep breaking) in `CLAUDE.md` files for future engineers.

Slash-command alternative:

/anatomy-park src/ # Deep subsystem review /anatomy-park --dry-run # Review only, no fixes

**Cronenberg (meta-router)** — when you don't know which cleanup metaphor fits, describe the goal and let `/cronenberg` pick the right pickle metaphor + cleanup chain for the task. Explicit invocation only — never auto-triggers.

🛠️ Troubleshooting

See docs/judge-spawn-troubleshooting.md for judge backend errors, ETIMEDOUT, sticky fallback semantics, and exit-reason mapping.

---