ccviz 0.2.0

Real-time workflow visualization for Claude Code

ccviz

See inside every Claude Code session — tool calls, thinking, parallel execution, all in one interactive graph.

---

Install

pip install ccviz
ccviz start
# → http://localhost:7842 opens automatically

Requires Python ≥ 3.10. No Node.js needed.

---

What You Get

Feature	Details
Per-turn workflow graph	Each user message gets its own DAG — no more one giant session
Parallel execution	Parallel tool calls render side-by-side in the same column
Thinking & planning nodes	Claude's reasoning steps appear inline between tool calls
Near-real-time updates	New nodes appear within 2–5 seconds as Claude executes
Node detail panel	Click any node to see full input/output with JSON formatting
Filter & search	Filter by tool type or search across all nodes in the current turn
Keyboard navigation	← → to jump between turns

Node Colors

Color	Type	Tools
🔵 Blue	File ops	Read, Edit, Write
🟠 Orange	Shell	Bash
🟢 Green	Search	WebSearch, WebFetch
🟣 Purple	Agent	Agent, sub-agents
🔴 Red	Interaction	AskUserQuestion, TodoWrite, plan mode
🔷 Indigo	Thinking	Extended thinking blocks
🟡 Yellow	Planning	Claude's reasoning text

---

Quick Start

# 1. Install and launch
pip install ccviz
ccviz start

# 2. Use Claude Code as normal in another terminal
claude

# 3. Open http://localhost:7842 — select a session and turn to see the graph

---

How It Works

You type a message
      │
      ▼  UserPromptSubmit hook → new Turn created
Claude thinks & calls tools
      │
      ├──  PreToolUse hook  → node inserted (status: running)
      │    [tool executes]
      └──  PostToolUse hook → node updated  (status: done, duration)
      │
      ▼  Stop hook → session marked ended
~/.ccviz/db.sqlite
      │
      ▼  SSE (2-5s)
http://localhost:7842  (React Flow DAG)

ccviz start injects four hooks into ~/.claude/settings.json (global, all projects). All data stays on your machine — nothing is sent off-device.

---

CLI

ccviz start [--port PORT] [--no-open]   # inject hooks, start server, open browser
ccviz stop                               # stop server (hooks stay active)
ccviz status                             # server · hooks · DB info
ccviz uninstall                          # remove hooks + stop server (data preserved)

Default port: 7842

---

Data

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

To wipe everything:

ccviz uninstall && rm -rf ~/.ccviz

---

Roadmap

• Token usage per turn
• Session search and filter
• Export turn as image / shareable link
• VS Code sidebar integration
• Multi-machine / remote session support

Contributions welcome — see CONTRIBUTING.md.

---

Development

git clone https://github.com/mshubian/ccviz
cd ccviz
pip install -e ".[dev]"
pytest tests/ -v

Frontend (pre-built assets ship with the package, rebuild only if you change UI):

cd frontend
npm install
npm run dev     # :5173, proxies /api → :7842
npm run build   # outputs to ccviz/frontend/

---

License

MIT © mshubian

---

If ccviz is useful to you, a ⭐ on GitHub goes a long way — thank you!