ccdash

name	ccdash
description	Answer CCDash project-intelligence questions using the shipped MCP tools when available and the in-repo `ccdash` CLI otherwise. Use when the operator or another agent asks about project status, feature forensics, workflow failure patterns, after-action reports, session intelligence (transcripts, search, detail), runtime validation posture, CLI timeout or caching behavior, container project onboarding, watcher binding, or how to troubleshoot the shipped CCDash API/worker/MCP surfaces. Keep routing aligned with the current shipped runtime contract and repo docs.
version	2.2
app_version	2026-06-11
updated	"2026-06-11T00:00:00.000Z"

ccdash Skill

Route CCDash questions to the shipped agent-facing surfaces that exist in this repo today:

• MCP stdio server via .mcp.json
• In-repo ccdash CLI (status, feature, workflow, report)
• Standalone CLI (ccdash-cli package, HTTP transport to remote server)
• Runtime-validation docs for API health and worker probes

The business logic is transport-neutral. CLI and MCP are adapters over backend/application/services/agent_queries/.

When To Use

Trigger on intents such as:

• "What's the state of this project?" / "project status" / "project summary"
• "Why did FEAT-X take so long?" / "retrospective on FEAT-X" / "AAR for FEAT-X"
• "Which workflows are failing?" / "failure burden" / "workflow diagnostics"
• "Show me the feature forensics for FEAT-X" / "list features matching X"
• "Is the hosted runtime healthy?" / "how do I validate API vs worker?" / "which probe should I hit?"
• "Is the MCP server shipped here?" / "should I use MCP or CLI for this?"
• "Why is my CLI timing out?" / "results look stale"
• "Prepare this project for the container stack" / "generate watcher env" / "bind worker-watch to a project"

When NOT To Use

• General coding tasks unrelated to CCDash observability or runtime posture.
• Inventing runtime behaviors that contradict the split API/worker contract.

Confidence Anchor

Repo-verified current surfaces:

In-repo CLI groups (backend/.venv/bin/ccdash):

• ccdash status project
• ccdash feature report <feature_id>
• ccdash feature list [--q TEXT] [--status STATUS]
• ccdash workflow failures
• ccdash report aar --feature <feature_id>
• ccdash session search <query> [--project PROJECT] [--feature FEATURE] [--limit N]
• ccdash session get <session_id> --project <project_id> [--include SEG]... [--cursor CUR] [--limit N]
• ccdash session transcript <session_id> --project <project_id> [--cursor CUR] [--limit N]

Global flags (all commands): --timeout N, --no-cache, --json, --md

MCP tools: ccdash_project_status, ccdash_feature_forensics, ccdash_workflow_failure_patterns, ccdash_generate_aar, ccdash_session_search, ccdash_session_detail, ccdash_session_transcript

Runtime entrypoints: hosted API via backend.runtime.bootstrap_api:app; worker via python -m backend.worker

Session Intelligence (Phase 3 — Transport-Neutral)

The session surfaces (MCP, repo-CLI, standalone-CLI, REST) are all backed by the same transport-neutral Phase 1 service at backend/application/services/agent_queries/session_detail.py.

MCP tools

Tool	Parameters	Notes
ccdash_session_search	project_id (required), query (required, min 2 chars), feature_id, limit (max 100), offset	Full-text / semantic search across session transcripts
ccdash_session_detail	project_id (required), session_id (required), include[], cursor, limit (max 200)	Full detail bundle with transcript, tokens, subagents, artifacts, links
ccdash_session_transcript	project_id (required), session_id (required), cursor, limit (max 200)	Cursor-paginated transcript page only

project_id is required for all three tools. Missing project_id → structured status: "error" response. Unknown session_id → status: "not_found". Empty optional segments → empty list (not an error).

MCP Payload Budget (T3-004)

Constant	Value	Purpose
MCP_TRANSCRIPT_DEFAULT_LIMIT	50 items	Default page size for MCP tool calls
MCP_TRANSCRIPT_MAX_LIMIT	200 items	Per-call hard ceiling (below service max of 1 000)
MCP_ENVELOPE_MAX_BYTES	1 048 576 (1 MiB)	Hard byte ceiling for MCP stdio envelopes

When the serialised response exceeds MCP_ENVELOPE_MAX_BYTES, transcript items are trimmed from the tail and the response metadata carries:

• meta.truncated: true
• meta.truncated_reason with cursor guidance
• meta.payload_bytes with the final byte count

Use data.transcript.nextCursor to retrieve the next page of a truncated transcript.

Repo-CLI session commands

# Search sessions (defaults to active project if --project omitted)
ccdash session search "authentication flow" --json
ccdash session search "timeout" --project proj-abc --feature FEAT-123 --limit 10

# Full detail (--project required, no active-project fallback)
ccdash session get sess-abc123 --project proj-abc --json
ccdash session get sess-abc123 --project proj-abc --include transcript --include tokens

# Paginated transcript
ccdash session transcript sess-abc123 --project proj-abc --limit 50 --json
# Use nextCursor from previous output:
ccdash session transcript sess-abc123 --project proj-abc --cursor <opaque> --json

Standalone CLI (ccdash-cli, HTTP transport)

# Transcript-bearing detail (Phase 2 REST endpoint, --project required)
ccdash session get sess-abc123 --project proj-abc --json
ccdash session get sess-abc123 --project proj-abc --include transcript --include tokens

# Existing commands (unchanged)
ccdash session list --feature FEAT-123
ccdash session search "authentication"
ccdash session show sess-abc123   # legacy endpoint, no transcript

Redaction note

All transcript payloads are redacted by the Phase 1 service before egress. Every transport (MCP, CLI, REST) inherits the same secret-scrubbing guarantee automatically. Layer 1 (pattern scan: API keys, AWS/GCP creds, bearer tokens) and Layer 2 (tool-name-aware field scan) are both applied. redactedFieldCount in the response indicates how many fields were redacted.

project_id usage note

The project_id parameter is the owning project of the session, not the currently active project. This enables cross-project session forensics without switching the active project. All three transports enforce this invariant — there is no silent active-project fallback.

Routing Posture

Use the following transport order:

1. Prefer MCP for in-workspace agent reasoning when the repo .mcp.json is present and the question maps cleanly to one of the four shipped tools. This avoids shelling out and matches the current Claude Code posture.
2. Use the in-repo CLI as the fallback adapter when MCP is unavailable, when you need explicit output modes, or when validating parity against the command surface.
3. Use the standalone CLI when the user is operating against a remote CCDash server rather than local data. See Standalone CLI vs In-Repo CLI below.
4. Use runtime docs and HTTP probes for deployment/runtime troubleshooting. Do not invent CLI transport-management commands that are not shipped.

Current shipped posture: MCP is discoverable, but not the only path. CLI remains valid. Runtime validation is a separate concern handled through the API/worker contract.

Standalone CLI vs In-Repo CLI

Dimension	In-Repo CLI	Standalone CLI
Install	backend/.venv/bin/ccdash	pipx install ccdash-cli → ccdash
Transport	Local data / lightweight bootstrap	HTTP to remote CCDash server (/api/v1/)
Auth	None	Bearer token via OS keyring or CCDASH_TOKEN
Config	None	~/.config/ccdash/config.toml (named targets)
Command groups	status, feature, workflow, report	All in-repo groups + session, target, doctor, diagnostics, version
Use when	Querying local project data	Operating against hosted/remote server

Do not suggest target, doctor, target login, or session commands to a user running only the in-repo CLI.

Query Caching

All four query services (project-status, feature-forensics, workflow-diagnostics, aar-report) use an in-process TTL cache:

Config	Default	Effect
CCDASH_QUERY_CACHE_TTL_SECONDS	60	Cache lifetime; set to 0 to disable
CCDASH_QUERY_CACHE_REFRESH_INTERVAL_SECONDS	300	Background warming interval; 0 disables
--no-cache CLI flag	off	Force cache miss for one invocation
bypass_cache=true query param	off	Force cache miss via HTTP

Guidance: Use --no-cache when debugging stale data. Do not disable the cache in production — background warming reduces cold-path latency. OpenTelemetry counters are emitted per cache event.

CLI Timeout

The standalone CLI exposes a global timeout on every command:

Config	Default	Notes
--timeout N flag	30s	Precedence: flag > env > default
CCDASH_TIMEOUT env var	30s	Applied when flag is absent

Commands that can be slow on large projects: status project, report aar, workflow failures. Consider --timeout 60 or higher when these time out. See /Users/miethe/dev/homelab/development/CCDash/docs/guides/cli-timeout-debugging.md for diagnosis patterns.

Routing Table

Intent	Preferred MCP Tool	CLI Fallback	Notes
Project status	ccdash_project_status	ccdash status project	Use MCP first for agent reasoning; CLI --json/--md modes useful
Feature forensics	ccdash_feature_forensics	ccdash feature report FEATURE_ID	Top-level name, status, telemetry_available, sessions_note fields available
Feature listing	ccdash_feature_forensics (list mode)	ccdash feature list [--q TEXT]	Paginated; max 200 results; truncated/total in response
Workflow failures	ccdash_workflow_failure_patterns	ccdash workflow failures	Same query service behind both surfaces
AAR / retrospective	ccdash_generate_aar	ccdash report aar --feature FEATURE_ID	Render markdown/human output as requested
Session transcript search	ccdash_session_search	ccdash session search <query> --project P	project_id required for MCP; optional (active-project fallback) for CLI
Session full detail	ccdash_session_detail	ccdash session get ID --project P	project_id required; transcript cursor-paginated; redaction auto-applied
Session transcript page	ccdash_session_transcript	ccdash session transcript ID --project P	Cursor pagination; use nextCursor for subsequent pages
Runtime validation	none	none	Route to /api/health, worker probes, and runbook docs
MCP setup/troubleshooting	shipped stdio server	CLI parity checks only	Follow docs/guides/mcp-setup-guide.md and docs/guides/mcp-troubleshooting.md

Runtime Contract

Hosted validation assumes a split runtime:

• API runtime serves HTTP and canonical reads.
• Worker runtime owns sync, refresh, and scheduled jobs.
• local is a convenience runtime and is not the hosted validation posture.
• test is for lightweight CLI/MCP bootstrap and automated coverage.

Canonical hosted entrypoints:

backend/.venv/bin/python -m uvicorn backend.runtime.bootstrap_api:app --host 0.0.0.0 --port 8000
backend/.venv/bin/python -m backend.worker

Local helpers like npm run dev:backend and npm run start:worker are wrappers around the same contract; the bootstrap modules are the canonical reference.

Containerized deployment: Docker/Podman compose profiles (local, enterprise, postgres, live-watch) are supported. Rootless Podman is supported. Single-command deployment via docker compose or podman-compose. Reference: /Users/miethe/dev/homelab/development/CCDash/docs/guides/containerized-deployment-quickstart.md.

Project onboarding and watcher binding: container roles resolve projects from mounted projects.json. Use /Users/miethe/dev/homelab/development/CCDash/backend/scripts/container_project_onboarding.py to prepare the registry entry and optional per-watcher env overlay. In v1, worker-watch binds one project at startup via CCDASH_WORKER_WATCH_PROJECT_ID; UI project switching, standalone CLI --project, and target defaults do not rebind a running watcher.

Probe Semantics

• GET /api/health — primary API/runtime contract check.
• Worker probe: CCDASH_WORKER_PROBE_HOST:CCDASH_WORKER_PROBE_PORT (default 127.0.0.1:9465).
  • /livez — basic process liveness
  • /readyz — readiness after worker binding contract is satisfied
  • /detailz — backlog/freshness detail and worker posture

A healthy API does not prove worker ownership is functioning; a ready worker does not replace the API health contract.

Lightweight Bootstrap Invariant

CLI and MCP use lightweight test-profile bootstrap paths. They do not stand up the full hosted runtime and do not own background jobs.

• CLI bootstrap: backend/cli/runtime.py
• MCP bootstrap: backend/mcp/bootstrap.py
• MCP transport: stdio via .mcp.json

Do not claim that CLI or MCP validates the hosted deployment by themselves.

Output Guidance

• For agent reasoning: prefer structured MCP responses or CLI --json.
• For user-facing narrative deliverables: use CLI --md where available, especially report aar.
• For runtime validation: summarize relevant health/probe fields rather than dumping the entire payload unless the user asks for raw output.

Multi-Step Flows (Recipes)

• recipes/feature-retrospective.md — feature forensics + AAR with MCP-first/CLI-fallback posture.
• recipes/task-attribution.md — infer work ownership from feature forensics and evidence rather than stale task/session commands.
• recipes/unreachable-server.md — troubleshoot the API/worker/MCP runtime contract and probe semantics.
• recipes/container-project-onboarding.md — prepare projects.json, generate watcher env overlays, and validate container project visibility without implying remote watcher orchestration.

Prefer a recipe whenever the user's question spans transport choice plus interpretation.

Do Not Say

• "MCP is deferred until a later phase."
• "Use ccdash doctor / ccdash target show / ccdash target login." (standalone CLI only — not available in the in-repo CLI)
• "Hosted validation should run against backend.main:app or npm run dev."
• "CLI or MCP starts the full runtime or proves worker ownership on its own."
• "The CLI has no timeout configuration." (it does: --timeout flag and CCDASH_TIMEOUT env var)
• "Session transcript search is only available in the standalone CLI." (Phase 3: in-repo CLI also has ccdash session search/get/transcript)
• "There is no active-project fallback for session get/transcript." (correct — by design; --project is required)
• "project_id is optional for session tools." (it is required for both MCP tools and CLI get/transcript)
• "Query results are always fresh." (they are cached; use --no-cache to bypass)
• "Changing the active project or CLI target rebinds a running worker-watch container."
• "The CCDash API/CLI/skill can remotely scale, start, or rebind watcher containers in the compose examples."

Key References

• /Users/miethe/dev/homelab/development/CCDash/docs/guides/enterprise-session-intelligence-runbook.md
• /Users/miethe/dev/homelab/development/CCDash/docs/setup-user-guide.md
• /Users/miethe/dev/homelab/development/CCDash/docs/guides/mcp-setup-guide.md
• /Users/miethe/dev/homelab/development/CCDash/docs/guides/mcp-troubleshooting.md
• /Users/miethe/dev/homelab/development/CCDash/docs/guides/cli-timeout-debugging.md
• /Users/miethe/dev/homelab/development/CCDash/docs/guides/query-cache-tuning-guide.md
• /Users/miethe/dev/homelab/development/CCDash/docs/guides/standalone-cli-guide.md
• /Users/miethe/dev/homelab/development/CCDash/docs/guides/containerized-deployment-quickstart.md
• /Users/miethe/dev/homelab/development/CCDash/docs/project_plans/design-specs/container-project-onboarding-and-watchers-v1.md
• /Users/miethe/dev/homelab/development/CCDash/deploy/runtime/README.md
• /Users/miethe/dev/homelab/development/CCDash/backend/scripts/container_project_onboarding.py
• /Users/miethe/dev/homelab/development/CCDash/backend/cli/main.py
• /Users/miethe/dev/homelab/development/CCDash/backend/mcp/server.py
• /Users/miethe/dev/homelab/development/CCDash/packages/ccdash_cli/