claudedash 1.1.18 → 1.1.20

package/README.md

@@ -1,59 +1,115 @@
 # claudedash
 
-See what your AI agent is actually doing.
+**See exactly what your AI agent is doing — in real time.**
 
-[![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)
+[![npm version](https://img.shields.io/npm/v/claudedash?color=00f5ff&labelColor=0f0f12)](https://www.npmjs.com/package/claudedash)
+[![npm downloads](https://img.shields.io/npm/dm/claudedash?labelColor=0f0f12)](https://www.npmjs.com/package/claudedash)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?labelColor=0f0f12)](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
+## 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.
+You tell Claude Code: _"refactor the auth system."_ It says: _"on it."_
 
-claudedash fixes that. One command, zero config. It reads Claude Code's own task files and gives you a live Kanban board.
+Terminal scrolls. Minutes pass. Is it on step 3 of 12? Stuck in a loop? Already done?
+
+**You have no idea.**
+
+claudedash fixes that. One command, zero config — a live dashboard for every Claude Code session.
 
 ```bash
 npx -y claudedash@latest start
 ```
 
-That's it. Open `localhost:4317`. Watch your agent work.
+Open `localhost:4317`. Watch your agent work.
 
-![claudedash demo](landing/assets/activitiy.mp4)
+---
 
-## How it works
+## Quick Start
 
-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.
+```bash
+# Zero-install — always gets the latest version
+npx -y claudedash@latest start
 
-**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`:
+# Install lifecycle hooks (recommended)
+claudedash hooks install
 
-```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.
+# Set up plan mode for structured task execution
+claudedash init
 ```
 
-Or run `claudedash init` — it generates a ready-to-use `CLAUDE.md` snippet.
+That's it. The dashboard auto-detects your Claude sessions.
+
+---
+
+## Features
 
-## Two modes
+- **Live Kanban board** — real-time task status from `~/.claude/tasks/`, updated via SSE within ~100ms
+- **Plan mode** — structured execution with dependencies, acceptance criteria, and blocked-task detection
+- **Context health** — token usage bar per session, warnings at 65% (warn) and 75% (critical)
+- **Quality gates** — lint / typecheck / test results per task with a full timeline history
+- **Worktrees** — map parallel agents across git branches, see dirty/ahead/behind at a glance
+- **Agent API** — `POST /log`, `POST /agent/register`, heartbeat, BLOCKED → instant browser push notification
+- **Hook integration** — PostToolUse/Stop/PreCompact/PostCompact hooks stream every tool call live
+- **Cost tracker** — 5-hour rolling billing block estimate per model, real-time
+- **MCP server** — `get_queue`, `get_sessions`, `get_cost`, `log_task` — Claude can query its own dashboard
+- **Zero infra** — no database, no cloud, reads files from `~/.claude/` directly
 
-| | 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 vs Plan Mode
+
+|                   | **Live Mode**                  | **Plan Mode**                |
+| ----------------- | ------------------------------ | ---------------------------- |
+| **What**          | Watch Claude work in real time | Structured project execution |
+| **Source**        | `~/.claude/tasks/`             | `.claudedash/queue.md`       |
+| **Setup**         | None                           | `claudedash init`            |
+| **Use when**      | Visibility matters             | Control matters              |
+| **Deps / AC**     | —                              | ✓ Full dependency graph      |
+| **Execution log** | —                              | ✓ `execution.log`            |
 
-Live mode is the default. Plan mode adds dependencies, acceptance criteria, and execution tracking on top.
+Live mode is on by default. Both modes can run simultaneously.
+
+---
 
-| Live | Queue | Activity |
-|---|---|---|
-| ![Live](landing/assets/live.png) | ![Queue](landing/assets/queue.png) | ![Activity](landing/assets/activitiy.mp4) |
+## Screenshots
+
+<table>
+  <tr>
+    <td align="center" width="50%">
+      <img src="landing/assets/live.png" alt="Live View" /><br/>
+      <sub><b>Live View</b> — Session Kanban + context health per agent</sub>
+    </td>
+    <td align="center" width="50%">
+      <img src="landing/assets/queue.png" alt="Queue" /><br/>
+      <sub><b>Queue</b> — Plan mode task board with dependency graph</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="50%">
+      <img src="landing/assets/worktrees.png" alt="Worktrees" /><br/>
+      <sub><b>Worktrees</b> — Parallel agents across git branches</sub>
+    </td>
+    <td align="center" width="50%">
+      <img src="landing/assets/activity.gif" alt="Activity" /><br/>
+      <sub><b>Activity</b> — Tool analytics + full prompt history</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="50%">
+      <img src="landing/assets/config.png" alt="Config" /><br/>
+      <sub><b>Config</b> — Hook setup, port, token management</sub>
+    </td>
+    <td align="center" width="50%">
+      <img src="landing/assets/docs.png" alt="Docs" /><br/>
+      <sub><b>Docs</b> — Built-in reference for API + plan mode</sub>
+    </td>
+  </tr>
+</table>
 
-| Worktrees | Config | Docs |
-|---|---|---|
-| ![Worktrees](landing/assets/worktrees.png) | ![Config](landing/assets/config.png) | ![Docs](landing/assets/docs.png) |
+---
 
 ## Install
 
@@ -66,9 +122,11 @@ npm i -g claudedash
 claudedash start
 ```
 
-### Plan mode
+---
+
+## Plan Mode
 
-For structured project execution with task dependencies and acceptance criteria.
+Initialize in your project:
 
 ```bash
 claudedash init
@@ -76,155 +134,133 @@ 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 |
+| File            | Purpose                                               |
+| --------------- | ----------------------------------------------------- |
+| `queue.md`      | Task list — slices, dependencies, acceptance criteria |
+| `workflow.md`   | Execution protocol for your agent                     |
+| `execution.log` | Agent logs `DONE` / `FAILED` / `BLOCKED` here         |
+| `CLAUDE.md`     | Paste into your project's `CLAUDE.md`                 |
 
-Then:
+**queue.md format:**
 
-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 start --host 0.0.0.0           # Expose to network (shows warning)
-claudedash start --token <secret>         # Enable token auth for sharing
-claudedash init                           # Init plan mode in current dir
-claudedash recover                        # Summarize last session after /clear
-claudedash spec                           # Create spec-mode templates
-claudedash worktree create <branch>       # Create isolated worktree
-```
+```markdown
+# Slice S1
 
-## Sharing with your team
+## S1-T1
 
-By default, claudedash only listens on `127.0.0.1` (localhost). To share the dashboard with a teammate:
+Area: Backend
+Depends: -
+Description: Setup database schema
+AC: Tables created, migrations run
 
-```bash
-# 1. Start with a secret token
-claudedash start --token mysecret123
+## S1-T2
 
-# Or use an environment variable
-CLAUDEDASH_TOKEN=mysecret123 claudedash start
+Area: Backend
+Depends: S1-T1
+Description: Implement user auth
+AC: Login and registration working
 ```
 
-Your teammate can then open the dashboard with the token in the URL:
+Tell your agent:
 
 ```
-http://your-host:4317?token=mysecret123
+Follow .claudedash/workflow.md, start with S1-T1.
 ```
 
-Or pass it as a header:
+---
+
+## CLI
+
+| Command                             | Description                               |
+| ----------------------------------- | ----------------------------------------- |
+| `claudedash start`                  | Start dashboard (auto-detect modes)       |
+| `claudedash start -p 3000`          | Custom port                               |
+| `claudedash start --token <secret>` | Enable auth token                         |
+| `claudedash init`                   | Init plan mode in current directory       |
+| `claudedash hooks install`          | Install PostToolUse/Stop/PreCompact hooks |
+| `claudedash status`                 | Single-line terminal summary (no browser) |
+| `claudedash doctor`                 | Check setup: hooks, port, version, queue  |
+| `claudedash recover`                | Summarize last session after `/clear`     |
+
+---
+
+## Sharing with Your Team
+
+By default claudedash listens on `127.0.0.1` only.
 
 ```bash
-curl -H "Authorization: Bearer mysecret123" http://your-host:4317/sessions
+# Start with a token
+claudedash start --token mysecret123
+
+# Or via env
+CLAUDEDASH_TOKEN=mysecret123 claudedash start
 ```
 
-> **Security:** Never commit your token to git. Use `.env` and add it to `.gitignore`. Consider using a local tunnel like [ngrok](https://ngrok.com) or [cloudflared](https://github.com/cloudflare/cloudflared) rather than exposing `--host 0.0.0.0` directly.
+Team access: `http://your-host:4317?token=mysecret123`
+
+> **Tip:** Use a tunnel instead of exposing `--host 0.0.0.0`:
 >
 > ```bash
-> # Share via tunnel without network exposure
 > claudedash start --token $(openssl rand -hex 16)
 > ngrok http 4317
 > ```
 
-## Queue format (Plan mode)
+---
 
-```markdown
-# Slice S1
+## Advanced Features
 
-## S1-T1
-Area: Backend
-Depends: -
-Description: Setup database schema
-AC: Tables created and migrations run
+### Context Health
 
-## S1-T2
-Area: Backend
-Depends: S1-T1
-Description: Implement user authentication
-AC: Login and registration endpoints working
-```
+Color-coded token usage per session — green → yellow → red at 65% / 75%.
+→ [Context Health docs](docs/context-health.md)
 
-Validates: required fields, duplicate IDs, unknown deps, circular deps.
+### Quality Gates
 
-## Execution log (Plan mode)
+Log `lint`, `typecheck`, `test` results per task via `meta.quality` in `execution.log`.
+See ✅/❌ inline in each card, with full timeline.
+→ [Quality Gates docs](docs/quality-gates.md)
 
-Append-only JSONL:
+### Worktrees
 
-```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"}
-```
+Running agents across multiple git branches? The Worktrees tab maps sessions to branches by `cwd`, shows dirty/ahead/behind state, and lists which tasks are running where. Native support for `claude --worktree <name>` (creates `.claude/worktrees/<name>/`).
+→ [Worktree docs](docs/worktrees.md)
 
-## Observability Features
+### MCP Server
 
-### Quality Gates
+Claude can query its own dashboard:
 
-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 }
-  }
-}
+```bash
+claude mcp add claudedash -- npx -y claudedash@latest mcp
 ```
 
-Select any task in Plan mode to see its quality check history with pass/fail badges. → [Quality Gates docs](docs/quality-gates.md)
+Tools: `get_queue`, `get_sessions`, `get_cost`, `get_history`, `log_task`, `create_task`, `register_agent`, `send_heartbeat`.
 
-### 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
+## API
 
-When running agents across multiple git worktrees in parallel, the new **Worktrees** tab shows:
+| Endpoint                    | Description                          |
+| --------------------------- | ------------------------------------ |
+| `GET /health`               | Status, modes, connected clients     |
+| `GET /sessions`             | All sessions with context health     |
+| `GET /sessions/:id/context` | Session JSONL summary                |
+| `GET /events`               | SSE stream                           |
+| `GET /snapshot`             | Plan mode state                      |
+| `GET /queue`                | Computed task statuses               |
+| `GET /worktrees`            | Git worktrees with task associations |
+| `GET /billing-block`        | Current 5h billing window            |
+| `GET /cost`                 | Estimated cost by model              |
+| `POST /log`                 | Log task result                      |
+| `POST /plan/task`           | Add task to queue.md                 |
+| `POST /agent/register`      | Register an agent                    |
 
-- 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)
+## Stack
 
-## API
+TypeScript · Fastify · chokidar · SSE · Next.js 16 · Tailwind CSS · Vitest
 
-| Endpoint | Description |
-|---|---|
-| `GET /health` | Status + available modes + `connectedClients` + `lastSessions` |
-| `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=` or `?file=`) |
-| `GET /worktrees` | Git worktrees with task associations |
-| `GET /claude-insights` | Claude usage report (sandboxed HTML) |
-| `POST /plan/task` | Add a task to queue.md |
-| `PATCH /plan/task/:id` | Update task status (DONE / BLOCKED / FAILED) |
+---
 
 ## Development
 
@@ -233,19 +269,18 @@ 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             # 165 tests
-npm run dev          # Dev server with watch
+npm run build    # Build core + dashboard
+npm test         # Run 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.
+PRs welcome. Open an issue first for anything beyond small fixes.
+See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License
 
-MIT
+MIT — not affiliated with Anthropic.

package/dist/cli.js

@@ -8,7 +8,7 @@ const program = new Command();
 program
     .name('claudedash')
     .description('Live Kanban, quality gates and context health monitoring for Claude Code agents')
-    .version('1.1.18');
+    .version('1.1.20');
 program
     .command('init')
     .description('Initialize claudedash in current directory')
@@ -77,6 +77,17 @@ Each task from \`queue.md\` is processed through these phases.
 
 ---
 
+## Phase 0 — BOOTSTRAP (run once at session start)
+
+1. Read \`.claudedash/CLAUDE.md\` — mandatory project rules (TodoWrite, MCP tools, pre-commit checklist).
+2. Read \`.claudedash/queue.md\` — full task list.
+3. Read \`.claudedash/execution.log\` — understand what is already DONE/FAILED/BLOCKED.
+4. Identify all READY tasks: dependencies satisfied, not yet in execution.log as DONE.
+
+If claudedash MCP is configured (\`claude mcp list\` shows \`claudedash\`), use \`get_queue\` instead of reading files manually.
+
+---
+
 ## Phase 1 — INTAKE
 
 Read the next READY task from \`.claudedash/queue.md\`.
@@ -91,37 +102,31 @@ Read the next READY task from \`.claudedash/queue.md\`.
 
 Implement the task.
 
-1. Read the task description and acceptance criteria.
+1. Read the task description and acceptance criteria carefully.
 2. Identify affected files using the codebase.
 3. Implement the change. Follow existing conventions.
-4. Run relevant tests/linters to verify.
+4. Run relevant tests/linters to verify the AC is met.
 
 ---
 
-## Phase 3 — LOG
+## Phase 3 — VERIFY (mandatory before logging DONE)
 
-Record the result. **Preferred: HTTP** (when claudedash server is running). **Fallback: file** (append to execution.log directly).
+Run the full pre-commit checklist. Never skip.
 
-### Option A — HTTP (preferred when server is running on port 4317)
+\`\`\`
+npm run lint                              # 0 errors required
+npx tsc --noEmit                          # server/CLI types
+cd dashboard && npx tsc --noEmit && cd .. # dashboard types
+npm run build                             # full build must succeed
+\`\`\`
 
-\`\`\`bash
-# Success
-curl -sf -X POST http://localhost:4317/log \\
-  -H 'Content-Type: application/json' \\
-  -d '{"task_id":"S1-T1","status":"DONE","agent":"claude"}' || true
+If any step fails: fix it, re-run, then proceed to Phase 4.
 
-# Failure
-curl -sf -X POST http://localhost:4317/log \\
-  -H 'Content-Type: application/json' \\
-  -d '{"task_id":"S1-T1","status":"FAILED","agent":"claude","reason":"tests failing"}' || true
+---
 
-# Blocked (triggers real-time browser notification)
-curl -sf -X POST http://localhost:4317/log \\
-  -H 'Content-Type: application/json' \\
-  -d '{"task_id":"S1-T1","status":"BLOCKED","agent":"claude","reason":"missing API key"}' || true
-\`\`\`
+## Phase 4 — LOG
 
-### Option B — File (fallback, append one JSON line)
+Append result to \`.claudedash/execution.log\` (one JSON line):
 
 Success:
 \`\`\`json
@@ -138,22 +143,11 @@ Blocked:
 {"task_id":"S1-T1","status":"BLOCKED","reason":"missing API key","timestamp":"2026-01-15T10:30:00Z","agent":"claude"}
 \`\`\`
 
----
-
-## Phase 3b — CHECK QUEUE (optional, when server is running)
-
-Get computed task statuses with dependency resolution:
-
-\`\`\`bash
-curl -sf http://localhost:4317/queue
-# Returns: { tasks: [...], summary: { total, done, failed, blocked, ready } }
-\`\`\`
-
-Use this instead of manually parsing queue.md + execution.log.
+If claudedash MCP is configured, use \`log_task\` tool instead of writing the file directly.
 
 ---
 
-## Phase 4 — NEXT
+## Phase 5 — NEXT
 
 Pick the next READY task and return to Phase 1.
 If no READY tasks remain, stop and report summary.
@@ -163,10 +157,12 @@ 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.
+2. Always run Phase 3 (verify) before Phase 4 (log). Never log DONE without a passing build.
+3. Always log to execution.log — never skip Phase 4.
+4. If stuck after 2 attempts, log FAILED and move on.
+5. Do not modify queue.md — it is read-only for the agent.
+6. Use \`new Date().toISOString()\` for timestamps.
+7. Use TodoWrite to track progress — the user monitors the live dashboard.
 `;
         writeFileSync(join(claudeWatchDir, 'workflow.md'), workflowTemplate);
         console.log('✓ Created workflow.md');