claudedash 0.5.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-scope contributors
+
+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,207 @@
+# claudedash
+
+See what your AI agent is actually doing.
+
+[![npm](https://img.shields.io/npm/v/claudedash)](https://www.npmjs.com/package/claudedash)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/yunusemrgrl/claudedash/actions/workflows/ci.yml/badge.svg)](https://github.com/yunusemrgrl/claudedash/actions/workflows/ci.yml)
+
+---
+
+## The problem
+
+You tell Claude Code to refactor your auth system. It says "on it." You wait. Terminal scrolls. Minutes pass. You have no idea if it's on task 2 of 12 or stuck in a loop. You're flying blind.
+
+claudedash fixes that. One command, zero config. It reads Claude Code's own task files and gives you a live Kanban board.
+
+```bash
+npx -y claudedash@latest start
+```
+
+That's it. Open `localhost:4317`. Watch your agent work.
+
+![claudedash demo](docs/screenrecord.gif)
+
+## How it works
+
+Claude Code writes task state to `~/.claude/tasks/` when it uses the TodoWrite tool. claudedash reads those files, watches for changes, and streams updates to your browser via SSE. No database. No auth. No cloud. Just files.
+
+**Important:** Claude Code only writes task files when TodoWrite is actively used. To ensure your sessions always appear on the dashboard, add this to your project's `CLAUDE.md`:
+
+```markdown
+You MUST use the TodoWrite tool to track your work.
+At the START of any multi-step task, create a todo list with all steps.
+Mark each task in_progress before starting, completed after finishing.
+```
+
+Or run `claudedash init` — it generates a ready-to-use `CLAUDE.md` snippet.
+
+## Two modes
+
+| | Live | Plan |
+|---|---|---|
+| **What** | Watch Claude Code work | Structured project planning |
+| **Source** | `~/.claude/tasks/` | `.claudedash/queue.md` |
+| **Setup** | None | `npx claudedash init` |
+| **Use when** | You want visibility | You want control |
+
+Live mode is the default. Plan mode adds dependencies, acceptance criteria, and execution tracking on top.
+
+| Live mode | Plan mode |
+|---|---|
+| ![Live](docs/screenshot-1.png) | ![Plan](docs/screenshot-2.png) |
+
+## Install
+
+```bash
+# Zero-install, always latest
+npx -y claudedash@latest start
+
+# Or install globally
+npm i -g claudedash
+claudedash start
+```
+
+### Plan mode
+
+For structured project execution with task dependencies and acceptance criteria.
+
+```bash
+claudedash init
+```
+
+This creates `.claudedash/` with:
+
+| File | Purpose |
+|---|---|
+| `queue.md` | Your task list — slices, dependencies, AC |
+| `workflow.md` | Execution protocol your agent follows |
+| `execution.log` | Agent logs DONE/FAILED/BLOCKED here |
+| `config.json` | Heading patterns, port, field definitions |
+| `CLAUDE.md` | Paste into your project's CLAUDE.md |
+
+Then:
+
+1. Edit `queue.md` with your actual tasks
+2. Copy `CLAUDE.md` contents into your project's CLAUDE.md
+3. Tell your agent: *"follow .claudedash/workflow.md, start with S1-T1"*
+4. Run `claudedash start` and watch the dashboard
+
+## CLI
+
+```bash
+claudedash start                          # Auto-detect modes, open dashboard
+claudedash start --claude-dir /path       # Custom Claude directory
+claudedash start -p 3000                  # Custom port
+claudedash init                           # Init plan mode in current dir
+```
+
+## Queue format (Plan mode)
+
+```markdown
+# Slice S1
+
+## S1-T1
+Area: Backend
+Depends: -
+Description: Setup database schema
+AC: Tables created and migrations run
+
+## S1-T2
+Area: Backend
+Depends: S1-T1
+Description: Implement user authentication
+AC: Login and registration endpoints working
+```
+
+Validates: required fields, duplicate IDs, unknown deps, circular deps.
+
+## Execution log (Plan mode)
+
+Append-only JSONL:
+
+```json
+{"task_id":"S1-T1","status":"DONE","timestamp":"2026-02-16T14:31:22Z","agent":"claude"}
+{"task_id":"S1-T2","status":"FAILED","timestamp":"2026-02-16T14:33:10Z","agent":"claude","meta":{"reason":"timeout"}}
+{"task_id":"S1-T3","status":"BLOCKED","reason":"API key missing","timestamp":"2026-02-16T14:35:00Z","agent":"claude"}
+```
+
+## Observability Features
+
+### Quality Gates
+
+Track lint, typecheck, and test results per task and view them as a timeline in the Plan mode dashboard.
+
+Log quality results in `execution.log`:
+
+```json
+{
+  "task_id": "F1-2",
+  "status": "DONE",
+  "timestamp": "2026-02-18T12:05:00Z",
+  "agent": "claude",
+  "meta": {
+    "file": "src/core/logParser.ts",
+    "quality": { "lint": true, "typecheck": true, "test": false }
+  }
+}
+```
+
+Select any task in Plan mode to see its quality check history with pass/fail badges. → [Quality Gates docs](docs/quality-gates.md)
+
+### Context Health
+
+See how much of Claude's context window each session is using, with color-coded warnings at 65% (warn) and 75% (critical).
+
+- Session cards show a compact `72%` indicator
+- Selected session shows a full progress bar in the token header
+- A header banner appears when any session crosses warn/critical level
+
+→ [Context Health docs](docs/context-health.md) | [Estimation methodology](docs/context-estimation.md)
+
+### Worktree Observability
+
+When running agents across multiple git worktrees in parallel, the new **Worktrees** tab shows:
+
+- Branch name and HEAD commit per worktree
+- Dirty/clean status (uncommitted changes)
+- Ahead/behind commits relative to upstream
+- Which agent tasks are running in each worktree
+
+→ [Worktree docs](docs/worktrees.md)
+
+## API
+
+| Endpoint | Description |
+|---|---|
+| `GET /health` | Status + available modes |
+| `GET /sessions` | All Claude Code sessions (includes `contextHealth`) |
+| `GET /sessions/:id` | Tasks for a session |
+| `GET /events` | SSE stream |
+| `GET /snapshot` | Plan mode state |
+| `GET /quality-timeline` | Quality check events (filter with `?taskId=`) |
+| `GET /worktrees` | Git worktrees with task associations |
+
+## Development
+
+```bash
+git clone https://github.com/yunusemrgrl/claudedash.git
+cd claudedash && npm install
+cd dashboard && npm install && cd ..
+
+npm run build        # Build core + dashboard
+npm test             # 163 tests
+npm run dev          # Dev server with watch
+```
+
+## Stack
+
+TypeScript, Fastify, chokidar, SSE, Next.js, Tailwind, Vitest.
+
+## Contributing
+
+PRs welcome. Open an issue first for anything beyond small fixes. See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { exec } from 'child_process';
+import { startServer } from './server/server.js';
+const program = new Command();
+program
+    .name('claudedash')
+    .description('Live Kanban, quality gates and context health monitoring for Claude Code agents')
+    .version('0.5.4');
+program
+    .command('init')
+    .description('Initialize claudedash in current directory')
+    .action(() => {
+    const claudeWatchDir = join(process.cwd(), '.claudedash');
+    // Create .claudedash/ directory
+    if (existsSync(claudeWatchDir)) {
+        console.log('⚠️  .claudedash/ already exists');
+        process.exit(1);
+    }
+    try {
+        mkdirSync(claudeWatchDir);
+        console.log('✓ Created .claudedash/');
+        // Create queue.md with realistic example
+        const queueTemplate = `# Slice S1
+
+## S1-T1
+Area: Setup
+Depends: -
+Description: Initialize project structure and install dependencies
+AC: Project builds and all linters pass
+
+## S1-T2
+Area: Core
+Depends: S1-T1
+Description: Implement core feature
+AC: Feature works end-to-end with happy path
+
+## S1-T3
+Area: Test
+Depends: S1-T1, S1-T2
+Description: Add integration tests for core feature
+AC: All tests pass, edge cases covered
+`;
+        writeFileSync(join(claudeWatchDir, 'queue.md'), queueTemplate);
+        console.log('✓ Created queue.md');
+        // Create empty execution.log
+        writeFileSync(join(claudeWatchDir, 'execution.log'), '');
+        console.log('✓ Created execution.log');
+        // Create config.json
+        const config = {
+            queueFile: 'queue.md',
+            logFile: 'execution.log',
+            port: 4317,
+            taskModel: {
+                fields: [
+                    { name: 'Area', type: 'enum', required: true, values: ['Setup', 'Core', 'Test'] },
+                    { name: 'Depends', type: 'refs', required: false },
+                    { name: 'Description', type: 'text', required: true },
+                    { name: 'AC', type: 'text', required: true }
+                ],
+                id: '{slice}-T{n}',
+                headings: {
+                    slice: '# Slice {name}',
+                    task: '## {id}'
+                }
+            }
+        };
+        writeFileSync(join(claudeWatchDir, 'config.json'), JSON.stringify(config, null, 2));
+        console.log('✓ Created config.json');
+        // Create workflow.md — autonomous execution protocol
+        const workflowTemplate = `# Agent Workflow
+
+Autonomous execution protocol for claudedash Plan mode.
+Each task from \`queue.md\` is processed through these phases.
+
+---
+
+## Phase 1 — INTAKE
+
+Read the next READY task from \`.claudedash/queue.md\`.
+
+1. Parse the task: ID, Area, Description, AC, Dependencies.
+2. Verify all dependencies have status DONE in \`execution.log\`.
+3. If dependencies are not met, log BLOCKED and move to next task.
+
+---
+
+## Phase 2 — EXECUTE
+
+Implement the task.
+
+1. Read the task description and acceptance criteria.
+2. Identify affected files using the codebase.
+3. Implement the change. Follow existing conventions.
+4. Run relevant tests/linters to verify.
+
+---
+
+## Phase 3 — LOG
+
+Append result to \`.claudedash/execution.log\` (one JSON line):
+
+Success:
+\`\`\`json
+{"task_id":"S1-T1","status":"DONE","timestamp":"2026-01-15T10:30:00Z","agent":"claude"}
+\`\`\`
+
+Failure:
+\`\`\`json
+{"task_id":"S1-T1","status":"FAILED","timestamp":"2026-01-15T10:30:00Z","agent":"claude","meta":{"reason":"tests failing"}}
+\`\`\`
+
+Blocked:
+\`\`\`json
+{"task_id":"S1-T1","status":"BLOCKED","reason":"missing API key","timestamp":"2026-01-15T10:30:00Z","agent":"claude"}
+\`\`\`
+
+---
+
+## Phase 4 — NEXT
+
+Pick the next READY task and return to Phase 1.
+If no READY tasks remain, stop and report summary.
+
+---
+
+## Rules
+
+1. One task at a time. Finish before starting next.
+2. Always log to execution.log — never skip Phase 3.
+3. If stuck after 2 attempts, log FAILED and move on.
+4. Do not modify queue.md — it is read-only for the agent.
+5. Use \`new Date().toISOString()\` for timestamps.
+`;
+        writeFileSync(join(claudeWatchDir, 'workflow.md'), workflowTemplate);
+        console.log('✓ Created workflow.md');
+        // Create CLAUDE.md snippet file
+        const claudeMdContent = `# claudedash Integration
+
+## Task Tracking (MANDATORY)
+
+You MUST use the TodoWrite tool to track your work. This is not optional.
+The user monitors your progress via a live dashboard that reads TodoWrite output.
+
+Rules:
+- At the START of any multi-step task, create a todo list with all steps.
+- Mark each task as \`in_progress\` BEFORE you start working on it.
+- Mark each task as \`completed\` IMMEDIATELY after finishing it.
+- Keep exactly ONE task as \`in_progress\` at any time.
+- Update the todo list as you discover new subtasks.
+
+If you skip TodoWrite, the user cannot see what you are doing.
+
+## Plan Mode (if .claudedash/queue.md exists)
+
+Follow \`.claudedash/workflow.md\` for structured task execution.
+Tasks are defined in \`.claudedash/queue.md\`.
+Log progress to \`.claudedash/execution.log\`.
+
+Log format (append one JSON line per task):
+\`\`\`json
+{"task_id":"S1-T1","status":"DONE","timestamp":"2026-01-15T10:30:00Z","agent":"claude"}
+\`\`\`
+
+Status values: \`DONE\`, \`FAILED\`, \`BLOCKED\` (requires \`reason\` field)
+
+## Dashboard
+
+Run \`npx -y claudedash@latest start\` to view progress.
+`;
+        writeFileSync(join(claudeWatchDir, 'CLAUDE.md'), claudeMdContent);
+        console.log('✓ Created CLAUDE.md');
+        console.log('\n✓ Ready! Next steps:');
+        console.log('  1. Edit .claudedash/queue.md with your tasks');
+        console.log('  2. Copy .claudedash/CLAUDE.md contents into your project CLAUDE.md');
+        console.log('  3. Tell your agent: "follow .claudedash/workflow.md, start with S1-T1"');
+        console.log('  4. Run: npx -y claudedash@latest start');
+    }
+    catch (error) {
+        console.error('❌ Failed to initialize:', error);
+        process.exit(1);
+    }
+});
+program
+    .command('start')
+    .description('Start the claudedash server and dashboard')
+    .option('--claude-dir <path>', 'Path to Claude directory', join(process.env.HOME || '~', '.claude'))
+    .option('-p, --port <number>', 'Port number', '4317')
+    .action(async (opts) => {
+    const claudeDir = opts.claudeDir;
+    const claudeWatchDir = join(process.cwd(), '.claudedash');
+    // Detect available modes
+    const hasLive = existsSync(join(claudeDir, 'tasks'));
+    const hasPlan = existsSync(claudeWatchDir);
+    if (!hasLive && !hasPlan) {
+        console.error('❌ No data sources found.');
+        console.error(`   Live mode: ${claudeDir}/tasks/ not found`);
+        console.error('   Plan mode: .claudedash/ not found (run "claudedash init")');
+        process.exit(1);
+    }
+    // Read port from config if plan mode available, otherwise use CLI option
+    let port = parseInt(opts.port, 10);
+    if (hasPlan) {
+        const configPath = join(claudeWatchDir, 'config.json');
+        if (existsSync(configPath)) {
+            try {
+                const configContent = await import('fs').then(fs => fs.promises.readFile(configPath, 'utf-8'));
+                const config = JSON.parse(configContent);
+                if (config.port && opts.port === '4317') {
+                    port = config.port;
+                }
+            }
+            catch { /* use default port */ }
+        }
+    }
+    const url = `http://localhost:${port}`;
+    try {
+        await startServer({
+            claudeDir,
+            port,
+            agentScopeDir: hasPlan ? claudeWatchDir : undefined
+        });
+        console.log(`✓ Server running on ${url}`);
+        if (hasLive)
+            console.log(`  Live mode: watching ${claudeDir}/tasks/`);
+        if (hasPlan)
+            console.log('  Plan mode: reading .claudedash/');
+        console.log('✓ Opening browser...');
+        const platform = process.platform;
+        const openCommand = platform === 'darwin' ? 'open' :
+            platform === 'win32' ? 'start' :
+                'xdg-open';
+        exec(`${openCommand} ${url}`, (error) => {
+            if (error) {
+                console.log('Could not auto-open browser. Please visit:', url);
+            }
+        });
+    }
+    catch (error) {
+        console.error('❌ Failed to start server:', error);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/contextHealth.d.ts

@@ -0,0 +1,14 @@
+import type { ClaudeSession, ContextHealth } from './types.js';
+/**
+ * Estimates context window usage percentage for a Claude session.
+ *
+ * Uses inputTokens as the primary proxy for context occupancy (see docs/context-estimation.md).
+ * Returns null when token data is unavailable or empty.
+ */
+export declare function estimateContextPercentage(session: ClaudeSession): number | null;
+/**
+ * Builds a full ContextHealth object for a session.
+ * Returns null when estimation is impossible.
+ */
+export declare function buildContextHealth(session: ClaudeSession): ContextHealth | null;
+//# sourceMappingURL=contextHealth.d.ts.map

package/dist/core/contextHealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextHealth.d.ts","sourceRoot":"","sources":["../../src/core/contextHealth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAuB,MAAM,YAAY,CAAC;AAgBpF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAQ/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAa/E"}

package/dist/core/contextHealth.js

@@ -0,0 +1,46 @@
+const DEFAULT_MAX_TOKENS = 200_000;
+const WARN_THRESHOLD = 65;
+const CRITICAL_THRESHOLD = 75;
+/**
+ * Derives warning level from a 0-100 percentage.
+ */
+function deriveWarningLevel(percentage) {
+    if (percentage >= CRITICAL_THRESHOLD)
+        return 'critical';
+    if (percentage >= WARN_THRESHOLD)
+        return 'warn';
+    return 'safe';
+}
+/**
+ * Estimates context window usage percentage for a Claude session.
+ *
+ * Uses inputTokens as the primary proxy for context occupancy (see docs/context-estimation.md).
+ * Returns null when token data is unavailable or empty.
+ */
+export function estimateContextPercentage(session) {
+    if (!session.tokenUsage)
+        return null;
+    const { inputTokens } = session.tokenUsage;
+    if (inputTokens <= 0)
+        return null;
+    const percentage = Math.min(100, (inputTokens / DEFAULT_MAX_TOKENS) * 100);
+    return Math.round(percentage * 10) / 10; // 1 decimal place
+}
+/**
+ * Builds a full ContextHealth object for a session.
+ * Returns null when estimation is impossible.
+ */
+export function buildContextHealth(session) {
+    const percentage = estimateContextPercentage(session);
+    if (percentage === null)
+        return null;
+    const tokensUsed = session.tokenUsage.inputTokens;
+    return {
+        percentage,
+        warningLevel: deriveWarningLevel(percentage),
+        tokensUsed,
+        maxTokens: DEFAULT_MAX_TOKENS,
+        estimationMethod: 'token-based',
+    };
+}
+//# sourceMappingURL=contextHealth.js.map

package/dist/core/contextHealth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextHealth.js","sourceRoot":"","sources":["../../src/core/contextHealth.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEnC,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B;;GAEG;AACH,SAAS,kBAAkB,CAAC,UAAkB;IAC5C,IAAI,UAAU,IAAI,kBAAkB;QAAE,OAAO,UAAU,CAAC;IACxD,IAAI,UAAU,IAAI,cAAc;QAAE,OAAO,MAAM,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAsB;IAC9D,IAAI,CAAC,OAAO,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAErC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAC3C,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,GAAG,kBAAkB,CAAC,GAAG,GAAG,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,kBAAkB;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,MAAM,UAAU,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAErC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAW,CAAC,WAAW,CAAC;IAEnD,OAAO;QACL,UAAU;QACV,YAAY,EAAE,kBAAkB,CAAC,UAAU,CAAC;QAC5C,UAAU;QACV,SAAS,EAAE,kBAAkB;QAC7B,gBAAgB,EAAE,aAAa;KAChC,CAAC;AACJ,CAAC"}

package/dist/core/insightsEngine.d.ts

@@ -0,0 +1,4 @@
+import type { ComputedTask, LogEvent, ClaudeSession, PlanInsights, LiveInsights } from './types.js';
+export declare function computePlanInsights(tasks: ComputedTask[], events: LogEvent[]): PlanInsights;
+export declare function computeLiveInsights(sessions: ClaudeSession[]): LiveInsights;
+//# sourceMappingURL=insightsEngine.d.ts.map

package/dist/core/insightsEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insightsEngine.d.ts","sourceRoot":"","sources":["../../src/core/insightsEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EAAE,EACrB,MAAM,EAAE,QAAQ,EAAE,GACjB,YAAY,CA8Dd;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,YAAY,CAgE3E"}