sdd-dashboard 0.1.1

Local dashboard observing SDD workflows in Claude Code

🧠 sdd-dashboard

Make your AI agents visible.

A local web dashboard that brings gentle-ai subagents out of the shadows.

When Claude Code runs an SDD workflow, subagents execute silently in the background — you see nothing except a blinking cursor. sdd-dashboard fixes that. Each subagent gets its own column with real-time output, token counts, and elapsed time.

---

✨ What it looks like

┌──────────────────────────────────────────────────────────────────┐
│  ○ sdd-dashboard                pampa-storm          48.2k tok   │
├──────────────────────────────────────────────────────────────────┤
│  ORCHESTRATOR                                         00:03:41 ● │
│  > Analyzing task scope...                                        │
│  > Delegating sdd-explore to map existing radar integration       │
├──────────┬────────────────┬────────────────┬─────────────────────┤
│ sdd-explore  ✓ 12.1k tok  │ sdd-design ● 8.4k tok │ sdd-apply ○  │
│ 00:01:12     [collapsed]  │ > Reading api.py...   │ waiting...   │
└──────────┴────────────────┴────────────────┴─────────────────────┘

---

📋 Requirements

• Python 3.11+
• Claude Code with gentle-ai installed
• Node.js 18+ (only if building the frontend from source)

---

🚀 Installation

pipx install sdd-dashboard

That's it. The installer automatically adds the required hooks to ~/.claude/settings.json.

💡 No pipx? Install it with pip install pipx && pipx ensurepath.

---

🖥️ Usage

# Start the dashboard (opens browser at http://localhost:3000)
sdd-dashboard

# Custom port
sdd-dashboard --port 4000

# Skip auto-open
sdd-dashboard --no-open

Then open Claude Code and run any gentle-ai SDD workflow normally. The dashboard activates itself when subagents start.

---

⚙️ How it works

Claude Code (terminal)
    │
    │  SubagentStart / SubagentStop hooks (HTTP)
    ▼
FastAPI backend  ──→  watchfiles reads .jsonl transcripts in real-time
    │
    │  WebSocket
    ▼
React frontend (browser)
    ├── OrchestratorPanel  — shows the lead agent's output
    └── SubagentColumns    — one column per active subagent

The dashboard is read-only. It does not modify Claude Code or gentle-ai. It only observes.

---

🛠️ Stack

Layer	Tech
Backend	Python 3.11 + FastAPI + Uvicorn
File watching	watchfiles
Frontend	React 19 + TypeScript + Vite
Styles	Tailwind CSS v4
Icons	Lucide React
Font	Geist Mono

---

🧑‍💻 Development setup

Backend

# Install Python deps
pip install -e ".[dev]"

# Start the server (no browser, hot reload)
uvicorn sdd_dashboard.main:app --reload --port 3000

Frontend

cd frontend
npm install
npm run dev      # starts at http://localhost:5173 with proxy to :3000
npm run build    # outputs to ../sdd_dashboard/static/

Run both

# Terminal 1
uvicorn sdd_dashboard.main:app --reload --port 3000

# Terminal 2
cd frontend && npm run dev

---

📁 Project structure

sdd-dashboard/
├── sdd_dashboard/          # Python backend
│   ├── main.py             # FastAPI app
│   ├── cli.py              # Entry point + hook installer
│   ├── api/
│   │   ├── hooks.py        # POST /api/hook — receives Claude Code events
│   │   └── session.py      # GET /api/session — current state snapshot
│   ├── state/
│   │   └── session.py      # In-memory session model
│   └── watcher/
│       ├── transcript.py   # Real-time .jsonl file tailer
│       └── parser.py       # JSONL → typed events
│
└── frontend/               # React app
    └── src/
        ├── App.tsx
        ├── hooks/useWebSocket.ts
        ├── store/session.ts
        └── components/
            ├── Header.tsx
            ├── OrchestratorPanel.tsx
            ├── SubagentRow.tsx
            ├── SubagentColumn.tsx
            ├── OutputLine.tsx
            └── StatusIcon.tsx

---

🤝 Contributing

Contributions are welcome. Open an issue first to discuss what you'd like to change.

Before submitting a PR:

• Backend: run pytest tests/
• Frontend: run npm run typecheck && npm run build
• Keep PRs focused — one thing at a time

🐛 Known gaps (good first issues)

• Per-agent token tracking (currently stubbed in watcher/transcript.py)
• Session persistence across server restarts
• Stop hook auto-registration in CLI
• OS notification when a session completes
• Pressing Esc to cancel leaves the subagent stuck in working state — it never receives a stop signal
• Subagent output is not streamed in real-time — it appears all at once when the agent finishes

---

🔗 Relation to gentle-ai

This project is a companion tool for gentle-ai. It has no runtime dependency on it — it only depends on Claude Code's hook system and .jsonl transcript format. If gentle-ai updates, the dashboard is unaffected.

---

📄 License

MIT