ralph-cli-sandboxed 0.6.3 → 0.6.4

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"];
@@ -485,7 +485,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 +503,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.`);
     }
@@ -610,6 +610,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

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) |
 
 ---
 

package/docs/CHAT-RESPONDERS.md

@@ -240,10 +240,10 @@ LLM responders automatically detect file paths mentioned in messages and include
 The responder will automatically read the file, extract ~20 lines around line 50, and include it in the LLM context.
 
 **Limits:**
-- Max 50KB total file content per message
-- Max 30KB per individual file
+- Max 15KB total file content per message
+- Max 8KB per individual file
 - Files larger than 100KB are skipped
-- 50+ file extensions supported (ts, js, py, go, rs, java, etc.)
+- 42 file extensions supported (ts, js, py, go, rs, java, etc.)
 
 #### Git Diff Keywords
 

package/docs/DEVELOPMENT.md

@@ -47,23 +47,61 @@ ralph-cli-sandboxed/
 ├── src/
 │   ├── index.ts              # CLI entry point
 │   ├── commands/             # Command implementations
+│   │   ├── action.ts         # ralph action
+│   │   ├── branch.ts         # ralph branch (list, merge, delete, pr)
+│   │   ├── chat.ts           # ralph chat
+│   │   ├── config.tsx        # ralph config (TUI launcher)
+│   │   ├── daemon.ts         # ralph daemon
+│   │   ├── docker.ts         # ralph docker
+│   │   ├── fix-config.ts     # ralph fix-config
+│   │   ├── fix-prd.ts        # ralph fix-prd
+│   │   ├── help.ts           # ralph help
 │   │   ├── init.ts           # ralph init
-│   │   ├── run.ts            # ralph run
+│   │   ├── listen.ts         # ralph listen
+│   │   ├── logo.ts           # ralph logo
+│   │   ├── notify.ts         # ralph notify
 │   │   ├── once.ts           # ralph once
 │   │   ├── prd.ts            # PRD management commands
-│   │   ├── docker.ts         # Docker commands
+│   │   ├── prd-convert.ts    # PRD YAML-to-JSON conversion
+│   │   ├── progress.ts       # ralph progress
 │   │   ├── prompt.ts         # ralph prompt
-│   │   ├── fix-prd.ts        # ralph fix-prd
-│   │   └── help.ts           # ralph help
+│   │   ├── run.ts            # ralph run
+│   │   └── slack.ts          # ralph slack
+│   ├── providers/            # Chat platform providers
+│   │   ├── discord.ts        # Discord bot provider
+│   │   ├── slack.ts          # Slack bot provider
+│   │   └── telegram.ts       # Telegram bot provider
+│   ├── responders/           # Chat responder implementations
+│   │   ├── claude-code-responder.ts
+│   │   ├── cli-responder.ts
+│   │   └── llm-responder.ts
+│   ├── tui/                  # Terminal UI (config editor)
+│   │   ├── ConfigEditor.tsx  # Main config editor component
+│   │   ├── components/       # UI components
+│   │   ├── hooks/            # React hooks
+│   │   └── utils/            # TUI utilities
 │   ├── utils/
+│   │   ├── chat-client.ts    # Chat client interface
 │   │   ├── config.ts         # Configuration loading
+│   │   ├── daemon-actions.ts # Daemon action handling
+│   │   ├── daemon-client.ts  # Daemon client interface
+│   │   ├── llm-client.ts     # LLM API client
+│   │   ├── message-queue.ts  # Message queue management
+│   │   ├── notification.ts   # Notification utilities
 │   │   ├── prd-validator.ts  # PRD validation and recovery
-│   │   └── prompt.ts         # Interactive prompts
+│   │   ├── prompt.ts         # Interactive prompts
+│   │   ├── responder-logger.ts # Responder logging
+│   │   ├── responder-presets.ts # Responder preset loading
+│   │   ├── responder.ts      # Base responder logic
+│   │   └── stream-json.ts    # JSON streaming utilities
 │   ├── templates/
+│   │   ├── macos-scripts.ts  # macOS/Swift script templates
 │   │   └── prompts.ts        # Prompt template generation
 │   └── config/
-│       ├── languages.json    # Language configurations
-│       └── cli-providers.json # CLI provider configurations
+│       ├── cli-providers.json    # CLI provider configurations
+│       ├── languages.json        # Language configurations
+│       ├── responder-presets.json # Chat responder presets
+│       └── skills.json           # Skill definitions
 ├── docs/                     # Documentation
 ├── dist/                     # Compiled output (generated)
 └── package.json

package/docs/DOCKER.md

@@ -18,8 +18,8 @@ ralph docker run
 | `ralph docker init` | Generate/regenerate Docker configuration files |
 | `ralph docker build` | Build the Docker image |
 | `ralph docker run` | Run ralph inside the container (auto-builds if needed) |
-| `ralph docker shell` | Open an interactive shell in the container |
-| `ralph docker status` | Show container and image status |
+| `ralph docker clean` | Remove Docker image and associated resources |
+| `ralph docker help` | Show help message |
 
 ## Generated Files
 
@@ -29,7 +29,8 @@ After running `ralph init` or `ralph docker init`, you'll find:
 .ralph/docker/
 ├── Dockerfile           # Container image definition
 ├── docker-compose.yml   # Container orchestration
-└── firewall.sh          # Network sandbox rules
+├── init-firewall.sh     # Network sandbox rules
+└── .dockerignore        # Build exclusions
 ```
 
 ## Features
@@ -206,7 +207,7 @@ sudo chown -R $(id -u):$(id -g) .ralph/
 
 The firewall script restricts outbound connections. If you need additional access:
 
-1. Edit `.ralph/docker/firewall.sh`
+1. Edit `.ralph/docker/init-firewall.sh`
 2. Add your required domains/IPs
 3. Rebuild: `ralph docker build`
 

package/docs/FAQ.md

@@ -0,0 +1,125 @@
+# FAQ
+
+## Getting Started
+
+### How do I initialize Ralph in my project?
+
+Run `ralph init` in your project root. The interactive wizard walks you through selecting a language, CLI provider (Claude Code, Aider, Codex, etc.), and optional skills. It creates the `.ralph/` directory with config files and generates Docker files automatically. Use `ralph init -y` to accept defaults (Claude Code + Node.js).
+
+### Which AI CLI tools does Ralph support?
+
+Ralph supports **Claude Code**, **Aider**, **Codex**, **Gemini CLI**, **OpenCode**, **AMP**, **Goose**, and **Ollama** out of the box. You can also use the `custom` provider to configure any CLI tool. Select your provider during `ralph init` or change it later in `.ralph/config.json` under `cliProvider`.
+
+### Which programming languages are supported?
+
+18 languages: TypeScript/Node, Python, Go, Rust, Java, Kotlin, C#/.NET, Ruby, PHP, Swift, Elixir, Scala, Zig, Haskell, Clojure, Deno, Bun, and Custom. Each comes with pre-configured `checkCommand` and `testCommand`.
+
+## Running Ralph
+
+### What's the difference between `ralph once` and `ralph run`?
+
+`ralph once` runs a single iteration inside the container. `ralph run` supports multiple modes:
+- `ralph run 5` — run 5 iterations
+- `ralph run --all` — run until all PRD items pass
+- `ralph run --loop` — run indefinitely, polling for new items every 30 seconds
+
+### When does Ralph stop running?
+
+Ralph stops when:
+- All PRD items are marked `passes: true`
+- The requested number of iterations is reached
+- 3 consecutive failures with the same exit code occur (likely a config error)
+- 3 iterations pass without progress (no tasks completed and no new tasks added)
+
+### Can I run Ralph without `ralph run`?
+
+Sometimes the execution (e.g. OpenCode) doesn't work or get stuck or isn't possible with free AMP. The following prompt lets Ralph loop, but keep in mind that no event is triggered when a task is finished:
+
+> Call in a loop `ralph prompt` and use this prompt — then check if @.ralph/prd.yaml has a task which isn't passes=true and start over with a fresh session and read the prompt and execute it.
+
+### How do I use a specific model?
+
+Pass `--model <name>` to `ralph run`, e.g. `ralph run --model claude-sonnet-4-5-20250929`. You can also set the model via environment variable (provider-specific: `CLAUDE_MODEL`, `AIDER_MODEL`, `CODEX_MODEL`, etc.).
+
+## PRD Management
+
+### What's the PRD format?
+
+PRD files (`.ralph/prd.yaml` or `.ralph/prd.json`) contain an array of items with:
+- `category` — one of: ui, feature, bugfix, setup, development, testing, docs
+- `description` — single sentence, imperative verb (e.g. "Add login page")
+- `steps` — concrete actions including verification steps
+- `passes` — boolean, set to `true` when the item is complete
+- `branch` — (optional) groups items onto a git branch
+
+### How do I write good PRD items?
+
+Keep items small and focused. Each item should be completable in one iteration. Write clear, concrete steps — include verification steps so the AI agent can confirm its work. Use `@{filepath}` syntax in steps to reference file contents.
+
+### My PRD got corrupted — what do I do?
+
+Run `ralph fix-prd`. It auto-diagnoses and repairs corruption (common when an LLM modifies the file incorrectly). Ralph also creates automatic backups in `.ralph/backups/` before each run. Use `ralph fix-prd --verify` to check without modifying, or restore from a specific backup file.
+
+## Docker & Containers
+
+### Why does Ralph need Docker?
+
+Docker provides a sandboxed environment where the AI agent runs with autonomous permissions (`--dangerously-skip-permissions` for Claude Code). This keeps your host system safe. The container also enforces network restrictions — only essential domains (GitHub, npm, your API provider) are allowed by default.
+
+### How do I add domains to the firewall whitelist?
+
+Add domains to `docker.firewall.allowedDomains` in `.ralph/config.json`, then rebuild the image with `ralph docker build`. You can also edit `.ralph/docker/init-firewall.sh` directly.
+
+### How do I add custom packages to the Docker image?
+
+Use `docker.packages` in config.json for system packages (installed via apt-get), or use `docker.buildCommands.root` / `docker.buildCommands.node` for custom build steps.
+
+### Can I customize ports, volumes, and environment variables?
+
+Yes — configure `docker.ports`, `docker.volumes`, and `docker.environment` in `.ralph/config.json`. Run `ralph docker init` to regenerate the docker-compose.yml after changes.
+
+## Branching
+
+### How does branching work in Ralph?
+
+Add a `branch` field to PRD items to group them onto a git branch. Ralph uses **git worktrees** (not `git checkout`) to isolate branch work — this avoids changing the host's mounted volume. Configure `docker.worktreesPath` in config.json to set where worktrees are stored on the host.
+
+### What branch commands are available?
+
+- `ralph branch list` — show all branches with item counts and status
+- `ralph branch merge <name>` — merge a completed branch back to base
+- `ralph branch pr <name>` — create a GitHub PR from the branch
+- `ralph branch delete <name>` — remove a worktree and delete the branch
+
+## Notifications & Monitoring
+
+### How do I set up notifications?
+
+Ralph supports **ntfy** (recommended — no install needed, just HTTP) and **command-based** notifications. Configure in `.ralph/config.json` under `notifications`. Events include `task_complete`, `prd_complete`, `ralph_complete`, `iteration_complete`, `run_stopped`, and `error`.
+
+### How do I monitor Ralph's progress?
+
+- `ralph status` — shows completion count, remaining items, and branch info
+- `ralph status --head` — compact status without item headlines
+- `.ralph/progress.txt` — detailed log of each iteration's work
+- `ralph progress summarize` — creates a timestamped backup and compresses the progress file
+
+## Troubleshooting
+
+### Ralph keeps failing after a few iterations
+
+If you see "CLI failed N times with exit code X", it's likely a configuration issue. Check:
+1. Your API key is set correctly (environment variable or mounted credentials)
+2. The CLI provider is installed and working outside Ralph
+3. Network connectivity — the firewall may be blocking required domains
+
+### Ralph seems stuck with "no progress"
+
+"No progress" means no PRD items were completed **and** no new items were added across 3 consecutive iterations. This usually means:
+- PRD steps are too vague for the AI to verify completion
+- The task is too large for a single iteration — break it into smaller items
+- The AI is hitting an error it can't resolve — check `.ralph/progress.txt` for details
+
+### The Docker image won't build
+
+Check that Docker is running, you have enough disk space, and platform-specific dependencies are available. If a provider installation fails, try `ralph docker build` again — transient network issues are common. For persistent failures, check the Dockerfile in `.ralph/docker/`.

package/docs/HOW-TO-WRITE-PRDs.md

@@ -22,16 +22,13 @@ Use consistent categories to organize your PRD:
 
 | Category | Use for |
 |----------|---------|
-| `setup` | Initial project configuration, build verification |
+| `ui` | User interface changes |
 | `feature` | New functionality |
 | `bugfix` | Fixing broken behavior |
-| `refactor` | Code improvements without behavior change |
+| `setup` | Initial project configuration, build verification |
+| `development` | Code improvements, refactoring, configuration |
+| `testing` | Adding or updating tests |
 | `docs` | Documentation updates |
-| `test` | Adding or updating tests |
-| `release` | Version bumps, changelog updates |
-| `config` | Configuration file changes |
-| `ui` | User interface changes |
-| `integration` | Connecting components, wiring, orchestration |
 
 ## Writing Good Descriptions
 
@@ -186,7 +183,7 @@ Break large features into smaller, independently completable items. Each item sh
 ## Quick Reference
 
 ```yaml
-- category: setup|feature|bugfix|refactor|docs|test|release|config|ui|integration
+- category: ui|feature|bugfix|setup|development|testing|docs
   description: Imperative verb + specific what + where (context)
   steps:
     - Concrete action with `commands` and file paths

package/docs/MACOS-DEVELOPMENT.md

@@ -392,9 +392,9 @@ ralph action gen_xcode
 With Ralph's Telegram integration, you can trigger actions remotely:
 
 ```
-/notify gen_xcode     # Generate Xcode project
-/notify build         # Build the project
-/notify fastlane_beta # Deploy to TestFlight
+/action gen_xcode     # Generate Xcode project
+/action build         # Build the project
+/action fastlane_beta # Deploy to TestFlight
 ```
 
 See the [Chat documentation](../README.md#chat-client-configuration) for setup.

package/docs/PRD-GENERATOR.md

@@ -39,7 +39,7 @@ tasks:    # <-- This wrapper causes issues
     description: ...
 ```
 
-> **Note:** Ralph will attempt to auto-unwrap common wrapper structures like `{tasks: [...]}`, `{items: [...]}`, or `{features: [...]}`, but it's best to use the correct format from the start.
+> **Note:** Ralph will attempt to auto-unwrap common wrapper structures like `{tasks: [...]}`, `{items: [...]}`, `{features: [...]}`, `{entries: [...]}`, `{prd: [...]}`, `{requirements: [...]}`, `{todo: [...]}`, or `{checklist: [...]}`, but it's best to use the correct format from the start.
 
 ### Required Fields
 
@@ -47,7 +47,7 @@ Each PRD item must have these fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `category` | string | One of: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration |
+| `category` | string | One of: ui, feature, bugfix, setup, development, testing, docs |
 | `description` | string | What to implement (imperative verb + specific action) |
 | `steps` | string[] | Concrete actions to complete the task |
 | `passes` | boolean | **Must be `false` for new items** - Ralph sets to `true` when completed |
@@ -144,16 +144,13 @@ If a task takes 2 minutes without thinking, combine with related work.
 
 | Category | When to Use |
 |----------|-------------|
-| `setup` | Project initialization, tooling, dependencies |
+| `ui` | User interface changes, frontend components |
 | `feature` | New functionality for users |
 | `bugfix` | Fixing broken behavior |
-| `refactor` | Code improvements, no behavior change |
+| `setup` | Project initialization, tooling, dependencies |
+| `development` | Code improvements, refactoring, configuration |
+| `testing` | Test coverage (unit, integration, e2e) |
 | `docs` | Documentation (README, guides, comments) |
-| `test` | Test coverage (unit, integration, e2e) |
-| `release` | Version bumps, changelogs, packaging |
-| `config` | Configuration files, settings |
-| `ui` | User interface changes, frontend components |
-| `integration` | Connecting components, wiring, orchestration |
 
 ## Branch Field (Optional)
 
@@ -197,7 +194,7 @@ PRD items can include an optional `branch` field to group related work into git
 ralph branch list              # Show all branches and their status
 ralph branch merge <name>      # Merge a completed branch into main
 ralph branch delete <name>     # Delete a branch and its worktree
-ralph branch pr <name>         # Create a PRD item to open a PR
+ralph branch pr <name>         # Create a GitHub PR from the branch
 ```
 
 ### When to Use Branches
@@ -406,7 +403,7 @@ Convert the following document into a Ralph prd.yaml file.
 
 Rules:
 1. Each sub-task or atomic feature = one PRD item
-2. Use categories: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration
+2. Use categories: ui, feature, bugfix, setup, development, testing, docs
 3. Descriptions: imperative verb + specific what + context
 4. Steps: 2-4 concrete actions + verification step
 5. Reference source document sections instead of copying code
@@ -444,7 +441,7 @@ Convert the following document into a Ralph prd.json file.
 
 Rules:
 1. Each sub-task or atomic feature = one PRD item
-2. Use categories: setup, feature, bugfix, refactor, docs, test, release, config, ui, integration
+2. Use categories: ui, feature, bugfix, setup, development, testing, docs
 3. Descriptions: imperative verb + specific what + context
 4. Steps: 2-4 concrete actions + verification step
 5. Reference source document sections instead of copying code

package/docs/RALPH-SETUP-TEMPLATE.md

@@ -89,29 +89,30 @@ Set up a Ralph CLI project based on the configuration above.
 
 | Stack | language | checkCommand | testCommand |
 |-------|----------|--------------|-------------|
-| Node/TS (pnpm) | `typescript` | `pnpm lint && pnpm build` | `pnpm test` |
-| Node/TS (npm) | `node` | `npm run lint && npm run build` | `npm test` |
-| Node/TS (bun) | `typescript` | `bun run lint && bun run build` | `bun test` |
-| Python (pip) | `python` | `mypy . && ruff check .` | `pytest` |
-| Python (poetry) | `python` | `poetry run mypy . && poetry run ruff check .` | `poetry run pytest` |
-| Python (uv) | `python` | `uv run mypy . && uv run ruff check .` | `uv run pytest` |
-| Go | `go` | `go build ./... && go vet ./...` | `go test ./...` |
-| Rust | `rust` | `cargo build && cargo clippy` | `cargo test` |
-
-### Required Domains by Tech Stack
-
-| Stack | Package Registry Domains |
-|-------|--------------------------|
-| Node.js | `registry.npmjs.org`, `github.com` |
-| Python | `pypi.org`, `files.pythonhosted.org`, `github.com` |
-| Go | `proxy.golang.org`, `sum.golang.org`, `github.com` |
-| Rust | `crates.io`, `static.crates.io`, `github.com` |
+| Node/TS (npm) | `node` | `npm run typecheck` | `npm test` |
+| Node/TS (bun) | `bun` | `bun check` | `bun test` |
+| Python | `python` | `mypy .` | `pytest` |
+| Go | `go` | `go build ./...` | `go test ./...` |
+| Rust | `rust` | `cargo check` | `cargo test` |
+
+### Firewall Domains
+
+The Docker firewall allows these domains by default: `github.com`, `api.github.com`, `raw.githubusercontent.com`, `registry.npmjs.org`, `api.anthropic.com`.
+
+Add additional domains to `docker.firewall.allowedDomains` in `.ralph/config.json` based on your stack:
+
+| Stack | Recommended Additions |
+|-------|----------------------|
+| Python | `pypi.org`, `files.pythonhosted.org` |
+| Go | `proxy.golang.org`, `sum.golang.org` |
+| Rust | `crates.io`, `static.crates.io` |
 
 ### API Provider Domains
 
+Add these to `docker.firewall.allowedDomains` if using external APIs:
+
 | Provider | Domains |
 |----------|---------|
-| Anthropic Claude | `api.anthropic.com` |
 | OpenAI | `api.openai.com` |
 | Google AI | `generativelanguage.googleapis.com` |
 | AWS | `*.amazonaws.com` |
@@ -124,6 +125,8 @@ Set up a Ralph CLI project based on the configuration above.
 
 ### Notifications Config
 
+Supported providers: `ntfy`, `pushover`, `gotify`, `command`.
+
 Using ntfy (recommended - no install needed):
 ```json
 {
@@ -137,6 +140,32 @@ Using ntfy (recommended - no install needed):
 }
 ```
 
+Using pushover:
+```json
+{
+  "notifications": {
+    "provider": "pushover",
+    "pushover": {
+      "user": "your-user-key",
+      "token": "your-app-token"
+    }
+  }
+}
+```
+
+Using gotify:
+```json
+{
+  "notifications": {
+    "provider": "gotify",
+    "gotify": {
+      "server": "https://gotify.example.com",
+      "token": "your-app-token"
+    }
+  }
+}
+```
+
 Using custom command:
 ```json
 {
@@ -205,10 +234,14 @@ Log task completions and ralph finished to file:
 ```
 
 Chat commands (send in Telegram):
-- `/run` - Start ralph automation
+- `/run [category]` - Start ralph automation
 - `/status` - Show PRD progress
+- `/stop` - Stop a running ralph process
 - `/add [desc]` - Add new task
 - `/exec [cmd]` - Execute shell command
+- `/action [name]` - Execute a daemon action
+- `/claude [prompt]` - Run Claude Code with a prompt
+- `/branch [subcommand]` - Manage git branches
 - `/help` - Show help
 
 ### PRD Task Categories
@@ -216,12 +249,11 @@ Chat commands (send in Telegram):
 | Category | Use For |
 |----------|---------|
 | `setup` | Project initialization, dependency installation |
-| `config` | Environment variables, configuration files |
 | `feature` | New functionality implementation |
-| `integration` | External API clients, third-party services |
-| `test` | Unit tests, integration tests |
-| `refactor` | Code restructuring without behavior change |
 | `bugfix` | Bug fixes |
+| `ui` | User interface changes |
+| `development` | Development tooling, build configuration |
+| `testing` | Unit tests, integration tests |
 | `docs` | Documentation |
 
 ### PRD Guidelines
@@ -231,7 +263,7 @@ Chat commands (send in Telegram):
 - Include 2-4 concrete steps per task
 - End with a verification step (build, typecheck, test)
 - All tasks start with `"passes": false`
-- Order by dependency: setup -> config -> features -> tests -> docs
+- Order by dependency: setup -> development -> feature -> testing -> docs
 
 ### Sandbox Safety
 

package/docs/SECURITY.md

@@ -20,7 +20,9 @@ When running inside a container, ralph automatically passes the appropriate auto
 | AMP | `--dangerously-allow-all` | ✅ Supported |
 | Aider | `--yes-always` | ✅ Supported |
 | Goose | (none needed) | ✅ Supported |
-| OpenCode | `--yolo` | ❌ Not yet implemented |
+| OpenCode | (none) | ❌ Not yet implemented |
+| Ollama | (none needed) | ✅ Supported |
+| Custom | (none) | ⚙️ User-configured |
 
 For providers without autonomous mode support, you may need to manually approve actions during execution.
 
@@ -64,7 +66,7 @@ For Claude Code users with Pro/Max subscriptions, the `~/.claude` directory is m
 
 ```yaml
 volumes:
-  - ~/.claude:/home/node/.claude:ro
+  - ~/.claude:/home/node/.claude
 ```
 
 This allows the AI agent to use your existing OAuth credentials without exposing API keys.

package/docs/SKILLS.md

@@ -174,11 +174,11 @@ Target project-specific requirements:
 
 ## How Skills Are Applied
 
-When ralph runs an iteration:
+During `ralph docker init`:
 
 1. Skills from `claude.skills` are loaded from config
-2. Skill instructions are injected into the prompt template
-3. Claude receives the combined prompt with all active skill instructions
+2. Each skill is written as a `.claude/commands/<name>.md` file with YAML frontmatter (`description`, `user-invocable`)
+3. Claude Code natively reads these command files and applies the skill instructions
 
 This ensures Claude consistently follows your defined rules across all iterations.
 

package/docs/chat-architecture.md

@@ -47,7 +47,8 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 │  │ └─────────┘ │                    ▼                                        │
 │  └─────────────┘    ┌───────────────────────────────────────┐               │
 │                     │           Command Handler              │               │
-│                     │  run, stop, status, exec, add, claude  │               │
+│                     │  run, stop, status, exec, add, claude, │               │
+│                     │  help, start, action, branch           │               │
 │                     └───────────────────┬───────────────────┘               │
 │                                         │                                    │
 │                                         ▼                                    │
@@ -96,7 +97,7 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 ┌─────────────────────────────────────────────────────────────────┐
 │                    ResponderMatcher                              │
 │                                                                  │
-│  1. Check @mention triggers: @qa, @review, @explain, @code      │
+│  1. Check @mention triggers: @qa, @review, @arch, @explain, @code│
 │  2. Check keyword triggers: !lint, help                          │
 │  3. Fall back to default responder                               │
 └─────────────────────────────┬───────────────────────────────────┘
@@ -111,11 +112,11 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 ┌─────────────────────────────────────────────────────────────────┐
 │                    LLM Responder                                 │
 │                                                                  │
-│  1. Detect git keyword: "last" → git show HEAD                  │
+│  1. Detect git keyword: "last" → git show HEAD --stat --patch   │
 │  2. Fetch git diff content                                       │
 │  3. Build message with diff                                      │
 │  4. Load conversation history (if thread)                        │
-│  5. Send to LLM (Anthropic/OpenAI)                              │
+│  5. Send to LLM (Anthropic/OpenAI/Ollama)                       │
 │  6. Log to .ralph/logs/responder-YYYY-MM-DD.log                 │
 │  7. Return response                                              │
 └─────────────────────────────┬───────────────────────────────────┘
@@ -168,48 +169,54 @@ Reply in thread               history (max 20 messages)
 
 ## Message Queue Format
 
+The messages file stores a direct JSON array (no wrapper object):
+
 ```json
-{
-  "messages": [
-    {
-      "id": "uuid-1234",
-      "from": "host",
-      "action": "run",
-      "args": ["feature"],
-      "timestamp": 1706789012345,
-      "status": "pending"
-    },
-    {
-      "id": "uuid-1234",
-      "from": "host",
-      "action": "run",
-      "args": ["feature"],
-      "timestamp": 1706789012345,
-      "status": "done",
-      "response": {
-        "success": true,
-        "output": "Ralph run started (category: feature)"
-      }
+[
+  {
+    "id": "uuid-1234",
+    "from": "host",
+    "action": "run",
+    "args": ["feature"],
+    "timestamp": 1706789012345,
+    "status": "pending"
+  },
+  {
+    "id": "uuid-1234",
+    "from": "host",
+    "action": "run",
+    "args": ["feature"],
+    "timestamp": 1706789012345,
+    "status": "done",
+    "response": {
+      "success": true,
+      "output": "Ralph run started (category: feature)"
     }
-  ]
-}
+  }
+]
 ```
 
+Fields:
+- `from`: `"sandbox"` or `"host"`
+- `args`: optional string array
+- `status`: `"pending"` or `"done"`
+- `response`: optional, contains `success` (boolean), `output` (optional string), and `error` (optional string)
+
 ## Git Diff Keywords
 
 | Keyword | Git Command | Description |
 |---------|-------------|-------------|
 | `diff` / `changes` | `git diff` | Unstaged changes |
 | `staged` | `git diff --cached` | Staged changes |
-| `last` / `last commit` | `git show HEAD` | Last commit |
+| `last` / `last commit` | `git show HEAD --stat --patch` | Last commit |
 | `all` | `git diff HEAD` | All uncommitted |
-| `HEAD~N` | `git show HEAD~N` | N commits ago |
+| `HEAD~N` | `git show HEAD~N --stat --patch` | N commits ago |
 
 ## Responder Types
 
 | Type | Description | Example Trigger |
 |------|-------------|-----------------|
-| `llm` | Send to LLM (Anthropic/OpenAI) | `@qa`, `@review` |
+| `llm` | Send to LLM (Anthropic/OpenAI/Ollama) | `@qa`, `@review` |
 | `claude-code` | Spawn Claude Code CLI | `@code` |
 | `cli` | Run shell command | `!lint` |
 

package/docs/run-state-machine.md

@@ -27,13 +27,21 @@ flowchart TD
     subgraph Analysis ["4. Result Analysis"]
         ExitCheck{Exit Code == 0?}
 
-        ExitCheck -- "No" --> FailurePath[Increment Failure Counter]
-        FailurePath --> CriticalCheck{Failures >= 3?}
+        ExitCheck -- "No" --> FailurePath[Track Failure]
+        FailurePath --> SameCode{Same Exit Code\nas Last Failure?}
+        SameCode -- "Yes" --> IncrementFailures[Increment Consecutive\nFailure Counter]
+        SameCode -- "No" --> ResetToOne[Reset Counter to 1]
+        IncrementFailures --> CriticalCheck{Consecutive\nFailures >= 3?}
+        ResetToOne --> CriticalCheck
         CriticalCheck -- "Yes" --> Abort([Abort: Too Many Errors])
-        CriticalCheck -- "No" --> SignalCheck
+        CriticalCheck -- "No" --> ProgressCheck
 
         ExitCheck -- "Yes" --> SuccessPath[Reset Failure Counter]
-        SuccessPath --> SignalCheck
+        SuccessPath --> ProgressCheck
+
+        ProgressCheck{All Mode:\nProgress Made?}
+        ProgressCheck -- "Yes / Not All Mode" --> SignalCheck
+        ProgressCheck -- "No progress\n3 iterations" --> StallAbort([Abort: No Progress])
 
         SignalCheck{COMPLETE Signal?}
         SignalCheck -- "Yes" --> CompleteModeCheck
@@ -73,5 +81,6 @@ flowchart TD
     style Analysis fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
     style Completion fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
     style Abort fill:#ffebee,stroke:#c62828,color:#c62828
+    style StallAbort fill:#ffebee,stroke:#c62828,color:#c62828
     style End fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {