@chuckssmith/agentloom 0.8.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,16 +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
@@ -48,6 +51,9 @@ Examples:
   loom collect
 `;
 switch (command) {
+    case 'init':
+        await init(args);
+        break;
     case 'setup':
         await setup();
         break;

package/dist/commands/crew.js

@@ -4,6 +4,8 @@ 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' });
@@ -69,8 +71,10 @@ export async function crew(args) {
     }
     const dryRun = args.includes('--dry-run');
     const serial = args.includes('--serial');
-    const filteredArgs = args.filter(a => a !== '--dry-run' && a !== '--serial');
-    const { specs, task } = parseWorkerSpec(filteredArgs);
+    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`);
@@ -112,6 +116,11 @@ export async function crew(args) {
     }
     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`);

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

@@ -2,7 +2,7 @@ import { readSession, readTasks, STATE_DIR } from '../state/session.js';
 import { existsSync, statSync } from 'fs';
 import { join } from 'path';
 import { readdir, readFile } from 'fs/promises';
-const STALE_THRESHOLD_MS = 10 * 60 * 1000; // 10 min with no log growth AND no live PID = stale
+import { loadConfig } from '../config.js';
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -40,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) {
@@ -72,7 +74,7 @@ export async function status() {
             const secs = Math.round(msSinceWrite / 1000);
             console.log(`  [${workerId}] running  (pid alive, last log ${secs}s ago)`);
         }
-        else if (msSinceWrite > STALE_THRESHOLD_MS) {
+        else if (msSinceWrite > staleThresholdMs) {
             const mins = Math.round(msSinceWrite / 60000);
             console.log(`  [${workerId}] STALE — pid dead, no log activity for ${mins}m`);
         }

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.8.0",
+  "version": "0.9.0",
   "description": "A workflow layer for Claude Code — reusable roles, persistence loops, and multi-agent crew coordination",
   "keywords": [
     "ai",