dashboard

Multi-Project Dashboard

Overview

Unified view across all PopKit-enabled projects, showing health scores, activity status, and enabling quick context switching.

Core principle: Quick status overview with actionable intelligence for multi-project developers.

Trigger: /popkit:dashboard command

When to Use

Invoke when:

• Managing multiple projects
• Need quick overview of all project statuses
• Switching context between projects
• Registering new projects
• Checking for projects needing attention

Do NOT use when working in single project - use /popkit:routine morning or /popkit:next instead.

Registry

Projects stored globally at ~/.claude/popkit/projects.json

See examples/registry-operations.md for all operations.

Key operations:

• Load/list projects
• Add/remove projects
• Switch projects
• Auto-discover projects
• Tag management
• Refresh issue counts

Dashboard Display

+============================================================+
|                   PopKit Dashboard                          |
+============================================================+

  Total: 5  |  Healthy: 3  |  Warning: 1  |  Critical: 1

  ----------------------------------------------------------
  | Project          | Health | Issues | Last Active   |
  ----------------------------------------------------------
  | popkit           | + 92   |   5    | 2 min ago     |
  | popkit-cloud     | ~ 78   |   3    | 1 hour ago    |
  | reseller-central | + 88   |  12    | 3 days ago    |
  | my-website       | ! 45   |   0    | 2 weeks ago   |
  ----------------------------------------------------------

  Commands: add <path> | remove <name> | refresh | switch <name>

Health Scoring

See examples/health-scoring.md for complete scoring details.

Score components (100 points total):

• Git Status (20): Clean working tree, commits, push status
• Build Status (20): Passing builds, warnings, failures
• Test Coverage (20): Coverage percentage
• Issue Health (20): Stale issue count
• Activity (20): Last activity timestamp

Quick vs Full checks:

• Quick (~0.5s): Git + activity only (dashboard default)
• Full (~2-3s): All components including tests

Subcommands

See examples/subcommands.md for all commands and examples.

Available commands:

• /popkit:dashboard - Show dashboard (default)
• /popkit:dashboard add <path> - Register project
• /popkit:dashboard remove <name> - Unregister project
• /popkit:dashboard refresh [name] - Update health scores
• /popkit:dashboard switch <name> - Change project context

Features

Auto-Discovery

Automatically find projects in common dev directories.

Project Tags

Filter and organize projects by tags (active, client-work, etc.).

Activity Feed

Show recent activity across all projects.

Unhealthy Alerts

Identify projects needing attention (health < 70).

Issue Count Cache

• Cached for 15 minutes (no network calls on dashboard load)
• Manual refresh available
• Graceful fallback if gh CLI unavailable

See examples/registry-operations.md for implementation details.

Integration

Related commands:

• /popkit:routine morning - Single-project health check
• /popkit:next - Context-aware recommendations

Implementation files:

• hooks/utils/project_registry.py - Registry CRUD operations
• hooks/utils/health_calculator.py - Health score calculation

Error Handling

Situation	Response
No projects registered	Suggest /popkit:dashboard add .
Project path not found	Remove from registry with warning
Health check fails	Show "--" for health, log error
gh CLI unavailable	Skip issue counts

Examples

See examples/ directory for:

• Complete health scoring details
• All registry operations with code
• Subcommand reference and usage
• Configuration examples

---

Version: 1.0.0 Category: Project Management Tier: Core