ralph-cli-sandboxed 0.5.0 → 0.6.0

package/README.md

@@ -44,6 +44,7 @@ ralph docker run
 | `ralph clean` | Remove all passing entries from PRD |
 | `ralph fix-prd [opts]` | Validate and recover corrupted PRD file |
 | `ralph prompt [opts]` | Display resolved prompt |
+| `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 |
 | `ralph notify [msg]` | Send notification (from sandbox to host) |
@@ -427,6 +428,20 @@ The PRD (`prd.json`) is an array of requirements:
 
 Categories: `setup`, `feature`, `bugfix`, `refactor`, `docs`, `test`, `release`, `config`, `ui`
 
+### Branching
+
+PRD items can be tagged with a `branch` field to group work onto separate git branches. Ralph uses git worktrees to isolate branch work from the main checkout, so the host's working directory stays untouched.
+
+```yaml
+- category: feature
+  description: Add login page
+  branch: feat/auth
+  steps: [...]
+  passes: false
+```
+
+See [docs/BRANCHING.md](docs/BRANCHING.md) for the full architecture, configuration, and branch management commands.
+
 ### Advanced: File References
 
 PRD steps can include file contents using the `@{filepath}` syntax:

package/dist/commands/branch.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Main branch command dispatcher.
+ */
+export declare function branch(args: string[]): Promise<void>;

package/dist/commands/branch.js

@@ -0,0 +1,408 @@
+import { execSync } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { extname, join } from "path";
+import { getRalphDir, getPrdFiles, loadBranchState, getProjectName } from "../utils/config.js";
+import { readPrdFile, writePrdAuto } from "../utils/prd-validator.js";
+import { promptConfirm } from "../utils/prompt.js";
+import YAML from "yaml";
+/**
+ * Converts a branch name to a worktree directory name, prefixed with the project name.
+ * e.g., "feat/login" -> "myproject_feat-login"
+ * The project prefix avoids conflicts when multiple projects share the same worktrees directory.
+ */
+function branchToWorktreeName(branch) {
+    const projectName = getProjectName();
+    return `${projectName}_${branch.replace(/\//g, "-")}`;
+}
+/**
+ * Gets the worktrees base path from config or defaults to /worktrees.
+ */
+function getWorktreesBase() {
+    return "/worktrees";
+}
+/**
+ * Loads PRD entries from the primary PRD file.
+ */
+function loadPrdEntries() {
+    const prdFiles = getPrdFiles();
+    if (!prdFiles.primary) {
+        console.error("\x1b[31mError: No PRD file found. Run 'ralph init' first.\x1b[0m");
+        return null;
+    }
+    const parsed = readPrdFile(prdFiles.primary);
+    if (!parsed || !Array.isArray(parsed.content)) {
+        console.error("\x1b[31mError: PRD file is corrupted. Run 'ralph fix-prd' to repair.\x1b[0m");
+        return null;
+    }
+    return { entries: parsed.content, prdPath: prdFiles.primary };
+}
+/**
+ * Gets the base branch (the branch that /workspace is on).
+ */
+function getBaseBranch() {
+    try {
+        return execSync("git -C /workspace rev-parse --abbrev-ref HEAD", { encoding: "utf-8" }).trim();
+    }
+    catch {
+        return "main";
+    }
+}
+/**
+ * Checks if a git branch exists.
+ */
+function branchExists(branch) {
+    try {
+        execSync(`git rev-parse --verify "${branch}"`, { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * List all branches referenced in the PRD and their status.
+ * Shows item counts, pass/fail status, worktree existence, and active branch indicator.
+ */
+function branchList() {
+    const result = loadPrdEntries();
+    if (!result)
+        return;
+    const { entries } = result;
+    const worktreesBase = getWorktreesBase();
+    const activeBranch = loadBranchState();
+    // Group items by branch
+    const branchGroups = new Map();
+    const noBranchItems = [];
+    for (const entry of entries) {
+        if (entry.branch) {
+            const group = branchGroups.get(entry.branch) || [];
+            group.push(entry);
+            branchGroups.set(entry.branch, group);
+        }
+        else {
+            noBranchItems.push(entry);
+        }
+    }
+    if (branchGroups.size === 0 && noBranchItems.length === 0) {
+        console.log("No PRD items found.");
+        return;
+    }
+    console.log("\x1b[1mBranches:\x1b[0m\n");
+    // Sort branches alphabetically
+    const sortedBranches = [...branchGroups.keys()].sort();
+    for (const branchName of sortedBranches) {
+        const items = branchGroups.get(branchName);
+        const passing = items.filter((e) => e.passes).length;
+        const total = items.length;
+        const allPassing = passing === total;
+        // Check if worktree exists on disk
+        const dirName = branchToWorktreeName(branchName);
+        const worktreePath = join(worktreesBase, dirName);
+        const hasWorktree = existsSync(worktreePath);
+        // Check if this is the active branch
+        const isActive = activeBranch?.currentBranch === branchName;
+        // Build the line
+        const statusIcon = allPassing ? "\x1b[32m✅\x1b[0m" : "\x1b[33m○\x1b[0m";
+        const activeIndicator = isActive ? " \x1b[36m◀ active\x1b[0m" : "";
+        const worktreeStatus = hasWorktree ? " \x1b[32m[worktree]\x1b[0m" : "";
+        const countStr = `${passing}/${total}`;
+        console.log(`  ${statusIcon} \x1b[1m${branchName}\x1b[0m  ${countStr}${worktreeStatus}${activeIndicator}`);
+    }
+    // Show no-branch group
+    if (noBranchItems.length > 0) {
+        const passing = noBranchItems.filter((e) => e.passes).length;
+        const total = noBranchItems.length;
+        const allPassing = passing === total;
+        const statusIcon = allPassing ? "\x1b[32m✅\x1b[0m" : "\x1b[33m○\x1b[0m";
+        const countStr = `${passing}/${total}`;
+        console.log(`  ${statusIcon} \x1b[2m(no branch)\x1b[0m  ${countStr}`);
+    }
+    console.log();
+}
+/**
+ * Merge a completed branch worktree back into the base branch.
+ * Handles merge conflicts by aborting and showing conflicting files.
+ */
+async function branchMerge(args) {
+    const branchName = args[0];
+    if (!branchName) {
+        console.error("Usage: ralph branch merge <branch-name>");
+        console.error("\nExample: ralph branch merge feat/login");
+        process.exit(1);
+    }
+    // Verify the branch exists
+    if (!branchExists(branchName)) {
+        console.error(`\x1b[31mError: Branch "${branchName}" does not exist.\x1b[0m`);
+        process.exit(1);
+    }
+    const baseBranch = getBaseBranch();
+    const worktreesBase = getWorktreesBase();
+    const dirName = branchToWorktreeName(branchName);
+    const worktreePath = join(worktreesBase, dirName);
+    console.log(`Branch: ${branchName}`);
+    console.log(`Base branch: ${baseBranch}`);
+    if (existsSync(worktreePath)) {
+        console.log(`Worktree: ${worktreePath}`);
+    }
+    console.log();
+    // Ask for confirmation
+    const confirmed = await promptConfirm(`Merge "${branchName}" into "${baseBranch}"?`, true);
+    if (!confirmed) {
+        console.log("Merge cancelled.");
+        return;
+    }
+    // Perform the merge from /workspace (which is on the base branch)
+    try {
+        console.log(`\nMerging "${branchName}" into "${baseBranch}"...`);
+        execSync(`git -C /workspace merge "${branchName}" --no-edit`, { stdio: "pipe" });
+        console.log(`\x1b[32mSuccessfully merged "${branchName}" into "${baseBranch}".\x1b[0m`);
+    }
+    catch (err) {
+        // Check if this is a merge conflict
+        let conflictingFiles = [];
+        try {
+            const status = execSync("git -C /workspace status --porcelain", { encoding: "utf-8" });
+            conflictingFiles = status
+                .split("\n")
+                .filter((line) => line.startsWith("UU") || line.startsWith("AA") || line.startsWith("DD") || line.startsWith("AU") || line.startsWith("UA") || line.startsWith("DU") || line.startsWith("UD"))
+                .map((line) => line.substring(3).trim());
+        }
+        catch {
+            // Ignore status errors
+        }
+        if (conflictingFiles.length > 0) {
+            // Merge conflict detected - abort and report
+            console.error(`\n\x1b[31mMerge conflict detected!\x1b[0m`);
+            console.error(`\nConflicting files:`);
+            for (const file of conflictingFiles) {
+                console.error(`  \x1b[33m${file}\x1b[0m`);
+            }
+            // Abort the merge
+            try {
+                execSync("git -C /workspace merge --abort", { stdio: "pipe" });
+                console.error(`\n\x1b[36mMerge aborted.\x1b[0m`);
+            }
+            catch {
+                console.error("\n\x1b[33mWarning: Could not abort merge. You may need to run 'git merge --abort' manually.\x1b[0m");
+            }
+            console.error(`\nTo resolve:`);
+            console.error(`  1. Resolve conflicts manually and merge again`);
+            console.error(`  2. Or add a PRD item to resolve the conflicts:`);
+            console.error(`     ralph prd add  # describe the conflict resolution needed`);
+            process.exit(1);
+        }
+        else {
+            // Some other merge error
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`\x1b[31mMerge failed: ${message}\x1b[0m`);
+            // Try to abort in case merge is in progress
+            try {
+                execSync("git -C /workspace merge --abort", { stdio: "pipe" });
+            }
+            catch {
+                // Ignore if nothing to abort
+            }
+            process.exit(1);
+        }
+    }
+    // Clean up worktree if it exists
+    if (existsSync(worktreePath)) {
+        console.log(`\nCleaning up worktree at ${worktreePath}...`);
+        try {
+            execSync(`git -C /workspace worktree remove "${worktreePath}"`, { stdio: "pipe" });
+            console.log(`\x1b[32mWorktree removed.\x1b[0m`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`\x1b[33mWarning: Could not remove worktree: ${message}\x1b[0m`);
+            console.warn("You can remove it manually with: git worktree remove " + worktreePath);
+        }
+    }
+    // Clean up the branch itself (optional - merged branches can be deleted)
+    console.log(`\n\x1b[32mDone!\x1b[0m Branch "${branchName}" has been merged into "${baseBranch}".`);
+}
+/**
+ * Gets the PRD file path, preferring the primary if it exists.
+ */
+function getPrdPath() {
+    const prdFiles = getPrdFiles();
+    if (prdFiles.primary) {
+        return prdFiles.primary;
+    }
+    return join(getRalphDir(), "prd.json");
+}
+/**
+ * Parses a PRD file (YAML or JSON) and returns the entries.
+ */
+function parsePrdFile(path) {
+    const content = readFileSync(path, "utf-8");
+    const ext = extname(path).toLowerCase();
+    try {
+        let result;
+        if (ext === ".yaml" || ext === ".yml") {
+            result = YAML.parse(content);
+        }
+        else {
+            result = JSON.parse(content);
+        }
+        return result ?? [];
+    }
+    catch {
+        console.error(`Error parsing ${path}. Run 'ralph fix-prd' to attempt automatic repair.`);
+        process.exit(1);
+    }
+}
+/**
+ * Saves PRD entries to the PRD file (YAML or JSON based on extension).
+ */
+function savePrd(entries) {
+    const path = getPrdPath();
+    const ext = extname(path).toLowerCase();
+    if (ext === ".yaml" || ext === ".yml") {
+        writeFileSync(path, YAML.stringify(entries));
+    }
+    else {
+        writeFileSync(path, JSON.stringify(entries, null, 2) + "\n");
+    }
+}
+/**
+ * Create a PRD item to open a pull request for a branch.
+ */
+function branchPr(args) {
+    const branchName = args[0];
+    if (!branchName) {
+        console.error("Usage: ralph branch pr <branch-name>");
+        console.error("\nExample: ralph branch pr feat/login");
+        process.exit(1);
+    }
+    // Verify the branch exists
+    if (!branchExists(branchName)) {
+        console.error(`\x1b[31mError: Branch "${branchName}" does not exist.\x1b[0m`);
+        process.exit(1);
+    }
+    const baseBranch = getBaseBranch();
+    const entry = {
+        category: "feature",
+        description: `Create a pull request from \`${branchName}\` into \`${baseBranch}\``,
+        steps: [
+            `Ensure all changes on \`${branchName}\` are committed`,
+            `Push \`${branchName}\` to the remote if not already pushed`,
+            `Create a pull request from \`${branchName}\` into \`${baseBranch}\` using the appropriate tool (e.g. gh pr create)`,
+            "Include a descriptive title and summary of the changes in the PR",
+        ],
+        passes: false,
+        branch: branchName,
+    };
+    const prdPath = getPrdPath();
+    const prd = parsePrdFile(prdPath);
+    prd.push(entry);
+    savePrd(prd);
+    console.log(`Added PRD entry #${prd.length}: Create PR for ${branchName} → ${baseBranch}`);
+    console.log(`Branch field set to: ${branchName}`);
+    console.log("Run 'ralph run' or 'ralph once' to execute.");
+}
+/**
+ * Delete a branch: remove worktree, delete git branch, and untag PRD items.
+ * Asks for confirmation before proceeding.
+ */
+async function branchDelete(args) {
+    const branchName = args[0];
+    if (!branchName) {
+        console.error("Usage: ralph branch delete <branch-name>");
+        console.error("\nExample: ralph branch delete feat/old-branch");
+        process.exit(1);
+    }
+    // Verify the branch exists
+    if (!branchExists(branchName)) {
+        console.error(`\x1b[31mError: Branch "${branchName}" does not exist.\x1b[0m`);
+        process.exit(1);
+    }
+    const worktreesBase = getWorktreesBase();
+    const dirName = branchToWorktreeName(branchName);
+    const worktreePath = join(worktreesBase, dirName);
+    const hasWorktree = existsSync(worktreePath);
+    // Load PRD to check for tagged items
+    const result = loadPrdEntries();
+    const taggedCount = result
+        ? result.entries.filter((e) => e.branch === branchName).length
+        : 0;
+    console.log(`Branch: ${branchName}`);
+    if (hasWorktree) {
+        console.log(`Worktree: ${worktreePath}`);
+    }
+    if (taggedCount > 0) {
+        console.log(`PRD items tagged: ${taggedCount}`);
+    }
+    console.log();
+    // Ask for confirmation
+    const confirmed = await promptConfirm(`Delete branch "${branchName}"${hasWorktree ? " and its worktree" : ""}?`, false);
+    if (!confirmed) {
+        console.log("Delete cancelled.");
+        return;
+    }
+    // Step 1: Remove worktree if it exists
+    if (hasWorktree) {
+        console.log(`\nRemoving worktree at ${worktreePath}...`);
+        try {
+            execSync(`git -C /workspace worktree remove "${worktreePath}" --force`, { stdio: "pipe" });
+            console.log(`\x1b[32mWorktree removed.\x1b[0m`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`\x1b[33mWarning: Could not remove worktree: ${message}\x1b[0m`);
+            console.warn("You can remove it manually with: git worktree remove " + worktreePath);
+        }
+    }
+    // Step 2: Delete the git branch
+    console.log(`Deleting branch "${branchName}"...`);
+    try {
+        execSync(`git -C /workspace branch -D "${branchName}"`, { stdio: "pipe" });
+        console.log(`\x1b[32mBranch deleted.\x1b[0m`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`\x1b[31mError deleting branch: ${message}\x1b[0m`);
+    }
+    // Step 3: Remove branch tag from PRD items
+    if (result && taggedCount > 0) {
+        console.log(`Removing branch tag from ${taggedCount} PRD item(s)...`);
+        const updatedEntries = result.entries.map((entry) => {
+            if (entry.branch === branchName) {
+                const { branch: _, ...rest } = entry;
+                return rest;
+            }
+            return entry;
+        });
+        writePrdAuto(result.prdPath, updatedEntries);
+        console.log(`\x1b[32mPRD items updated.\x1b[0m`);
+    }
+    console.log(`\n\x1b[32mDone!\x1b[0m Branch "${branchName}" has been deleted.`);
+}
+/**
+ * Main branch command dispatcher.
+ */
+export async function branch(args) {
+    const subcommand = args[0];
+    switch (subcommand) {
+        case "list":
+            branchList();
+            break;
+        case "merge":
+            await branchMerge(args.slice(1));
+            break;
+        case "delete":
+            await branchDelete(args.slice(1));
+            break;
+        case "pr":
+            branchPr(args.slice(1));
+            break;
+        default:
+            console.error("Usage: ralph branch <subcommand>");
+            console.error("\nSubcommands:");
+            console.error("  list             List all branches and their status");
+            console.error("  merge <name>     Merge a branch worktree into the base branch");
+            console.error("  delete <name>    Delete a branch and its worktree");
+            console.error("  pr <name>        Create a PRD item to open a PR for a branch");
+            process.exit(1);
+    }
+}

package/dist/commands/chat.js

@@ -2,7 +2,7 @@
  * Chat command for managing Telegram, Slack, and other chat integrations.
  * Allows ralph to receive commands and send notifications via chat services.
  */
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, watch } from "fs";
 import { join, basename, extname } from "path";
 import { spawn } from "child_process";
 import YAML from "yaml";
@@ -11,7 +11,7 @@ import { createTelegramClient } from "../providers/telegram.js";
 import { createSlackClient } from "../providers/slack.js";
 import { createDiscordClient } from "../providers/discord.js";
 import { generateProjectId, formatStatusMessage, formatStatusForChat, } from "../utils/chat-client.js";
-import { getMessagesPath, sendMessage, waitForResponse } from "../utils/message-queue.js";
+import { getMessagesPath, sendMessage, waitForResponse, getPendingMessages, respondToMessage, cleanupOldMessages, } from "../utils/message-queue.js";
 const CHAT_STATE_FILE = "chat-state.json";
 /**
  * Load chat state from .ralph/chat-state.json
@@ -536,6 +536,67 @@ function createChatClient(config, debug) {
         allowedChatIds: config.chat.telegram.allowedChatIds,
     };
 }
+/**
+ * Process a message from the sandbox (container).
+ * Handles notification actions like slack_notify, telegram_notify, discord_notify.
+ */
+async function processSandboxMessage(message, client, allowedChatIds, messagesPath, debug) {
+    const { action, args } = message;
+    if (debug) {
+        console.log(`[chat] Processing sandbox message: ${action} ${args?.join(" ") || ""}`);
+    }
+    // Handle notification actions
+    if (action === "slack_notify" || action === "telegram_notify" || action === "discord_notify") {
+        const notifyMessage = args?.join(" ") || "Ralph notification";
+        // Check if this notification is for our provider
+        const expectedProvider = action === "slack_notify" ? "slack" : action === "telegram_notify" ? "telegram" : "discord";
+        if (client.provider !== expectedProvider) {
+            if (debug) {
+                console.log(`[chat] Ignoring ${action} - current provider is ${client.provider}`);
+            }
+            respondToMessage(messagesPath, message.id, {
+                success: false,
+                error: `Chat provider is ${client.provider}, not ${expectedProvider}`,
+            });
+            return;
+        }
+        // Send to all allowed chat IDs
+        if (!allowedChatIds || allowedChatIds.length === 0) {
+            respondToMessage(messagesPath, message.id, {
+                success: false,
+                error: "No chat IDs configured",
+            });
+            return;
+        }
+        try {
+            for (const chatId of allowedChatIds) {
+                await client.sendMessage(chatId, notifyMessage);
+            }
+            if (debug) {
+                console.log(`[chat] Sent notification to ${allowedChatIds.length} chat(s)`);
+            }
+            respondToMessage(messagesPath, message.id, {
+                success: true,
+                output: `Sent to ${client.provider}`,
+            });
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : "Unknown error";
+            if (debug) {
+                console.error(`[chat] Failed to send notification: ${errorMsg}`);
+            }
+            respondToMessage(messagesPath, message.id, {
+                success: false,
+                error: errorMsg,
+            });
+        }
+        return;
+    }
+    // Unknown action - don't respond (let daemon handle it if running)
+    if (debug) {
+        console.log(`[chat] Ignoring unknown action: ${action}`);
+    }
+}
 /**
  * Start the chat daemon (listens for messages and handles commands).
  */
@@ -610,9 +671,61 @@ async function startChat(config, debug) {
         console.error(`Failed to connect: ${err instanceof Error ? err.message : err}`);
         process.exit(1);
     }
+    // Watch for sandbox messages (notifications from container)
+    const messagesPath = getMessagesPath(false); // host path
+    const ralphDir = getRalphDir();
+    let sandboxWatcher = null;
+    let sandboxPollInterval = null;
+    let processingMessages = false;
+    const checkSandboxMessages = async () => {
+        if (processingMessages)
+            return;
+        processingMessages = true;
+        try {
+            const pending = getPendingMessages(messagesPath, "sandbox");
+            for (const msg of pending) {
+                // Only handle notification actions - let daemon handle others
+                if (msg.action === "slack_notify" ||
+                    msg.action === "telegram_notify" ||
+                    msg.action === "discord_notify") {
+                    await processSandboxMessage(msg, client, allowedChatIds, messagesPath, debug);
+                }
+            }
+            // Cleanup old messages periodically
+            cleanupOldMessages(messagesPath, 60000);
+        }
+        catch (err) {
+            if (debug) {
+                console.error(`[chat] Error processing sandbox messages: ${err}`);
+            }
+        }
+        processingMessages = false;
+    };
+    // Process any pending sandbox messages on startup
+    await checkSandboxMessages();
+    // Watch the .ralph directory for changes
+    if (existsSync(ralphDir)) {
+        sandboxWatcher = watch(ralphDir, { persistent: true }, (eventType, filename) => {
+            if (filename === "messages.json") {
+                checkSandboxMessages();
+            }
+        });
+    }
+    // Also poll periodically as backup
+    sandboxPollInterval = setInterval(checkSandboxMessages, 1000);
+    if (debug) {
+        console.log(`[chat] Watching for sandbox notifications at: ${messagesPath}`);
+    }
     // Handle shutdown
     const shutdown = async () => {
         console.log("\nShutting down chat daemon...");
+        // Stop sandbox message watching
+        if (sandboxWatcher) {
+            sandboxWatcher.close();
+        }
+        if (sandboxPollInterval) {
+            clearInterval(sandboxPollInterval);
+        }
         // Send disconnected message to all allowed chats
         if (allowedChatIds && allowedChatIds.length > 0) {
             for (const chatId of allowedChatIds) {

package/dist/commands/daemon.js

@@ -240,6 +240,16 @@ async function processMessage(message, actions, messagesPath, debug) {
     if (debug) {
         console.log(`[daemon] Processing: ${message.action} (${message.id})`);
     }
+    // Skip chat notification actions - these are handled by the chat client
+    // (which has the connected Socket Mode client)
+    const chatNotifyActions = ["slack_notify", "telegram_notify", "discord_notify"];
+    if (chatNotifyActions.includes(message.action)) {
+        if (debug) {
+            console.log(`[daemon] Skipping ${message.action} - handled by chat client`);
+        }
+        // Don't respond - let the chat client handle it
+        return;
+    }
     const action = actions[message.action];
     if (!action) {
         respondToMessage(messagesPath, message.id, {

package/dist/commands/docker.js

@@ -97,19 +97,24 @@ ${commands}
 ${commands}
 `;
     }
-    // Build git config section if configured
-    let gitConfigSection = "";
-    if (dockerConfig?.git && (dockerConfig.git.name || dockerConfig.git.email)) {
-        const gitCommands = [];
-        if (dockerConfig.git.name) {
-            gitCommands.push(`git config --global user.name "${dockerConfig.git.name}"`);
-        }
-        if (dockerConfig.git.email) {
-            gitCommands.push(`git config --global user.email "${dockerConfig.git.email}"`);
-        }
-        gitConfigSection = `
-# Configure git identity
+    // Build git config section — always set init.defaultBranch, plus identity if configured
+    const gitCommands = [`git config --global init.defaultBranch main`];
+    if (dockerConfig?.git?.name) {
+        gitCommands.push(`git config --global user.name "${dockerConfig.git.name}"`);
+    }
+    if (dockerConfig?.git?.email) {
+        gitCommands.push(`git config --global user.email "${dockerConfig.git.email}"`);
+    }
+    const gitConfigSection = `
+# Configure git defaults
 RUN ${gitCommands.join(" \\\n    && ")}
+`;
+    // Build worktrees directory section if configured
+    let worktreesDir = "";
+    if (dockerConfig?.worktreesPath) {
+        worktreesDir = `
+# Create worktrees directory for git worktree storage
+RUN mkdir -p /worktrees && chown node:node /worktrees
 `;
     }
     // Build asciinema installation section if enabled
@@ -215,7 +220,7 @@ RUN echo "node ALL=(ALL) NOPASSWD: /usr/local/bin/init-firewall.sh" >> /etc/sudo
 RUN mkdir -p /workspace && chown node:node /workspace
 RUN mkdir -p /home/node/.claude && chown node:node /home/node/.claude
 RUN mkdir -p /commandhistory && chown node:node /commandhistory
-${asciinemaDir}
+${worktreesDir}${asciinemaDir}
 # Copy firewall script
 COPY init-firewall.sh /usr/local/bin/init-firewall.sh
 RUN chmod +x /usr/local/bin/init-firewall.sh
@@ -351,6 +356,11 @@ function generateDockerCompose(imageName, dockerConfig) {
         "      - ${HOME}/.claude:/home/node/.claude",
         `      - ${imageName}-history:/commandhistory`,
     ];
+    // Mount worktrees path if configured
+    if (dockerConfig?.worktreesPath) {
+        baseVolumes.push("      # Mount host worktrees directory for git worktree storage");
+        baseVolumes.push(`      - ${dockerConfig.worktreesPath}:/worktrees`);
+    }
     if (dockerConfig?.volumes && dockerConfig.volumes.length > 0) {
         const customVolumeLines = dockerConfig.volumes.map((vol) => `      - ${vol}`);
         baseVolumes.push(...customVolumeLines);
@@ -1075,7 +1085,7 @@ Docker files generated in .ralph/docker/
 
 Next steps:
   1. Build the image: ralph docker build
-  2. Run container:    ralph docker run
+  2. Run container:   ralph docker run
 
 Or use docker compose directly:
   cd .ralph/docker && docker compose run --rm ralph
@@ -1186,7 +1196,7 @@ Docker files generated in .ralph/docker/
 
 Next steps:
   1. Build the image: ralph docker build
-  2. Run container:    ralph docker run
+  2. Run container:   ralph docker run
 
 Or use docker compose directly:
   cd .ralph/docker && docker compose run --rm ralph