@proletariat/cli 0.3.14 → 0.3.15

package/README.md

@@ -15,7 +15,7 @@
 
 > ⚠️ **Beta Software** — Under active development. Commands and APIs may change between versions, and bugs are actively being squashed.
 >
-> - [Book a call](https://cal.com/chrismcdermut) - Feedback, ideas, or chat multi-agent workflows and the future of work/labor (and economic labor theory..)
+> **Let's get you shipping** [Book a call][cal-link] - I'm happy to help you get prlt running or chat feedback, ideas, multi-agent workflows, and the future of work/labor (and economic labor theory..)
 
 ---
 
@@ -55,6 +55,9 @@ prlt work spawn                    # Interactive: select tickets, environment, a
 # Agent creates PR → You review → Merge → Done
 ```
 
+<details>
+<summary><b>Workflow Diagram</b> (click to expand)</summary>
+
 ```mermaid
 sequenceDiagram
     participant You
@@ -76,6 +79,8 @@ sequenceDiagram
     You->>GitHub: Review & approve
 ```
 
+</details>
+
 Spawn agents to implement, groom, or review—not just write code.
 
 ### Interactive Menus
@@ -83,19 +88,19 @@ Spawn agents to implement, groom, or review—not just write code.
 `prlt work` guides you through project and ticket selection:
 
 <p align="center">
-  <img src="docs/images/work/work-project-select.png" alt="Project Selection" width="600">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/work/work-project-select.png" alt="Project Selection" width="600">
 </p>
 
 Choose your operation—start a single agent, batch spawn, or watch a column:
 
 <p align="center">
-  <img src="docs/images/work/work-operations-menu.png" alt="Work Operations Menu" width="600">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/work/work-operations-menu.png" alt="Work Operations Menu" width="600">
 </p>
 
 Select tickets to spawn, grouped by priority:
 
 <p align="center">
-  <img src="docs/images/work/work-ticket-select.png" alt="Ticket Selection" width="800">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/work/work-ticket-select.png" alt="Ticket Selection" width="800">
 </p>
 
 ---
@@ -249,7 +254,7 @@ $ prlt ticket create
 View ticket details with `prlt ticket`:
 
 <p align="center">
-  <img src="docs/images/ticket/ticket-view.png" alt="Ticket View" width="600">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/ticket/ticket-view.png" alt="Ticket View" width="600">
 </p>
 
 #### 2. JSON Mode (AI Agents)
@@ -381,7 +386,7 @@ Each agent works in its own branch. No conflicts.
 Monitor running agents with `prlt execution`:
 
 <p align="center">
-  <img src="docs/images/execution/execution-list.png" alt="Execution List" width="800">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/execution/execution-list.png" alt="Execution List" width="800">
 </p>
 
 ```mermaid
@@ -414,7 +419,7 @@ flowchart LR
 Agent-created PRs ready for review:
 
 <p align="center">
-  <img src="docs/images/execution/github-prs.png" alt="GitHub Pull Requests" width="800">
+  <img src="https://raw.githubusercontent.com/chrismcdermut/proletariat/main/docs/images/execution/github-prs.png" alt="GitHub Pull Requests" width="800">
 </p>
 
 ### Command Reference
@@ -637,7 +642,7 @@ Claude Code handles its own authentication via `claude login`.
 
 - **Discord**: [discord.gg/tmZyjNNSvw](https://discord.gg/tmZyjNNSvw)
 - **GitHub Issues**: [Report bugs or request features](https://github.com/chrismcdermut/proletariat-cli/issues)
-- **Chat**: [Book a call](https://cal.com/chrismcdermut) — Feedback, ideas, or talk multi-agent workflows
+- **Setup Help**: [Book a call][cal-link] - I'll help you get things running
 
 ---
 
@@ -654,3 +659,5 @@ Apache 2.0
 [Star on GitHub](https://github.com/chrismcdermut/proletariat) | [Install from NPM](https://www.npmjs.com/package/@proletariat/cli) | [Report Issues](https://github.com/chrismcdermut/proletariat/issues)
 
 Made with ⚒️ by the proletariat.
+
+[cal-link]: https://cal.com/chrismcdermut

package/dist/commands/agent/staff/add.d.ts

@@ -9,6 +9,7 @@ export default class Add extends Command {
         'no-container': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         theme: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        clone: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static strict: boolean;
     run(): Promise<void>;

package/dist/commands/agent/staff/add.js

@@ -32,6 +32,10 @@ export default class Add extends Command {
             description: 'Output prompt configuration as JSON (for AI agents/scripts)',
             default: false,
         }),
+        clone: Flags.boolean({
+            description: 'Use independent git clone instead of worktree (more isolation, no real-time sync)',
+            default: false,
+        }),
     };
     static strict = false; // Allow multiple agent names
     async run() {
@@ -249,6 +253,7 @@ export default class Add extends Command {
             const addedAgents = await addAgentsToWorkspace(workspaceInfo, agentNames, {
                 skipDevcontainer: flags['no-container'],
                 themeId,
+                mountMode: flags.clone ? 'clone' : 'worktree',
             });
             if (addedAgents.length === 0) {
                 this.log(chalk.yellow('No new agents to add. All specified agents already exist.'));

package/dist/commands/work/revise.js

@@ -13,6 +13,7 @@ import { runExecution, isDockerRunning, isDevcontainerCliInstalled } from '../..
 import { ExecutionStorage } from '../../lib/execution/storage.js';
 import { loadExecutionConfig, getTerminalApp, getShell, hasTerminalPreference, hasShellPreference } from '../../lib/execution/config.js';
 import { hasDevcontainerConfig } from '../../lib/execution/devcontainer.js';
+import { detectRepoWorktrees, resolveWorktreePath } from '../../lib/execution/context.js';
 import { isGHInstalled, isGHAuthenticated, getPRFeedback, hasPendingFeedback, formatPRFeedbackForPrompt, } from '../../lib/pr/index.js';
 import { shouldOutputJson, outputErrorAsJson, createMetadata, } from '../../lib/prompt-json.js';
 export default class WorkRevise extends PMOCommand {
@@ -187,23 +188,14 @@ export default class WorkRevise extends PMOCommand {
                 db.close();
                 this.error(`Agent directory not found at ${agentDir}.`);
             }
-            let worktreePath = agentDir;
-            const agentContents = fs.readdirSync(agentDir);
-            const repoWorktrees = agentContents.filter(item => {
-                const itemPath = path.join(agentDir, item);
-                const gitPath = path.join(itemPath, '.git');
-                return fs.statSync(itemPath).isDirectory() && fs.existsSync(gitPath);
-            });
-            if (repoWorktrees.length === 1) {
-                worktreePath = path.join(agentDir, repoWorktrees[0]);
-            }
-            else if (repoWorktrees.length > 1) {
-                worktreePath = agentDir;
+            // Detect repository worktrees within agent directory
+            const repoWorktrees = detectRepoWorktrees(agentDir);
+            const worktreePath = resolveWorktreePath(agentDir, repoWorktrees);
+            if (repoWorktrees.length > 1) {
                 this.log(styles.muted(`   Repos: ${repoWorktrees.join(', ')}`));
             }
-            else {
+            else if (repoWorktrees.length === 0) {
                 this.log(styles.muted(`   No git worktree found, using current directory`));
-                worktreePath = process.cwd();
             }
             // Get branch from ticket metadata or current branch
             const branch = ticket.metadata?.pr_branch || this.getCurrentBranch(worktreePath);
@@ -221,6 +213,8 @@ export default class WorkRevise extends PMOCommand {
                 worktreePath,
                 branch,
                 hqPath,
+                pmoPath: this.pmoPath,
+                repoWorktrees,
                 // Revision-specific context
                 isRevision: true,
                 prFeedback: formattedFeedback,

package/dist/commands/work/spawn.d.ts

@@ -24,6 +24,7 @@ export default class WorkSpawn extends PMOCommand {
         action: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         session: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         focus: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        clone: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         project: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     execute(): Promise<void>;

package/dist/commands/work/spawn.js

@@ -109,6 +109,10 @@ export default class WorkSpawn extends PMOCommand {
             description: 'Bring terminal to foreground when opening new tabs (default: opens in background)',
             default: false,
         }),
+        clone: Flags.boolean({
+            description: 'Use independent git clone instead of worktree (more isolation, no real-time sync)',
+            default: false,
+        }),
     };
     async execute() {
         const { flags, argv } = await this.parse(WorkSpawn);
@@ -757,6 +761,9 @@ export default class WorkSpawn extends PMOCommand {
                     // IMPORTANT: Pass --project to avoid re-prompting for project selection
                     // Pass --ephemeral to signal work:start should create an ephemeral agent
                     const startArgs = [ticket.id, '--project', projectId, '--ephemeral'];
+                    // Pass clone flag if specified
+                    if (flags.clone)
+                        startArgs.push('--clone');
                     if (flags['per-ticket']) {
                         // Per-ticket mode: only pass display flag, let start prompt for the rest
                         // batchDisplayMode is for devcontainer, batchDisplay is for host

package/dist/commands/work/start.d.ts

@@ -26,6 +26,7 @@ export default class WorkStart extends PMOCommand {
         agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ephemeral: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         focus: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        clone: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         project: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     execute(): Promise<void>;

package/dist/commands/work/start.js

@@ -14,6 +14,7 @@ import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCl
 import { ExecutionStorage, ContainerStorage } from '../../lib/execution/storage.js';
 import { loadExecutionConfig, getTerminalApp, promptTerminalPreference, getShell, promptShellPreference, hasTerminalPreference, hasShellPreference, getOrPromptCoderName } from '../../lib/execution/config.js';
 import { hasDevcontainerConfig } from '../../lib/execution/devcontainer.js';
+import { detectRepoWorktrees, resolveWorktreePath } from '../../lib/execution/context.js';
 import { isGHInstalled, isGHAuthenticated } from '../../lib/pr/index.js';
 /**
  * Try to execute a git command, return true if successful
@@ -169,6 +170,10 @@ export default class WorkStart extends PMOCommand {
             description: 'Bring terminal to foreground when opening new tabs (default: opens in background)',
             default: false,
         }),
+        clone: Flags.boolean({
+            description: 'Use independent git clone instead of worktree (more isolation, no real-time sync)',
+            default: false,
+        }),
     };
     async execute() {
         const { args, flags } = await this.parse(WorkStart);
@@ -314,6 +319,7 @@ export default class WorkStart extends PMOCommand {
                 const ephemeralResult = await createEphemeralAgent(workspaceInfo, {
                     skipDevcontainer: flags['run-on-host'],
                     log: (msg) => this.log(msg),
+                    mountMode: flags.clone ? 'clone' : 'worktree',
                 });
                 agentName = ephemeralResult.name;
                 agentWorktreePath = ephemeralResult.worktreePath;
@@ -381,6 +387,7 @@ export default class WorkStart extends PMOCommand {
                         const ephemeralResult = await createEphemeralAgent(workspaceInfo, {
                             skipDevcontainer: flags['run-on-host'],
                             log: (msg) => this.log(msg),
+                            mountMode: flags.clone ? 'clone' : 'worktree',
                         });
                         agentName = ephemeralResult.name;
                         agentWorktreePath = ephemeralResult.worktreePath;
@@ -397,6 +404,7 @@ export default class WorkStart extends PMOCommand {
                     const ephemeralResult = await createEphemeralAgent(workspaceInfo, {
                         skipDevcontainer: flags['run-on-host'],
                         log: (msg) => this.log(msg),
+                        mountMode: flags.clone ? 'clone' : 'worktree',
                     });
                     agentName = ephemeralResult.name;
                     agentWorktreePath = ephemeralResult.worktreePath;
@@ -495,31 +503,14 @@ export default class WorkStart extends PMOCommand {
                     }
                 }
             }
-            // Find worktree path for agent
-            // Agent directory may contain multiple repo worktrees - use the agent dir itself
-            // so Claude can work across all repos (frontend, backend, etc.)
-            let worktreePath = agentDir;
-            // Check if agent has repository worktrees (subdirectories with .git)
-            const agentContents = fs.readdirSync(agentDir);
-            const repoWorktrees = agentContents.filter(item => {
-                const itemPath = path.join(agentDir, item);
-                const gitPath = path.join(itemPath, '.git');
-                return fs.statSync(itemPath).isDirectory() && fs.existsSync(gitPath);
-            });
-            if (repoWorktrees.length === 1) {
-                // Single repo - open directly in the repo worktree
-                worktreePath = path.join(agentDir, repoWorktrees[0]);
-            }
-            else if (repoWorktrees.length > 1) {
-                // Multiple repos - open in agent directory, Claude can navigate between them
-                worktreePath = agentDir;
+            // Detect repository worktrees within agent directory
+            const repoWorktrees = detectRepoWorktrees(agentDir);
+            const worktreePath = resolveWorktreePath(agentDir, repoWorktrees);
+            if (repoWorktrees.length > 1) {
                 this.log(styles.muted(`   Repos: ${repoWorktrees.join(', ')}`));
             }
-            else {
-                // No git worktrees found - agent is a placeholder
-                // Fall back to the current working directory
+            else if (repoWorktrees.length === 0) {
                 this.log(styles.muted(`   No git worktree found for agent, using current directory`));
-                worktreePath = process.cwd();
             }
             // Get coder name for branch naming (prompts on first use)
             const coderName = await getOrPromptCoderName(db);
@@ -647,6 +638,7 @@ export default class WorkStart extends PMOCommand {
                 branch,
                 hqPath,
                 pmoPath: this.pmoPath, // PMO path for container mounting
+                repoWorktrees,
                 // Action context
                 actionId: selectedAction?.id,
                 actionName: selectedAction?.name || (customPrompt ? 'Custom' : undefined),
@@ -1500,6 +1492,7 @@ export default class WorkStart extends PMOCommand {
                     ...(flags['run-on-host'] ? ['--run-on-host'] : []),
                     ...(flags.force ? ['--force'] : []),
                     '--permission-mode', batchPermissionMode,
+                    ...(flags.clone ? ['--clone'] : []),
                 ]);
                 successCount++;
             }
@@ -1527,17 +1520,9 @@ export default class WorkStart extends PMOCommand {
         if (!fs.existsSync(agentDir)) {
             throw new Error(`Agent directory not found: ${agentDir}`);
         }
-        // Find worktree path
-        let worktreePath = agentDir;
-        const agentContents = fs.readdirSync(agentDir);
-        const repoWorktrees = agentContents.filter(item => {
-            const itemPath = path.join(agentDir, item);
-            const gitPath = path.join(itemPath, '.git');
-            return fs.statSync(itemPath).isDirectory() && fs.existsSync(gitPath);
-        });
-        if (repoWorktrees.length === 1) {
-            worktreePath = path.join(agentDir, repoWorktrees[0]);
-        }
+        // Detect repository worktrees within agent directory
+        const repoWorktrees = detectRepoWorktrees(agentDir);
+        const worktreePath = resolveWorktreePath(agentDir, repoWorktrees);
         // Get coder name for branch naming (prompts on first use)
         const coderName = await getOrPromptCoderName(db);
         // Use ticket's existing branch or generate a new one
@@ -1583,6 +1568,7 @@ export default class WorkStart extends PMOCommand {
             branch,
             hqPath: workspaceInfo.path,
             pmoPath: this.pmoPath,
+            repoWorktrees,
             createPR: flags['create-pr'] || false,
             // Use 'implement' action for batch mode
             actionId: defaultAction?.id,

package/dist/lib/agents/commands.d.ts

@@ -1,4 +1,4 @@
-import { Agent, Repository } from '../database/index.js';
+import { Agent, Repository, MountMode as DBMountMode } from '../database/index.js';
 export interface AgentStatus {
     name: string;
     exists: boolean;
@@ -68,9 +68,11 @@ export declare function validateAgentNames(agentNames: string[]): {
     valid: string[];
     invalid: string[];
 };
+export type MountMode = DBMountMode;
 export interface AddAgentOptions {
     skipDevcontainer?: boolean;
     themeId?: string;
+    mountMode?: DBMountMode;
 }
 /**
  * Create agent worktrees and update database
@@ -90,6 +92,8 @@ export interface EphemeralAgentOptions {
      * Optional logger for conflict messages (e.g., when a tmux session or directory already exists)
      */
     log?: (message: string) => void;
+    /** Mount mode: 'worktree' = git worktree (default), 'clone' = independent clone */
+    mountMode?: DBMountMode;
 }
 export interface EphemeralAgentResult {
     name: string;

package/dist/lib/agents/commands.js

@@ -283,15 +283,15 @@ export async function addAgentsToWorkspace(workspaceInfo, agentNames, options) {
     if (newAgents.length === 0) {
         return [];
     }
-    // Create worktrees
+    // Create worktrees/clones
     if (workspaceInfo.type === 'hq') {
         await createAgentWorktrees(workspaceInfo.agentsPath, newAgents, workspaceInfo.path, options);
     }
     else {
         await createAgentWorktrees(workspaceInfo.agentsPath, newAgents, undefined, options);
     }
-    // Add to database (with optional theme ID)
-    addAgentsToDatabase(workspaceInfo.path, newAgents, options?.themeId);
+    // Add to database (with optional theme ID and mount mode)
+    addAgentsToDatabase(workspaceInfo.path, newAgents, options?.themeId, options?.mountMode || 'clone');
     return newAgents;
 }
 /**
@@ -441,27 +441,53 @@ export async function createEphemeralAgent(workspaceInfo, options) {
     if (!fs.existsSync(agentDir)) {
         fs.mkdirSync(agentDir, { recursive: true });
     }
-    // Create worktrees for each repository
+    // Create worktrees/clones for each repository
     const reposPath = path.join(workspaceInfo.path, 'repos');
+    const mountMode = options?.mountMode || 'worktree';
     if (fs.existsSync(reposPath) && workspaceInfo.repositories.length > 0) {
         for (const repo of workspaceInfo.repositories) {
             const sourceRepoPath = path.join(reposPath, repo.name);
-            const worktreePath = path.join(agentDir, repo.name);
-            if (fs.existsSync(sourceRepoPath) && !fs.existsSync(worktreePath)) {
-                try {
-                    // Create git worktree for the repository
-                    // Don't create a branch yet - that happens in work:start
-                    // Use --detach to create without a branch reference
-                    execSync(`git worktree add --detach "${worktreePath}"`, {
-                        cwd: sourceRepoPath,
-                        stdio: 'pipe'
-                    });
+            const targetPath = path.join(agentDir, repo.name);
+            if (fs.existsSync(sourceRepoPath) && !fs.existsSync(targetPath)) {
+                if (mountMode === 'clone') {
+                    // CLONE MODE: Create independent git clone
+                    try {
+                        // Get remote URL from source repo
+                        const remoteUrl = execSync('git remote get-url origin', {
+                            cwd: sourceRepoPath,
+                            encoding: 'utf-8',
+                            stdio: ['pipe', 'pipe', 'pipe']
+                        }).trim();
+                        if (remoteUrl) {
+                            execSync(`git clone "${remoteUrl}" "${targetPath}"`, {
+                                stdio: 'pipe'
+                            });
+                        }
+                    }
+                    catch {
+                        // If clone fails, try to just create the directory
+                        if (!fs.existsSync(targetPath)) {
+                            fs.mkdirSync(targetPath, { recursive: true });
+                        }
+                    }
                 }
-                catch {
-                    // If worktree creation fails, try to just create the directory
-                    // The agent can still work without a worktree (e.g., for non-git projects)
-                    if (!fs.existsSync(worktreePath)) {
-                        fs.mkdirSync(worktreePath, { recursive: true });
+                else {
+                    // WORKTREE MODE: Create git worktree
+                    try {
+                        // Create git worktree for the repository
+                        // Don't create a branch yet - that happens in work:start
+                        // Use --detach to create without a branch reference
+                        execSync(`git worktree add --detach "${targetPath}"`, {
+                            cwd: sourceRepoPath,
+                            stdio: 'pipe'
+                        });
+                    }
+                    catch {
+                        // If worktree creation fails, try to just create the directory
+                        // The agent can still work without a worktree (e.g., for non-git projects)
+                        if (!fs.existsSync(targetPath)) {
+                            fs.mkdirSync(targetPath, { recursive: true });
+                        }
                     }
                 }
             }
@@ -474,12 +500,13 @@ export async function createEphemeralAgent(workspaceInfo, options) {
             createDevcontainerConfig({
                 agentName,
                 agentDir,
-                repoWorktrees: workspaceInfo.repositories.map(r => r.name)
+                repoWorktrees: mountMode === 'worktree' ? workspaceInfo.repositories.map(r => r.name) : undefined,
+                mountMode,
             });
         }
     }
     // Add to database
-    const agent = addEphemeralAgentToDatabase(workspaceInfo.path, agentName, baseName, options?.themeId);
+    const agent = addEphemeralAgentToDatabase(workspaceInfo.path, agentName, baseName, options?.themeId, mountMode);
     return {
         name: agentName,
         baseName,

package/dist/lib/agents/index.d.ts

@@ -20,11 +20,15 @@ export { findHQRoot } from '../workspace.js';
  * Prompt user to enter agent names
  */
 export declare function promptAgentNames(existingAgents?: string[]): Promise<string[]>;
+export type MountMode = 'worktree' | 'clone';
 export interface CreateAgentOptions {
     skipDevcontainer?: boolean;
+    mountMode?: MountMode;
 }
 /**
- * Create agent worktrees (shared between HQ and workspace-only modes)
+ * Create agent repos (worktree or clone mode)
+ * - worktree mode: Uses git worktree add (shared .git, requires parent repo mounts in container)
+ * - clone mode: Uses git clone (independent repo, no path translation needed)
  */
 export declare function createAgentWorktrees(workspacePath: string, agents: string[], hqPath?: string, options?: CreateAgentOptions): Promise<void>;
 /**