@towles/tool 0.0.127 → 0.0.129

package/node_modules/@towles/shared/src/errors.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { AppError } from "./errors";
+
+describe("AppError", () => {
+  it("carries code and message", () => {
+    const err = new AppError("my_code", "boom");
+    expect(err.code).toBe("my_code");
+    expect(err.message).toBe("boom");
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(AppError);
+  });
+
+  it("uses the constructor name as the error name", () => {
+    class ChildError extends AppError {
+      constructor(message: string) {
+        super("child_code", message);
+      }
+    }
+    expect(new AppError("c", "m").name).toBe("AppError");
+    expect(new ChildError("m").name).toBe("ChildError");
+  });
+
+  it("forwards cause to the native Error.cause", () => {
+    const root = new Error("root");
+    const err = new AppError("wrapped", "outer", { cause: root });
+    expect(err.cause).toBe(root);
+  });
+
+  it("leaves cause undefined when not provided", () => {
+    const err = new AppError("nope", "no cause");
+    expect(err.cause).toBeUndefined();
+  });
+});

package/node_modules/@towles/shared/src/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared error base class for towles-tool.
+ *
+ * Uses the native ES2022 `Error.cause` option so stack traces chain properly.
+ */
+export class AppError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = new.target.name;
+    this.code = code;
+  }
+}

package/node_modules/@towles/shared/src/index.ts

@@ -1,3 +1,4 @@
+export { AppError } from "./errors.js";
 export { ensureDir, fileExists, readFile, writeFile } from "./fs.js";
 export { getTerminalColumns, limitText, printWithHexColor } from "./render.js";
 export { formatDate, generateJournalFilename, getMondayOfWeek, getWeekInfo } from "./date-utils.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.127",
+  "version": "0.0.129",
   "description": "One off quality of life scripts that I use on a daily basis.",
   "homepage": "https://github.com/ChrisTowles/towles-tool#readme",
   "bugs": {
@@ -50,32 +50,32 @@
     "prepare": "simple-git-hooks"
   },
   "dependencies": {
-    "@anthropic-ai/claude-code": "^2.1.4",
-    "@anthropic-ai/sdk": "^0.56.0",
+    "@anthropic-ai/claude-code": "^2.1.107",
+    "@anthropic-ai/sdk": "^0.88.0",
     "@towles/shared": "workspace:*",
-    "citty": "^0.1.6",
+    "citty": "^0.2.2",
     "consola": "^3.4.2",
     "d3-hierarchy": "^3.1.2",
     "fzf": "^0.5.2",
-    "luxon": "^3.7.1",
+    "luxon": "^3.7.2",
     "neverthrow": "^8.2.0",
     "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
-    "zod": "^4.0.5"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/d3-hierarchy": "^3.1.7",
-    "@types/luxon": "^3.6.2",
-    "@types/node": "^22.16.3",
+    "@types/luxon": "^3.7.1",
+    "@types/node": "^25.6.0",
     "@types/prompts": "^2.4.9",
-    "@typescript/native-preview": "^7.0.0-dev.20260111.1",
-    "bumpp": "^10.4.0",
-    "oxfmt": "^0.24.0",
-    "oxlint": "^1.7.0",
-    "simple-git-hooks": "^2.13.0",
-    "typescript": "^5.8.3",
-    "vitest": "^4.0.17"
+    "@typescript/native-preview": "^7.0.0-dev.20260414.1",
+    "bumpp": "^11.0.1",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0",
+    "simple-git-hooks": "^2.13.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   },
   "bundledDependencies": [
     "@towles/shared"

package/packages/agentboard/apps/tui/package.json

@@ -12,8 +12,8 @@
   "dependencies": {
     "@babel/core": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
-    "@opentui/core": "^0.1.88",
-    "@opentui/solid": "^0.1.88",
+    "@opentui/core": "^0.1.99",
+    "@opentui/solid": "^0.1.99",
     "@tt-agentboard/mux-tmux": "workspace:*",
     "@tt-agentboard/runtime": "workspace:*",
     "babel-plugin-module-resolver": "^5.0.2",

package/packages/agentboard/apps/tui/src/constants.ts

@@ -32,5 +32,7 @@ export function logResizeDebug(message: string, data?: Record<string, unknown>):
   const extra = data ? ` ${JSON.stringify(data)}` : "";
   try {
     appendFileSync(TUI_RESIZE_LOG, `[${ts}] [pid:${process.pid}] ${message}${extra}\n`);
-  } catch {}
+  } catch {
+    // intentionally ignored: debug log file write is best-effort
+  }
 }

package/packages/agentboard/apps/tui/src/index.tsx

@@ -360,7 +360,9 @@ function App() {
         if (startupFocusToPublish) {
           send({ type: "focus-session", name: startupFocusToPublish });
         }
-      } catch {}
+      } catch {
+        // intentionally ignored: socket setup errors are non-fatal at startup
+      }
     };
 
     socket.onclose = () => {

package/packages/agentboard/apps/tui/src/mux-context.ts

@@ -34,7 +34,9 @@ export function refocusMainPane(muxCtx: MuxContext): void {
         const paneId = main.split(" ")[0];
         Bun.spawnSync(["tmux", "select-pane", "-t", paneId], { stdout: "pipe", stderr: "pipe" });
       }
-    } catch {}
+    } catch {
+      // intentionally ignored: pane discovery is best-effort
+    }
   }
 }
 

package/packages/agentboard/packages/runtime/src/agents/watchers/amp.ts

@@ -129,13 +129,17 @@ export class AmpAgentWatcher implements AgentWatcher {
     if (this.fsWatcher) {
       try {
         this.fsWatcher.close();
-      } catch {}
+      } catch {
+        // intentionally ignored: watcher may already be closed during shutdown
+      }
       this.fsWatcher = null;
     }
     if (this.sessionWatcher) {
       try {
         this.sessionWatcher.close();
-      } catch {}
+      } catch {
+        // intentionally ignored: watcher may already be closed during shutdown
+      }
       this.sessionWatcher = null;
     }
     if (this.pollTimer) {

package/packages/agentboard/packages/runtime/src/agents/watchers/claude-code.ts

@@ -175,7 +175,9 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
     for (const w of this.fsWatchers) {
       try {
         w.close();
-      } catch {}
+      } catch {
+        // intentionally ignored: watcher may already be closed during shutdown
+      }
     }
     this.fsWatchers = [];
     if (this.pollTimer) {
@@ -211,7 +213,9 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
           try {
             const mtime = (await stat(filePath)).mtimeMs;
             if (Date.now() - mtime > JOURNAL_IDLE_TIMEOUT_MS) becomeIdle = true;
-          } catch {}
+          } catch {
+            // intentionally ignored: stat failure leaves becomeIdle unchanged
+          }
         }
 
         if (becomeIdle) {
@@ -271,7 +275,9 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
         try {
           const mtime = (await stat(filePath)).mtimeMs;
           if (Date.now() - mtime > JOURNAL_IDLE_TIMEOUT_MS) latestStatus = "idle";
-        } catch {}
+        } catch {
+          // intentionally ignored: stat failure leaves status unchanged
+        }
       }
 
       this.sessions.set(threadId, {
@@ -448,7 +454,9 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
       });
       this.fsWatchers.push(w);
       this.watchedDirs.add(dirPath);
-    } catch {}
+    } catch {
+      // intentionally ignored: watching dir is best-effort, will retry on next setup
+    }
   }
 
   private hasRecentFiles(dirPath: string): boolean {
@@ -461,9 +469,13 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
         try {
           const s = fs.statSync(join(dirPath, file));
           if (now - s.mtimeMs < STALE_MS) return true;
-        } catch {}
+        } catch {
+          // intentionally ignored: skip unreadable file
+        }
       }
-    } catch {}
+    } catch {
+      // intentionally ignored: dir unreadable, treat as no recent files
+    }
     return false;
   }
 
@@ -503,6 +515,8 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
         this.watchDir(dirPath);
       });
       this.fsWatchers.push(w);
-    } catch {}
+    } catch {
+      // intentionally ignored: top-level watch is best-effort
+    }
   }
 }

package/packages/agentboard/packages/runtime/src/agents/watchers/codex.ts

@@ -212,7 +212,9 @@ export class CodexAgentWatcher implements AgentWatcher {
     if (this.fsWatcher) {
       try {
         this.fsWatcher.close();
-      } catch {}
+      } catch {
+        // intentionally ignored: watcher may already be closed during shutdown
+      }
       this.fsWatcher = null;
     }
     if (this.pollTimer) {
@@ -238,7 +240,9 @@ export class CodexAgentWatcher implements AgentWatcher {
         if (entry.id && entry.thread_name) {
           names.set(entry.id, entry.thread_name);
         }
-      } catch {}
+      } catch {
+        // intentionally ignored: skip malformed JSON line
+      }
     }
 
     this.threadNames = names;
@@ -359,6 +363,8 @@ export class CodexAgentWatcher implements AgentWatcher {
         if (!filename?.endsWith(".jsonl")) return;
         this.processFile(join(this.sessionsDir, filename));
       });
-    } catch {}
+    } catch {
+      // intentionally ignored: sessions dir watch is best-effort
+    }
   }
 }

package/packages/agentboard/packages/runtime/src/agents/watchers/opencode.ts

@@ -86,7 +86,9 @@ export class OpenCodeAgentWatcher implements AgentWatcher {
     }
     try {
       this.db?.close();
-    } catch {}
+    } catch {
+      // intentionally ignored: best-effort sqlite handle cleanup
+    }
     this.db = null;
     this.ctx = null;
   }
@@ -124,7 +126,9 @@ export class OpenCodeAgentWatcher implements AgentWatcher {
       } catch {
         try {
           this.db.close();
-        } catch {}
+        } catch {
+          // intentionally ignored: best-effort sqlite handle cleanup
+        }
         this.db = null;
         return;
       }
@@ -153,7 +157,9 @@ export class OpenCodeAgentWatcher implements AgentWatcher {
               for (const pr of partRows) {
                 try {
                   lastParts.push(JSON.parse(pr.data));
-                } catch {}
+                } catch {
+                  // intentionally ignored: skip malformed part JSON
+                }
               }
             }
           } catch {
@@ -164,7 +170,9 @@ export class OpenCodeAgentWatcher implements AgentWatcher {
           if (lastMsg) {
             try {
               lastMsgData = JSON.parse(lastMsg.data);
-            } catch {}
+            } catch {
+              // intentionally ignored: leave lastMsgData null on parse failure
+            }
           }
 
           const status = determineStatus(lastMsgData, lastParts);
@@ -211,7 +219,9 @@ export class OpenCodeAgentWatcher implements AgentWatcher {
             for (const pr of partRows) {
               try {
                 lastParts.push(JSON.parse(pr.data));
-              } catch {}
+              } catch {
+                // intentionally ignored: skip malformed part JSON
+              }
             }
           }
         } catch {
@@ -222,7 +232,9 @@ export class OpenCodeAgentWatcher implements AgentWatcher {
         if (lastMsg) {
           try {
             lastMsgData = JSON.parse(lastMsg.data);
-          } catch {}
+          } catch {
+            // intentionally ignored: leave lastMsgData null on parse failure
+          }
         }
 
         const status = determineStatus(lastMsgData, lastParts);

package/packages/agentboard/packages/runtime/src/debug.ts

@@ -15,5 +15,7 @@ export function debugLog(category: string, msg: string, data?: Record<string, un
   const line = `[${ts}] [${category}] ${msg}${extra}\n`;
   try {
     appendFileSync(DEBUG_LOG, line);
-  } catch {}
+  } catch {
+    // intentionally ignored: debug log file write is best-effort
+  }
 }

package/packages/agentboard/packages/runtime/src/server/index.ts

@@ -1,6 +1,9 @@
 import { readFileSync, unlinkSync, writeFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+
+import consola from "consola";
+
 import type { MuxProvider } from "../contracts/mux";
 import { isFullSidebarCapable, isBatchCapable } from "../contracts/mux";
 import type { AgentEvent } from "../contracts/agent";
@@ -40,7 +43,9 @@ function log(category: string, msg: string, data?: Record<string, unknown>) {
   const line = `[${ts}] [${category}] ${msg}${extra}\n`;
   try {
     appendFileSync(DEBUG_LOG, line);
-  } catch {}
+  } catch {
+    // intentionally ignored: debug log file write is best-effort
+  }
 }
 
 // shell, getGitInfo, invalidateGitCache imported from ./git-info
@@ -67,7 +72,9 @@ export function startServer(
   // Clear previous log on server start
   try {
     writeFileSync(DEBUG_LOG, "");
-  } catch {}
+  } catch {
+    // intentionally ignored: clearing debug log is best-effort
+  }
   log("server", "starting", { providers: allProviders.map((p) => p.name) });
 
   // Load initial theme from config
@@ -840,7 +847,9 @@ export function startServer(
       try {
         const data = JSON.parse(readFileSync(join(sessionsDir, `${agentPid}.json`), "utf-8"));
         if (data.sessionId === threadId) return pane.id;
-      } catch {}
+      } catch {
+        // intentionally ignored: Claude session file missing or malformed — try next pane
+      }
     }
     return undefined;
   }
@@ -870,7 +879,9 @@ export function startServer(
     } finally {
       try {
         db.close();
-      } catch {}
+      } catch {
+        // intentionally ignored: best-effort sqlite handle cleanup
+      }
     }
     return undefined;
   }
@@ -894,7 +905,9 @@ export function startServer(
         const logText = readFileSync(pathMatch[1], "utf-8");
         const match = logText.match(/ses_[A-Za-z0-9]+/);
         if (match?.[0] === threadId) return pane.id;
-      } catch {}
+      } catch {
+        // intentionally ignored: OpenCode log file unreadable — try next pane
+      }
     }
     return undefined;
   }
@@ -1189,7 +1202,9 @@ export function startServer(
           continue;
         }
       }
-    } catch {}
+    } catch {
+      // intentionally ignored: Claude projects dir missing or unreadable
+    }
     return {};
   }
 
@@ -1216,10 +1231,13 @@ export function startServer(
         .get(`pid:${agentPid}:%`);
       if (row?.thread_id) return { threadId: row.thread_id };
     } catch {
+      // intentionally ignored: Codex sqlite query failed — no thread info available
     } finally {
       try {
         db.close();
-      } catch {}
+      } catch {
+        // intentionally ignored: best-effort sqlite handle cleanup
+      }
     }
     return {};
   }
@@ -1498,7 +1516,9 @@ export function startServer(
     if (idleTimer) clearTimeout(idleTimer);
     try {
       unlinkSync(PID_FILE);
-    } catch {}
+    } catch {
+      // intentionally ignored: PID file may already be gone during shutdown
+    }
     for (const p of allProviders) p.cleanupHooks();
   }
 
@@ -1542,7 +1562,9 @@ export function startServer(
             const name = body.trim().replace(/^"+|"+$/g, "");
             if (name) handleFocus(name);
           }
-        } catch {}
+        } catch {
+          // intentionally ignored: malformed focus body is non-fatal, respond ok
+        }
         return new Response("ok", { status: 200 });
       }
 
@@ -1553,7 +1575,9 @@ export function startServer(
           log("http", "POST /toggle", { ctx });
           toggleSidebar(ctx);
           broadcastState();
-        } catch {}
+        } catch {
+          // intentionally ignored: malformed toggle body is non-fatal, respond ok
+        }
         return new Response("ok", { status: 200 });
       }
 
@@ -1573,7 +1597,9 @@ export function startServer(
           const ctx = parseContext(body) ?? undefined;
           log("http", "POST /switch-index", { index, ctx });
           switchToVisibleIndex(index, ctx?.clientTty);
-        } catch {}
+        } catch {
+          // intentionally ignored: malformed switch-index body is non-fatal, respond ok
+        }
         return new Response("ok", { status: 200 });
       }
 
@@ -1585,7 +1611,9 @@ export function startServer(
           // Debounce ensure-sidebar during rapid switching — intermediate sessions
           // don't need full sidebar validation immediately.
           debouncedEnsureSidebar(ctx ?? undefined);
-        } catch {}
+        } catch {
+          // intentionally ignored: malformed ensure-sidebar body is non-fatal, respond ok
+        }
         return new Response("ok", { status: 200 });
       }
 
@@ -1737,7 +1765,9 @@ export function startServer(
           const cmd = JSON.parse(msg as string) as ClientCommand;
           log("ws", "command", { type: cmd.type });
           handleCommand(cmd, ws);
-        } catch {}
+        } catch {
+          // intentionally ignored: malformed websocket command is non-fatal
+        }
       },
     },
   });
@@ -1775,5 +1805,5 @@ export function startServer(
   });
 
   const names = allProviders.map((p) => p.name).join(", ");
-  console.log(`agentboard server listening on ${SERVER_HOST}:${SERVER_PORT} (mux: ${names})`);
+  consola.info(`agentboard server listening on ${SERVER_HOST}:${SERVER_PORT} (mux: ${names})`);
 }

package/packages/agentboard/packages/runtime/src/server/launcher.ts

@@ -40,7 +40,9 @@ export async function ensureServer(): Promise<void> {
     // Stale PID file — remove before spawning a new server
     try {
       unlinkSync(PID_FILE);
-    } catch {}
+    } catch {
+      // intentionally ignored: PID file may already be gone
+    }
   }
 
   const proc = Bun.spawn(["tt", "agentboard", "server"], {

package/packages/agentboard/packages/runtime/src/server/pane-scanner.ts

@@ -170,7 +170,9 @@ function resolveClaudeCodeJournalInfo(threadId: string): {
         continue;
       }
     }
-  } catch {}
+  } catch {
+    // intentionally ignored: Claude projects dir missing or unreadable
+  }
   return {};
 }
 
@@ -197,10 +199,13 @@ function resolveCodexPaneInfo(
       .get(`pid:${agentPid}:%`);
     if (row?.thread_id) return { threadId: row.thread_id };
   } catch {
+    // intentionally ignored: Codex sqlite query failed — no thread info available
   } finally {
     try {
       db.close();
-    } catch {}
+    } catch {
+      // intentionally ignored: best-effort sqlite handle cleanup
+    }
   }
   return {};
 }

package/packages/core/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tt",
-  "description": "Core dev workflow commands: interview-me, write-prd, prd-to-issues, tdd, improve-architecture, refine-text, task.",
-  "version": "0.0.109",
+  "description": "Core dev workflow commands and skills: interview-me, write-prd, prd-to-issues, tdd, improve-architecture, refine-text, task, parallel-slots, towles-tool.",
+  "version": "0.0.129",
   "author": {
     "name": "Chris Towles"
   }

package/packages/core/README.md

@@ -10,6 +10,13 @@ Core workflow automation commands for Claude Code.
 | `/tt:improve` | Explore codebase and suggest improvements     |
 | `/tt:refine`  | Fix grammar/spelling in files                 |
 
+## Skills
+
+| Skill               | Description                                                                       |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `tt:towles-tool`    | `tt` CLI reference: git/gh helpers, journaling, dependency checks.                |
+| `tt:parallel-slots` | Fan out parallel Claude Code agents across slot clones of any repo, via `gh` CLI. |
+
 ## Installation
 
 ```bash

package/packages/core/skills/parallel-slots/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: parallel-slots
+description: Use when the user wants to dispatch parallel Claude Code agents across slot clones of a repo, asks to "fan out", "run N in parallel", "use the slots", or wants to coordinate multiple isolated working copies of the same repo. Explains the slot directory layout, when to fan out vs. stay in primary, and the `gh`-driven workflow that ties slots together.
+user_invocable: true
+---
+
+# Parallel slots
+
+The slot pattern lets you run independent Claude Code sessions on the same repo without stepping on each other. Mirrors Boris Cherny's "5 terminal tabs, each a separate git checkout" workflow.
+
+## Layout
+
+```
+~/code/<scope>/<repo>-repos/
+  <repo>-primary/   # interactive work
+  <repo>-slot-1/    # parallel agent slot
+  <repo>-slot-2/
+  <repo>-slot-3/
+  <repo>-slot-4/
+  <repo>-slot-5/
+```
+
+Each slot is a full clone of the same GitHub remote, not a worktree. They check out branches independently. Use the `gh` CLI for all GitHub-side operations (issue → branch, PR create, PR merge, status). If the repo ships a tmux sidebar (e.g. AgentBoard in towles-tool), it watches every slot and surfaces completion via the stop-hook sweep.
+
+## When to fan out
+
+Fan out (use slots) when:
+
+- Three or more independent tasks would benefit from running simultaneously (e.g. one PR, one bug, one refactor).
+- A task is risky and you want a clean, throwaway slot that won't pollute primary's working tree.
+- You're iterating on the agent harness itself and want to leave primary stable.
+
+Stay in primary when:
+
+- The work is sequential or all the changes need to land in the same commit.
+- You're reading/exploring; spinning a slot just adds overhead.
+
+## Dispatch flow
+
+1. Pick a free slot (any slot whose sidebar pane is idle).
+2. `cd` into it and confirm the working tree is clean.
+3. Branch off from a GitHub issue: `gh issue develop <issue-number> --checkout` — creates a remote branch tied to the issue and switches the slot to it. If there's no issue, name the branch and use `gh pr checkout <pr>` later if you need to hop onto a colleague's PR.
+4. Hand the task to Claude in that slot — either via the repo's sidebar TUI or by running `tt auto-claude` with a prompt.
+5. Watch the sidebar pane for completion. The stop-hook prints results back to it.
+
+## Coordination rules
+
+- Never run two agents on the _same_ branch in two slots — push/pull races destroy work.
+- Branch names should be unique per slot for the duration of the run.
+- If a slot's working tree is dirty when you arrive, treat it as in-progress work — investigate before resetting.
+- Pre-commit hooks (format + lint + typecheck) run in every slot, so `--no-verify` is forbidden.
+
+## Verifying a slot's output
+
+Before merging from a slot, run that repo's verify command (`/verify` in towles-tool) inside it. Don't trust the slot's own self-report; the agent that wrote the change is not the right reviewer.
+
+## Shipping from a slot
+
+Open the PR with `gh pr create` (use `--fill` to seed title/body from commits, or pass `--title`/`--body` explicitly). Merge with `gh pr merge --rebase --admin` — the standard merge style.
+
+## Cleanup
+
+After a slot's branch is merged: confirm with `gh pr status` that the slot's PR is merged, then prune the local branch. Use `compound-engineering:ce-clean-gone-branches` to bulk-prune across multiple slots in one pass.
+
+## Anti-patterns
+
+- Spinning all 5 slots on the same task "for redundancy". You'll spend the time merging conflicts.
+- Treating slots as long-lived workspaces. They are scratch checkouts — keep them transient.
+- Editing files in primary while a slot has them open. Stay in one or the other for any given file.