@chuckssmith/agentloom 0.4.0 → 0.5.0

package/README.md

@@ -1,9 +1,9 @@
 # agentloom
 
-A workflow layer for Claude Code. Better routing, reusable roles, and multi-agent crew coordination — built natively on what Claude Code already provides.
+A workflow layer for Claude Code — persistence loops, parallel crews, and typed agent roles, built natively on what Claude Code already provides.
 
 ```bash
-npm install -g agentloom
+npm install -g @chuckssmith/agentloom
 loom setup
 ```
 
@@ -12,10 +12,11 @@ loom setup
 ## What this is
 
 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 a crew of workers from your terminal
+- **`loom crew`** — CLI to spawn and monitor a crew from your terminal
 
 It does not replace Claude Code. It wraps it.
 
@@ -24,14 +25,24 @@ It does not replace Claude Code. It wraps it.
 ## Quick start
 
 ```bash
-npm install -g agentloom
-loom setup          # installs skills, validates deps
+npm install -g @chuckssmith/agentloom
+loom setup          # installs $grind, $crew, $architect skills + validates deps
 
-# From your terminal:
+# Spawn workers from your terminal:
 loom crew "audit every API endpoint for security issues"
 loom crew 2:explore+1:code-reviewer "review the payment flow"
+loom crew --dry-run 3 "migrate the database schema"   # preview before launching
+
+# Monitor:
+loom watch           # live tail all worker logs
+loom status          # session overview + stale worker detection
+loom logs w00        # full output for one worker
+
+# After workers finish:
+loom collect         # synthesize results with Claude
+loom reset --force   # clear state for next run
 
-# Or from inside a Claude Code session:
+# Or use inside any Claude Code session:
 # $grind "port the auth module to the new interface"
 # $crew "analyze all three data pipeline stages in parallel"
 ```
@@ -40,49 +51,81 @@ loom crew 2:explore+1:code-reviewer "review the payment flow"
 
 ## Skills
 
-Install with `loom setup`. Then use inside any Claude Code session:
+Install with `loom setup`. Use inside any Claude Code session:
 
-| Skill | What it does |
-|---|---|
-| `$grind` | Persistence loop with mandatory verification gate |
-| `$crew` | Parallel workers — decomposes task, runs simultaneously, verifies |
-| `$architect` | Deep analysis — maps system, finds real problems, recommends approach |
+| 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 |
 
 ---
 
-## CLI
+## CLI reference
+
+### 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
+```
+
+### Monitoring
 
 ```
-loom crew [N] "<task>"                  Spawn N general-purpose workers
-loom crew 3 "<task>"                    Spawn 3 workers
-loom crew 2:explore "<task>"            Spawn 2 Explore-type workers
-loom crew 2:explore+1:code-reviewer     Spawn typed crew
-loom status                             Show active session
-loom setup                              Install skills + validate
+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 logs <workerId>         Full log + result for one worker (e.g. loom logs w00)
 ```
 
-### Worker types
+### After workers finish
 
-Matches Claude Code's built-in subagent types:
+```
+loom collect                 Read worker results + synthesize summary with Claude
+loom collect --no-ai         Concatenate results without Claude synthesis
+```
 
-| Type | Best for |
-|---|---|
-| `explore` | Read-only research, codebase mapping |
-| `plan` | Architecture decisions, approach planning |
-| `code-reviewer` | Audits, security reviews, quality checks |
-| `frontend-developer` | UI and component work |
-| `general-purpose` | General implementation (default) |
+### Housekeeping
+
+```
+loom setup                   Install skills to ~/.claude/skills/, validate deps
+loom reset --force           Wipe .claude-team/ state
+```
+
+---
+
+## Worker types
+
+Each type gets a role-specific system prompt that shapes its behavior:
+
+| Type | Role | Modifies files? |
+|---|---|---|
+| `explore` | Maps code, documents structure and connections | No |
+| `plan` | Reasons about approach, produces ordered action plan | No |
+| `code-reviewer` | Audits for correctness, security, quality; assigns severity | No |
+| `frontend-developer` | UI, components, styling, client-side logic | Yes |
+| `general-purpose` | Does whatever the subtask requires (default) | Yes |
 
 ---
 
 ## State directory
 
+Session state lives in `.claude-team/` (gitignored):
+
 ```
-.agentloom/
-  tasks/          Task queue — workers claim atomically
-  workers/        Worker status and results
-  context/        Shared context snapshots
-  session.json    Active session metadata
+.claude-team/
+  session.json          Active session metadata
+  context/              Shared context snapshots (workers read + append)
+  tasks/                Task queue — workers claim atomically via file rename
+  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
 ```
 
 ---
@@ -90,8 +133,8 @@ Matches Claude Code's built-in subagent types:
 ## Requirements
 
 - Node.js 20+
-- Claude Code CLI (`claude`)
-- tmux (optional — used for crew mode on Mac/Linux; falls back to background processes on WSL/Windows)
+- Claude Code CLI (`claude`) — authenticated
+- tmux (optional — used on Mac/Linux; falls back to background processes on Windows/WSL)
 
 ---
 

package/dist/cli.js

@@ -5,6 +5,7 @@ import { status } from './commands/status.js';
 import { logs } from './commands/logs.js';
 import { collect } from './commands/collect.js';
 import { reset } from './commands/reset.js';
+import { watch } from './commands/watch.js';
 const [, , command, ...args] = process.argv;
 const usage = `
 agentloom (loom) — workflow layer for Claude Code
@@ -14,13 +15,21 @@ Usage:
   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 status                           Show active crew session
+  loom watch                            Live tail all worker logs (Ctrl+C to stop)
+  loom status                           Show active crew session + stale worker detection
   loom logs                             Show worker output summary
   loom logs <workerId>                  Show full log for a specific worker
   loom collect                          Synthesize worker results into a summary
   loom collect --no-ai                  Collect results without Claude synthesis
   loom reset --force                    Clear all session state
 
+Agent types (use with crew):
+  explore          Read-only research and mapping
+  plan             Architecture and approach planning
+  code-reviewer    Audit for correctness, security, quality
+  frontend-developer  UI and component work
+  general-purpose  Default — does whatever the subtask requires
+
 Modes (use $grind or $crew inside a Claude Code session):
   $grind   Persistence loop — keeps working until verified complete
   $crew    Parallel workers — decompose and execute simultaneously
@@ -31,8 +40,8 @@ Examples:
   loom crew 3 "audit every API endpoint for security issues"
   loom crew 2:explore+1:code-reviewer "review the payment flow"
   loom crew --dry-run 3 "migrate the database schema"
-  loom logs
-  loom logs w00
+  loom watch
+  loom collect
 `;
 switch (command) {
     case 'setup':
@@ -41,6 +50,9 @@ switch (command) {
     case 'crew':
         await crew(args);
         break;
+    case 'watch':
+        await watch(args);
+        break;
     case 'status':
         await status();
         break;

package/dist/commands/crew.js

@@ -13,6 +13,53 @@ const hasTmux = () => {
     }
 };
 const isWSL = () => process.platform === 'linux' && !!process.env.WSL_DISTRO_NAME;
+// Role-specific instructions injected into each worker prompt
+const AGENT_ROLE = {
+    'explore': `Your role is EXPLORER. You are read-only. Do not modify any files.
+- Map out the relevant code, files, and structure
+- Document what exists, how it connects, and what's notable
+- Your output feeds the other workers — be thorough and specific`,
+    'plan': `Your role is PLANNER. You are read-only. Do not modify any files.
+- Reason about the best approach to the subtask
+- Identify risks, dependencies, and open questions
+- Produce a concrete, ordered action plan other workers can execute`,
+    'code-reviewer': `Your role is CODE REVIEWER. You are read-only. Do not modify any files.
+- Audit the relevant code for correctness, security, and quality
+- Flag specific lines, patterns, or logic that are problematic
+- Assign severity (critical / high / medium / low) to each finding`,
+    'frontend-developer': `Your role is FRONTEND DEVELOPER.
+- Focus on UI, components, styling, and client-side logic
+- Follow existing conventions in the codebase
+- Write clean, accessible code`,
+    'general-purpose': `Your role is GENERAL PURPOSE WORKER.
+- Do whatever the subtask requires — research, implementation, or both
+- Use all tools available to you`,
+};
+function buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType) {
+    const resultFile = join(STATE_DIR, 'workers', `${workerId}-result.md`);
+    const roleInstructions = AGENT_ROLE[agentType] ?? AGENT_ROLE['general-purpose'];
+    return `You are worker ${workerId} in an agentloom crew session (${sessionId}).
+
+${roleInstructions}
+
+## Your assigned subtask
+
+"${subtask}"
+
+## Protocol
+
+1. Read the shared context: ${contextPath}
+2. Do the work thoroughly using all tools available to you
+3. Append key findings to the context file so other workers can see them
+4. When done, write a result summary to: ${resultFile}
+   Format: brief markdown — what you did, what you found, any blockers
+
+## Rules
+- Stay focused on your assigned subtask and role
+- Do not stop until your subtask is complete or you have hit a genuine blocker
+
+Begin now.`;
+}
 export async function crew(args) {
     if (args.length === 0) {
         console.error('Usage: loom crew [--dry-run] [N] "<task>"');
@@ -49,47 +96,28 @@ export async function crew(args) {
     console.log(`Tasks:   ${tasks.length} created`);
     console.log(`Context: ${contextPath}\n`);
     if (hasTmux() && !isWSL()) {
-        await launchTmux(session.id, totalWorkers, specs, tasks.map(t => t.description), contextPath);
+        await launchTmux(session.id, specs, tasks, contextPath);
     }
     else {
-        await launchBackground(session.id, specs, tasks.map(t => t.description), contextPath);
+        await launchBackground(session.id, specs, tasks, contextPath);
     }
     console.log(`\nWorkers launched. Monitor with:`);
     console.log(`  loom status`);
     console.log(`  loom logs`);
+    console.log(`  loom crew --watch   (live tail)`);
     console.log(`State dir: ${STATE_DIR}/`);
 }
-function buildWorkerPrompt(subtask, contextPath, sessionId, workerId) {
-    const resultFile = join(STATE_DIR, 'workers', `${workerId}-result.md`);
-    return `You are worker ${workerId} in an agentloom crew session (${sessionId}).
-
-Your assigned subtask: "${subtask}"
-
-## Protocol
-
-1. Read the shared context: ${contextPath}
-2. Do the work thoroughly using all tools available to you
-3. When done, write a result summary to: ${resultFile}
-   Format: brief markdown — what you did, what you found, any blockers
-
-## Rules
-- Focus only on your assigned subtask
-- Write findings to the context file (${contextPath}) so other workers can see them
-- Do not stop until your subtask is complete or you have hit a genuine blocker
-
-Begin now.`;
-}
-async function launchBackground(sessionId, specs, subtasks, contextPath) {
+async function launchBackground(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 = subtasks[workerIdx] ?? subtasks[0] ?? '';
+            const subtask = tasks[workerIdx]?.description ?? tasks[0]?.description ?? '';
+            const agentType = tasks[workerIdx]?.agentType ?? spec.agentType;
             workerIdx++;
-            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId);
+            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType);
             const logFile = join(STATE_DIR, 'workers', `${workerId}.log`);
-            // Write prompt to disk for inspection
             await writeFile(join(STATE_DIR, 'workers', `${workerId}-prompt.md`), prompt);
             const log = await open(logFile, 'w');
             const child = spawn('claude', ['--print', '--dangerously-skip-permissions', '-p', prompt], {
@@ -99,27 +127,28 @@ async function launchBackground(sessionId, specs, subtasks, contextPath) {
             });
             child.on('close', () => log.close());
             child.unref();
-            console.log(`  ✓ Worker ${workerId} (${spec.agentType}) launched [pid ${child.pid}] → ${logFile}`);
+            console.log(`  ✓ Worker ${workerId} (${agentType}) launched [pid ${child.pid}] → ${logFile}`);
         }
     }
 }
-async function launchTmux(sessionId, count, specs, subtasks, contextPath) {
+async function launchTmux(sessionId, specs, tasks, contextPath) {
     const tmuxSession = `loom-${sessionId}`;
     execSync(`tmux new-session -d -s ${tmuxSession} -x 220 -y 50`);
     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 = subtasks[workerIdx] ?? subtasks[0] ?? '';
+            const subtask = tasks[workerIdx]?.description ?? tasks[0]?.description ?? '';
+            const agentType = tasks[workerIdx]?.agentType ?? spec.agentType;
             workerIdx++;
-            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId);
+            const prompt = buildWorkerPrompt(subtask, contextPath, sessionId, workerId, agentType);
             if (workerIdx > 1) {
                 execSync(`tmux split-window -h -t ${tmuxSession}`);
                 execSync(`tmux select-layout -t ${tmuxSession} tiled`);
             }
             const cmd = `AGENTLOOM_WORKER_ID=${workerId} AGENTLOOM_SESSION=${sessionId} claude --print --dangerously-skip-permissions -p '${prompt.replace(/'/g, "'\"'\"'")}'; echo '[worker done]'; read`;
             execSync(`tmux send-keys -t ${tmuxSession} "${cmd}" Enter`);
-            console.log(`  ✓ Worker ${workerId} (${spec.agentType}) launched in tmux pane`);
+            console.log(`  ✓ Worker ${workerId} (${agentType}) launched in tmux pane`);
         }
     }
     execSync(`tmux attach-session -t ${tmuxSession}`);

package/dist/commands/status.js

@@ -1,6 +1,8 @@
-import { readSession, readTasks, readWorkers } from '../state/session.js';
-import { existsSync } from 'fs';
-import { STATE_DIR } from '../state/session.js';
+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
 export async function status() {
     if (!existsSync(STATE_DIR)) {
         console.log('No active session. Run: loom crew "<task>"');
@@ -12,7 +14,6 @@ export async function status() {
         return;
     }
     const tasks = await readTasks();
-    const workers = await readWorkers();
     const pending = tasks.filter(t => t.status === 'pending').length;
     const claimed = tasks.filter(t => t.status === 'claimed').length;
     const done = tasks.filter(t => t.status === 'done').length;
@@ -22,13 +23,44 @@ export async function status() {
     console.log(`Task:    ${session.description}`);
     console.log(`Started: ${session.createdAt}`);
     console.log(`\nTasks:   ${pending} pending  ${claimed} active  ${done} done  ${failed} failed`);
-    console.log(`Workers: ${workers.length} (${session.workerCount} total)`);
-    if (workers.length > 0) {
-        console.log('\nWorker status:');
-        for (const w of workers) {
-            const task = w.currentTaskId ? tasks.find(t => t.id === w.currentTaskId) : null;
-            const desc = task ? `  → ${task.description.slice(0, 60)}` : '';
-            console.log(`  [${w.id}] ${w.status}${desc}`);
+    // Worker status from log files
+    const workersDir = join(STATE_DIR, 'workers');
+    if (!existsSync(workersDir))
+        return;
+    const files = await readdir(workersDir);
+    const logFiles = files.filter(f => f.endsWith('.log')).sort();
+    if (logFiles.length === 0)
+        return;
+    console.log(`\nWorkers: ${logFiles.length}`);
+    const now = Date.now();
+    for (const logFile of logFiles) {
+        const workerId = logFile.replace('.log', '');
+        const logPath = join(workersDir, logFile);
+        const resultPath = join(workersDir, `${workerId}-result.md`);
+        const hasResult = existsSync(resultPath);
+        if (hasResult) {
+            console.log(`  [${workerId}] done ✓`);
+            continue;
+        }
+        // Check if log is growing (worker is alive) or stale
+        const logStat = statSync(logPath);
+        const msSinceWrite = now - logStat.mtimeMs;
+        const isStale = msSinceWrite > STALE_THRESHOLD_MS;
+        const logSize = logStat.size;
+        if (logSize === 0) {
+            console.log(`  [${workerId}] starting...`);
         }
+        else if (isStale) {
+            const mins = Math.round(msSinceWrite / 60000);
+            console.log(`  [${workerId}] STALE — no activity for ${mins}m (log: ${logPath})`);
+        }
+        else {
+            const secs = Math.round(msSinceWrite / 1000);
+            console.log(`  [${workerId}] running  (last activity ${secs}s ago)`);
+        }
+    }
+    const allDone = logFiles.every(f => existsSync(join(workersDir, f.replace('.log', '-result.md'))));
+    if (allDone && logFiles.length > 0) {
+        console.log(`\nAll workers done. Run: loom collect`);
     }
 }

package/dist/commands/watch.d.ts

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

package/dist/commands/watch.js

@@ -0,0 +1,69 @@
+import { readdir, stat, readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { STATE_DIR } from '../state/session.js';
+const WORKERS_DIR = join(STATE_DIR, 'workers');
+const POLL_MS = 800;
+// A rotating set of ANSI colors for worker prefixes
+const COLORS = ['\x1b[36m', '\x1b[33m', '\x1b[35m', '\x1b[32m', '\x1b[34m', '\x1b[31m'];
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+export async function watch(_args) {
+    if (!existsSync(WORKERS_DIR)) {
+        console.log('No active session. Run: loom crew "<task>"');
+        process.exit(1);
+    }
+    console.log(`${DIM}Watching worker logs. Ctrl+C to stop.${RESET}\n`);
+    // Track how many bytes we've read from each log file
+    const offsets = {};
+    const seen = new Set();
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (!existsSync(WORKERS_DIR))
+            break;
+        const files = await readdir(WORKERS_DIR);
+        const logFiles = files.filter(f => f.endsWith('.log')).sort();
+        for (const logFile of logFiles) {
+            const workerId = logFile.replace('.log', '');
+            const color = COLORS[parseInt(workerId.replace('w', ''), 10) % COLORS.length] ?? COLORS[0];
+            const filePath = join(WORKERS_DIR, logFile);
+            if (!seen.has(workerId)) {
+                seen.add(workerId);
+                const resultExists = existsSync(join(WORKERS_DIR, `${workerId}-result.md`));
+                console.log(`${color}[${workerId}]${RESET} ${DIM}started${resultExists ? ' (already done)' : ''}${RESET}`);
+            }
+            const currentSize = (await stat(filePath)).size;
+            const offset = offsets[workerId] ?? 0;
+            if (currentSize > offset) {
+                const buf = await readFile(filePath);
+                const newContent = buf.slice(offset).toString('utf8');
+                offsets[workerId] = currentSize;
+                const lines = newContent.split('\n');
+                for (const line of lines) {
+                    if (line.trim()) {
+                        process.stdout.write(`${color}[${workerId}]${RESET} ${line}\n`);
+                    }
+                }
+            }
+            // Check if worker just finished (result file appeared)
+            const resultPath = join(WORKERS_DIR, `${workerId}-result.md`);
+            const doneKey = `${workerId}-done`;
+            if (existsSync(resultPath) && !seen.has(doneKey)) {
+                seen.add(doneKey);
+                console.log(`${color}[${workerId}]${RESET} ${DIM}✓ result written${RESET}`);
+            }
+        }
+        // Exit when all known workers have results
+        if (logFiles.length > 0) {
+            const allDone = logFiles.every(f => {
+                const id = f.replace('.log', '');
+                return existsSync(join(WORKERS_DIR, `${id}-result.md`));
+            });
+            if (allDone) {
+                console.log(`\n${DIM}All workers done. Run: loom collect${RESET}`);
+                break;
+            }
+        }
+        await new Promise(resolve => setTimeout(resolve, POLL_MS));
+    }
+}

package/package.json

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