@locusai/cli 0.8.0 → 0.8.1

package/README.md

@@ -0,0 +1,155 @@
+# @locusai/cli
+
+Command-line interface for [Locus](https://locusai.dev) - an AI-native project management platform for engineering teams.
+
+## Installation
+
+```bash
+npm install -g @locusai/cli
+```
+
+Or with other package managers:
+
+```bash
+# pnpm
+pnpm add -g @locusai/cli
+
+# yarn
+yarn global add @locusai/cli
+
+# bun
+bun add -g @locusai/cli
+```
+
+## Quick Start
+
+```bash
+# Initialize Locus in your project
+locus init
+
+# Index your codebase for AI context
+locus index
+
+# Run an agent to work on tasks
+locus run --api-key YOUR_API_KEY
+
+# Execute a prompt with repository context
+locus exec "Explain the authentication flow"
+```
+
+## Commands
+
+### `locus init`
+
+Initialize Locus in the current directory. Creates the necessary configuration files and directory structure:
+
+- `.locus/` - Configuration directory
+- `.locus/config.json` - Project settings
+- `CLAUDE.md` - AI instructions and context
+- `.agent/skills/` - Domain-specific agent skills
+
+Running `init` on an already initialized project will update the configuration to the latest version.
+
+### `locus index`
+
+Index the codebase for AI context. This analyzes your project structure and creates a searchable index that helps AI agents understand your codebase.
+
+```bash
+locus index [options]
+
+Options:
+  --dir <path>      Project directory (default: current directory)
+  --model <name>    AI model to use
+  --provider <name> AI provider: claude or codex (default: claude)
+```
+
+### `locus run`
+
+Start an agent to work on tasks from your Locus workspace.
+
+```bash
+locus run [options]
+
+Options:
+  --api-key <key>     Your Locus API key (required)
+  --workspace <id>    Workspace ID to connect to
+  --sprint <id>       Sprint ID to work on
+  --model <name>      AI model to use
+  --provider <name>   AI provider: claude or codex (default: claude)
+  --api-url <url>     Custom API URL
+  --dir <path>        Project directory (default: current directory)
+  --skip-planning     Skip the planning phase
+```
+
+### `locus exec`
+
+Run a prompt with repository context. Supports both single execution and interactive REPL mode.
+
+```bash
+locus exec "your prompt" [options]
+locus exec --interactive [options]
+
+Options:
+  --interactive, -i   Start interactive REPL mode
+  --session, -s <id>  Resume a previous session
+  --model <name>      AI model to use
+  --provider <name>   AI provider: claude or codex (default: claude)
+  --dir <path>        Project directory (default: current directory)
+  --no-stream         Disable streaming output
+  --no-status         Disable status display
+```
+
+#### Session Management
+
+Manage your exec sessions with these subcommands:
+
+```bash
+# List recent sessions
+locus exec sessions list
+
+# Show messages from a session
+locus exec sessions show <session-id>
+
+# Delete a session
+locus exec sessions delete <session-id>
+
+# Clear all sessions
+locus exec sessions clear
+```
+
+## Configuration
+
+Locus stores its configuration in the `.locus/` directory within your project:
+
+- `config.json` - Project settings including workspace ID and version
+- `codebase-index.json` - Indexed codebase structure
+
+The `CLAUDE.md` file in your project root provides AI instructions and context that agents use when working on your codebase.
+
+## AI Providers
+
+Locus supports multiple AI providers:
+
+- **Claude** (default) - Anthropic's Claude models
+- **Codex** - OpenAI Codex models
+
+Specify the provider with the `--provider` flag:
+
+```bash
+locus exec "your prompt" --provider codex
+locus run --api-key YOUR_KEY --provider claude
+```
+
+## Requirements
+
+- Node.js 18 or later
+- A Locus API key (for `run` command)
+
+## Links
+
+- [Documentation](https://locusai.dev/docs)
+- [Website](https://locusai.dev)
+
+## License
+
+MIT

package/bin/agent/worker.js

@@ -17011,6 +17011,10 @@ var require_ignore = __commonJS((exports, module) => {
   define(module.exports, Symbol.for("setupWindows"), setupWindows);
 });
 
+// ../sdk/src/agent/worker.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join6 } from "node:path";
+
 // ../sdk/src/core/config.ts
 import { join } from "node:path";
 var PROVIDER = {
@@ -17029,7 +17033,9 @@ var LOCUS_CONFIG = {
   artifactsDir: "artifacts",
   documentsDir: "documents",
   agentSkillsDir: ".agent/skills",
-  sessionsDir: "sessions"
+  sessionsDir: "sessions",
+  reviewsDir: "reviews",
+  plansDir: "plans"
 };
 function getLocusPath(projectPath, fileName) {
   if (fileName === "contextFile") {
@@ -17120,7 +17126,7 @@ class ClaudeRunner {
   setEventEmitter(emitter) {
     this.eventEmitter = emitter;
   }
-  async run(prompt, _isPlanning = false) {
+  async run(prompt) {
     const maxRetries = 3;
     let lastError = null;
     for (let attempt = 1;attempt <= maxRetries; attempt++) {
@@ -36686,7 +36692,7 @@ File tree:
 ${tree}
 
 Return ONLY valid JSON, no markdown formatting.`;
-        const response = await this.deps.aiRunner.run(prompt, true);
+        const response = await this.deps.aiRunner.run(prompt);
         const jsonMatch = response.match(/\{[\s\S]*\}/);
         if (jsonMatch) {
           return JSON.parse(jsonMatch[0]);
@@ -36749,6 +36755,66 @@ class DocumentFetcher {
   }
 }
 
+// ../sdk/src/agent/review-service.ts
+import { execSync } from "node:child_process";
+
+class ReviewService {
+  deps;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  async reviewStagedChanges(sprint2) {
+    const { projectPath, log } = this.deps;
+    try {
+      execSync("git add -A", { cwd: projectPath, stdio: "pipe" });
+      log("Staged all changes for review.", "info");
+    } catch (err) {
+      log(`Failed to stage changes: ${err instanceof Error ? err.message : String(err)}`, "error");
+      return null;
+    }
+    let diff;
+    try {
+      diff = execSync("git diff --cached --stat && echo '---' && git diff --cached", {
+        cwd: projectPath,
+        maxBuffer: 10 * 1024 * 1024
+      }).toString();
+    } catch (err) {
+      log(`Failed to get staged diff: ${err instanceof Error ? err.message : String(err)}`, "error");
+      return null;
+    }
+    if (!diff.trim()) {
+      return null;
+    }
+    const sprintInfo = sprint2 ? `Sprint: ${sprint2.name} (${sprint2.id})` : "No active sprint";
+    const reviewPrompt = `# Code Review Request
+
+## Context
+${sprintInfo}
+Date: ${new Date().toISOString()}
+
+## Staged Changes (git diff)
+\`\`\`diff
+${diff}
+\`\`\`
+
+## Instructions
+You are reviewing the staged changes at the end of a sprint. Produce a thorough markdown review report with the following sections:
+
+1. **Summary** — Brief overview of what changed and why.
+2. **Files Changed** — List each file with a short description of changes.
+3. **Code Quality** — Note any code quality concerns (naming, structure, complexity).
+4. **Potential Issues** — Identify bugs, security issues, edge cases, or regressions.
+5. **Recommendations** — Actionable suggestions for improvement.
+6. **Overall Assessment** — A short verdict (e.g., "Looks good", "Needs attention", "Critical issues found").
+
+Keep the review concise but thorough. Focus on substance over style.
+Do NOT output <promise>COMPLETE</promise> — just output the review report as markdown.`;
+    log("Running AI review on staged changes...", "info");
+    const report = await this.deps.aiRunner.run(reviewPrompt);
+    return report;
+  }
+}
+
 // ../sdk/src/core/prompt-builder.ts
 import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync4, statSync } from "node:fs";
 import { homedir } from "node:os";
@@ -37113,29 +37179,8 @@ class TaskExecutor {
       taskContext: context
     });
     try {
-      let plan = null;
-      this.deps.log("Phase 1: Planning (CLI)...", "info");
-      const planningPrompt = `${basePrompt}
-
-## Phase 1: Planning
-Analyze and create a detailed plan for THIS SPECIFIC TASK. Do NOT execute changes yet.`;
-      plan = await this.deps.aiRunner.run(planningPrompt, true);
       this.deps.log("Starting Execution...", "info");
-      let executionPrompt = basePrompt;
-      if (plan != null) {
-        executionPrompt += `
-
-## Phase 2: Execution
-Based on the plan, execute the task:
-
-${plan}`;
-      } else {
-        executionPrompt += `
-
-## Execution
-Execute the task directly.`;
-      }
-      executionPrompt += `
+      const executionPrompt = `${basePrompt}
 
 When finished, output: <promise>COMPLETE</promise>`;
       const output = await this.deps.aiRunner.run(executionPrompt);
@@ -37169,11 +37214,9 @@ class AgentWorker {
   indexerService;
   documentFetcher;
   taskExecutor;
-  consecutiveEmpty = 0;
-  maxEmpty = 60;
+  reviewService;
   maxTasks = 50;
   tasksCompleted = 0;
-  pollInterval = 1e4;
   constructor(config2) {
     this.config = config2;
     const projectPath = config2.projectPath || process.cwd();
@@ -37210,6 +37253,11 @@ class AgentWorker {
       projectPath,
       log
     });
+    this.reviewService = new ReviewService({
+      aiRunner: this.aiRunner,
+      projectPath,
+      log
+    });
     const providerLabel = provider === "codex" ? "Codex" : "Claude";
     this.log(`Using ${providerLabel} CLI for all phases`, "info");
   }
@@ -37255,33 +37303,42 @@ class AgentWorker {
     await this.indexerService.reindex();
     return result;
   }
+  async runStagedChangesReview(sprint2) {
+    try {
+      const report = await this.reviewService.reviewStagedChanges(sprint2);
+      if (report) {
+        const reviewsDir = join6(this.config.projectPath, LOCUS_CONFIG.dir, "reviews");
+        if (!existsSync5(reviewsDir)) {
+          mkdirSync3(reviewsDir, { recursive: true });
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const sprintSlug = sprint2?.name ? sprint2.name.toLowerCase().replace(/\s+/g, "-").slice(0, 40) : "no-sprint";
+        const fileName = `review-${sprintSlug}-${timestamp}.md`;
+        const filePath = join6(reviewsDir, fileName);
+        writeFileSync3(filePath, report);
+        this.log(`Review report saved to .locus/reviews/${fileName}`, "success");
+      } else {
+        this.log("No staged changes to review.", "info");
+      }
+    } catch (err) {
+      this.log(`Review failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+    }
+  }
   async run() {
     this.log(`Agent started in ${this.config.projectPath || process.cwd()}`, "success");
     const sprint2 = await this.getActiveSprint();
     if (sprint2) {
-      this.log(`Active sprint found: ${sprint2.name}. Ensuring plan is up to date...`, "info");
-      try {
-        await this.client.sprints.triggerAIPlanning(sprint2.id, this.config.workspaceId);
-        this.log(`Sprint plan sync checked on server.`, "success");
-      } catch (err) {
-        this.log(`Sprint planning sync failed (non-critical): ${err instanceof Error ? err.message : String(err)}`, "warn");
-      }
+      this.log(`Active sprint found: ${sprint2.name}`, "info");
     } else {
-      this.log("No active sprint found for planning.", "warn");
+      this.log("No active sprint found.", "warn");
     }
-    while (this.tasksCompleted < this.maxTasks && this.consecutiveEmpty < this.maxEmpty) {
+    while (this.tasksCompleted < this.maxTasks) {
       const task2 = await this.getNextTask();
       if (!task2) {
-        if (this.consecutiveEmpty === 0) {
-          this.log("Queue empty, waiting for tasks...", "info");
-        }
-        this.consecutiveEmpty++;
-        if (this.consecutiveEmpty >= this.maxEmpty)
-          break;
-        await new Promise((r) => setTimeout(r, this.pollInterval));
-        continue;
+        this.log("No tasks remaining. Running review on staged changes...", "info");
+        await this.runStagedChangesReview(sprint2);
+        break;
       }
-      this.consecutiveEmpty = 0;
       this.log(`Claimed: ${task2.title}`, "success");
       const result = await this.executeTask(task2);
       try {

package/bin/locus.js

@@ -6341,7 +6341,7 @@ File tree:
 ${tree}
 
 Return ONLY valid JSON, no markdown formatting.`;
-        const response = await this.deps.aiRunner.run(prompt, true);
+        const response = await this.deps.aiRunner.run(prompt);
         const jsonMatch = response.match(/\{[\s\S]*\}/);
         if (jsonMatch) {
           return JSON.parse(jsonMatch[0]);
@@ -6389,14 +6389,22 @@ var init_config = __esm(() => {
     artifactsDir: "artifacts",
     documentsDir: "documents",
     agentSkillsDir: ".agent/skills",
-    sessionsDir: "sessions"
+    sessionsDir: "sessions",
+    reviewsDir: "reviews",
+    plansDir: "plans"
   };
   LOCUS_GITIGNORE_PATTERNS = [
     "# Locus AI - Session data (user-specific, can grow large)",
     ".locus/sessions/",
     "",
     "# Locus AI - Artifacts (local-only, user-specific)",
-    ".locus/artifacts/"
+    ".locus/artifacts/",
+    "",
+    "# Locus AI - Review reports (generated per sprint)",
+    ".locus/reviews/",
+    "",
+    "# Locus AI - Plans (generated per task)",
+    ".locus/plans/"
   ];
 });
 
@@ -6448,6 +6456,67 @@ var init_document_fetcher = __esm(() => {
   init_config();
 });
 
+// ../sdk/src/agent/review-service.ts
+import { execSync } from "node:child_process";
+
+class ReviewService {
+  deps;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  async reviewStagedChanges(sprint) {
+    const { projectPath, log } = this.deps;
+    try {
+      execSync("git add -A", { cwd: projectPath, stdio: "pipe" });
+      log("Staged all changes for review.", "info");
+    } catch (err) {
+      log(`Failed to stage changes: ${err instanceof Error ? err.message : String(err)}`, "error");
+      return null;
+    }
+    let diff;
+    try {
+      diff = execSync("git diff --cached --stat && echo '---' && git diff --cached", {
+        cwd: projectPath,
+        maxBuffer: 10 * 1024 * 1024
+      }).toString();
+    } catch (err) {
+      log(`Failed to get staged diff: ${err instanceof Error ? err.message : String(err)}`, "error");
+      return null;
+    }
+    if (!diff.trim()) {
+      return null;
+    }
+    const sprintInfo = sprint ? `Sprint: ${sprint.name} (${sprint.id})` : "No active sprint";
+    const reviewPrompt = `# Code Review Request
+
+## Context
+${sprintInfo}
+Date: ${new Date().toISOString()}
+
+## Staged Changes (git diff)
+\`\`\`diff
+${diff}
+\`\`\`
+
+## Instructions
+You are reviewing the staged changes at the end of a sprint. Produce a thorough markdown review report with the following sections:
+
+1. **Summary** — Brief overview of what changed and why.
+2. **Files Changed** — List each file with a short description of changes.
+3. **Code Quality** — Note any code quality concerns (naming, structure, complexity).
+4. **Potential Issues** — Identify bugs, security issues, edge cases, or regressions.
+5. **Recommendations** — Actionable suggestions for improvement.
+6. **Overall Assessment** — A short verdict (e.g., "Looks good", "Needs attention", "Critical issues found").
+
+Keep the review concise but thorough. Focus on substance over style.
+Do NOT output <promise>COMPLETE</promise> — just output the review report as markdown.`;
+    log("Running AI review on staged changes...", "info");
+    const report = await this.deps.aiRunner.run(reviewPrompt);
+    return report;
+  }
+}
+var init_review_service = () => {};
+
 // ../../node_modules/zod/v4/core/core.js
 function $constructor(name, initializer, params) {
   function init(inst, def) {
@@ -21645,29 +21714,8 @@ class TaskExecutor {
       taskContext: context
     });
     try {
-      let plan = null;
-      this.deps.log("Phase 1: Planning (CLI)...", "info");
-      const planningPrompt = `${basePrompt}
-
-## Phase 1: Planning
-Analyze and create a detailed plan for THIS SPECIFIC TASK. Do NOT execute changes yet.`;
-      plan = await this.deps.aiRunner.run(planningPrompt, true);
       this.deps.log("Starting Execution...", "info");
-      let executionPrompt = basePrompt;
-      if (plan != null) {
-        executionPrompt += `
-
-## Phase 2: Execution
-Based on the plan, execute the task:
-
-${plan}`;
-      } else {
-        executionPrompt += `
-
-## Execution
-Execute the task directly.`;
-      }
-      executionPrompt += `
+      const executionPrompt = `${basePrompt}
 
 When finished, output: <promise>COMPLETE</promise>`;
       const output = await this.deps.aiRunner.run(executionPrompt);
@@ -21768,7 +21816,7 @@ class ClaudeRunner {
   setEventEmitter(emitter) {
     this.eventEmitter = emitter;
   }
-  async run(prompt, _isPlanning = false) {
+  async run(prompt) {
     const maxRetries = 3;
     let lastError = null;
     for (let attempt = 1;attempt <= maxRetries; attempt++) {
@@ -37854,6 +37902,8 @@ var init_src2 = __esm(() => {
 });
 
 // ../sdk/src/agent/worker.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join6 } from "node:path";
 function resolveProvider(value) {
   if (!value || value.startsWith("--")) {
     console.warn("Warning: --provider requires a value. Falling back to 'claude'.");
@@ -37872,11 +37922,9 @@ class AgentWorker {
   indexerService;
   documentFetcher;
   taskExecutor;
-  consecutiveEmpty = 0;
-  maxEmpty = 60;
+  reviewService;
   maxTasks = 50;
   tasksCompleted = 0;
-  pollInterval = 1e4;
   constructor(config2) {
     this.config = config2;
     const projectPath = config2.projectPath || process.cwd();
@@ -37913,6 +37961,11 @@ class AgentWorker {
       projectPath,
       log
     });
+    this.reviewService = new ReviewService({
+      aiRunner: this.aiRunner,
+      projectPath,
+      log
+    });
     const providerLabel = provider === "codex" ? "Codex" : "Claude";
     this.log(`Using ${providerLabel} CLI for all phases`, "info");
   }
@@ -37958,33 +38011,42 @@ class AgentWorker {
     await this.indexerService.reindex();
     return result;
   }
+  async runStagedChangesReview(sprint2) {
+    try {
+      const report = await this.reviewService.reviewStagedChanges(sprint2);
+      if (report) {
+        const reviewsDir = join6(this.config.projectPath, LOCUS_CONFIG.dir, "reviews");
+        if (!existsSync5(reviewsDir)) {
+          mkdirSync3(reviewsDir, { recursive: true });
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const sprintSlug = sprint2?.name ? sprint2.name.toLowerCase().replace(/\s+/g, "-").slice(0, 40) : "no-sprint";
+        const fileName = `review-${sprintSlug}-${timestamp}.md`;
+        const filePath = join6(reviewsDir, fileName);
+        writeFileSync3(filePath, report);
+        this.log(`Review report saved to .locus/reviews/${fileName}`, "success");
+      } else {
+        this.log("No staged changes to review.", "info");
+      }
+    } catch (err) {
+      this.log(`Review failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+    }
+  }
   async run() {
     this.log(`Agent started in ${this.config.projectPath || process.cwd()}`, "success");
     const sprint2 = await this.getActiveSprint();
     if (sprint2) {
-      this.log(`Active sprint found: ${sprint2.name}. Ensuring plan is up to date...`, "info");
-      try {
-        await this.client.sprints.triggerAIPlanning(sprint2.id, this.config.workspaceId);
-        this.log(`Sprint plan sync checked on server.`, "success");
-      } catch (err) {
-        this.log(`Sprint planning sync failed (non-critical): ${err instanceof Error ? err.message : String(err)}`, "warn");
-      }
+      this.log(`Active sprint found: ${sprint2.name}`, "info");
     } else {
-      this.log("No active sprint found for planning.", "warn");
+      this.log("No active sprint found.", "warn");
     }
-    while (this.tasksCompleted < this.maxTasks && this.consecutiveEmpty < this.maxEmpty) {
+    while (this.tasksCompleted < this.maxTasks) {
       const task2 = await this.getNextTask();
       if (!task2) {
-        if (this.consecutiveEmpty === 0) {
-          this.log("Queue empty, waiting for tasks...", "info");
-        }
-        this.consecutiveEmpty++;
-        if (this.consecutiveEmpty >= this.maxEmpty)
-          break;
-        await new Promise((r) => setTimeout(r, this.pollInterval));
-        continue;
+        this.log("No tasks remaining. Running review on staged changes...", "info");
+        await this.runStagedChangesReview(sprint2);
+        break;
       }
-      this.consecutiveEmpty = 0;
       this.log(`Claimed: ${task2.title}`, "success");
       const result = await this.executeTask(task2);
       try {
@@ -38024,6 +38086,7 @@ var init_worker = __esm(() => {
   init_colors();
   init_codebase_indexer_service();
   init_document_fetcher();
+  init_review_service();
   init_task_executor();
   if (process.argv[1]?.includes("agent-worker") || process.argv[1]?.includes("worker")) {
     process.title = "locus-worker";
@@ -38068,6 +38131,7 @@ var init_worker = __esm(() => {
 var init_agent2 = __esm(() => {
   init_codebase_indexer_service();
   init_document_fetcher();
+  init_review_service();
   init_task_executor();
   init_worker();
 });
@@ -38493,14 +38557,14 @@ var init_event_emitter = __esm(() => {
 
 // ../sdk/src/exec/history-manager.ts
 import {
-  existsSync as existsSync5,
-  mkdirSync as mkdirSync3,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync4,
   readdirSync as readdirSync2,
   readFileSync as readFileSync5,
   rmSync,
-  writeFileSync as writeFileSync3
+  writeFileSync as writeFileSync4
 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 function generateSessionId2() {
   const timestamp = Date.now().toString(36);
   const random = Math.random().toString(36).substring(2, 9);
@@ -38511,26 +38575,26 @@ class HistoryManager {
   historyDir;
   maxSessions;
   constructor(projectPath, options) {
-    this.historyDir = options?.historyDir ?? join6(projectPath, LOCUS_CONFIG.dir, LOCUS_CONFIG.sessionsDir);
+    this.historyDir = options?.historyDir ?? join7(projectPath, LOCUS_CONFIG.dir, LOCUS_CONFIG.sessionsDir);
     this.maxSessions = options?.maxSessions ?? DEFAULT_MAX_SESSIONS;
     this.ensureHistoryDir();
   }
   ensureHistoryDir() {
-    if (!existsSync5(this.historyDir)) {
-      mkdirSync3(this.historyDir, { recursive: true });
+    if (!existsSync6(this.historyDir)) {
+      mkdirSync4(this.historyDir, { recursive: true });
     }
   }
   getSessionPath(sessionId) {
-    return join6(this.historyDir, `${sessionId}.json`);
+    return join7(this.historyDir, `${sessionId}.json`);
   }
   saveSession(session) {
     const filePath = this.getSessionPath(session.id);
     session.updatedAt = Date.now();
-    writeFileSync3(filePath, JSON.stringify(session, null, 2), "utf-8");
+    writeFileSync4(filePath, JSON.stringify(session, null, 2), "utf-8");
   }
   loadSession(sessionId) {
     const filePath = this.getSessionPath(sessionId);
-    if (!existsSync5(filePath)) {
+    if (!existsSync6(filePath)) {
       return null;
     }
     try {
@@ -38542,7 +38606,7 @@ class HistoryManager {
   }
   deleteSession(sessionId) {
     const filePath = this.getSessionPath(sessionId);
-    if (!existsSync5(filePath)) {
+    if (!existsSync6(filePath)) {
       return false;
     }
     try {
@@ -38630,7 +38694,7 @@ class HistoryManager {
     return files.filter((f) => f.endsWith(".json")).length;
   }
   sessionExists(sessionId) {
-    return existsSync5(this.getSessionPath(sessionId));
+    return existsSync6(this.getSessionPath(sessionId));
   }
   findSessionByPartialId(partialId) {
     const sessions = this.listSessions();
@@ -38649,7 +38713,7 @@ class HistoryManager {
     for (const file2 of files) {
       if (file2.endsWith(".json")) {
         try {
-          rmSync(join6(this.historyDir, file2));
+          rmSync(join7(this.historyDir, file2));
           deleted++;
         } catch {}
       }
@@ -38932,8 +38996,8 @@ var init_exec = __esm(() => {
 
 // ../sdk/src/orchestrator.ts
 import { spawn as spawn3 } from "node:child_process";
-import { existsSync as existsSync6 } from "node:fs";
-import { dirname as dirname2, join as join7 } from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import { dirname as dirname2, join as join8 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { EventEmitter as EventEmitter4 } from "events";
 var AgentOrchestrator;
@@ -39034,8 +39098,8 @@ ${c.success("✅ Orchestrator finished")}`);
       const potentialPaths = [];
       const currentModulePath = fileURLToPath2(import.meta.url);
       const currentModuleDir = dirname2(currentModulePath);
-      potentialPaths.push(join7(currentModuleDir, "agent", "worker.js"), join7(currentModuleDir, "worker.js"), join7(currentModuleDir, "agent", "worker.ts"));
-      const workerPath = potentialPaths.find((p) => existsSync6(p));
+      potentialPaths.push(join8(currentModuleDir, "agent", "worker.js"), join8(currentModuleDir, "worker.js"), join8(currentModuleDir, "agent", "worker.ts"));
+      const workerPath = potentialPaths.find((p) => existsSync7(p));
       if (!workerPath) {
         throw new Error(`Worker file not found. Checked: ${potentialPaths.join(", ")}. ` + `Make sure the SDK is properly built and installed.`);
       }
@@ -40281,22 +40345,22 @@ import { parseArgs } from "node:util";
 init_index_node();
 
 // src/utils/version.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
-import { dirname as dirname3, join as join8 } from "node:path";
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname3, join as join9 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 function getVersion() {
   try {
     const __filename2 = fileURLToPath3(import.meta.url);
     const __dirname2 = dirname3(__filename2);
-    const bundledPath = join8(__dirname2, "..", "package.json");
-    const sourcePath = join8(__dirname2, "..", "..", "package.json");
-    if (existsSync7(bundledPath)) {
+    const bundledPath = join9(__dirname2, "..", "package.json");
+    const sourcePath = join9(__dirname2, "..", "..", "package.json");
+    if (existsSync8(bundledPath)) {
       const pkg = JSON.parse(readFileSync6(bundledPath, "utf-8"));
       if (pkg.name === "@locusai/cli") {
         return pkg.version || "0.0.0";
       }
     }
-    if (existsSync7(sourcePath)) {
+    if (existsSync8(sourcePath)) {
       const pkg = JSON.parse(readFileSync6(sourcePath, "utf-8"));
       if (pkg.name === "@locusai/cli") {
         return pkg.version || "0.0.0";
@@ -40319,12 +40383,12 @@ function printBanner() {
 }
 // src/utils/helpers.ts
 init_index_node();
-import { existsSync as existsSync8 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync9 } from "node:fs";
+import { join as join10 } from "node:path";
 function isProjectInitialized(projectPath) {
-  const locusDir = join9(projectPath, LOCUS_CONFIG.dir);
-  const configPath = join9(locusDir, LOCUS_CONFIG.configFile);
-  return existsSync8(locusDir) && existsSync8(configPath);
+  const locusDir = join10(projectPath, LOCUS_CONFIG.dir);
+  const configPath = join10(locusDir, LOCUS_CONFIG.configFile);
+  return existsSync9(locusDir) && existsSync9(configPath);
 }
 function requireInitialization(projectPath, command) {
   if (!isProjectInitialized(projectPath)) {
@@ -40649,6 +40713,7 @@ function showHelp2() {
     ${c.success("init")}      Initialize Locus in the current directory
     ${c.success("index")}     Index the codebase for AI context
     ${c.success("run")}       Start an agent to work on tasks
+    ${c.success("review")}    Review staged changes with AI
     ${c.success("exec")}      Run a prompt with repository context
               ${c.dim("--interactive, -i  Start interactive REPL mode")}
               ${c.dim("--session, -s <id> Resume a previous session")}
@@ -40665,6 +40730,7 @@ function showHelp2() {
     ${c.dim("$")} ${c.primary("locus init")}
     ${c.dim("$")} ${c.primary("locus index")}
     ${c.dim("$")} ${c.primary("locus run --api-key YOUR_KEY")}
+    ${c.dim("$")} ${c.primary("locus review")}
     ${c.dim("$")} ${c.primary("locus exec sessions list")}
 
   For more information, visit: ${c.underline("https://locusai.dev/docs")}
@@ -40676,8 +40742,8 @@ import { parseArgs as parseArgs2 } from "node:util";
 
 // src/config-manager.ts
 init_index_node();
-import { existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join10 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join11 } from "node:path";
 
 // src/templates/skills.ts
 var DEFAULT_SKILLS = [
@@ -40966,12 +41032,53 @@ Guidance for understanding and maintaining the overall project architecture.
 
 // src/config-manager.ts
 var LOCUS_GITIGNORE_MARKER = "# Locus AI";
+var CLAUDE_MD_TEMPLATE = `# CLAUDE.md
+
+## Planning First
+
+Every task must be planned before writing code. Create \`.locus/plans/<task-name>.md\` with: goal, approach, affected files, and acceptance criteria. Update the plan if the approach changes. Mark complete when done.
+
+## Code
+
+- Follow the existing formatter, linter, and code style. Run them before finishing.
+- Keep changes minimal and atomic. Separate refactors from behavioral changes.
+- No new dependencies without explicit approval.
+- Never put raw secrets or credentials in the codebase.
+
+## Testing
+
+- Every behavioral change needs a test. Bug fixes need a regression test.
+- Run the relevant test suite before marking work complete.
+- Don't modify tests just to make them pass — understand why they fail.
+
+## Communication
+
+- If the plan needs to change, update it and explain why before continuing.
+`;
 function updateGitignore(projectPath) {
-  const gitignorePath = join10(projectPath, ".gitignore");
+  const gitignorePath = join11(projectPath, ".gitignore");
   let content = "";
-  if (existsSync9(gitignorePath)) {
+  const locusBlock = LOCUS_GITIGNORE_PATTERNS.join(`
+`);
+  if (existsSync10(gitignorePath)) {
     content = readFileSync7(gitignorePath, "utf-8");
     if (content.includes(LOCUS_GITIGNORE_MARKER)) {
+      const lines = content.split(`
+`);
+      const startIdx = lines.findIndex((l) => l.includes(LOCUS_GITIGNORE_MARKER));
+      let endIdx = startIdx;
+      for (let i = startIdx;i < lines.length; i++) {
+        if (lines[i].startsWith(LOCUS_GITIGNORE_MARKER) || lines[i].startsWith(".locus/") || lines[i].trim() === "") {
+          endIdx = i;
+        } else {
+          break;
+        }
+      }
+      const before = lines.slice(0, startIdx);
+      const after = lines.slice(endIdx + 1);
+      content = [...before, locusBlock, ...after].join(`
+`);
+      writeFileSync5(gitignorePath, content);
       return;
     }
     if (content.length > 0 && !content.endsWith(`
@@ -40984,10 +41091,9 @@ function updateGitignore(projectPath) {
 `;
     }
   }
-  content += `${LOCUS_GITIGNORE_PATTERNS.join(`
-`)}
+  content += `${locusBlock}
 `;
-  writeFileSync4(gitignorePath, content);
+  writeFileSync5(gitignorePath, content);
 }
 
 class ConfigManager {
@@ -40996,27 +41102,35 @@ class ConfigManager {
     this.projectPath = projectPath;
   }
   async init(version2) {
-    const locusConfigDir = join10(this.projectPath, LOCUS_CONFIG.dir);
+    const locusConfigDir = join11(this.projectPath, LOCUS_CONFIG.dir);
     const locusConfigPath = getLocusPath(this.projectPath, "configFile");
     const claudeMdPath = getLocusPath(this.projectPath, "contextFile");
-    if (!existsSync9(claudeMdPath)) {
-      const template = `# Locus Project Context
-
-# Workflow
-- Run lint and typecheck before completion
-`;
-      writeFileSync4(claudeMdPath, template);
+    if (!existsSync10(claudeMdPath)) {
+      writeFileSync5(claudeMdPath, CLAUDE_MD_TEMPLATE);
+    }
+    if (!existsSync10(locusConfigDir)) {
+      mkdirSync5(locusConfigDir, { recursive: true });
     }
-    if (!existsSync9(locusConfigDir)) {
-      mkdirSync4(locusConfigDir, { recursive: true });
+    const locusSubdirs = [
+      LOCUS_CONFIG.artifactsDir,
+      LOCUS_CONFIG.documentsDir,
+      LOCUS_CONFIG.sessionsDir,
+      LOCUS_CONFIG.reviewsDir,
+      LOCUS_CONFIG.plansDir
+    ];
+    for (const subdir of locusSubdirs) {
+      const subdirPath = join11(locusConfigDir, subdir);
+      if (!existsSync10(subdirPath)) {
+        mkdirSync5(subdirPath, { recursive: true });
+      }
     }
-    if (!existsSync9(locusConfigPath)) {
+    if (!existsSync10(locusConfigPath)) {
       const config2 = {
         version: version2,
         createdAt: new Date().toISOString(),
         projectPath: "."
       };
-      writeFileSync4(locusConfigPath, JSON.stringify(config2, null, 2));
+      writeFileSync5(locusConfigPath, JSON.stringify(config2, null, 2));
     }
     const skillLocations = [
       LOCUS_CONFIG.agentSkillsDir,
@@ -41026,15 +41140,15 @@ class ConfigManager {
       ".gemini/skills"
     ];
     for (const location of skillLocations) {
-      const skillsDir = join10(this.projectPath, location);
-      if (!existsSync9(skillsDir)) {
-        mkdirSync4(skillsDir, { recursive: true });
+      const skillsDir = join11(this.projectPath, location);
+      if (!existsSync10(skillsDir)) {
+        mkdirSync5(skillsDir, { recursive: true });
       }
       for (const skill of DEFAULT_SKILLS) {
-        const skillPath = join10(skillsDir, skill.name);
-        if (!existsSync9(skillPath)) {
-          mkdirSync4(skillPath, { recursive: true });
-          writeFileSync4(join10(skillPath, "SKILL.md"), skill.content);
+        const skillPath = join11(skillsDir, skill.name);
+        if (!existsSync10(skillPath)) {
+          mkdirSync5(skillPath, { recursive: true });
+          writeFileSync5(join11(skillPath, "SKILL.md"), skill.content);
         }
       }
     }
@@ -41042,7 +41156,7 @@ class ConfigManager {
   }
   loadConfig() {
     const path3 = getLocusPath(this.projectPath, "configFile");
-    if (existsSync9(path3)) {
+    if (existsSync10(path3)) {
       return JSON.parse(readFileSync7(path3, "utf-8"));
     }
     return null;
@@ -41062,7 +41176,7 @@ class ConfigManager {
       skillsCreated: [],
       gitignoreUpdated: false
     };
-    const locusConfigDir = join10(this.projectPath, LOCUS_CONFIG.dir);
+    const locusConfigDir = join11(this.projectPath, LOCUS_CONFIG.dir);
     const claudeMdPath = getLocusPath(this.projectPath, "contextFile");
     const config2 = this.loadConfig();
     if (config2) {
@@ -41073,24 +41187,21 @@ class ConfigManager {
         result.versionUpdated = true;
       }
     }
-    if (!existsSync9(claudeMdPath)) {
-      const template = `# Locus Project Context
-
-# Workflow
-- Run lint and typecheck before completion
-`;
-      writeFileSync4(claudeMdPath, template);
+    if (!existsSync10(claudeMdPath)) {
+      writeFileSync5(claudeMdPath, CLAUDE_MD_TEMPLATE);
       result.directoriesCreated.push("CLAUDE.md");
     }
     const locusSubdirs = [
       LOCUS_CONFIG.artifactsDir,
       LOCUS_CONFIG.documentsDir,
-      LOCUS_CONFIG.sessionsDir
+      LOCUS_CONFIG.sessionsDir,
+      LOCUS_CONFIG.reviewsDir,
+      LOCUS_CONFIG.plansDir
     ];
     for (const subdir of locusSubdirs) {
-      const subdirPath = join10(locusConfigDir, subdir);
-      if (!existsSync9(subdirPath)) {
-        mkdirSync4(subdirPath, { recursive: true });
+      const subdirPath = join11(locusConfigDir, subdir);
+      if (!existsSync10(subdirPath)) {
+        mkdirSync5(subdirPath, { recursive: true });
         result.directoriesCreated.push(`.locus/${subdir}`);
       }
     }
@@ -41102,24 +41213,25 @@ class ConfigManager {
       ".gemini/skills"
     ];
     for (const location of skillLocations) {
-      const skillsDir = join10(this.projectPath, location);
-      if (!existsSync9(skillsDir)) {
-        mkdirSync4(skillsDir, { recursive: true });
+      const skillsDir = join11(this.projectPath, location);
+      if (!existsSync10(skillsDir)) {
+        mkdirSync5(skillsDir, { recursive: true });
         result.directoriesCreated.push(location);
       }
       for (const skill of DEFAULT_SKILLS) {
-        const skillPath = join10(skillsDir, skill.name);
-        if (!existsSync9(skillPath)) {
-          mkdirSync4(skillPath, { recursive: true });
-          writeFileSync4(join10(skillPath, "SKILL.md"), skill.content);
+        const skillPath = join11(skillsDir, skill.name);
+        if (!existsSync10(skillPath)) {
+          mkdirSync5(skillPath, { recursive: true });
+          writeFileSync5(join11(skillPath, "SKILL.md"), skill.content);
           result.skillsCreated.push(`${location}/${skill.name}`);
         }
       }
     }
-    const gitignorePath = join10(this.projectPath, ".gitignore");
-    const hadLocusPatterns = existsSync9(gitignorePath) && readFileSync7(gitignorePath, "utf-8").includes(LOCUS_GITIGNORE_MARKER);
+    const gitignorePath = join11(this.projectPath, ".gitignore");
+    const gitignoreBefore = existsSync10(gitignorePath) ? readFileSync7(gitignorePath, "utf-8") : "";
     updateGitignore(this.projectPath);
-    if (!hadLocusPatterns) {
+    const gitignoreAfter = readFileSync7(gitignorePath, "utf-8");
+    if (gitignoreBefore !== gitignoreAfter) {
       result.gitignoreUpdated = true;
     }
     return result;
@@ -41136,7 +41248,7 @@ class ConfigManager {
   }
   saveConfig(config2) {
     const path3 = getLocusPath(this.projectPath, "configFile");
-    writeFileSync4(path3, JSON.stringify(config2, null, 2));
+    writeFileSync5(path3, JSON.stringify(config2, null, 2));
   }
 }
 
@@ -41156,7 +41268,7 @@ Return ONLY a JSON object with this structure:
 
 File Tree:
 ${tree}`;
-    const output = await this.aiRunner.run(prompt, true);
+    const output = await this.aiRunner.run(prompt);
     const jsonMatch = output.match(/\{[\s\S]*\}/);
     if (jsonMatch)
       return JSON.parse(jsonMatch[0]);
@@ -41264,9 +41376,69 @@ async function initCommand() {
   For more information, visit: ${c.underline("https://locusai.dev/docs")}
 `);
 }
-// src/commands/run.ts
+// src/commands/review.ts
 init_index_node();
+import { existsSync as existsSync11, mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { join as join12 } from "node:path";
 import { parseArgs as parseArgs3 } from "node:util";
+async function reviewCommand(args) {
+  const { values } = parseArgs3({
+    args,
+    options: {
+      model: { type: "string" },
+      provider: { type: "string" },
+      dir: { type: "string" }
+    },
+    strict: false
+  });
+  const projectPath = values.dir || process.cwd();
+  requireInitialization(projectPath, "review");
+  const provider = resolveProvider2(values.provider);
+  const model = values.model || DEFAULT_MODEL[provider];
+  const aiRunner = createAiRunner(provider, {
+    projectPath,
+    model
+  });
+  const reviewService = new ReviewService({
+    aiRunner,
+    projectPath,
+    log: (msg, level) => {
+      switch (level) {
+        case "error":
+          console.log(`  ${c.error("✖")} ${msg}`);
+          break;
+        case "success":
+          console.log(`  ${c.success("✔")} ${msg}`);
+          break;
+        default:
+          console.log(`  ${c.dim(msg)}`);
+      }
+    }
+  });
+  console.log(`
+  ${c.primary("\uD83D\uDD0D")} ${c.bold("Reviewing staged changes...")}
+`);
+  const report = await reviewService.reviewStagedChanges(null);
+  if (!report) {
+    console.log(`  ${c.dim("No changes to review.")}
+`);
+    return;
+  }
+  const reviewsDir = join12(projectPath, LOCUS_CONFIG.dir, LOCUS_CONFIG.reviewsDir);
+  if (!existsSync11(reviewsDir)) {
+    mkdirSync6(reviewsDir, { recursive: true });
+  }
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const reportPath = join12(reviewsDir, `review-${timestamp}.md`);
+  writeFileSync6(reportPath, report, "utf-8");
+  console.log(`
+  ${c.success("✔")} ${c.success("Review complete!")}`);
+  console.log(`  ${c.dim("Report saved to:")} ${c.primary(reportPath)}
+`);
+}
+// src/commands/run.ts
+init_index_node();
+import { parseArgs as parseArgs4 } from "node:util";
 
 // src/workspace-resolver.ts
 init_index_node();
@@ -41307,7 +41479,7 @@ class WorkspaceResolver {
 
 // src/commands/run.ts
 async function runCommand(args) {
-  const { values } = parseArgs3({
+  const { values } = parseArgs4({
     args,
     options: {
       "api-key": { type: "string" },
@@ -41391,6 +41563,9 @@ async function main() {
     case "exec":
       await execCommand(args);
       break;
+    case "review":
+      await reviewCommand(args);
+      break;
     default:
       showHelp2();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@locusai/cli",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "CLI for Locus - AI-native project management platform",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@locusai/sdk": "^0.8.0"
+    "@locusai/sdk": "^0.8.1"
   },
   "devDependencies": {}
 }