@poulles/worktree-dashboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gpoulles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @poulles/worktree-dashboard
+
+A local dashboard for monitoring and managing your git worktrees with Claude Code agents.
+
+## Install
+
+```bash
+npm install -g @poulles/worktree-dashboard
+```
+
+Or run it directly without installing:
+
+```bash
+npx @poulles/worktree-dashboard
+```
+
+## Usage
+
+```bash
+worktree-dashboard [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port <number>` | `3333` | Port to listen on |
+| `--logo <path>` | — | Path to a local image file, embedded as base64 |
+| `--title <string>` | `"Worktree Dashboard"` | Title shown in the header |
+| `--worktrees <path>` | `.claude/worktrees` | Path to the worktrees folder |
+| `--config <path>` | `.worktree-dashboard.json` | Path to a config file |
+
+## Config file
+
+Create `.worktree-dashboard.json` in your project root. CLI flags override these values.
+
+```json
+{
+  "port": 3333,
+  "logo": "./logo.png",
+  "title": "My Dashboard",
+  "worktrees": ".claude/worktrees"
+}
+```
+
+## Running dev servers per worktree
+
+Add a `run` block to start a project script (e.g. `ng serve`) from each worktree, with a different port per worktree so they can run side by side.
+
+```json
+{
+  "run": {
+    "scripts": ["start"],
+    "command": "npm run {script} -- --port {port}",
+    "basePort": 4200
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `scripts` | `["start"]` | Allowlist of `package.json` scripts that may be started. Only scripts that exist in a worktree's `package.json` are shown. |
+| `command` | `npm run {script} -- --port {port}` | Command template. `{script}` and `{port}` are substituted before running. |
+| `basePort` | `4200` | Port for the first worktree; each subsequent worktree gets `basePort + index`, skipping ports already in use. |
+
+When `run` is configured, each worktree card gets a **Start** control. Starting a script launches it in the worktree directory with the assigned port (also exported as the `PORT` env var) and shows a clickable `localhost:<port>` link. **Stop** terminates the process group. Processes are also stopped when the dashboard shuts down.
+
+For an Angular worktree, the default command runs `ng serve --port 4201`, `4202`, … one per worktree. Frameworks that read the `PORT` env var (Next.js, Create React App) work with a simpler `"command": "npm run {script}"`.
+
+## Worktree templates
+
+Templates let you turn a repetitive setup into a one-click flow: pick a **Type** in the
+"New worktree" dialog, fill in a field (e.g. a review ID), and the dashboard creates the
+worktree and opens VS Code with Claude already started on a predefined prompt.
+
+Add a `templates` array to your config:
+
+```json
+{
+  "templates": [
+    {
+      "id": "review",
+      "label": "Review (ADO)",
+      "fields": [
+        { "key": "id", "label": "ADO Review ID", "placeholder": "12345" }
+      ],
+      "name": "review-{id}",
+      "branch": "review/{id}",
+      "prompt": "You are doing a peer review for Azure DevOps review #{id}.\nSummarize the changes on this branch, look for correctness, security, and style issues, and list anything that needs the author's attention."
+    }
+  ]
+}
+```
+
+`{key}` placeholders in `name`, `branch`, and `prompt` are replaced with the values you
+type. On create, the dashboard writes two files into the new worktree:
+
+- `CLAUDE_TASK.md` — the interpolated prompt.
+- `.vscode/tasks.json` — a `folderOpen` task that runs `claude` against that prompt.
+
+> **First run:** VS Code asks once to trust the folder and to *Allow Automatic Tasks*.
+> After you allow it, future template worktrees launch Claude automatically. Both files are
+> left untracked in the worktree — add them to a global gitignore if you'd rather not see
+> them in the changed-files list.
+
+## How it works
+
+The dashboard reads from `~/.claude/projects/` — the JSONL session files written by Claude Code as it runs agents in each worktree. It parses these files to determine the current status of each agent (working, thinking, waiting, done, idle) and surfaces the last tool used, last file touched, and last message.
+
+Each worktree card links to VS Code so you can jump straight to the relevant file.
+
+## Requirements
+
+- Node.js 18+
+- git
+- VS Code with `code` on PATH
+
+## WSL
+
+On Windows Subsystem for Linux the browser opens automatically via `explorer.exe`.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { spawn } from 'child_process';
+import { createServer } from '../src/server.mjs';
+
+const VERSION = '0.1.0';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--port' && argv[i + 1]) args.port = parseInt(argv[++i], 10);
+    else if (argv[i] === '--logo' && argv[i + 1]) args.logo = argv[++i];
+    else if (argv[i] === '--title' && argv[i + 1]) args.title = argv[++i];
+    else if (argv[i] === '--worktrees' && argv[i + 1]) args.worktrees = argv[++i];
+    else if (argv[i] === '--config' && argv[i + 1]) args.configPath = argv[++i];
+  }
+  return args;
+}
+
+function loadFileConfig(configPath) {
+  const filePath = configPath || join(process.cwd(), '.worktree-dashboard.json');
+  if (existsSync(filePath)) {
+    try {
+      return JSON.parse(readFileSync(filePath, 'utf8'));
+    } catch (e) {
+      console.error(`Warning: failed to parse config file: ${e.message}`);
+    }
+  }
+  return {};
+}
+
+function normalizeRunConfig(run) {
+  if (!run) return null;
+  return {
+    scripts: Array.isArray(run.scripts) && run.scripts.length ? run.scripts : ['start'],
+    command: typeof run.command === 'string' ? run.command : 'npm run {script} -- --port {port}',
+    basePort: Number.isInteger(run.basePort) ? run.basePort : 4200,
+  };
+}
+
+function loadLogo(logoPath) {
+  if (!logoPath) return null;
+  const resolved = resolve(process.cwd(), logoPath);
+  if (!existsSync(resolved)) return null;
+  const ext = resolved.split('.').pop().toLowerCase();
+  const mimeMap = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', svg: 'image/svg+xml', webp: 'image/webp' };
+  const mime = mimeMap[ext] || 'image/png';
+  const data = readFileSync(resolved).toString('base64');
+  return `data:${mime};base64,${data}`;
+}
+
+function openBrowser(url) {
+  try {
+    const procVersion = readFileSync('/proc/version', 'utf8').toLowerCase();
+    if (procVersion.includes('microsoft')) {
+      spawn('explorer.exe', [url], { detached: true, stdio: 'ignore' });
+      return;
+    }
+  } catch {}
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    spawn('open', [url], { detached: true, stdio: 'ignore' });
+  } else {
+    spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
+  }
+}
+
+function main() {
+  const cliArgs = parseArgs(process.argv.slice(2));
+  const fileConfig = loadFileConfig(cliArgs.configPath);
+
+  const config = {
+    port: cliArgs.port ?? fileConfig.port ?? 3333,
+    title: cliArgs.title ?? fileConfig.title ?? 'Worktree Dashboard',
+    worktrees: cliArgs.worktrees ?? fileConfig.worktrees ?? '.claude/worktrees',
+    logo: loadLogo(cliArgs.logo ?? fileConfig.logo),
+    run: normalizeRunConfig(fileConfig.run),
+    templates: fileConfig.templates ?? [],
+    cwd: process.cwd(),
+    version: VERSION,
+  };
+
+  const server = createServer(config);
+  server.listen(config.port, '127.0.0.1', () => {
+    const url = `http://localhost:${config.port}`;
+    console.log(`\n  🌳 Worktree Dashboard is up and running! (v${VERSION})`);
+    console.log(`\n  Open it in your browser: ${url}`);
+    console.log(`  Keeping an eye on ${config.worktrees}/ for you.`);
+    console.log('\n  All set — press Ctrl+C whenever you want to stop.\n');
+    openBrowser(url);
+  });
+
+  process.on('SIGINT', () => {
+    console.log('\n  👋 Thanks for stopping by — shutting down. See you next time!\n');
+    server.close();
+    process.exit(0);
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@poulles/worktree-dashboard",
+  "version": "0.1.0",
+  "description": "A local dashboard for monitoring and managing git worktrees with Claude Code agents",
+  "type": "module",
+  "bin": {
+    "worktree-dashboard": "./bin/cli.mjs"
+  },
+  "files": ["bin", "src"],
+  "engines": { "node": ">=18" },
+  "keywords": ["claude-code", "worktree", "git", "dashboard", "developer-tools"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gpoulles/worktree-dashboard.git"
+  },
+  "bugs": { "url": "https://github.com/gpoulles/worktree-dashboard/issues" },
+  "homepage": "https://github.com/gpoulles/worktree-dashboard#readme",
+  "publishConfig": { "access": "public" }
+}