ralph-cli-sandboxed 0.6.3 → 0.6.5

package/README.md

@@ -42,8 +42,10 @@ ralph docker run
 | `ralph status` | Show PRD completion status |
 | `ralph toggle <n>` | Toggle passes status for entry n |
 | `ralph clean` | Remove all passing entries from PRD |
+| `ralph reset` | Reset all PRD entries to passes: false |
 | `ralph fix-prd [opts]` | Validate and recover corrupted PRD file |
 | `ralph prompt [opts]` | Display resolved prompt |
+| `ralph progress <sub>` | Manage progress file (summarize) |
 | `ralph branch <sub>` | Manage PRD branches (list, merge, pr, delete) |
 | `ralph docker <sub>` | Manage Docker sandbox environment |
 | `ralph daemon <sub>` | Manage host daemon for sandbox notifications |
@@ -233,10 +235,10 @@ Ralph supports 18 programming languages with pre-configured build/test commands:
 | Java | `mvn compile` | `mvn test` |
 | Kotlin | `gradle build` | `gradle test` |
 | C#/.NET | `dotnet build` | `dotnet test` |
-| Ruby | `bundle exec rubocop` | `bundle exec rspec` |
-| PHP | `composer validate` | `vendor/bin/phpunit` |
+| Ruby | `bundle exec rubocop --fail-level error` | `bundle exec rspec` |
+| PHP | `composer validate && php -l` | `vendor/bin/phpunit` |
 | Swift | `swift build` | `swift test` |
-| Elixir | `mix compile` | `mix test` |
+| Elixir | `mix compile --warnings-as-errors` | `mix test` |
 | Scala | `sbt compile` | `sbt test` |
 | Zig | `zig build` | `zig build test` |
 | Haskell | `stack build` | `stack test` |
@@ -255,6 +257,7 @@ Ralph supports multiple AI CLI tools. Select your provider during `ralph init`:
 | [OpenCode](https://github.com/anomalyco/opencode) | Working | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` | No autonomous/yolo mode yet. Requires [PR #9073](https://github.com/anomalyco/opencode/pull/9073) |
 | [Aider](https://github.com/paul-gauthier/aider) | Working | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | |
 | [Goose](https://github.com/block/goose) | Working | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | Block's AI coding agent |
+| [Ollama](https://ollama.com/) | Working | (none) | Local LLM server |
 | [Codex CLI](https://github.com/openai/codex) | Testers wanted | `OPENAI_API_KEY` | Sponsors welcome |
 | [AMP](https://ampcode.com/) | Testers wanted | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | Sponsors welcome |
 | Custom | - | User-defined | Configure your own CLI |
@@ -353,6 +356,7 @@ Not all CLI providers support stream-json output. Here's the compatibility matri
 | Goose | ✅ Yes | `--output-format stream-json` |
 | Aider | ❌ No | - |
 | AMP | ❌ No | - |
+| Ollama | ❌ No | - |
 | Custom | ❌ No* | *Add `streamJsonArgs` to your custom config |
 
 Each provider uses different command-line arguments and output formats. Ralph automatically selects the correct parser based on your configured provider.
@@ -426,7 +430,7 @@ The PRD (`prd.json`) is an array of requirements:
 ]
 ```
 
-Categories: `setup`, `feature`, `bugfix`, `refactor`, `docs`, `test`, `release`, `config`, `ui`
+Categories: `ui`, `feature`, `bugfix`, `setup`, `development`, `testing`, `docs`
 
 ### Branching
 
@@ -499,7 +503,7 @@ ralph fix-prd backup.json  # Restore from a specific backup file
 
 ### Dynamic Iteration Limits
 
-To prevent runaway loops, `ralph run` limits iterations to `incomplete_tasks + 3`. This limit adjusts dynamically if new tasks are added during execution.
+To prevent runaway loops, `ralph run` stops after 3 consecutive iterations without progress (no tasks completed and no new tasks added). It also stops after 3 consecutive failures with the same exit code.
 
 ## Docker Sandbox
 

package/dist/commands/docker.js

@@ -17,6 +17,7 @@ function computeConfigHash(config) {
         cliProvider: config.cliProvider,
         docker: config.docker,
         claude: config.claude,
+        cliModel: config.cli?.model,
     };
     const content = JSON.stringify(relevantConfig, null, 2);
     return createHash("sha256").update(content).digest("hex").substring(0, 16);
@@ -71,9 +72,15 @@ function getCliProviderSnippet(cliProvider) {
     }
     return provider.docker.install;
 }
-function generateDockerfile(language, javaVersion, cliProvider, dockerConfig) {
+function generateDockerfile(language, javaVersion, cliProvider, dockerConfig, cliModel) {
     const languageSnippet = getLanguageSnippet(language, javaVersion);
     const cliSnippet = getCliProviderSnippet(cliProvider);
+    // Ollama model pull: when provider is ollama and a model is configured,
+    // start the server briefly and pull the model during the Docker build
+    let ollamaModelPull = "";
+    if (cliProvider === "ollama" && cliModel) {
+        ollamaModelPull = `\n# Pull Ollama model during build\nRUN ollama serve & sleep 2 && ollama pull ${cliModel}\n`;
+    }
     // Build custom packages section
     let customPackages = "";
     if (dockerConfig?.packages && dockerConfig.packages.length > 0) {
@@ -206,14 +213,14 @@ if [ -z "$RALPH_BANNER_SHOWN" ]; then
   echo "\\033[38;2;253;216;53m██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║    ██║     ██║     ██║\\033[0m"
   echo "\\033[38;2;251;192;45m██║  ██║██║  ██║███████╗██║     ██║  ██║    ╚██████╗███████╗██║\\033[0m"
   echo "\\033[38;2;249;168;37m╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝     ╚═════╝╚══════╝╚═╝\\033[0m"
-  RALPH_VERSION=$(ralph --version 2>/dev/null | head -1 || echo "unknown")
-  echo "\\033[38;5;248mv$RALPH_VERSION\\033[0m"
+  RALPH_VERSION=$(ralph --version 2>/dev/null | awk '{print $NF}' || echo "unknown")
+  echo "\\033[38;5;248m$RALPH_VERSION\\033[0m"
   echo ""
 fi
 RALPH_BANNER
 
 ${cliSnippet}
-
+${ollamaModelPull}
 # Install ralph-cli-sandboxed from npm registry
 RUN npm install -g ralph-cli-sandboxed
 RUN ralph logo
@@ -654,7 +661,7 @@ function generateClaudeSettings() {
     };
     return JSON.stringify(settings, null, 2) + "\n";
 }
-async function generateFiles(ralphDir, language, imageName, force = false, javaVersion, cliProvider, dockerConfig, claudeConfig) {
+async function generateFiles(ralphDir, language, imageName, force = false, javaVersion, cliProvider, dockerConfig, claudeConfig, cliModel) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     // Create docker directory
     if (!existsSync(dockerDir)) {
@@ -665,7 +672,7 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
     const files = [
         {
             name: "Dockerfile",
-            content: generateDockerfile(language, javaVersion, cliProvider, dockerConfig),
+            content: generateDockerfile(language, javaVersion, cliProvider, dockerConfig, cliModel),
         },
         { name: "init-firewall.sh", content: generateFirewallScript(customDomains) },
         { name: "docker-compose.yml", content: generateDockerCompose(imageName, dockerConfig) },
@@ -797,6 +804,7 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         cliProvider,
         docker: dockerConfig,
         claude: claudeConfig,
+        cli: cliModel ? { command: "", model: cliModel } : undefined,
     };
     const hash = computeConfigHash(configForHash);
     saveConfigHash(dockerDir, hash);
@@ -816,7 +824,7 @@ async function buildImage(ralphDir) {
             await generateFiles(ralphDir, config.language, config.imageName ||
                 `ralph-${basename(process.cwd())
                     .toLowerCase()
-                    .replace(/[^a-z0-9-]/g, "-")}`, true, config.javaVersion, config.cliProvider, config.docker, config.claude);
+                    .replace(/[^a-z0-9-]/g, "-")}`, true, config.javaVersion, config.cliProvider, config.docker, config.claude, config.cli?.model);
             console.log("");
         }
     }
@@ -957,11 +965,12 @@ async function runContainer(ralphDir, imageName, language, javaVersion, cliProvi
             cliProvider,
             docker: dockerConfig,
             claude: claudeConfig,
+            cli: fullConfig?.cli?.model ? { command: "", model: fullConfig.cli.model } : undefined,
         };
         if (hasConfigChanged(ralphDir, configForHash)) {
             const regenerate = await promptConfirm("Config has changed since last docker init. Regenerate Docker files?");
             if (regenerate) {
-                await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig, claudeConfig);
+                await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig, claudeConfig, fullConfig?.cli?.model);
                 console.log("");
             }
         }
@@ -970,7 +979,7 @@ async function runContainer(ralphDir, imageName, language, javaVersion, cliProvi
     if (!dockerfileExists || !hasImage) {
         if (!dockerfileExists) {
             console.log("Docker folder not found. Initializing docker setup...\n");
-            await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig, claudeConfig);
+            await generateFiles(ralphDir, language, imageName, true, javaVersion, cliProvider, dockerConfig, claudeConfig, fullConfig?.cli?.model);
             console.log("");
         }
         if (!hasImage) {
@@ -1249,7 +1258,7 @@ export async function dockerInit(silent = false) {
         console.log(`CLI provider: ${config.cliProvider}`);
     }
     console.log(`Image name: ${imageName}\n`);
-    await generateFiles(ralphDir, config.language, imageName, true, config.javaVersion, config.cliProvider, config.docker, config.claude);
+    await generateFiles(ralphDir, config.language, imageName, true, config.javaVersion, config.cliProvider, config.docker, config.claude, config.cli?.model);
     if (!silent) {
         console.log(`
 Docker files generated in .ralph/docker/
@@ -1367,7 +1376,7 @@ INSTALLING PACKAGES (works with Docker & Podman):
                 console.log(`CLI provider: ${config.cliProvider}`);
             }
             console.log(`Image name: ${imageName}\n`);
-            await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion, config.cliProvider, config.docker, config.claude);
+            await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion, config.cliProvider, config.docker, config.claude, config.cli?.model);
             console.log(`
 Docker files generated in .ralph/docker/
 

package/dist/commands/init.js

@@ -98,6 +98,11 @@ export async function init(args) {
             };
         }
         console.log(`\nSelected CLI provider: ${CLI_PROVIDERS[selectedCliProviderKey].name}`);
+        // Optional: specify default model
+        const modelInput = await promptInput("Enter default model name (optional, press Enter to skip): ");
+        if (modelInput.trim()) {
+            cliConfig.model = modelInput.trim();
+        }
         // Step 2: Select language (second)
         const languageKeys = Object.keys(LANGUAGES);
         const languageNames = languageKeys.map((k) => `${LANGUAGES[k].name} - ${LANGUAGES[k].description}`);
@@ -369,6 +374,7 @@ config.json
 # Runtime state files
 messages.json
 chat-state.json
+prd-tasks.json
 
 # Service logs
 daemon.log

package/dist/commands/once.js

@@ -36,6 +36,10 @@ export async function once(args) {
     });
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
+    // Use config model as fallback when --model flag is not provided
+    if (!model && cliConfig.model) {
+        model = cliConfig.model;
+    }
     // Check if stream-json output is enabled
     const streamJsonConfig = config.docker?.asciinema?.streamJson;
     const streamJsonEnabled = streamJsonConfig?.enabled ?? false;

package/dist/commands/run.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, writeFileSync, unlinkSync, appendFileSync, mk
 import { extname, join } from "path";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer, saveBranchState, loadBranchState, clearBranchState, getProjectName, } from "../utils/config.js";
 import { resolvePromptVariables, getCliProviders, GEMINI_MD } from "../templates/prompts.js";
-import { validatePrd, smartMerge, readPrdFile, writePrd, writePrdAuto, expandPrdFileReferences, } from "../utils/prd-validator.js";
+import { validatePrd, smartMerge, readPrdFile, writePrdAuto, expandPrdFileReferences, } from "../utils/prd-validator.js";
 import { getStreamJsonParser } from "../utils/stream-json.js";
 import { sendNotificationWithDaemonEvents } from "../utils/notification.js";
 const CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
@@ -118,11 +118,11 @@ function setupWorktreeRalphDir(worktreePath, branchItems, workspacePaths) {
 }
 /**
  * Creates a filtered PRD file containing only incomplete items (passes: false).
- * Optionally filters by category if specified.
+ * Optionally filters by category and/or branch if specified.
  * Expands @{filepath} references to include file contents.
  * Returns the path to the temp file, or null if all items pass.
  */
-function createFilteredPrd(prdPath, baseDir, category) {
+function createFilteredPrd(prdPath, baseDir, category, branchFilterActive, branchFilter) {
     // Use readPrdFile to handle both JSON and YAML formats
     const parsed = readPrdFile(prdPath);
     if (!parsed) {
@@ -145,6 +145,10 @@ function createFilteredPrd(prdPath, baseDir, category) {
     if (category) {
         filteredItems = filteredItems.filter((item) => item.category === category);
     }
+    // Apply branch filter if specified
+    if (branchFilterActive) {
+        filteredItems = applyBranchFilter(filteredItems, branchFilter);
+    }
     // Expand @{filepath} references in description and steps
     const expandedItems = expandPrdFileReferences(filteredItems, baseDir);
     // Write to .ralph/prd-tasks.json so LLMs see a sensible path
@@ -406,11 +410,24 @@ function formatElapsedTime(startTime, endTime) {
         parts.push(`${seconds}s`);
     return parts.join(" ");
 }
+/**
+ * Filters PRD items by branch.
+ * - branchFilter = "name": only items whose branch field matches "name"
+ * - branchFilter = "": only items that have any branch field set (non-empty)
+ */
+function applyBranchFilter(items, branchFilter) {
+    if (branchFilter === "") {
+        // --branch without value: include only items that have a branch set
+        return items.filter((item) => item.branch && item.branch.length > 0);
+    }
+    // --branch <name>: include only items whose branch matches
+    return items.filter((item) => item.branch === branchFilter);
+}
 /**
  * Counts total and incomplete items in the PRD.
- * Optionally filters by category if specified.
+ * Optionally filters by category and/or branch if specified.
  */
-function countPrdItems(prdPath, category) {
+function countPrdItems(prdPath, category, branchFilterActive, branchFilter) {
     // Use readPrdFile to handle both JSON and YAML formats
     const parsed = readPrdFile(prdPath);
     if (!parsed) {
@@ -430,7 +447,10 @@ function countPrdItems(prdPath, category) {
     const items = parsed.content;
     let filteredItems = items;
     if (category) {
-        filteredItems = items.filter((item) => item.category === category);
+        filteredItems = filteredItems.filter((item) => item.category === category);
+    }
+    if (branchFilterActive) {
+        filteredItems = applyBranchFilter(filteredItems, branchFilter);
     }
     const complete = filteredItems.filter((item) => item.passes === true).length;
     const incomplete = filteredItems.filter((item) => item.passes === false).length;
@@ -485,7 +505,7 @@ function validateAndRecoverPrd(prdPath, validPrd) {
     if (!parsed) {
         console.log("\nNote: PRD corrupted (invalid JSON) - restored from memory.");
         const mergedPrd = [...validPrd, ...newItems];
-        writePrd(prdPath, mergedPrd);
+        writePrdAuto(prdPath, mergedPrd);
         if (newItems.length > 0) {
             console.log(`Preserved ${newItems.length} newly-added item(s).`);
         }
@@ -503,7 +523,7 @@ function validateAndRecoverPrd(prdPath, validPrd) {
     // Add any newly-added items
     const mergedPrd = [...mergeResult.merged, ...newItems];
     // Write the valid structure back (with new items)
-    writePrd(prdPath, mergedPrd);
+    writePrdAuto(prdPath, mergedPrd);
     if (mergeResult.itemsUpdated > 0) {
         console.log(`Recovered: merged ${mergeResult.itemsUpdated} passes flag(s) into valid PRD structure.`);
     }
@@ -537,6 +557,8 @@ function loadValidPrd(prdPath) {
 export async function run(args) {
     // Parse flags
     let category;
+    let branchFilter; // undefined = no filter, "" = any branch, "name" = specific branch
+    let branchFilterActive = false; // true when --branch flag is present
     let model;
     let loopMode = false;
     let allModeExplicit = false;
@@ -554,6 +576,18 @@ export async function run(args) {
                 process.exit(1);
             }
         }
+        else if (args[i] === "--branch" || args[i] === "-b") {
+            branchFilterActive = true;
+            // Check if next arg is a branch name (not another flag)
+            if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+                branchFilter = args[i + 1];
+                i++; // Skip the branch value
+            }
+            else {
+                // --branch without a value: filter to items that have any branch set
+                branchFilter = "";
+            }
+        }
         else if (args[i] === "--model" || args[i] === "-m") {
             if (i + 1 < args.length) {
                 model = args[i + 1];
@@ -610,6 +644,10 @@ export async function run(args) {
     });
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
+    // Use config model as fallback when --model flag is not provided
+    if (!model && cliConfig.model) {
+        model = cliConfig.model;
+    }
     // Check if stream-json output is enabled
     const streamJsonConfig = config.docker?.asciinema?.streamJson;
     // Get provider-specific streamJsonArgs, falling back to Claude's defaults
@@ -634,7 +672,7 @@ export async function run(args) {
     // Container is required, so always run with skip-permissions
     const sandboxed = true;
     if (allMode) {
-        const counts = countPrdItems(paths.prd, category);
+        const counts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
         console.log("Starting ralph in --all mode (runs until all tasks complete)...");
         console.log(`PRD Status: ${counts.complete}/${counts.total} complete, ${counts.incomplete} remaining`);
     }
@@ -647,6 +685,25 @@ export async function run(args) {
     if (category) {
         console.log(`Filtering PRD items by category: ${category}`);
     }
+    if (branchFilterActive) {
+        if (branchFilter === "") {
+            console.log("Filtering PRD items to only branched items");
+        }
+        else {
+            console.log(`Filtering PRD items by branch: ${branchFilter}`);
+        }
+        // Check if any items match the branch filter; if not, exit early
+        const branchCounts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
+        if (branchCounts.total === 0) {
+            if (branchFilter === "") {
+                console.error("\nNo PRD items have a branch field set.");
+            }
+            else {
+                console.error(`\nNo PRD items match branch "${branchFilter}".`);
+            }
+            process.exit(1);
+        }
+    }
     if (streamJson?.enabled) {
         console.log("Stream JSON output enabled - displaying formatted Claude output");
         if (streamJson.saveRawJson) {
@@ -664,7 +721,7 @@ export async function run(args) {
     let iterationCount = 0;
     // Progress tracking for --all mode
     // Progress = tasks completed OR new tasks added (allows ralph to expand the PRD)
-    const initialCounts = countPrdItems(paths.prd, category);
+    const initialCounts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
     let lastCompletedCount = initialCounts.complete;
     let lastTotalCount = initialCounts.total;
     let iterationsWithoutProgress = 0;
@@ -792,7 +849,7 @@ export async function run(args) {
     try {
         while (true) {
             iterationCount++;
-            const currentCounts = countPrdItems(paths.prd, category);
+            const currentCounts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
             // Check if we should stop (not in loop mode)
             if (!loopMode && !allMode) {
                 if (iterationCount > requestedIterations) {
@@ -819,6 +876,9 @@ export async function run(args) {
             if (category) {
                 itemsForIteration = itemsForIteration.filter((item) => item.category === category);
             }
+            if (branchFilterActive) {
+                itemsForIteration = applyBranchFilter(itemsForIteration, branchFilter);
+            }
             const branchGroups = groupItemsByBranch(itemsForIteration);
             // Check if there are any incomplete items
             if (branchGroups.size === 0) {
@@ -834,7 +894,7 @@ export async function run(args) {
                     console.log("=".repeat(50));
                     while (true) {
                         await sleep(POLL_INTERVAL_MS);
-                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, paths.dir, category);
+                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, paths.dir, category, branchFilterActive, branchFilter);
                         if (newItems) {
                             console.log("\nNew incomplete item(s) detected! Resuming...");
                             break;
@@ -846,7 +906,7 @@ export async function run(args) {
                 else {
                     console.log("\n" + "=".repeat(50));
                     if (allMode) {
-                        const counts = countPrdItems(paths.prd, category);
+                        const counts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
                         if (category) {
                             console.log(`PRD COMPLETE - All "${category}" tasks finished!`);
                         }
@@ -976,7 +1036,7 @@ export async function run(args) {
                         console.log(`\n\x1b[36m--- No-branch items (${noBranchItems.length} item(s)) ---\x1b[0m`);
                     }
                     // Create filtered PRD for no-branch items only (or all items if no branches exist)
-                    const { tempPath } = createFilteredPrd(paths.prd, paths.dir, category);
+                    const { tempPath } = createFilteredPrd(paths.prd, paths.dir, category, branchFilterActive, branchFilter);
                     filteredPrdPath = tempPath;
                     // If there are branch groups, rewrite prd-tasks.json to only include no-branch items
                     if (hasBranches) {
@@ -995,7 +1055,7 @@ export async function run(args) {
             validateAndRecoverPrd(paths.prd, validPrd);
             // Track progress for --all mode: stop if no progress after N iterations
             if (allMode) {
-                const progressCounts = countPrdItems(paths.prd, category);
+                const progressCounts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
                 const tasksCompleted = progressCounts.complete > lastCompletedCount;
                 const tasksAdded = progressCounts.total > lastTotalCount;
                 if (tasksCompleted || tasksAdded) {
@@ -1056,7 +1116,7 @@ export async function run(args) {
             // so its COMPLETE signal means "this group is done", not "all PRD items are done".
             // We must verify the full PRD before treating this as a global completion.
             if (iterOutput.includes("<promise>COMPLETE</promise>")) {
-                const fullCounts = countPrdItems(paths.prd, category);
+                const fullCounts = countPrdItems(paths.prd, category, branchFilterActive, branchFilter);
                 if (fullCounts.incomplete > 0) {
                     // There are still incomplete items in other groups — continue the loop
                     if (debug) {
@@ -1070,7 +1130,7 @@ export async function run(args) {
                     console.log("=".repeat(50));
                     while (true) {
                         await sleep(POLL_INTERVAL_MS);
-                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, paths.dir, category);
+                        const { hasIncomplete: newItems } = createFilteredPrd(paths.prd, paths.dir, category, branchFilterActive, branchFilter);
                         if (newItems) {
                             console.log("\nNew incomplete item(s) detected! Resuming...");
                             break;

package/dist/config/cli-providers.json

@@ -135,6 +135,24 @@
       },
       "modelArgs": ["--model"]
     },
+    "ollama": {
+      "name": "Ollama",
+      "description": "Local LLM server with CLI interface",
+      "command": "ollama",
+      "defaultArgs": [],
+      "yoloArgs": [],
+      "promptArgs": ["run"],
+      "docker": {
+        "install": "# Install zstd (required for Ollama model layers)\nRUN apt-get update && apt-get install -y zstd && rm -rf /var/lib/apt/lists/*\n\n# Install Ollama\nRUN curl -fsSL https://ollama.com/install.sh | sh",
+        "note": "After building, Ollama needs a model pulled. Set cli.model in config.json and rebuild, or pull manually inside the container with: ollama pull <model>"
+      },
+      "envVars": [],
+      "credentialMount": null,
+      "modelConfig": {
+        "note": "Set cli.model in config.json (e.g., \"qwen3:1.7b\") to auto-pull during docker build. Or pull manually: ollama pull <model>"
+      },
+      "modelArgs": []
+    },
     "custom": {
       "name": "Custom CLI",
       "description": "Configure your own AI CLI tool",

package/dist/tui/components/SectionNav.js

@@ -12,6 +12,12 @@ export const CONFIG_SECTIONS = [
         icon: "⚙",
         fields: ["language", "checkCommand", "testCommand", "imageName", "technologies", "javaVersion"],
     },
+    {
+        id: "cli",
+        label: "CLI",
+        icon: "⌨",
+        fields: ["cliProvider", "cli.command", "cli.args", "cli.model", "cli.yoloArgs", "cli.promptArgs", "cli.modelArgs", "cli.fileArgs"],
+    },
     {
         id: "docker",
         label: "Docker",

package/dist/utils/config.d.ts

@@ -4,6 +4,7 @@ export interface CliConfig {
     yoloArgs?: string[];
     promptArgs?: string[];
     modelArgs?: string[];
+    model?: string;
     fileArgs?: string[];
 }
 /**

package/docs/BRANCHING.md

@@ -177,18 +177,18 @@ The branch state is cleaned up from config after the group completes.
 
 ### `ralph branch list`
 
-Shows all branches referenced in `prd.yaml` with status:
+Shows all branches referenced in the PRD with status:
 
 ```
 Branches:
 
-  * feat/auth     2/3 complete  [worktree: /worktrees/cool-prj_feat-auth]
-    feat/ui       0/1 complete  [no worktree]
-    (no branch)   1/2 complete
-
-  * = currently active
+  ○ feat/auth  2/3 [worktree] ◀ active
+  ○ feat/ui  0/1
+  ○ (no branch)  1/2
 ```
 
+Each branch shows a pass/total count, a `[worktree]` indicator if the worktree directory exists on disk, and `◀ active` if it's the branch currently being worked on.
+
 ### `ralph branch merge <name>`
 
 Merges a completed branch back into the base branch:
@@ -199,33 +199,25 @@ ralph branch merge feat/auth
 
 1. Asks for confirmation
 2. Merges `feat/auth` into the base branch (in `/workspace`)
-3. Removes the worktree with `git worktree remove`
-4. Cleans up the worktree directory from the host
+3. Removes the worktree with `git worktree remove` (if it exists)
 
 If there are merge conflicts, ralph aborts the merge, lists the conflicting files, and suggests resolving manually or creating a PRD item for the AI to resolve.
 
 ### `ralph branch pr <name>`
 
-Creates a new PRD item that instructs the AI to open a pull request:
+Creates a GitHub pull request for the branch using the `gh` CLI:
 
 ```bash
 ralph branch pr feat/auth
 ```
 
-Appends to `prd.yaml`:
-
-```yaml
-- category: integration
-  description: Create a pull request from feat/auth into main
-  branch: feat/auth
-  steps:
-    - Push feat/auth to the remote repository
-    - Create a pull request from feat/auth into main using `gh pr create`
-    - Include a summary of changes in the PR description
-  passes: false
-```
+1. Verifies `gh` is installed and authenticated
+2. Pushes the branch to the remote if it has no upstream tracking
+3. Generates a PR body with PRD item checklist and commit log
+4. Asks for confirmation
+5. Creates the PR via `gh pr create`
 
-This lets the AI create the PR in the next `ralph run`, or the user can create it manually.
+Requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
 
 ### `ralph branch delete <name>`
 
@@ -245,17 +237,18 @@ ralph branch delete feat/old-feature
 When `ralph branch merge` detects conflicts:
 
 ```
-Merge conflict detected for feat/auth → main
+Merge conflict detected!
 
 Conflicting files:
-  - src/components/App.tsx
-  - src/utils/config.ts
+  src/components/App.tsx
+  src/utils/config.ts
 
-The merge has been aborted (no changes made).
+Merge aborted.
 
-Options:
-  1. Resolve manually: git merge feat/auth (in /workspace)
-  2. Create a PRD item: ralph branch pr feat/auth
+To resolve:
+  1. Resolve conflicts manually and merge again
+  2. Or add a PRD item to resolve the conflicts:
+     ralph prd add  # describe the conflict resolution needed
 ```
 
 Conflicts are a normal part of branching. They occur when both the branch and the base branch modify the same lines. Ralph never force-merges — it always aborts cleanly and lets the user decide.

package/docs/CHAT-CLIENTS.md

@@ -79,6 +79,7 @@ The bot will respond to commands in the allowed chats.
 | `/stop` | Stop running ralph process |
 | `/action build` | Execute a daemon action |
 | `/claude Fix the CSS` | Run Claude Code with a prompt |
+| `/branch list` | List branches and their status |
 | `/help` | Show available commands |
 
 ---
@@ -132,20 +133,14 @@ Socket Mode allows the bot to receive events without a public URL.
    - `message.im` - Direct messages
 4. Click **Save Changes**
 
-### Step 6: Create Slash Commands (Optional)
+### Step 6: Create Slash Command (Optional)
 
 1. Go to **Slash Commands**
-2. Click **Create New Command** for each:
+2. Click **Create New Command**:
 
 | Command | Request URL | Description |
 |---------|-------------|-------------|
-| `/run` | (leave empty for Socket Mode) | Start ralph automation |
-| `/status` | (leave empty for Socket Mode) | Show PRD progress |
-| `/add` | (leave empty for Socket Mode) | Add new task |
-| `/exec` | (leave empty for Socket Mode) | Execute shell command |
-| `/stop` | (leave empty for Socket Mode) | Stop ralph process |
-| `/action` | (leave empty for Socket Mode) | Execute daemon action |
-| `/claude` | (leave empty for Socket Mode) | Run Claude Code |
+| `/ralph` | (leave empty for Socket Mode) | Ralph unified command (use subcommands like `/ralph run`, `/ralph status`) |
 
 ### Step 7: Get Channel IDs
 
@@ -186,17 +181,18 @@ ralph chat start
 
 ### Slack Commands
 
-Use either slash commands (`/run`) or message the bot with commands:
+Use the `/ralph` slash command with subcommands, or message the bot directly:
 
 | Command | Description |
 |---------|-------------|
-| `/run` or `/run feature` | Start automation |
-| `/status` | Show PRD progress |
-| `/add Fix the bug` | Add a task |
-| `/exec npm test` | Execute command |
-| `/stop` | Stop ralph |
-| `/action build` | Execute action |
-| `/claude Fix CSS` | Run Claude Code |
+| `/ralph run` or `/ralph run feature` | Start automation |
+| `/ralph status` | Show PRD progress |
+| `/ralph add Fix the bug` | Add a task |
+| `/ralph exec npm test` | Execute command |
+| `/ralph stop` | Stop ralph |
+| `/ralph action build` | Execute action |
+| `/ralph branch list` | Manage branches |
+| `/ralph Fix CSS` | Run Claude Code (any unrecognized subcommand) |
 
 ---