Claude Viz

Real-time visualization for Claude Code - view plans, track tasks, and monitor progress.

Quick Start

npx claude-viz

Features

Plans View

• Live Preview: Markdown rendering with syntax highlighting
• Split Editor: Side-by-side editor and preview
• Real-time Updates: Changes sync via Server-Sent Events
• Create Plans: Create new plan files from the UI
• Export Plans: Export plans to your project directory

Tasks View

• Kanban Board: Track tasks across Pending, In Progress, and Completed columns
• Session Tabs: Switch between multiple Claude Code sessions
• Real-time Updates: Tasks update instantly as Claude works
• Task Dependencies: See blocked tasks and what they're waiting on

General

• Keyboard Shortcuts: Ctrl/Cmd+S to save
• Conflict Detection: Warning when files change externally
• Dark/Light Mode: Toggle between themes

Installation

No Installation Required (npx)

npx claude-viz

Global Installation (Optional)

npm install -g claude-viz
claude-viz

Usage

Switching Views

Use the Plans / Tasks toggle in the header to switch between views.

Plans View

Toggle between view modes using the toolbar buttons:

• Preview: Read-only markdown preview (default)
• Split: Editor on left, live preview on right

Creating Plans

1. Click + New in the plan dropdown
2. Enter a filename (.md extension added automatically)
3. Click Create

Exporting Plans

Export plans to your project directory using the Export button.

Editing Plans

1. Select a plan from the dropdown
2. Switch to Split view
3. Type in the editor - preview updates live
4. Press Ctrl+S (or Cmd+S on Mac) to save

Tasks View

The Kanban board shows tasks organized by status:

• Pending: Tasks waiting to be started
• In Progress: Tasks currently being worked on
• Completed: Finished tasks

Click any task card to see full details including description and dependencies.

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl/Cmd+S | Save current plan |

Configuration

Port Configuration

Default port: 8888

Using --port flag:

npx claude-viz --port 3000

Using PORT environment variable:

PORT=3000 npx claude-viz

Watched Directories

Claude Viz watches these directories (used by Claude Code):

• Plans: ~/.claude/plans/ - Markdown plan files
• Tasks: ~/.claude/tasks/ - Task JSON files organized by session

Requirements

• Node.js: 18.0.0 or higher
• Claude Code: For generating plan files (optional - you can create plans manually)

How It Works

Claude Viz runs a lightweight Express server that:

1. Watches Files: Uses chokidar to monitor ~/.claude/plans/ and ~/.claude/tasks/
2. Parses Content: Converts plans to HTML, parses task JSON files
3. Streams Updates: Broadcasts changes via Server-Sent Events (SSE)
4. Handles Saves: REST endpoints for saving and creating plans

Architecture

┌─────────────────────────────────┐
│          Browser UI             │
│  ┌─────────────┬──────────────┐ │
│  │ Plans View  │  Tasks View  │ │
│  │ (Editor +   │  (Kanban     │ │
│  │  Preview)   │   Board)     │ │
│  └─────────────┴──────────────┘ │
└───────────────┬─────────────────┘
                │ SSE Stream + REST API
                │
┌───────────────▼─────────────────┐
│        Express Server           │
│         (Port 8888)             │
└───────────────┬─────────────────┘
                │
    ┌───────────┴───────────┐
    │                       │
┌───▼───────────┐   ┌───────▼───────┐
│ Plan Watcher  │   │ Task Watcher  │
│  (chokidar)   │   │  (chokidar)   │
└───────┬───────┘   └───────┬───────┘
        │                   │
┌───────▼───────┐   ┌───────▼───────┐
│ ~/.claude/    │   │ ~/.claude/    │
│ └─ plans/     │   │ └─ tasks/     │
└───────────────┘   └───────────────┘

Troubleshooting

Port Already in Use

Error: EADDRINUSE: address already in use

Solution: Use a different port

npx claude-viz --port 3000

No Plans Showing

Issue: Editor shows empty state

Solutions:

1. Check directory exists: ls ~/.claude/plans/
2. Create a plan manually or use Claude Code's plan mode

Browser Doesn't Auto-Open

Issue: CLI starts but browser doesn't open

Solution: Manually open the URL shown in terminal:

http://localhost:8888

Permission Errors

Issue: Cannot read/write ~/.claude/ directories

Solution: Ensure your user has read/write permissions:

ls -la ~/.claude/plans/

Development

Local Development

# Clone the repository
git clone [email protected]:sparkmints/claude-viz.git
cd claude-viz

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
npm run dev

Project Structure

claude-viz/
├── src/
│   ├── cli.ts               # CLI entry point
│   ├── server.ts            # Express server with REST API
│   ├── types.ts             # TypeScript type definitions
│   ├── watchers/
│   │   ├── plan-watcher.ts  # Plans file watcher + save/create
│   │   └── task-watcher.ts  # Tasks file watcher
│   ├── parsers/
│   │   └── markdown.ts      # Markdown to HTML parser
│   └── public/              # Frontend (HTML/CSS/JS)
├── screenshots/             # README screenshots
├── dist/                    # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Tech Stack

• Runtime: Node.js 18+
• Framework: Express.js
• File Watching: Chokidar
• Markdown Parsing: Marked (client-side)
• Syntax Highlighting: Highlight.js
• Browser Launcher: Open
• Language: TypeScript
• Real-time Updates: Server-Sent Events (SSE)

License

MIT License - See LICENSE file for details

Links

• Repository: https://github.com/sparkmints/claude-viz
• Issues: https://github.com/sparkmints/claude-viz/issues
• Claude Code: https://claude.com/claude-code

Built with love for the Claude Code community