ccviz 0.1.0

Real-time workflow visualization for Claude Code

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.

---

Install

pip install ccviz

Requires Python ≥ 3.10. No Node.js needed.

---

Quick Start

# 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

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:

ccviz uninstall
rm -rf ~/.ccviz

Nothing is ever sent off-device.

---

Development

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