Metadata-Version: 2.4
Name: sdd-dashboard
Version: 0.1.1
Summary: Local dashboard observing SDD workflows in Claude Code
Project-URL: Homepage, https://github.com/TinMon11/sdd-dashboard
Project-URL: Repository, https://github.com/TinMon11/sdd-dashboard
License: MIT
License-File: LICENSE
Keywords: agents,ai,claude,dashboard,sdd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: watchfiles>=0.21
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🧠 sdd-dashboard

> ***Make your AI agents visible.***

A local web dashboard that brings [gentle-ai](https://github.com/Gentleman-Programming/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 screenshot](frontend/src/assets/Dashboard.png)

```
┌──────────────────────────────────────────────────────────────────┐
│  ○ 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](https://claude.ai/code) with [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai) installed
- **Node.js** 18+ *(only if building the frontend from source)*

---

## 🚀 Installation

```bash
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

```bash
# 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

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

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

### Frontend

```bash
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

```bash
# 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](https://github.com/Gentleman-Programming/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
