Metadata-Version: 2.4
Name: ccviz
Version: 0.1.0
Summary: Real-time workflow visualization for Claude Code
Project-URL: Homepage, https://github.com/ccviz/ccviz
Project-URL: Bug Tracker, https://github.com/ccviz/ccviz/issues
License: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,developer-tools,visualization,workflow
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: watchfiles>=0.21.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ccviz

Real-time workflow visualization for Claude Code.

See exactly what tools Claude called, in what order, and how long each step took — rendered as an interactive DAG in your browser.

![ccviz screenshot](https://placeholder)

---

## Install

```bash
pip install ccviz
```

Requires Python ≥ 3.10. No Node.js needed.

---

## Quick Start

```bash
# Start the visualizer (injects hooks + opens browser)
ccviz start

# Run Claude Code as usual
claude

# Open http://localhost:7842 to see the workflow
```

That's it. Every tool call Claude makes will appear in the graph within a few seconds.

---

## How It Works

```
Claude Code runs
      │
      ▼
Hooks (PreToolUse / PostToolUse / Stop)
injected into ~/.claude/settings.json
      │
      ▼
~/.ccviz/db.sqlite
      │
      ▼
ccviz server  http://localhost:7842
      │  SSE (2-5s latency)
      ▼
Browser — React Flow DAG
```

`ccviz start` writes three hooks into `~/.claude/settings.json` (global, affects all projects). Claude Code calls these hooks on every tool use, passing a JSON payload via stdin. The hook handler writes to a local SQLite database. The web UI polls via SSE and updates the graph in near-real-time.

---

## UI Overview

```
┌──────────────┬──────────────────┬─────────────────────────────┐
│ Sessions     │ Turns            │ Workflow Graph               │
│              │                  │                              │
│ ● project-a  │ > turn 1  12:01  │  [Read]──►[Bash]──►[Edit]   │
│   project-b  │   turn 2  12:05  │                  │           │
│              │ ● turn 3  live   │               [Agent]        │
│              │                  │              ┌────┤           │
│              │                  │           [Read] [Write]      │
└──────────────┴──────────────────┴──────────────────────────────┘
                                                 ▼ click node
                                          ┌─────────────────┐
                                          │  tool: Bash      │
                                          │  input: {...}    │
                                          │  output: ...     │
                                          │  duration: 120ms │
                                          └─────────────────┘
```

- **Left sidebar** — all sessions, sorted by recency. Active sessions show a live indicator.
- **Middle panel** — turns (one per user message) within the selected session.
- **Right panel** — the workflow DAG for the selected turn.
- **Node colors** — blue = file ops, orange = shell, green = search/web, purple = sub-agent, gray = other.
- **Click any node** — opens a detail panel with full input/output and duration.

---

## CLI Reference

```bash
ccviz start [--port PORT] [--no-open]   # inject hooks, start server, open browser
ccviz stop                               # stop server (hooks remain active)
ccviz status                             # show server + hook + DB status
ccviz uninstall                          # remove hooks, stop server (data preserved)
```

Default port is **7842**.

---

## Data

All data is stored locally in `~/.ccviz/`:

```
~/.ccviz/
├── db.sqlite      # sessions, turns, tool calls
└── server.log     # server stderr
```

To wipe all data:

```bash
ccviz uninstall
rm -rf ~/.ccviz
```

Nothing is ever sent off-device.

---

## Development

```bash
git clone https://github.com/ccviz/ccviz
cd ccviz

# Backend
pip install -e ".[dev]"
pytest tests/ -v

# Frontend (optional — pre-built assets are included)
cd frontend
npm install
npm run dev    # dev server at :5173, proxies /api to :7842
npm run build  # outputs to ccviz/frontend/
```

### Project Structure

```
ccviz/
├── ccviz/
│   ├── db.py        # SQLite schema + queries
│   ├── hooks.py     # hook handler (called by Claude Code)
│   ├── server.py    # FastAPI REST + SSE
│   ├── cli.py       # ccviz start/stop/status/uninstall
│   └── frontend/    # pre-built React app (ships with pip package)
├── frontend/        # React source (development only)
│   └── src/
│       ├── App.tsx
│       ├── components/
│       │   ├── SessionList.tsx
│       │   ├── TurnList.tsx
│       │   ├── WorkflowGraph.tsx   # React Flow
│       │   └── NodeDetail.tsx
│       └── hooks/useSSE.ts
└── tests/
```

---

## License

MIT
