AI Ralph

What it does

• Reuses discover_workspace_repos() so the same repo set as ralph --workspace (execution) is planned
• Reads planning context from both ai/ (workbench convention) and .ralph/specs/ (ralph-native); concatenates when both exist
• Engine writes structured output (## tasks, ## ambiguities, ## cross-repo) to .ralph/.workspace_plan/<repo>.out.md, then workspace_plan_merge_repo_section merges it back into the per-repo section with trim-compare dedupe against preserved [~] / [x] lines
• Cross-repo tasks land in a consolidated ## cross-repo section, deduped
• --repos a,b,c allowlist — unlisted repos are untouched
• --dry-run runs the planner per repo but does NOT write fix_plan.md; summary still emitted
• End-of-run summary: repos planned, new vs preserved tasks, cross-repo count, ambiguities per repo, engine, elapsed time
• Preflight: cwd must be a workspace root (no top-level .git, one or more child repos with .git/, .ralph/fix_plan.md present). Clean errors otherwise
• Sequential execution only for now — parallel workspace planning is a follow-up

Usage

ralph-plan --workspace                       # default engine (Claude)
ralph-plan --workspace --engine devin        # via Devin
ralph-plan --workspace --repos svc-a,svc-b   # plan only two repos
ralph-plan --workspace --dry-run             # summary only, no writes

New files

• lib/workspace_plan.sh — preflight, context collection, engine drive, parse, merge, cross-repo, filter
• tests/unit/test_workspace_mode.bats — 20 new tests (happy path, state preservation, cross-repo, preflight fail, --repos, --dry-run)

What it fixes

• worktree_cleanup's unconditional cp worktree/fix_plan.md → main/fix_plan.md clobbered sibling parallel agents' [~] / [x] marks under rpc.p / rpd.p / rpx.p, leading to duplicate task picks
• The pick_next_task lock itself was correct (10 concurrent pickers → 10 distinct picks); the race was at cleanup time

How it works

• worktree_create: snapshot baseline copy of fix_plan.md to .ralph/.fix_plan_baseline.md
• worktree_cleanup: call new _merge_fix_plan_back instead of raw cp
• _merge_fix_plan_back: lock-guarded 3-way merge via git merge-file (worktree-final × baseline × main-current) under the existing _acquire_task_lock mutex, reused as shared mutex for all fix_plan.md writers
• _merge_fix_plan_status: awk line-level fallback, picks the most-advanced marker per task ([x] > [~] > [ ]) and preserves sibling-added rows; never regresses state
• 6 new tests in tests/unit/test_worktree_merge.bats

What it fixes

• _worktree_install_deps (pre-gate) had no timeout, no stdin redirect, no live output; a hung npm install / pnpm install (private-registry auth, network, interactive prompt) blocked the loop with only "Running quality gates..." visible
• Gate output was captured via gate_output=$(... 2>&1) and replayed after the fact, so operators saw nothing until the gate returned

How it works

• WORKTREE_INSTALL_TIMEOUT (default 600s, env/.ralphrc overridable) wraps the install step; stdin → /dev/null so registry-auth prompts can't block. Exit 124/137 logged as DEPS_INSTALL: TIMEOUT after Ns
• All three engine loops (+ Claude --qg mode + QG retry loop, 4 sites) replaced the capture with a streaming pipeline: worktree_run_quality_gates 2>&1 | while read; do log_status INFO; done + gate_result=${PIPESTATUS[0]}. Operators now see DEPS_INSTALL: and QUALITY_GATE[N]: progress in real time
• Start log prints the bounds: Running quality gates (install timeout Ns, per-gate timeout Ns)...

Files

• lib/worktree_manager.sh, devin/lib/worktree_manager.sh, codex/lib/worktree_manager.sh — WORKTREE_INSTALL_TIMEOUT and timeout-wrapped install
• ralph_loop.sh (+ run_qg_mode + QG retry loop), devin/ralph_loop_devin.sh, codex/ralph_loop_codex.sh — gate streaming

What it does

• Per-gate timeout. WORKTREE_GATE_TIMEOUT (default 600s, env / .ralphrc overridable) wraps each detected/configured gate in timeout --foreground "$WORKTREE_GATE_TIMEOUT" bash -c "$cmd" </dev/null (falls back to gtimeout on macOS, no-op when neither exists). Stdin redirect prevents TTY-probing commands (npm test watch, prompts) from blocking forever. Exit 124/137 recorded as FAIL: <cmd> (timeout Ns) so the QG fix prompt and PR description carry the real reason
• Execution Failed box. The else branch of if [[ $exec_result -eq 0 ]] now prints a red summary with task name, exit code, preserved worktree branch (worktree_cleanup "false"), session ID, and the engine's resume command. Reverts the [~] marker to [ ] so the task is retryable on the next loop. Wired into all three engine loops
• rpc.p / rpc.p.b parity. Previously rpc.int.p was the only Claude parallel alias — it forced every run through --live --monitor, whose tmux + stream-json tee/FIFO file descriptors leaked into the synchronous post-loop gate_output=$(... 2>&1) capture and hung the loop at "Running quality gates...". New rpc.p mirrors rpd.p (plain ralph --parallel, no --live / --monitor); rpc.int.p is now opt-in for the dashboard
• Reworded misleading Retrying with fresh session WARN in ralph_loop.sh — execute_claude_code returns immediately after reset_session, there is no retry within the same invocation

Usage

# Override gate timeout for a flaky test suite
WORKTREE_GATE_TIMEOUT=1200 ralph

# Or pin it in .ralphrc
echo 'WORKTREE_GATE_TIMEOUT=1200' >> .ralphrc

# Non-interactive parallel (new default for parity)
rpc.p 3        # 3 parallel agents, auto-exit, no streaming
rpc.live.p 3   # 3 parallel agents with streaming output (single pane)
rpc.int.p 3    # 3 parallel agents with full tmux 3-pane split (opt-in)

What it fixes

• Claude scopes session IDs by cwd. In worktree mode each iteration has a new worktree cwd, so claude --resume <id> looked in the new worktree's pool and reported "No conversation found with session ID …", killing the loop
• rpc.int.p N compounded the issue: every agent shared a single .claude_session_id resolved against the main project root; the first save raced/clobbered the rest, and every agent failed on its next iteration

How it works

• init_claude_session, save_claude_session, and the stream-mode fallback session-ID writer are now gated on WORKTREE_ENABLED != true
• In worktree mode every iteration is a fresh Claude session — the only behaviour consistent with worktree-per-iter cwds
• Non-worktree mode keeps --resume continuity unchanged

How it works

• pick_workspace_tasks_parallel() picks up to N tasks (one per repo), skips repos with in-progress tasks and the cross-repo section, atomically marks all [~]
• run_workspace_tasks_parallel() spawns background workers for each task, waits for completion, marks [x] on success or reverts [ ] on failure
• get_workspace_parallel_limit() calculates safe parallelism (min of repos with pending tasks and requested count; 0 = auto)
• Per-worker log files in .ralph/logs/parallel/ws_worker_<repo>_<pid>.log

Usage

ralph --workspace --parallel 3
rpc.ws.p 3    # Claude alias
rpd.ws.p 3    # Devin alias
rpx.ws.p 3    # Codex alias

What it does

• --model <name> passes --model through to the Claude or Devin CLI (e.g. opus, sonnet, claude-opus-4-7, claude-sonnet-4); Codex ignores with a WARN
• --thinking hard prepends a "Think hard…" preamble to the planning prompt for every engine; Claude engine also gets --effort high
• --thinking ultra prepends an ultrathink preamble; Claude engine also gets --effort max. Devin has no --effort equivalent so it stops at the preamble
• Invalid --thinking values are rejected at parse time with a typed error
• Previously rpc.opus / rpd.opus only changed the execution-loop model — planning sessions always used the engine default. This closes that gap

Usage

ralph-plan --model opus                                  # Claude + Opus
ralph-plan --thinking ultra                              # ultrathink + --effort max
ralph-plan --model opus --thinking ultra --yolo --superpowers  # deepest Claude planning
ralph-plan --engine devin --model claude-opus-4.6        # Devin + Anthropic model

# Aliases (Claude)
rpc.plan.opus          # --model opus
rpc.plan.sonnet        # --model sonnet
rpc.plan.hard          # --thinking hard
rpc.plan.ultra         # --thinking ultra
rpc.plan.opus.ultra    # --model opus --thinking ultra
rpc.plan.max           # --model opus --thinking ultra --yolo --superpowers

# Aliases (Devin)
rpd.plan.opus          # --engine devin --model opus
rpd.plan.sonnet        # --engine devin --model sonnet
rpd.plan.hard          # --engine devin --thinking hard
rpd.plan.ultra         # --engine devin --thinking ultra
rpd.plan.opus.ultra    # --engine devin --model opus --thinking ultra

Changed files

• ralph_plan.sh — flag parsing, validation, prompt preamble injection, Claude --effort wiring, Devin --model pass-through
• ALIASES.sh — 6 new rpc.plan.* aliases
• devin/ALIASES.sh — 5 new rpd.plan.* aliases
• README.md — feature bullets + rpc/rpd alias tables

What it fixes

• Claude engine was creating an isolated git worktree per loop iteration, but the claude CLI was being spawned from the main project directory, so all file edits and commits landed on the main branch instead of the feature branch
• Devin and Codex engines already wrapped their CLI calls in (cd "$work_dir" && ...); Claude was the lone outlier

How it works

• All three Claude execution paths in ralph_loop.sh now cd into the worktree before invoking the CLI: live mode (line 1439), modern background mode (line 1525), legacy background mode (line 1540)
• Paths of output_file, stderr_file, and PROMPT_FILE are resolved in the parent shell (pre-subshell) so logs still land in the main .ralph/logs/ tree
• 4 new unit tests in test_cli_modern.bats guard against regression

What it fixes

• pick_next_task() correctly picks and locks a task ([~]) in fix_plan.md, but the picked task info was never passed to the AI in the prompt
• The AI would independently read fix_plan.md and choose its own task — causing mismatches, especially in parallel mode where multiple agents run simultaneously

How it works

• All three engine loops (Claude, Devin, Codex) now pass the picked task ID, line number, and description through their execute_*_session() functions
• A “task assignment directive” is injected at the top of the prompt, telling the AI exactly which task to work on
• The directive includes task ID, line number in fix_plan.md, and the full task description

What it does

• Archives current fix_plan.md before compression (timestamped backup in .ralph/logs/)
• AI collapses completed items into summary lines with task ID lists
• Shortens verbose pending/in-progress descriptions to concise one-liners
• Preserves all task IDs, checkbox states, and dependency annotations
• Shows pre/post compression stats (item count, file size)

Usage

ralph-plan --compress                # Claude (default)
ralph-plan --engine codex --compress # Codex
rpc.compress                         # Claude alias
rpd.compress                         # Devin alias
rpx.compress                         # Codex alias

New files

• lib/compress_plan.sh — core compression logic (find, count, archive, invoke AI)
• templates/PROMPT_COMPRESS.md — AI prompt template with compression rules
• tests/unit/test_compress_plan.bats — 33 unit tests

What it does

• Reads a document file and uses AI to extract actionable tasks into fix_plan.md
• Supports Markdown (.md), JSON (.json), YAML (.yml/.yaml), and plain text (.txt) files
• Detects file type and applies format-specific interpretation rules
• Works with all three engines (Claude, Codex, Devin)
• Walk-up search for fix_plan.md — works from any subdirectory

Usage

ralph-plan --file ./docs/spec.md            # Claude (default)
ralph-plan --engine codex --file ./api.json # Codex
rpc.plan.file ./docs/spec.md               # Claude alias
rpd.plan.file ./docs/spec.md               # Devin alias
rpx.plan.file ./docs/spec.md               # Codex alias

New files

• lib/file_plan.sh — core logic (type detection, walk-up search, AI invocation)
• templates/PROMPT_FILE_PLAN.md — AI prompt template with per-format rules
• tests/unit/test_file_plan.bats — 34 unit tests