Handoff MCP Dashboard

Visualize and manage handoff-mcp tasks, sessions, and metrics — right inside VS Code.

Features

Task Explorer — Tree view with status icons, priority badges, and milestone filtering. Click any task to open its detail panel with done-criteria checklist, schedule, and time tracking.

Dashboard — Project overview showing task counts by status, completion percentage, effort budget burn-down, Kanban board, work timeline, and recent activity feed.

Gantt Chart — Interactive timeline with month/day headers, drag-to-reschedule, milestone grouping, and auto-scroll to today.

Kanban Board — Drag-and-drop cards across status columns (todo / in_progress / review / done). Status changes write back to .handoff/ automatically.

Metrics Panel — Effort hours (estimated vs actual), velocity trends, session duration analytics, and filterable label/milestone breakdowns.

Time Tracker — Start/stop timer linked to the active task. Idle detection pauses automatically. Accumulated time persists across VS Code restarts. AI agents can control the timer remotely via handoff-mcp — start, stop, pause, and resume from the coding session.

Session Browser — Browse AI session history with summaries, decisions, blockers, and file pointers from each handoff.

Effort Budget — Configure total project hours in config.toml. The dashboard shows remaining budget and burn rate.

Requirements Explorer — TreeView for browsing and managing requirements across documents. Inline operations: change dev_stage, create linked tasks, backfill stable IDs, group by category/priority/status, and filter by coverage gaps.

V-model Map — Visualize requirement-to-test traceability across V-model layers. Drill down from layer summaries to individual items. Includes trace matrix and table views showing the N×M requirement–test relationship.

Coverage Trend Chart — Track requirement coverage over time with a trend graph. See how implemented, tested, and not_started counts evolve across sessions.

Inspector — Context-sensitive detail panel driven by a selection model. Select a task, document, session, referral, or requirement anywhere in the UI and the Inspector shows its full detail with inline editing.

Document Viewer — View handoff documents with section outlines, verification state indicators, SubItem (requirement) UI, treemap visualization, and impact analysis. Parent/child/related document navigation.

Suspect / Stale Display — When a requirement's linked code changes, the item is flagged as suspect. Stale banners appear in the editor and explorer, with one-click navigation to the affected trace item.

Diagnostics UI — Structured warnings from handoff-mcp are displayed as health cards on the dashboard. Empty states show actionable WHY/HOW guidance instead of blank panels.

Diagram Rendering — Fenced plantuml and aelm code blocks in documents are rendered as inline SVG diagrams using configurable external renderers. Timeout and error fallback to source display.

Home Section — Landing view with project health summary, recent activity, and quick navigation to all panels.

Plan Section — Sidebar views for effort planning, milestone tracking, and project configuration.

Bottom Panel — Persistent footer showing the current in-progress task with timer, status, and quick actions.

Report System — Generate, browse, and approve verification, weekly, monthly, milestone, defect, and completion reports. Edit templates with live preview and export to HTML for external sharing. Full approval workflow (submit → approve / revision requested).

Verification Campaigns — Browse campaigns, record pass/fail/blocked/waived checks with structured evidence (path, type, caption). Progress tracking with auto-generated checklists.

Metrics Trend Charts — Snapshot-based trend visualization for effort hours and velocity over time.

Plan Document Explorer — Browse plan documents with requirement coverage indicators and one-click navigation to linked tasks.

Gantt Enhancements — Plan-scoped filtering, baseline comparison bars (scheduled vs. actual), and suspect-requirement highlighting on the timeline.

Setup

1. Install handoff-mcp (the MCP server)

This extension visualizes data created by handoff-mcp — an MCP server that gives AI coding agents persistent memory across sessions.

Option A — Claude Code Plugin (recommended)

# Install the binary
npm install -g handoff-mcp-server

# Add the marketplace and install (in Claude Code)
/plugin marketplace add alphaelements/handoff-mcp
/plugin install handoff-mcp@handoff-mcp-marketplace

This registers the MCP server and all skills (handoff, handoff-load, handoff-memory, handoff-refer, handoff-import) automatically — no manual setup needed.

Optional: memory auto-injection hooks

/plugin install handoff-mcp-hooks@handoff-mcp-marketplace
/plugin enable handoff-mcp-hooks

Injects relevant project memories on every prompt and file edit. Disable anytime with /plugin disable handoff-mcp-hooks.

Option B — Manual setup

npm install -g handoff-mcp-server
claude mcp add -s user handoff -- handoff-mcp

Optionally copy skill files for automatic session handling:

cp -r $(npm root -g)/handoff-mcp-server/skills/* ~/.claude/skills/

3. Add to your project's CLAUDE.md

Add the following to your project's CLAUDE.md so the agent uses handoff consistently across sessions:

## Session Handoff

This project uses handoff-mcp for session continuity.

- **Session start**: Call `handoff_load_context` to load previous session state.
  If not initialized, call `handoff_init` with the project name.
  If `session_guidance` is present, immediately call `handoff_save_context`
  with `session_status: "active"` to establish a persistent session before
  starting work.
- **Session end**: Call `handoff_save_context` with a summary, decisions, and blockers.
- **During work**: Use `handoff_update_task` to track progress.
  Mark tasks `in_progress` when starting, `done` when complete.

4. Initialize your project

In an AI coding session (e.g. Claude Code), ask the agent to initialize handoff:

> Initialize handoff for this project

This creates a .handoff/ directory in your project root with config.toml and empty tasks/ and sessions/ directories.

5. Install this extension

Search "Handoff" in the VS Code Marketplace, or run:

ext install alphaelements.handoff-vscode

6. Open your project

Open the folder containing .handoff/ in VS Code. The extension activates automatically:

• Task Explorer appears in the sidebar
• Dashboard is available via Ctrl+Shift+P / Cmd+Shift+P → Handoff: Open Dashboard
• Status Bar shows task counts and active timer

Requirements

• VS Code 1.90+
• A project with a .handoff/ directory (created by handoff-mcp)

Try it without handoff-mcp

Clone this repo and open it in VS Code — it includes a .handoff/ directory with realistic demo data (42 tasks, sessions, milestones, and effort budget). No MCP server needed to explore the UI.

Commands

All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Configuration

Key settings under handoff.* in VS Code Settings:

For the full list of settings plus config.toml reference, see Configuration.

Change history

Unreleased

0.15.0 — 2026-10-27

Added

• Milestone TreeView: dedicated Activity Bar panel listing all milestones with status, progress, date, and color; filter by status (all / planning / active / completed)
• Milestone commands: changeMilestoneStatus and filterMilestones for quick milestone management
• Mock attribute display: Requirements Explorer shows mock/golden icons on items that have mock HTML or golden screenshots defined
• Gantt Chart milestones: milestone markers rendered as diamond shapes on the Gantt timeline; clicking opens the milestone popup in Project settings

Improved

• Requirement Mindmap: tree filter switched from dim to hide mode — filtered-out nodes are removed from the tree instead of faded, reducing visual clutter

Fixed

• E2E test t141.5: adapted to handoff-mcp v0.43.0 suspect detection changes (AT-002 baseline hash drift)
• E2E test t531.4: campaign create now succeeds by providing layer items in the test fixture
• E2E test 3.5: milestone TreeView wiring proof now verifies the actual TreeDataProvider, not just command registration

0.14.1 — 2026-10-24

Fixed

• Trace Table: requirements mode now shows all items when V-model mode is unavailable (previously, projects where every document has a layer showed zero items)
• Requirement Mindmap: default layer changed from brainstorm to the first non-brainstorm left layer (typically requirement), so the tree opens on the most relevant data
• Requirement Mindmap: added layer selector dropdown when multiple left layers exist (shows item count per layer)

0.14.0 — 2026-10-18

Added

• Requirement Mindmap: interactive 2D tree visualization of V-model traceability data (report schema v3)
  • SVG + Canvas dual backend with d3-hierarchy layout (tree / radial modes)
  • 4-level LOD, rAF frame scheduler, spatial index, viewport culling for large trees
  • Node glyphs: circle (leaf), rounded-rect (composite), diamond (decision), hexagon (select)
  • Status rings, verification badges, suspect/priority indicators, DAG shared-parent markers
  • Status background patterns with ON/OFF toggle setting
  • Expand/collapse with depth-level toolbar, subtree focus with breadcrumb navigation
  • Filter panel (status, verification, kind, gap kinds), legend with interactive toggles
  • Context menu: open document, focus subtree, expand/collapse all, linked tasks, create task, add child requirement
  • Keyboard navigation (arrow keys, Home/End, Enter/Escape) unified across all layout modes
  • Inspector integration: trace tree sections with linked tasks and document details
  • High-contrast theme support, ARIA tree accessibility
  • Canvas backend for high-density rendering
• handoff-mcp CLI: trace tree action commands (focus, expand, linked tasks)

Fixed

• ErrorBoundary: host message listener moved outside boundary to survive React crashes
• Context menu: "Open document" grayed out for items without documents; "Linked tasks" disabled when no tasks linked
• Focus ring visibility improved (2→2.5px, semi-transparent fill)

0.13.0 — 2026-10-15

Added

• Requirements Explorer: TreeView with inline operations — change dev_stage, create linked tasks, backfill stable IDs, group by category/priority/status, filter by coverage gaps (no tests, P0 only, advanced multi-axis)
• V-model Map: layer visualization with drill-down to individual items
• Trace Matrix / Table: N×M requirement–test traceability matrix
• Coverage Trend Chart: track requirement coverage over time
• Inspector: context-sensitive detail panel with selection model — tasks, documents, sessions, referrals, and requirements
• Plan Section: sidebar views for effort planning and milestone tracking
• Home Section: landing view with project health summary and quick navigation
• Bottom Panel: persistent footer showing current in-progress task with timer and quick actions
• 5-Section Shell: header + 5 navigable sections (Home, Work, Specs, Plan, Sessions)
• Document Viewer: section outlines with verification state, SubItem UI, treemap, metrics, impact analysis, parent/child/related navigation
• Suspect / Stale Display: flag changed requirements with suspect banners in editor and explorer
• Diagnostics UI: structured warnings as health cards, empty-state WHY/HOW guidance
• Diagram Rendering: inline SVG for plantuml / aelm code blocks via configurable external renderers
• Create Task form: header + Task button opens a form in the Inspector (title, parent, priority, assignee, requirement links via handoff-mcp CLI)
• Document links: link/unlink documents from the Inspector or Specs & Requirements view (bidirectional task_links ↔ task_ids, undoable)
• Document header: edit document type and auto_inject, or delete, from the Docs section header
• Requirement sub-items: edit priority and impl/test references from the Inspector (layer documents offer Edit in body)
• Document outline: verification state dot per section, parent/child/related documents
• handoff-mcp CLI integration: native binary calls for task–requirement linking and V-model trace commands
• Perf bench infrastructure: automated performance regression testing
• Project Status Dashboard: project-level status overview with layer completion indicators
• Verification Campaign UI: browse campaigns, record checks, attach evidence with structured metadata
• Report Explorer: browse and manage reports (verification, weekly, monthly, milestone, defect, completion)
• Report Approval Workflow: submit, approve, reject, and view revision history from the UI
• Template Editing: edit report templates with live preview, HTML export for external sharing
• Metrics Snapshot Trend Charts: visualize effort and velocity trends over time
• Plan Document Explorer: browse plan documents with requirement coverage indicators
• Requirement Coverage Status Bar: live indicator of overall requirement coverage
• Suspect Status Bar Badge: status bar badge showing count of suspect (stale) requirements
• Gantt Plan Filter: filter Gantt chart by plan document scope
• Gantt Baseline Comparison Bar: visualize schedule baseline vs. actual dates
• Gantt Suspect Highlight: highlight tasks linked to suspect requirements on the Gantt chart

Changed

• UI rebuilt on V1 architecture (5-section shell, Inspector-centric navigation)
• TraceGraph (2D graph) replaced with table-centric trace matrix UI
• Undo of schedule edits now restores fields that were empty before
• Removed settings: handoff.statusBar.showBranch, handoff.autoRefresh, handoff.overworkLimitPercent, handoff.aiEstimateMultiplier (last two moved to config.toml)
• Removed command: handoff.reassembleDoc
• Removed settings: handoff.defaultView, handoff.gantt.defaultScale

Fixed

• Timer double-counting when switching tasks
• Stale banner timer not clearing on navigation
• React hooks warnings in development mode
• Render error reporting (errors now surface in the UI instead of silently failing)
• Display bugs (FR-918): four known rendering issues

Performance

• Incremental reload with per-file cache (skip unchanged files)
• Snapshot / patch / resync protocol for efficient data updates
• Optimistic updates for instant UI feedback on writes
• Web Worker scheduler for background data processing
• Gantt chart memoization
• Document content-hash lazy computation

Project Structure

The extension reads from the .handoff/ directory created by handoff-mcp:

your-project/
└── .handoff/
    ├── config.toml          # Project name, effort budget
    ├── tasks/
    │   ├── t1-auth/
    │   │   └── _task.done.json
    │   └── t2-api/
    │       └── _task.in_progress.json
    └── sessions/
        └── s-20260619-.../
            └── session.json

Task status is encoded in the filename: _task.todo.json, _task.in_progress.json, _task.review.json, _task.done.json.

Demo Data

This repository includes a .handoff/ directory with a realistic sample project ("Nimbus — Realtime Collaboration API") containing 42 tasks across multiple milestones, 6 AI sessions, effort budgets, assignee calendars, and more. Clone the repo, open it in VS Code, and the extension will pick it up automatically.

Issues & Feedback

Found a bug or have a feature request? Please open an issue.

Documentation

For detailed guides on each feature, see the Wiki:

Getting Started · Task Explorer · Task Detail · Dashboard · Gantt Chart · Metrics · Time Tracker · Session Browser · Team Panel · Requirements Explorer · V-model Map · Inspector · Document Viewer · Configuration · FAQ

Links

• handoff-mcp — The MCP server that creates the .handoff/ data this extension visualizes
• VS Code Marketplace

License

Source code is proprietary (All rights reserved). This repository contains documentation, examples, and issue templates.