task-dashboard

Task Dashboard reads your task state — OpenSpec changes or Markdown plans — combines it with optional execution and review evidence, and serves a live panel on loopback. The same state is exposed to AI harnesses through one MCP tool, so Claude, Codex, and Antigravity all see exactly what you see.

It refreshes by conditional HTTP polling, not by waking a model. Sending a typical 9.2 KB project state to a model every 20 seconds would be roughly 410K input tokens per hour. This costs zero.

Why it exists

Long agent runs are opaque. You either interrupt the agent to ask where it is, or you tail a log. Task Dashboard gives the run a surface: current task, next action, weighted progress, blockers, and evidence — continuously, in a browser tab, and on demand inside the agent's own chat.

Related MCP server: reins MCP Server

Highlights

• Zero token cost. ETag/304 conditional polling. No code path wakes a model to refresh.

• Zero runtime dependencies. Pure standard library. MCP support is an optional extra.

• Loopback only. Exact 127.0.0.1 origins, proxies bypassed, redirects refused, GET/HEAD only.

• Strictly read-only. Never writes a plan, an OpenSpec change, evidence, or Git state.

• Cross-harness. One MCP server for Claude Code, OpenAI Codex, and Antigravity.

• Honest states. Pending, Active, Review, Blocked, Complete — with review-gated weighted progress.

• 8 layouts x 8 themes, plus a /legacy view.

Quickstart

Python 3.11 or newer.

git clone https://github.com/skarL007/task-dashboard.git
cd task-dashboard
python -m pip install .

Point it at a project and open the URL it prints:

task-dashboard serve --root /path/to/project

TASK_DASHBOARD_URL=http://127.0.0.1:<port>/

That is the whole setup for the browser panel. For a weighted Markdown plan with an evidence index:

task-dashboard serve   --root /path/to/project   --tasks-file /path/to/project/docs/plan.md   --evidence-file /path/to/project/evidence/index.md   --layout mission-control   --theme graphite-industrial

Explore what is available with task-dashboard layouts, task-dashboard themes, and task-dashboard doctor --root /path/to/project.

Connect it to your AI agent

Install the optional MCP extra, then register the server with each harness. The dashboard must already be running; the URL below is the one it printed.

python -m pip install ".[widget]"
task-dashboard mcp doctor --url http://127.0.0.1:55219/ --json   # verify first

claude mcp add -s user task-dashboard --   /path/to/python -m task_dashboard mcp serve --url http://127.0.0.1:55219/

codex mcp add task-dashboard --   /path/to/python -m task_dashboard mcp serve --url http://127.0.0.1:55219/

agy mcp add task-dashboard /path/to/python --   -m task_dashboard mcp serve --url http://127.0.0.1:55219/

Then ask your agent: "show the task dashboard". It calls show_widget and reports live progress.

Task Dashboard also ships its own installer for JSON-based configurations, which preserves unrelated servers, refuses to clobber a differing entry, writes atomically, and keeps a timestamped backup — see Optional MCP widget.

Optionally install the harness skill so the agent knows when to use the dashboard:

task-dashboard install --harness claude      --destination ~/.claude/skills
task-dashboard install --harness codex       --destination ~/.codex/skills
task-dashboard install --harness antigravity --destination ~/.gemini/antigravity/skills

Optional MCP widget

Task Dashboard 0.4.0 keeps the main package dependency-free and ships MCP support only in the explicit widget extra:

python -m pip install ".[widget]"
task-dashboard mcp doctor --url http://127.0.0.1:55219/ --json
task-dashboard mcp serve --url http://127.0.0.1:55219/

mcp serve is a stdio server with three parameterless, read-only tools:

• read_me explains capability negotiation and the Browser fallback without reading task content.

• show_widget returns a bounded live summary and points MCP Apps clients to the io.modelcontextprotocol/ui resource ui://task-dashboard/live-card.html.

• open_live_dashboard returns the health-verified modern and /legacy URLs; the host, not the server, decides whether to open them.

An MCP Apps-capable client can render the compact card inline. A client without the negotiated renderer still receives the same structured snapshot and exact Browser links. The inline card is a verified point-in-time snapshot: it carries the 20-second conditional poll, but a host that renders ui:// resources in an opaque-origin sandbox blocks its cross-origin loopback fetch — the dashboard deliberately sends no CORS headers — so the card then shows "Browser required" and keeps its last verified snapshot. Re-invoke show_widget to refresh it. Continuous 20-second ETag polling is the Browser dashboard's guarantee, not the inline card's. Claude may render inline on an MCP Apps-capable chat surface; Claude Code/Desktop Code must use its Browser pane when that capability is absent. Antigravity uses the same show_widget tool, but inline rendering remains unverified on the installed host, so its truthful acceptance path is the fallback summary plus exact Antigravity Browser URL. Gemini CLI receives text/structured content and the URL; it does not render inline HTML.

Configuration installation always names the destination and should be dry-run first. The installer preserves unrelated JSON, refuses duplicate keys or a conflicting owned entry unless --force is explicit, writes atomically, and reports any backup:

# Claude project/user MCP configuration selected by the operator
task-dashboard mcp install --harness claude `
  --destination E:\my-project\.mcp.json `
  --url http://127.0.0.1:55219/ `
  --python C:\path\to\widget-venv\Scripts\python.exe `
  --dry-run

# Antigravity project configuration selected by the operator
task-dashboard mcp install --harness antigravity `
  --destination E:\my-project\.agents\mcp_config.json `
  --url http://127.0.0.1:55219/ `
  --python C:\path\to\widget-venv\Scripts\python.exe `
  --dry-run

Claude destinations may be an explicit .mcp.json or selected user MCP config. Antigravity destinations may be an explicit .agents/mcp_config.json or ~/.gemini/config/mcp_config.json; the command never guesses a home-directory path.

The widget accepts only an exact loopback http://127.0.0.1:<port>/ identity, or http://[::1]:<port>/ when the dashboard is serving IPv6 loopback. It exposes no write operation, credentials, environment values, local filesystem paths, remote assets, analytics, or telemetry, and bounds all returned task data. The initial Apps resource publishes no connect origin, connect-domain CSP or dashboard URL; after show_widget verifies health, its generated polling code and _meta.ui.csp target only that exact origin and reject redirects, and a later failed or mismatched show_widget or open_live_dashboard revokes both again. Only show_widget grants that capability. The CSP names the origin form the dashboard is serving; a bracketed IPv6 literal is not a portable CSP host-source, so an IPv6 loopback card may fall back to "Browser required" even on an Apps host. Loopback requests never traverse an http_proxy. Because the 2026-07-28 MCP envelope carries no server-side session, that verified card state is scoped to one mcp serve process: run one server process per host rather than sharing a single instance. Local 20-second ETag polling uses zero model tokens and never wakes a model; a user-requested MCP tool call may consume the active agent turn. Blocking decisions still belong exclusively to each harness's native question tool.

Publishing a package never changes an owned runtime. Every cutover must stage the reviewed candidate with autostart install --no-start, stop only the strongly owned prior process, verify modern and /legacy health plus 200-to-304 polling, and use the preserved rollback path on any failed gate. The actual from/to versions belong in Task 7 evidence rather than this evergreen release guide.

Persistent Windows runtime

Version 0.4.0 can install a self-contained snapshot under .task-dashboard/runtime and register Task Dashboard for the current user's logon. The scheduled task uses interactive logon with LIMITED run level: no SYSTEM, stored password, elevation, external download, or Startup-folder fallback. Ownership requires a durable UUID marker plus exact task path, current principal, logon type, run level, single action, single logon trigger, working directory, and settings.

Installation is transactional. It performs collision, ownership, current-status, and port checks before writing; builds in a versioned sibling staging directory; validates modern UI, legacy UI, polling 200 → 304, delta, observability, metrics, health, digest, and logs; then swaps the runtime. Compatible healthy installs return unchanged. A failed registration or start restores the previous snapshot and registration and preserves the failed candidate for audit.

Use dry-run first. When replacing an already running source server, install with --no-start, validate the snapshot, stop only the owned old process, and then start the registered runtime:

task-dashboard autostart install `
  --runtime-dir E:\task-dashboard\.task-dashboard\runtime `
  --root C:\path\to\project `
  --tasks-file C:\path\to\project\docs\plans\roadmap.md `
  --evidence-file C:\path\to\project\evidence\index.md `
  --port 55219 `
  --refresh-seconds 20 `
  --layout mission-control `
  --theme graphite-industrial `
  --task-name "Task Dashboard" `
  --no-start

# Confirm the exact old dashboard PID/session, stop only that owned process,
# and require port 55219 to be free before this command:
task-dashboard autostart start --runtime-dir E:\task-dashboard\.task-dashboard\runtime
task-dashboard autostart status --runtime-dir E:\task-dashboard\.task-dashboard\runtime --json

Lifecycle and rollback commands:

task-dashboard autostart stop --runtime-dir E:\task-dashboard\.task-dashboard\runtime
task-dashboard autostart remove --runtime-dir E:\task-dashboard\.task-dashboard\runtime

autostart remove stops the exact owned task, independently verifies its receipt PID and per-process instance UUID have exited, then unregisters the queried task object. A missing task with a still-live, strongly verified receipt is classified as orphaned and stopped before removal completes; a live PID without fresh matching health is degraded and is never killed automatically. Manifest/receipt schema 2, validation evidence, prior backup, failed candidate, and logs/task-dashboard.log remain available for audit. A same-name task with another ownership marker, principal, trigger, action, or setting is reported as a foreign collision and is never replaced or deleted. If current-user Task Scheduler registration is denied by Windows policy, installation fails closed and the existing server remains untouched. Every successful install receipt prints the exact quoted rollback command.

Animated isolated demo

Run a five-stage temporary scenario without changing the monitored project:

task-dashboard demo --port 0 --step-seconds 5

The command prints TASK_DASHBOARD_DEMO_URL=..., polls every two seconds, and progresses through Pending, Active, Review, Blocked, and Complete. It writes only to its temporary directory, visibly marks modern and legacy pages as DEMO, and removes that directory when the demo exits normally.

Layouts

Visual themes

Layout and theme selectors are independent, yielding 64 combinations. Use --layout/--theme, TASK_DASHBOARD_LAYOUT/TASK_DASHBOARD_THEME, TOML, or ?layout=<id>&theme=<id>. Browser choices persist per monitored source.

The modern application deliberately remains eight modern layouts, eight visual themes, and 64 combinations. The original OpenSpec panel is preserved separately at /legacy, with its compact cards, Todos/Feito/Pendente filters, search, countdown rail, and 20-second conditional polling. Both views read the same canonical state; links in their headers switch views without changing the selected modern layout or theme.

Legacy --template remains supported. terminal-matrix maps to operations-grid + matrix; other legacy template ids map to the same layout + graphite-industrial.

Configuration

Create task-dashboard.toml in the launch directory:

[dashboard]
root = "."
tasks_file = "docs/plan.md"
evidence_file = "autobuild/index.md"
host = "127.0.0.1"
port = 0
refresh_seconds = 20
layout = "mission-control"
theme = "graphite-industrial"
activity_limit = 30

Precedence is CLI, TASK_DASHBOARD_* environment variables, TOML, then safe defaults. Non-loopback hosts are rejected.

Harness adapters

Installation always requires an explicit destination. Use --dry-run first:

# Generic / shared agents
task-dashboard install --harness agents --destination C:\path\to\.agents\skills --dry-run

# Codex / OpenAI
task-dashboard install --harness codex --destination C:\path\to\.codex\skills

# Claude Code
task-dashboard install --harness claude --destination C:\path\to\.claude\skills

# Google Antigravity / Gemini
task-dashboard install --harness antigravity --destination C:\path\to\.gemini\skills

Adapters require the same startup receipt, doctor result, health JSON, conditional polling proof, visible URL verification, organic update evidence, and owned-process cleanup boundary.

Native decisions and runtime controls

Inspect the exact native decision capability before presenting a blocking choice:

task-dashboard interactions
task-dashboard interactions --harness codex --json

Codex uses request_user_input in its Browser pane beside the task chat. Claude Code uses AskUserQuestion in the Claude Desktop Preview pane (or a verified localhost link in other hosts). Google Antigravity uses ask_question in its Browser surface. Generic adapters report no native clickable question capability; they pause rather than replacing a decision with numbered prose.

Every portable decision has two or three clickable options, exactly one recommended option appears first, and that option's label carries (Recommended) (or (Recomendado) in Portuguese UI copy) with a trade-off description. A missing native tool or required interactive/plan mode blocks the decision; it does not fall back to plain text.

Portable bundles use unique snake_case question IDs. Validate and render the bundle immediately before the native call:

task-dashboard decision render --harness codex --input .\decision-bundle.json

The command validates the full bundle and prints only the exact native payload JSON: Codex receives id, header, question, and option label/description; Claude receives header, question, options, and multiSelect: false; Antigravity receives question, options, and is_multi_select: false. It does not call a native tool or write the input, source, or dashboard. --harness agents fails closed because the generic adapter has no native question control. Adapters pass successful output unchanged to their assigned tool.

Workflow ownership remains explicit: Traycer frames the uncertainty and recommendation; OpenSpec records settled behavior and executable tasks; Superpowers supplies isolated execution, TDD, and verification; same-SHA independent code review supplies integration evidence. Task Dashboard only reads those artifacts. A dashboard click never writes an answer, and local polling does not wake a model, scheduled prompt, or background agent.

For an already installed owned runtime, the concise lifecycle aliases preserve the ownership and collision protections of autostart:

task-dashboard on --runtime-dir E:\task-dashboard\.task-dashboard\runtime
task-dashboard status --runtime-dir E:\task-dashboard\.task-dashboard\runtime --json
task-dashboard show --runtime-dir E:\task-dashboard\.task-dashboard\runtime --json
task-dashboard off --runtime-dir E:\task-dashboard\.task-dashboard\runtime

on and off only start or stop the owned runtime and accept --quiet for silent successful output. status reports the ownership-aware receipt, and show returns a URL only while that owned runtime is healthy. None of these aliases install, delete, force-replace, or bind beyond loopback.

Polling, token cost, and observability

The browser polls local GET /api/poll every 20 seconds. The first response returns state plus an ETag; unchanged requests send If-None-Match and receive 304 Not Modified with no state body. Markdown parsing and UI replacement occur only after the source revision changes.

This local transport makes zero model tokens and zero LLM calls. The measured the monitored project state is about 9.2 KB. Sending that full state to a model every 20 seconds would mean 180 calls/hour and, using a rough four-characters-per-token estimate, approximately 410K input tokens/hour before prompt, history, tools, reasoning, and output. This is an engineering estimate, not an API invoice.

Use /api/observability for JSON counters and /metrics for Prometheus text. Both expose polls, 304 responses, changes, errors, state builds, bytes, timestamps, revision, compact-delta generation, and explicit zero LLM call/token counters.

/api/delta exposes only the latest bounded local change: progress before/after, group status changes, added/removed tasks, and attention changes. The modern page loads it only after a changed poll and enables an explicit Copiar delta button. Copying writes JSON to the local clipboard; it does not invoke or transmit data to a model. A harness may summarize that compact delta only when the user explicitly asks.

Recommended cost order:

1. Local ETag polling for synchronization — zero model usage.

2. On-demand model summaries of compact change deltas.

3. For optional automated summaries, use a small model with a cooldown; never invoke an agent every 20 seconds merely to check for file changes.

OpenAI notes that model choice, context, reasoning, tools, retrieval, and caching all affect usage, so prompt length alone is not a reliable bill estimate. Current rates and limits: https://learn.chatgpt.com/docs/pricing.

HTTP surface

• / — dashboard application.

• /api/state — canonical JSON state.

• /api/poll — conditional state with ETag/304.

• /api/delta — latest compact deterministic change, generated locally.

• /api/observability — local polling and zero-token counters.

• /metrics — Prometheus text exposition.

• /api/layouts — eight structural layouts.

• /api/themes — eight visual themes.

• /api/templates — legacy compatibility mappings.

• /events — compatibility SSE stream; not the default browser sync.

• /legacy — original self-contained OpenSpec dashboard view.

• /health — source readability, layout, theme, and legacy template.

Only GET and HEAD are supported. The server sends no-store, nosniff, and no-referrer headers and never exposes a write route.

Development

$env:PYTHONPATH = 'src'
python -m unittest discover -s tests -v
python -m compileall -q src tests
python -m pip wheel . --no-deps -w dist
# Offline build when uv already has the backend cached:
uv build --wheel --offline

See docs/specs/2026-08-31-task-dashboard-multiharness-design.md for the complete architecture and safety contract.

Project status and roadmap

0.4.0 is the first public release. It is used daily by its author on Windows, and CI covers Ubuntu and Windows across Python 3.11–3.13.

Known limitations, stated plainly:

• Not on PyPI yet. Installation is from source today. Publishing is the next step, which will make it pipx install "task-dashboard[widget]".

• The inline MCP card is a point-in-time snapshot. Hosts that render ui:// resources in an opaque-origin sandbox block its loopback request by design, so the card falls back to "Browser required". Continuous 20-second polling is the browser dashboard's guarantee.

• The persistent runtime is Windows-only. The dashboard, the MCP server, and every other surface are cross-platform; only autostart depends on Windows Task Scheduler.

• mcp install writes JSON configurations. For OpenAI Codex, whose config is TOML, use codex mcp add as shown above.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md first — it explains the three properties that must not break (no runtime dependencies, loopback only, zero model tokens) and how changes are expected to arrive.

• Bugs and features: open an issue

• Security: see SECURITY.md — please do not open a public issue

• Conduct: CODE_OF_CONDUCT.md

• History: CHANGELOG.md

Licence

MIT © Marcelo Machuca