@chuckssmith/agentloom 0.7.0 → 0.9.0

package/README.md

@@ -14,9 +14,9 @@ loom setup
 Claude Code is the execution engine. agentloom adds:
 
 - **`$grind`** — persistence loop that keeps working until a task is verified complete
-- **`$crew`** — parallel workers that decompose and execute simultaneously  
+- **`$crew`** — parallel workers that decompose and execute simultaneously
 - **`$architect`** — deep analysis mode before major decisions
-- **`loom crew`** — CLI to spawn and monitor a crew from your terminal
+- **`loom crew`** — CLI to spawn, monitor, and collect results from a crew
 
 It does not replace Claude Code. It wraps it.
 
@@ -27,19 +27,24 @@ It does not replace Claude Code. It wraps it.
 ```bash
 npm install -g @chuckssmith/agentloom
 loom setup          # installs $grind, $crew, $architect skills + validates deps
+loom init           # create .loomrc config in current project (optional)
 
-# Spawn workers from your terminal:
+# Spawn workers:
 loom crew "audit every API endpoint for security issues"
+loom crew 3 "refactor the auth module"
 loom crew 2:explore+1:code-reviewer "review the payment flow"
-loom crew --dry-run 3 "migrate the database schema"   # preview before launching
+
+# Useful flags:
+loom crew --dry-run 3 "migrate the schema"   # preview decomposed subtasks first
+loom crew --watch "audit the codebase"       # launch + immediately tail logs
+loom crew --serial 3 "build the pipeline"    # run workers sequentially
 
 # Monitor:
-loom watch           # live tail all worker logs
-loom status          # session overview + stale worker detection
-loom logs w00        # full output for one worker
+loom watch           # live color-coded tail of all worker logs
+loom status          # session overview + per-worker liveness (PID-aware)
 
 # After workers finish:
-loom collect         # synthesize results with Claude
+loom collect         # synthesize results with Claude into summary.md
 loom reset --force   # clear state for next run
 
 # Or use inside any Claude Code session:
@@ -53,46 +58,58 @@ loom reset --force   # clear state for next run
 
 Install with `loom setup`. Use inside any Claude Code session:
 
-| Skill | Trigger | What it does |
-|---|---|---|
-| `$grind` | `$grind "<task>"` | Persistence loop — plans, executes in parallel, verifies. Won't stop until a code-reviewer subagent returns PASS |
-| `$crew` | `$crew "<task>"` | Decomposes task into independent streams, runs workers simultaneously, verifies result |
-| `$architect` | `$architect "<task>"` | Deep analysis — maps the system, finds real problems, recommends approach before you write code |
+| Skill | What it does |
+|---|---|
+| `$grind` | Persistence loop — plans, executes in parallel, verifies. Won't stop until a code-reviewer returns PASS |
+| `$crew` | Decomposes task into independent streams, runs workers simultaneously, verifies result |
+| `$architect` | Deep analysis — maps the system, finds real problems, recommends approach |
 
 ---
 
 ## CLI reference
 
+### Setup
+
+```
+loom init            Create .loomrc in current directory (see Configuration below)
+loom setup           Install skills to ~/.claude/skills/, validate claude + tmux
+```
+
 ### Spawning workers
 
 ```
-loom crew "<task>"                       2 general-purpose workers (default)
-loom crew 3 "<task>"                     3 workers
-loom crew 2:explore "<task>"             2 explore-type workers
-loom crew 2:explore+1:code-reviewer "<task>"   typed crew
-loom crew --dry-run 3 "<task>"           preview decomposed subtasks, no launch
+loom crew "<task>"                           Use defaults from .loomrc (or 2 general-purpose)
+loom crew 3 "<task>"                         3 workers
+loom crew 2:explore "<task>"                 2 explore-type workers
+loom crew 2:explore+1:code-reviewer "<task>" Typed crew
+
+Flags (combinable):
+  --dry-run    Preview AI-decomposed subtasks without launching
+  --watch      Launch then immediately tail all worker logs
+  --serial     Run workers sequentially — each worker reads prior results from context file
 ```
 
 ### Monitoring
 
 ```
-loom watch                   Live tail all worker logs with color-coded output
-loom status                  Session overview, task counts, stale worker detection
-loom logs                    Summary of all workers (status + last line)
+loom watch                   Live color-coded tail (auto-exits when all workers done)
+loom status                  Session overview, task counts, per-worker liveness
+loom logs                    Summary: all workers, status, last log line
 loom logs <workerId>         Full log + result for one worker (e.g. loom logs w00)
 ```
 
 ### After workers finish
 
 ```
-loom collect                 Read worker results + synthesize summary with Claude
+loom collect                 Read worker results + synthesize with Claude into .claude-team/summary.md
 loom collect --no-ai         Concatenate results without Claude synthesis
 ```
 
 ### Housekeeping
 
 ```
-loom setup                   Install skills to ~/.claude/skills/, validate deps
+loom stop                    Kill all background workers (SIGTERM)
+loom stop <workerId>         Kill one worker
 loom reset --force           Wipe .claude-team/ state
 ```
 
@@ -100,7 +117,7 @@ loom reset --force           Wipe .claude-team/ state
 
 ## Worker types
 
-Each type gets a role-specific system prompt that shapes its behavior:
+Each type gets a role-specific system prompt. Read-only roles do **not** receive `--dangerously-skip-permissions`.
 
 | Type | Role | Modifies files? |
 |---|---|---|
@@ -112,20 +129,45 @@ Each type gets a role-specific system prompt that shapes its behavior:
 
 ---
 
+## Configuration
+
+Run `loom init` to create a `.loomrc` in your project directory:
+
+```json
+{
+  "workers": 2,
+  "agentType": "general-purpose",
+  "claimTtlMinutes": 30,
+  "staleMinutes": 10
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `workers` | 2 | Default worker count when none specified |
+| `agentType` | `general-purpose` | Default agent type when none specified |
+| `claimTtlMinutes` | 30 | Minutes before a crashed worker's claimed task is re-queued |
+| `staleMinutes` | 10 | Minutes of dead-pid + log silence before worker is flagged STALE |
+
+---
+
 ## State directory
 
 Session state lives in `.claude-team/` (gitignored):
 
 ```
 .claude-team/
-  session.json          Active session metadata
-  context/              Shared context snapshots (workers read + append)
-  tasks/                Task queue — workers claim atomically via file rename
+  session.json              Active session metadata
+  context/                  Shared context snapshots (workers read + append)
+  tasks/                    Task queue — workers claim atomically via file rename
+                            Stale claimed tasks (>claimTtlMinutes) auto re-queued
   workers/
-    w00.log             Live stdout from worker 00
-    w00-prompt.md       Prompt sent to worker 00
-    w00-result.md       Result summary written by worker 00 on completion
-  summary.md            Final synthesis from loom collect
+    w00.log                 Live stdout from worker 00
+    w00.pid                 PID of worker 00 process
+    w00-prompt.md           Prompt sent to worker 00
+    w00-result.md           Result summary written by worker 00 on completion
+    w00-run.mjs             Node.js runner script (tmux mode)
+  summary.md                Final synthesis from loom collect
 ```
 
 ---
@@ -134,7 +176,7 @@ Session state lives in `.claude-team/` (gitignored):
 
 - Node.js 20+
 - Claude Code CLI (`claude`) — authenticated
-- tmux (optional — used on Mac/Linux; falls back to background processes on Windows/WSL)
+- tmux (optional — used on Mac/Linux interactive terminals; background processes used on Windows/WSL/CI)
 
 ---
 

package/dist/cli.js

@@ -7,15 +7,19 @@ import { collect } from './commands/collect.js';
 import { reset } from './commands/reset.js';
 import { watch } from './commands/watch.js';
 import { stop } from './commands/stop.js';
+import { init } from './commands/init.js';
 const [, , command, ...args] = process.argv;
 const usage = `
 agentloom (loom) — workflow layer for Claude Code
 
 Usage:
+  loom init                             Create .loomrc config in current directory
   loom setup                            Install skills and initialize state dir
   loom crew [N] "<task>"                Spawn N parallel workers on a task
   loom crew 2:explore "<task>"          Spawn typed workers (explore/plan/code-reviewer)
   loom crew --dry-run [N] "<task>"      Preview decomposed subtasks without launching
+  loom crew --serial [N] "<task>"       Run workers sequentially (each sees prior results)
+  loom crew --watch [N] "<task>"        Launch workers and immediately tail logs
   loom watch                            Live tail all worker logs (Ctrl+C to stop)
   loom stop                             Kill all background workers (SIGTERM)
   loom stop <workerId>                  Kill one worker
@@ -47,6 +51,9 @@ Examples:
   loom collect
 `;
 switch (command) {
+    case 'init':
+        await init(args);
+        break;
     case 'setup':
         await setup();
         break;

package/dist/commands/crew.js

@@ -1,8 +1,11 @@
 import { execSync, spawn, spawnSync } from 'child_process';
 import { writeFile, mkdir, open } from 'fs/promises';
 import { join } from 'path';
+import { existsSync } from 'fs';
 import { parseWorkerSpec, initSession, writeContextSnapshot, decomposeTasks, } from '../team/orchestrator.js';
 import { STATE_DIR } from '../state/session.js';
+import { watch } from './watch.js';
+import { loadConfig } from '../config.js';
 const hasTmux = () => {
     try {
         execSync('tmux -V', { stdio: 'ignore' });
@@ -67,8 +70,11 @@ export async function crew(args) {
         process.exit(1);
     }
     const dryRun = args.includes('--dry-run');
-    const filteredArgs = args.filter(a => a !== '--dry-run');
-    const { specs, task } = parseWorkerSpec(filteredArgs);
+    const serial = args.includes('--serial');
+    const watchAfter = args.includes('--watch');
+    const filteredArgs = args.filter(a => !['--dry-run', '--serial', '--watch'].includes(a));
+    const config = await loadConfig();
+    const { specs, task } = parseWorkerSpec(filteredArgs, config.workers, config.agentType);
     const totalWorkers = specs.reduce((sum, s) => sum + s.count, 0);
     const slug = task.slice(0, 30).toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
     console.log(`\nagentloom crew`);
@@ -90,25 +96,83 @@ export async function crew(args) {
         return;
     }
     const useTmux = hasTmux() && !isWSL() && process.stdout.isTTY;
-    console.log(`Mode:    ${useTmux ? 'tmux' : 'background processes'}\n`);
+    const mode = serial ? 'serial' : useTmux ? 'tmux' : 'background processes';
+    console.log(`Mode:    ${mode}\n`);
     const session = await initSession(task, totalWorkers);
     const contextPath = await writeContextSnapshot(slug, task);
     const tasks = await decomposeTasks(task, specs);
     console.log(`Session: ${session.id}`);
     console.log(`Tasks:   ${tasks.length} created`);
     console.log(`Context: ${contextPath}\n`);
-    if (useTmux) {
+    if (serial) {
+        await launchSerial(session.id, specs, tasks, contextPath);
+        console.log(`\nAll workers finished. Run: loom collect`);
+    }
+    else if (useTmux) {
         await launchTmux(session.id, specs, tasks, contextPath);
+        console.log(`\nWorkers launched. Monitor with:`);
+        console.log(`  loom status`);
+        console.log(`  loom stop    (kill all workers)`);
     }
     else {
         await launchBackground(session.id, specs, tasks, contextPath);
+        if (watchAfter) {
+            console.log();
+            await watch([]);
+            return;
+        }
+        console.log(`\nWorkers launched. Monitor with:`);
+        console.log(`  loom status`);
+        console.log(`  loom watch`);
+        console.log(`  loom stop    (kill all workers)`);
     }
-    console.log(`\nWorkers launched. Monitor with:`);
-    console.log(`  loom status`);
-    console.log(`  loom watch`);
-    console.log(`  loom stop    (kill all workers)`);
     console.log(`State dir: ${STATE_DIR}/`);
 }
+async function launchSerial(sessionId, specs, tasks, contextPath) {
+    await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
+    let workerIdx = 0;
+    for (const spec of specs) {
+        for (let i = 0; i < spec.count; i++) {
+            const workerId = `w${String(workerIdx).padStart(2, '0')}`;
+            const subtask = tasks[workerIdx]?.description ?? tasks[0]?.description ?? '';
+            const agentType = tasks[workerIdx]?.agentType ?? spec.agentType;
+            workerIdx++;
+            // Each worker receives results from all previous workers via the context file
+            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType);
+            const logFile = join(STATE_DIR, 'workers', `${workerId}.log`);
+            await writeFile(join(STATE_DIR, 'workers', `${workerId}-prompt.md`), prompt);
+            console.log(`  → Worker ${workerId} (${agentType}) starting...`);
+            const claudeArgs = [
+                '--print',
+                ...(!READ_ONLY_ROLES.has(agentType) ? ['--dangerously-skip-permissions'] : []),
+                '-p',
+                prompt,
+            ];
+            // Run synchronously — block until this worker is done before starting the next
+            const result = spawnSync('claude', claudeArgs, {
+                encoding: 'utf8',
+                timeout: 30 * 60 * 1000, // 30 min max per worker
+                env: { ...process.env, AGENTLOOM_WORKER_ID: workerId, AGENTLOOM_SESSION: sessionId },
+            });
+            const output = (result.stdout ?? '') + (result.stderr ?? '');
+            await writeFile(logFile, output);
+            if (result.status !== 0) {
+                const resultFile = join(STATE_DIR, 'workers', `${workerId}-result.md`);
+                await writeFile(resultFile, `# Error\n\nWorker exited with code ${result.status ?? 'unknown'}\n\n${output.slice(-500)}`);
+                console.log(`  ✗ Worker ${workerId} failed (exit ${result.status ?? '?'})`);
+            }
+            else {
+                // If worker didn't write its own result file, write a placeholder
+                const resultFile = join(STATE_DIR, 'workers', `${workerId}-result.md`);
+                if (!existsSync(resultFile)) {
+                    const lastLines = output.trim().split('\n').slice(-20).join('\n');
+                    await writeFile(resultFile, `# Result\n\n${lastLines}`);
+                }
+                console.log(`  ✓ Worker ${workerId} done`);
+            }
+        }
+    }
+}
 async function launchBackground(sessionId, specs, tasks, contextPath) {
     await mkdir(join(STATE_DIR, 'workers'), { recursive: true });
     let workerIdx = 0;

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(_args: string[]): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,4 @@
+import { initConfig } from '../config.js';
+export async function init(_args) {
+    await initConfig();
+}

package/dist/commands/status.js

@@ -1,8 +1,17 @@
 import { readSession, readTasks, STATE_DIR } from '../state/session.js';
 import { existsSync, statSync } from 'fs';
 import { join } from 'path';
-import { readdir } from 'fs/promises';
-const STALE_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes with no log growth = stale
+import { readdir, readFile } from 'fs/promises';
+import { loadConfig } from '../config.js';
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function status() {
     if (!existsSync(STATE_DIR)) {
         console.log('No active session. Run: loom crew "<task>"');
@@ -31,6 +40,8 @@ export async function status() {
     const logFiles = files.filter(f => f.endsWith('.log')).sort();
     if (logFiles.length === 0)
         return;
+    const config = await loadConfig();
+    const staleThresholdMs = config.staleMinutes * 60 * 1000;
     console.log(`\nWorkers: ${logFiles.length}`);
     const now = Date.now();
     for (const logFile of logFiles) {
@@ -42,21 +53,34 @@ export async function status() {
             console.log(`  [${workerId}] done ✓`);
             continue;
         }
-        // Check if log is growing (worker is alive) or stale
+        // Check PID liveness first — a quiet log doesn't mean a dead worker
+        const pidPath = join(workersDir, `${workerId}.pid`);
+        let pidAlive = false;
+        if (existsSync(pidPath)) {
+            const pid = parseInt(await readFile(pidPath, 'utf8').catch(() => ''), 10);
+            if (!isNaN(pid))
+                pidAlive = isProcessAlive(pid);
+        }
         const logStat = statSync(logPath);
         const msSinceWrite = now - logStat.mtimeMs;
-        const isStale = msSinceWrite > STALE_THRESHOLD_MS;
         const logSize = logStat.size;
-        if (logSize === 0) {
+        if (logSize === 0 && pidAlive) {
+            console.log(`  [${workerId}] starting... (pid alive)`);
+        }
+        else if (logSize === 0) {
             console.log(`  [${workerId}] starting...`);
         }
-        else if (isStale) {
+        else if (pidAlive) {
+            const secs = Math.round(msSinceWrite / 1000);
+            console.log(`  [${workerId}] running  (pid alive, last log ${secs}s ago)`);
+        }
+        else if (msSinceWrite > staleThresholdMs) {
             const mins = Math.round(msSinceWrite / 60000);
-            console.log(`  [${workerId}] STALE — no activity for ${mins}m (log: ${logPath})`);
+            console.log(`  [${workerId}] STALE — pid dead, no log activity for ${mins}m`);
         }
         else {
             const secs = Math.round(msSinceWrite / 1000);
-            console.log(`  [${workerId}] running  (last activity ${secs}s ago)`);
+            console.log(`  [${workerId}] stopped? — pid dead, last log ${secs}s ago`);
         }
     }
     const allDone = logFiles.every(f => existsSync(join(workersDir, f.replace('.log', '-result.md'))));

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export declare const LOOMRC = ".loomrc";
+export type LoomConfig = {
+    workers?: number;
+    agentType?: string;
+    claimTtlMinutes?: number;
+    staleMinutes?: number;
+    dangerouslySkipPermissions?: boolean;
+};
+export declare function loadConfig(): Promise<Required<LoomConfig>>;
+export declare function initConfig(): Promise<void>;

package/dist/config.js

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+export const LOOMRC = '.loomrc';
+const DEFAULTS = {
+    workers: 2,
+    agentType: 'general-purpose',
+    claimTtlMinutes: 30,
+    staleMinutes: 10,
+    dangerouslySkipPermissions: false,
+};
+export async function loadConfig() {
+    if (!existsSync(LOOMRC))
+        return { ...DEFAULTS };
+    try {
+        const raw = await readFile(LOOMRC, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return { ...DEFAULTS };
+        return { ...DEFAULTS, ...parsed };
+    }
+    catch {
+        console.error(`[agentloom] Warning: could not parse ${LOOMRC} — using defaults`);
+        return { ...DEFAULTS };
+    }
+}
+export async function initConfig() {
+    if (existsSync(LOOMRC)) {
+        console.log(`${LOOMRC} already exists.`);
+        return;
+    }
+    const config = {
+        workers: 2,
+        agentType: 'general-purpose',
+        claimTtlMinutes: 30,
+        staleMinutes: 10,
+    };
+    await writeFile(LOOMRC, JSON.stringify(config, null, 2) + '\n');
+    console.log(`Created ${LOOMRC}`);
+    console.log(`\nOptions:`);
+    console.log(`  workers              Default number of workers (default: 2)`);
+    console.log(`  agentType            Default agent type (default: general-purpose)`);
+    console.log(`  claimTtlMinutes      Minutes before crashed worker's task is re-queued (default: 30)`);
+    console.log(`  staleMinutes         Minutes before dead-pid worker is flagged STALE (default: 10)`);
+}

package/dist/team/orchestrator.d.ts

@@ -3,7 +3,7 @@ export type WorkerSpec = {
     count: number;
     agentType: string;
 };
-export declare function parseWorkerSpec(args: string[]): {
+export declare function parseWorkerSpec(args: string[], defaultWorkers?: number, defaultAgentType?: string): {
     specs: WorkerSpec[];
     task: string;
 };

package/dist/team/orchestrator.js

@@ -3,20 +3,15 @@ import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { spawnSync } from 'child_process';
 import { STATE_DIR, ensureStateDir, writeSession, writeTask } from '../state/session.js';
-export function parseWorkerSpec(args) {
-    // Formats:
-    //   omc team "task description"
-    //   omc team 3 "task description"
-    //   omc team 2:explore "task description"
-    //   omc team 2:explore+1:code-reviewer "task description"
+export function parseWorkerSpec(args, defaultWorkers = 2, defaultAgentType = 'general-purpose') {
     const task = args[args.length - 1] ?? '';
     const specArg = args.length > 1 ? args[0] ?? '' : '';
     if (!specArg) {
-        return { specs: [{ count: 2, agentType: 'general-purpose' }], task };
+        return { specs: [{ count: defaultWorkers, agentType: defaultAgentType }], task };
     }
     // Plain number: "3"
     if (/^\d+$/.test(specArg)) {
-        return { specs: [{ count: parseInt(specArg), agentType: 'general-purpose' }], task };
+        return { specs: [{ count: parseInt(specArg), agentType: defaultAgentType }], task };
     }
     // Typed specs: "2:explore+1:code-reviewer"
     const parts = specArg.split('+');
@@ -24,7 +19,7 @@ export function parseWorkerSpec(args) {
         const [countStr, agentType] = part.split(':');
         return {
             count: parseInt(countStr ?? '1'),
-            agentType: agentType ?? 'general-purpose',
+            agentType: agentType ?? defaultAgentType,
         };
     });
     return { specs, task };

package/dist/team/queue.js

@@ -1,11 +1,13 @@
 import { readdir, readFile, rename, writeFile, stat, unlink } from 'fs/promises';
 import { join } from 'path';
 import { STATE_DIR } from '../state/session.js';
+import { loadConfig } from '../config.js';
 const TASKS_DIR = join(STATE_DIR, 'tasks');
-const CLAIM_TTL_MS = 30 * 60 * 1000; // 30 minutes
 // Recover tasks whose worker crashed before completing.
 // Finds -claimed- files older than CLAIM_TTL_MS and re-queues them as -pending.
 export async function recoverStaleClaims() {
+    const config = await loadConfig();
+    const claimTtlMs = config.claimTtlMinutes * 60 * 1000;
     let recovered = 0;
     let files;
     try {
@@ -20,7 +22,7 @@ export async function recoverStaleClaims() {
         const filePath = join(TASKS_DIR, file);
         try {
             const { mtimeMs } = await stat(filePath);
-            if (now - mtimeMs < CLAIM_TTL_MS)
+            if (now - mtimeMs < claimTtlMs)
                 continue;
             const taskId = file.split('-claimed-')[0];
             if (!taskId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chuckssmith/agentloom",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A workflow layer for Claude Code — reusable roles, persistence loops, and multi-agent crew coordination",
   "keywords": [
     "ai",