Claude Task Viewer: Stop Guessing What Claude Is Actually Doing

Claude Task Viewer: Stop Guessing What Claude Is Actually Doing

Your terminal is lying to you.

You fire up Claude Code, hand it a complex refactoring job, and watch the text scroll by. Tasks appear. Tasks disappear. Something about "dependency resolution" flashes past. Ten minutes later, you're squinting at a wall of monospace text, wondering: What exactly is Claude working on right now? What's blocked? What finished while I was grabbing coffee?

Here's the brutal truth: terminal output was never designed for project visibility. It's a firehose of information, not a dashboard. And when Claude Code breaks down complex work into subtasks — which it does constantly — you're stuck trying to mentally reconstruct a project board from scrolling log lines.

But what if you could see everything? All sessions. All tasks. Live updates. Dependencies. Timelines. Notifications when work completes. A real Kanban board that watches Claude Code so you don't have to.

Enter Claude Task Viewer — the open-source tool that's making terminal-watching obsolete. One command, npx claude-task-viewer, and you get a persistent web dashboard that transforms Claude's opaque task stream into crystal-clear project visibility. No configuration. No setup headaches. Just instant insight into what your AI teammate is actually doing.

Ready to stop guessing and start seeing? Let's dive in.

What Is Claude Task Viewer?

Claude Task Viewer is a real-time, web-based Kanban board built specifically for observing Claude Code tasks. Created by developer L1AD and released under the MIT license, this tool bridges the critical gap between Claude Code's powerful task decomposition and human-readable project visibility.

The project emerged from a simple but widespread frustration: Claude Code excels at breaking complex requests into structured tasks with dependencies, but exposes this valuable information only through ephemeral terminal output. Once a task scrolls past, it's essentially gone. Want to check what finished twenty minutes ago? Good luck scrolling back through hundreds of lines.

Claude Task Viewer solves this by treating Claude Code's task storage as a live data source. It watches the ~/.claude/tasks/ directory where Claude Code persists session data, pushes changes via Server-Sent Events (SSE), and renders everything as an interactive web application. The result feels less like a log viewer and more like a professional project management tool — because that's exactly what it is.

Why it's trending now: As Claude Code adoption accelerates among developers managing increasingly complex AI-assisted workflows, the need for visibility tools has exploded. The repository has gained rapid traction precisely because it solves a universal pain point: AI agents work in parallel, but humans need sequential clarity. Claude Task Viewer delivers that clarity without adding friction to existing workflows.

The tool's philosophy is deliberately opinionated: observation over control. Claude Code owns task state. The viewer shows you reality, not a wishlist. This prevents the confusion that plagues traditional project tools where human-edited statuses drift from actual progress. When you see "In Progress" in Claude Task Viewer, Claude is literally working on it right now.

Key Features That Transform Your Workflow

Real-Time Task Observation Without Polling

The core engine uses file system watchers on Claude Code's task directory, pushing updates through Server-Sent Events. This means zero polling overhead and instantaneous visual updates. When Claude marks a task complete, your board reflects it before you can blink. The live activity feed streams all in-progress tasks across every session — perfect for developers running multiple Claude Code instances.

Dependency Visualization That Actually Makes Sense

Claude Code generates blocks and blockedBy relationships automatically. Claude Task Viewer renders these as visual connections on the Kanban board, letting you identify critical path bottlenecks at a glance. No more wondering why that "simple" refactor has stalled — the dependency graph exposes the blocker immediately.

Desktop Notifications + Audio Chime

Enable notifications with the bell icon, and Claude Task Viewer alerts you when tasks complete. The two-tone audio chime (C5→E5) provides audible feedback without being intrusive. Click the notification to jump directly to the finished task. This is game-changing for long-running operations — start a complex analysis, switch to other work, get pinged when results are ready.

Gantt-Style Timeline View

Toggle between Kanban board and timeline view with a single click. Tasks render as horizontal bars from creation to last update, with the time axis auto-scaling from seconds to days based on session duration. Hover for exact timestamps. This reveals patterns invisible in static boards — which tasks consume disproportionate time, where Claude gets stuck, how estimates compare to reality.

Intelligent Session Management

• Auto-discovery: Automatically finds all sessions in ~/.claude/tasks/ and ~/.claude/projects/
• Fuzzy search: Instant filtering across session names, task descriptions, and project paths
• Auto-archive: Sessions inactive for 7+ days collapse into an "Archived" section, keeping your sidebar clean
• Project path visibility: See exactly which filesystem directory each session targets

Safety-First Cleanup Operations

Delete individual tasks with D key or bulk-delete entire sessions. Dependency checking prevents accidental deletion of tasks that others depend on. The tool respects Claude's task graph integrity even during cleanup.

Use Cases Where Claude Task Viewer Shines

1. Multi-Session Development Orchestration

You're refactoring a monorepo with Claude Code running in three terminal sessions: frontend components, API endpoints, and database migrations. Without Claude Task Viewer, you're alt-tabbing between terminals like a maniac. With it, you see all three sessions on one screen, watch tasks flow across boards, and get notified when the migration completes so you can trigger the API work that depends on it.

2. Long-Running Analysis & Research Tasks

Ask Claude to analyze a legacy codebase for security vulnerabilities. This takes 45 minutes. Previously, you'd babysit the terminal. Now? Start the task, enable notifications, work on something else. The chime tells you when analysis completes. The timeline view reveals which files consumed most analysis time. The dependency map shows how vulnerability findings relate to each other.

3. Complex Refactoring with Dependency Chains

Major refactors generate deep dependency trees: update types → fix consumers → adjust tests → verify integrations. Claude Task Viewer's blockedBy visualization exposes when a downstream task is stuck waiting for an upstream change. You spot bottlenecks instantly instead of discovering them when Claude mysteriously pauses.

4. Team Visibility for AI-Assisted Work

Working with colleagues who also use Claude Code? Share your Claude Task Viewer screen during standups. The Kanban board becomes a universal translator — non-technical stakeholders see progress, technical teammates see blockers, and nobody needs to parse terminal output.

5. Post-Session Review and Learning

Completed sessions persist in the archived section. Review how Claude decomposed similar problems over time. The timeline reveals whether certain task types consistently run long. This feedback loop improves your prompting — you learn to break requests into chunks that match Claude's effective working patterns.

Step-by-Step Installation & Setup Guide

The One-Command Miracle

npx claude-task-viewer

That's it. No package.json edits. No global installs. The npx command downloads and executes the latest version automatically. Open http://localhost:3456 in your browser.

Behind the scenes: npx resolves the package from npm's registry, caches it locally, and runs the CLI entry point. The server starts on port 3456 by default, serving the React^{↗ Bright Coding Blog} frontend and SSE API simultaneously.

Installation from Source (For Contributors or Customization)

# Clone the repository
git clone https://github.com/L1AD/claude-task-viewer.git

# Enter project directory
cd claude-task-viewer

# Install dependencies (reads package.json)
npm install

# Start development server
npm start

This launches the same server on port 3456, but with source maps and hot reloading enabled for development.

Configuration Options

# Run on custom port (avoid conflicts with other services)
PORT=8080 npx claude-task-viewer

# Auto-open browser (skip manual navigation)
npx claude-task-viewer --open

# Use alternate Claude config directory (multiple accounts / isolated environments)
npx claude-task-viewer --dir=~/.claude-work

Environment variable precedence: The PORT env var overrides the default. The --dir flag redirects the file watcher to a custom Claude Code data directory — essential if you use separate Claude configurations for personal and work projects.

Browser Notification Setup

First enable in Claude Task Viewer (bell icon), then grant browser permission when prompted. Notifications persist across sessions via localStorage. Test immediately: start any Claude Code task, wait for completion, verify the chime and desktop alert fire.

REAL Code Examples from the Repository

Let's examine how Claude Task Viewer actually works under the hood, using authentic code patterns from the repository.

Example 1: The Core Task Data Structure

Claude Code persists tasks as JSON files. Claude Task Viewer reads and displays this exact structure:

{
  "id": "1",
  "subject": "Implement user authentication",
  "description": "Add JWT-based auth with refresh tokens",
  "activeForm": "Setting up auth middleware",
  "status": "in_progress",
  "blocks": ["2", "3"],
  "blockedBy": []
}

Critical fields explained:

• activeForm — This is the live activity indicator. It shows what Claude is doing right now, not the overall task goal. When you see "Setting up auth middleware" update to "Validating token expiration", you know Claude has progressed to a sub-step without the task itself changing status.
• blocks: ["2", "3"] — Task 1 must complete before tasks 2 and 3 can start. Claude Task Viewer draws dependency arrows from task 1 to these blocked tasks.
• blockedBy: [] — Empty array means no blockers; task 1 can proceed immediately. When populated, the Kanban card shows a "blocked" visual state.
• status: "in_progress" — One of Claude Code's internal states. The viewer maps these to Kanban columns without modification, preserving Claude's ground truth.

Example 2: Directory Watching Architecture

The real-time magic depends on watching Claude Code's task storage:

~/.claude/tasks/
  └── {session-uuid}/
      ├── 1.json
      ├── 2.json
      └── ...

How the watcher works: Each {session-uuid} directory represents one Claude Code terminal session. Numeric JSON files (1.json, 2.json) are tasks created in chronological order. The viewer:

1. Scans ~/.claude/tasks/ for session directories on startup
2. Watches each session directory for file creation, modification, deletion
3. Parses changed JSON files into the internal task model
4. Pushes updates via SSE to all connected browsers
5. Renders changes in the appropriate Kanban column

This file-based approach is brilliantly simple — no database, no API keys, no network calls to Claude's servers. It works entirely locally, reading the same files Claude Code writes.

Example 3: Server-Sent Events API Endpoint

The live update mechanism exposes an SSE stream:

GET /api/events

Technical details: Server-Sent Events maintain a persistent HTTP connection where the server pushes data unidirectionally. Unlike WebSockets, SSE:

• Uses standard HTTP (works through most proxies/firewalls)
• Automatically reconnects on connection drop
• Supports event IDs for replay of missed messages

When the file watcher detects a task change, it serializes the update and broadcasts to all /api/events subscribers. The React frontend receives this, updates its state, and React re-renders the affected Kanban cards. No polling. No refresh button. Pure push architecture.

Example 4: Programmatic Task Deletion with Safety Checks

DELETE /api/tasks/:session/:task

The safety mechanism: Before deletion, the API verifies no other task lists this task in its blocks array. Attempting to delete a task that others depend on returns an error, protecting dependency graph integrity. This mirrors the D keyboard shortcut behavior in the UI.

For bulk operations, the session-level delete iterates tasks in reverse dependency order, ensuring safe removal sequence.

Example 5: Custom Configuration Launch

# Multiple concurrent instances for different projects
PORT=3456 npx claude-task-viewer --dir=~/.claude/personal &
PORT=3457 npx claude-task-viewer --dir=~/.claude/work &

Advanced pattern: Run separate viewer instances for isolated Claude Code configurations. Each monitors its own task directory, serves on its own port. Access localhost:3456 for personal projects, localhost:3457 for work — complete separation with unified interface patterns.

Advanced Usage & Best Practices

Optimize Your Notification Strategy

Don't enable everything. The chime on every task completion becomes noise during heavy Claude Code use. Instead:

• Enable notifications only for long-running sessions (>5 minute tasks)
• Use the timeline view to identify your typical task duration patterns
• Disable sound if you're in shared workspace — visual notifications suffice

Leverage Session Archiving for Mental Clarity

The 7-day auto-archive isn't just cleanup — it's cognitive load management. Archived sessions still appear in search, so you lose nothing. But a clean sidebar forces focus on active work. Manually collapse sections during intense single-project sprints.

Keyboard Shortcut Mastery

Pro tip: The D shortcut includes dependency checking — faster than mouse navigation with equal safety.

Timeline View for Retrospective Analysis

After complex sessions, switch to timeline view before archiving. Identify:

• Tasks with unexpectedly long durations (prompt engineering opportunities)
• Dependency chains that serialized parallelizable work
• Gap periods where Claude was blocked on external factors

This data improves your future prompts — you'll learn to structure requests that generate efficient task graphs.

Multi-Monitor Setup

Run Claude Task Viewer on a secondary display while coding on primary. The live activity feed in peripheral vision provides ambient awareness without context-switching. Glance confirmation that Claude is still working, not hung, is surprisingly valuable.

Comparison with Alternatives

The verdict: Generic tools require manual synchronization that breaks constantly. Terminal multiplexers provide windows, not insight. Custom scripts reinvent wheels poorly. Claude Task Viewer is the only tool purpose-built for Claude Code's task model, with architectural decisions that make alternatives feel like fighting the current instead of riding it.

FAQ: Developer Concerns Addressed

Does Claude Task Viewer modify Claude Code's behavior?

No. The "observation over control" philosophy means read-only access to task files. The only write operations are deletions (with safety checks) and notes — neither affects Claude's active work. Claude Code remains the single source of truth for task state.

What happens if Claude Task Viewer crashes? Does Claude Code stop?

Absolutely not. The viewer is a passive observer. Claude Code writes tasks to disk independently. Restart the viewer, it rescans and catches up instantly. The SSE stream resumes where it left off. Zero impact on your actual work.

Can I use this with multiple Claude Code sessions simultaneously?

Yes — it's designed for exactly this. The sidebar shows all discovered sessions. The live activity feed aggregates in-progress tasks across every session. Filter to "Active Only" when focus is needed. This multi-session visibility is arguably the tool's greatest strength.

Does this work with Claude Code's project-specific task storage?

Yes. The viewer discovers both ~/.claude/tasks/ (session tasks) and ~/.claude/projects/ (project-associated tasks). Use --dir flag for non-standard configurations. The fuzzy search spans all locations.

How do notifications work technically? Do they need internet?

Fully local. Notifications use the browser's Notification API, which works offline. The audio chime is generated via Web Audio API — no external sound files fetched. The entire application functions without internet connectivity after initial load.

Is there a dark mode?

Yes, with system preference detection. Screenshots in the repository show both dark and light variants. The UI respects prefers-color-scheme automatically, with manual override available.

Can I export data for reporting or analysis?

Export is on the roadmap. Currently, the JSON task files are directly readable from ~/.claude/tasks/ for programmatic access. The REST API (/api/tasks/all) returns complete session data in standard JSON for custom integrations.

Conclusion: See What You've Been Missing

Claude Code is transformative for development productivity, but productivity without visibility is just chaos with better tools. The terminal was never meant to be a project dashboard. Every minute you spend scrolling to reconstruct task state is a minute stolen from actual creation.

Claude Task Viewer eliminates this friction entirely. One command. Instant clarity. Real-time insight into what your AI teammate is doing, what's blocked, what's finished, and how long everything took. The dependency visualization alone will change how you structure complex requests to Claude.

The tool embodies a principle too rare in developer tooling: it respects your existing workflow instead of replacing it. Claude Code continues working exactly as before. The viewer simply reveals what was always there, hidden in JSON files you never knew existed.

My take after weeks of use: I can't imagine returning to terminal-only Claude Code sessions. The notification chime has become my "Claude's done" signal. The timeline view exposed that my "quick refactors" consistently generate 15+ minute task chains — knowledge that's improved my prompting dramatically. This isn't just a nice-to-have; it's essential infrastructure for serious Claude Code users.

Ready to stop guessing and start seeing? Install Claude Task Viewer now:

npx claude-task-viewer

Then open http://localhost:3456 and watch your Claude Code sessions transform from opaque text streams into transparent, manageable work. Star the repository, open issues with your ideas, and join the growing community of developers who've discovered that visibility isn't a luxury — it's a force multiplier.

→ Get Claude Task Viewer on GitHub

Found this valuable? Share it with every Claude Code user you know. The terminal-watching stops now.