Metadata-Version: 2.4
Name: ccviz
Version: 0.2.0
Summary: Real-time workflow visualization for Claude Code
Project-URL: Homepage, https://github.com/mshubian/ccviz
Project-URL: Bug Tracker, https://github.com/mshubian/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

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

[![PyPI version](https://img.shields.io/pypi/v/ccviz?color=blue)](https://pypi.org/project/ccviz/)
[![Python](https://img.shields.io/pypi/pyversions/ccviz)](https://pypi.org/project/ccviz/)
[![License](https://img.shields.io/github/license/mshubian/ccviz)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/mshubian/ccviz/ci.yml?label=CI)](https://github.com/mshubian/ccviz/actions)
[![PyPI downloads](https://img.shields.io/pypi/dm/ccviz?color=green)](https://pypi.org/project/ccviz/)

![ccviz screenshot](assets/ccviz.png)

---

## Install

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

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

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

```bash
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](CONTRIBUTING.md).

---

## Development

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

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

---

## License

MIT © [mshubian](https://github.com/mshubian)

---

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