cc-dash

🌐 PUBLIC repository — hosted publicly on GitHub. Scrub PII and secrets before every commit.

A local dashboard and Model Context Protocol server for managing a multi-project portfolio whose entire state lives in markdown files.

Projects declare their state in ROADMAP.md, SESSION_PROGRESS.md, and QA.md files using a small schema. cc-dash reads those files, renders them as boards, timelines, and queues, and writes changes back to the same markdown. There is no database. The dashboard is a lens over your files, not a copy of them.

The MCP server exposes the same operations to Claude Code, so an agent can read a roadmap, advance a session, or work a QA queue without anyone opening the UI.

The MCP server

src/mcp/server.ts is a standard MCP server over stdio, with 25 zod-typed tools.

claude mcp add --scope user cc-dash -- npx tsx /path/to/cc-dash/src/mcp/server.ts

Tools are grouped by what they act on:

Every tool validates its input with zod and returns structured content. A tool that cannot do what was asked raises instead of returning a plausible-looking empty result, so an agent cannot silently proceed on bad state.

Related MCP server: Memory Bank MCP Server

Why markdown as the database

Three properties fall out of that constraint, and they are the reason it is worth its cost:

• The files stay useful without the app. A ROADMAP.md is readable in any editor, diffable in any review, greppable from any shell.

• Git is the audit log. Every state change is a commit: attributable, revertible, and with no separate migration story.

• Agents already understand it. A coding agent can read and edit the source of truth directly, with or without the MCP server.

The cost is that parsing and serialization have to be exact. Round-trip fidelity is enforced by tests: parse a file, serialize it, and the bytes must match.

Features

• Project discovery across configured scan directories

• Roadmap board with kanban and list views, drag and drop, and bulk status edits

• Session tracking for tasks, decisions, and failed attempts across work sessions

• QA queues, portfolio-wide and per-project, with a keyboard-driven focus mode

• Today's Directions, a generated daily plan with dispatch commands per project

• Agent activity feed that attributes commits to the AI agents that co-authored them

• Ideas system with a guided capture wizard

• Milestone timeline built from roadmap and session events

Setup

Requires Node.js 22 or newer.

npm install
npm run dev     # http://localhost:3737
npm run mcp     # run the MCP server over stdio

Create ~/.config/cc-dash/config.json:

{
  "scan_dirs": ["~/projects"],
  "exclude_dirs": ["node_modules", ".git", "vendor"],
  "explicit_projects": [],
  "scan_depth": 2,
  "port": 3737,
  "orchestrator_dir": "~/projects"
}

orchestrator_dir is the portfolio-level directory your orchestrator agent runs from, and where TODAYS_DIRECTIONS.md is written. Every machine-specific path lives in this file, outside the repository, so nothing personal is ever committed.

A project is discovered when it contains a schema file:

---
schema: cc-dash/roadmap@1
project: my-project
description: One-line description
last_updated: 2026-01-01T00:00:00Z
---

Roadmap items carry stable IDs in HTML comments, so an item can be reworded without losing its identity:

- <!-- id:r_a1b2c status:planned --> **Item name** - What it does

Commands

1,666 tests across 148 files.

Constraints

These are enforced, not aspirational:

• No database. Markdown files are the only state.

• Round-trip fidelity. Parse then serialize must reproduce the file byte for byte.

• Atomic writes. Every mutation writes to a .tmp file, then renames.

• Item IDs are permanent. Once assigned, an ID never changes.

Stack

Next.js 15, React 19, TypeScript, Tailwind CSS 4, zod, @modelcontextprotocol/sdk, Vitest, Playwright.

License

MIT. See LICENSE.