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.

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.

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. Install it first:

npm install -g handoff-mcp-server

Then register it in Claude Code. Run:

claude mcp add -s user handoff -- handoff-mcp

The -s user flag registers it globally (available in all projects). You can verify with claude mcp get handoff.

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "handoff": {
      "type": "stdio",
      "command": "handoff-mcp",
      "args": []
    }
  }
}

2. Register the skill (optional but recommended)

handoff-mcp provides a skill file that teaches the agent to automatically load/save context. Copy it to your Claude Code user skills directory:

From npm (if you installed globally in step 1):

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

From GitHub:

git clone --depth 1 https://github.com/alphaelements/handoff-mcp.git /tmp/handoff-mcp
cp -r /tmp/handoff-mcp/skills/handoff ~/.claude/skills/

With the skill installed, the agent will automatically call handoff_load_context at session start and handoff_save_context at session end — no manual prompting needed.

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 22 settings plus config.toml reference, see Configuration.

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 · 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.