feat(run): headless mode and no-auto-skills flag

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-starter",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Ralph Wiggum made easy. One command to run autonomous AI coding loops with auto-commit, PRs, and Docker sandbox.",
   "main": "dist/index.js",
   "bin": {

src/cli.ts

@@ -79,6 +79,8 @@ program
   .option('--limit <n>', 'Max items to fetch for --from integrations', '20')
   .option('--issue <n>', 'Specific issue number to fetch (for github)')
   .option('--output-dir <path>', 'Directory to run the task in (skips location prompt)')
+  .option('--headless', 'Suppress non-essential CLI output for embedding/automation')
+  .option('--no-auto-skills', 'Disable automatic skill installation from skills.sh')
   // New options
   .option(
     '--preset <name>',

src/commands/run.ts

@@ -277,6 +277,8 @@ export interface RunCommandOptions {
   limit?: number;
   issue?: number;
   outputDir?: string;
+  headless?: boolean;
+  autoSkills?: boolean;
   // New options
   preset?: string;
   completionPromise?: string;
@@ -319,7 +321,18 @@ export async function runCommand(
   options: RunCommandOptions
 ): Promise<void> {
   let cwd = process.cwd();
-  const spinner = ora();
+  const headless = options.headless ?? false;
+  const noopSpinner = {
+    start: (_text?: string) => noopSpinner,
+    stop: () => noopSpinner,
+    succeed: (_text?: string) => noopSpinner,
+    fail: (_text?: string) => noopSpinner,
+    warn: (_text?: string) => noopSpinner,
+    info: (_text?: string) => noopSpinner,
+    text: '',
+    isSpinning: false,
+  };
+  const spinner = headless ? noopSpinner : ora();
 
   // Handle --output-dir flag
   if (options.outputDir) {
@@ -328,7 +341,9 @@ export async function runCommand(
     mkdirSync(cwd, { recursive: true });
   }
 
-  showWelcome();
+  if (!headless) {
+    showWelcome();
+  }
 
   // Check for git repo
   if (options.commit || options.push || options.pr) {
@@ -1181,7 +1196,9 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
   }
 
   // Auto-install relevant skills from skills.sh (enabled by default)
-  await autoInstallSkillsFromTask(finalTask, cwd, options.from?.toLowerCase());
+  if (options.autoSkills !== false) {
+    await autoInstallSkillsFromTask(finalTask, cwd, options.from?.toLowerCase());
+  }
 
   // Copy design reference image to specs/ so the agent can read it
   let designImagePath: string | undefined;
@@ -1434,14 +1451,18 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
     visualValidation,
     figmaScreenshotPaths,
     ampMode: options.ampMode,
+    headless,
+    enableSkills: options.autoSkills !== false,
   };
 
   // Swarm mode: run with multiple agents in parallel
   if (options.swarm) {
     const { runSwarm } = await import('../loop/swarm.js');
     const strategy = options.strategy || 'race';
-    console.log(chalk.cyan.bold(`Swarm mode: ${strategy} strategy`));
-    console.log();
+    if (!headless) {
+      console.log(chalk.cyan.bold(`Swarm mode: ${strategy} strategy`));
+      console.log();
+    }
 
     const swarmResult = await runSwarm({
       task: loopOptions.task,
@@ -1453,9 +1474,18 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
       pr: loopOptions.pr,
       push: loopOptions.push,
       commit: loopOptions.commit,
-      onProgress: (msg) => console.log(chalk.dim(`  ${msg}`)),
+      onProgress: headless ? undefined : (msg) => console.log(chalk.dim(`  ${msg}`)),
+      headless,
+      enableSkills: options.autoSkills !== false,
     });
 
+    if (headless) {
+      if (!swarmResult.winner) {
+        throw new Error('Swarm failed: no successful result');
+      }
+      return;
+    }
+
     // Print swarm summary
     console.log();
     if (swarmResult.winner) {
@@ -1479,6 +1509,13 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
 
   const result = await runLoop(loopOptions);
 
+  if (headless) {
+    if (!result.success) {
+      throw new Error(result.error || result.exitReason || 'Loop failed');
+    }
+    return;
+  }
+
   // Print summary
   console.log();
   if (result.success) {

src/loop/executor.ts

@@ -256,6 +256,7 @@ export type LoopOptions = {
   agentTimeout?: number;
   initialValidationFeedback?: string;
   maxSkills?: number;
+  enableSkills?: boolean;
   skipPlanInstructions?: boolean;
   fixMode?: 'design' | 'scan' | 'custom';
   taskTitle?: string;
@@ -556,7 +557,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
   let lintCommands = detectLintCommands(options.cwd);
 
   // Detect Claude Code skills (capped by maxSkills option)
-  const detectedSkills = detectClaudeSkills(options.cwd);
+  const detectedSkills = options.enableSkills === false ? [] : detectClaudeSkills(options.cwd);
   let taskWithSkills = options.task;
   if (detectedSkills.length > 0) {
     const skillsPrompt = formatSkillsForPrompt(detectedSkills, options.task, options.maxSkills);

src/loop/swarm.ts

@@ -28,6 +28,8 @@ export type SwarmConfig = {
   cwd: string;
   agents?: Agent[];
   strategy: SwarmStrategy;
+  headless?: boolean;
+  enableSkills?: boolean;
   auto?: boolean;
   validate?: boolean;
   maxIterations?: number;
@@ -70,6 +72,8 @@ export async function runSwarm(config: SwarmConfig): Promise<SwarmResult> {
     task,
     cwd,
     strategy,
+    headless = false,
+    enableSkills,
     auto = true,
     validate = true,
     maxIterations = 15,
@@ -103,6 +107,8 @@ export async function runSwarm(config: SwarmConfig): Promise<SwarmResult> {
         auto,
         validate,
         maxIterations,
+        headless,
+        enableSkills,
         onProgress,
       });
       break;
@@ -111,6 +117,8 @@ export async function runSwarm(config: SwarmConfig): Promise<SwarmResult> {
         auto,
         validate,
         maxIterations,
+        headless,
+        enableSkills,
         onProgress,
       });
       break;
@@ -119,6 +127,8 @@ export async function runSwarm(config: SwarmConfig): Promise<SwarmResult> {
         auto,
         validate,
         maxIterations,
+        headless,
+        enableSkills,
         onProgress,
       });
       break;
@@ -171,6 +181,8 @@ type StrategyOptions = {
   auto: boolean;
   validate: boolean;
   maxIterations: number;
+  headless: boolean;
+  enableSkills?: boolean;
   onProgress?: (message: string) => void;
 };
 
@@ -192,6 +204,8 @@ function makeLoopOptions(
     pr: false,
     trackProgress: true,
     trackCost: true,
+    headless: opts.headless,
+    enableSkills: opts.enableSkills,
   };
 }