Monitor Claude Code background agents in real-time — without spending a single extra token.

ClaudeOverseer is a desktop application that reads Claude Code's local JSONL transcript files and presents them as a live-updating, beautifully formatted chat interface. Watch your background agents work, debug sessions, and understand exactly what Claude is doing behind the scenes — all from your filesystem, with zero API calls.

• Live Session Monitoring — Watch Claude Code sessions update in real-time as agents work
• Chat-Style Interface — Familiar message stream with user messages, assistant responses, and tool calls
• Dark / Light / System Theme — Three-mode theme switcher; System mode auto-follows OS appearance
• Pinned Projects — Pin favourite projects to the top of the sidebar for quick access
• Project Sort Controls — Cycle through sort modes (Recent / A-Z / Sessions)
• Resizable Panels — Draggable panel dividers with persistent widths
• Preferences Persistence — Selected project/session, window size/position, and panel widths survive restarts
• Team Support — Discover and display team configurations with member details
• Activity Indicators — Live status dots on project icons (green/blue/gray)
• Session Status — Visual indicators for active (🟢), recent (🔵), and stale (⚪) sessions
• Tool Call Visualization — Expandable cards with syntax-highlighted tool I/O
• Token Usage Tracking — Input/output token counts with visual bars
• Keyboard Shortcuts — Navigate projects and sessions with Cmd+1/2/3, Cmd+J
• Raw JSON Toggle — View the underlying JSONL structure when debugging
• Zero Cost — Reads local files only, no API calls required
• Cross-Platform — macOS, Linux, and Windows (both x64 and ARM64)

Download the appropriate package for your platform from the latest release:

Available formats:

• .dmg — Disk image installer (drag to Applications folder)
• .zip — Portable app bundle (extract and run)

# Or build from source (requires macOS):
git clone https://github.com/Xalior/ClaudeOverseer.git
cd ClaudeOverseer
pnpm install
pnpm run dist:mac

Available formats:

• .AppImage — Universal Linux package (no installation, just make executable and run)
• .deb — Debian/Ubuntu package (for apt-based distros)

# Run AppImage:
chmod +x ClaudeOverseer-*.AppImage
./ClaudeOverseer-*.AppImage

# Or install .deb:
sudo dpkg -i ClaudeOverseer-*.deb

# Or build from source:
git clone https://github.com/Xalior/ClaudeOverseer.git
cd ClaudeOverseer
pnpm install
pnpm run dist:linux

Available formats:

• -win-x64.exe — x64 NSIS installer (installs system-wide with Start Menu shortcuts)
• -win-x64.zip — x64 portable version (extract and run, no installation)
• -win-arm64.exe — ARM64 NSIS installer
• -win-arm64.zip — ARM64 portable version
• -win.exe — Universal installer (auto-detects architecture, includes both x64 and ARM64)

# Or build from source:
git clone https://github.com/Xalior/ClaudeOverseer.git
cd ClaudeOverseer
pnpm install
pnpm run dist:win

• Node.js 20 or higher
• pnpm 9+ (npm install -g pnpm)
• Claude Code installed with active or historical sessions in ~/.claude/projects/

# Development mode (with hot-reload)
pnpm run dev

# Or run the packaged app after building
./release/ClaudeOverseer.app  # macOS
./release/ClaudeOverseer       # Linux

By default, ClaudeOverseer reads from ~/.claude/projects/. To point it at a custom location:

1. Create or edit paths.txt in the project root:

   Claude Project Dir = /path/to/your/.claude/projects
   

2. Restart the app

ClaudeOverseer is built with:

• Electron — Desktop shell with filesystem access
• React 19 + TypeScript — Component-based UI
• Radix UI — Accessible, unstyled primitives with custom styling
• TanStack React Query — Server-state management with event-driven invalidation
• Vite + electron-vite — Fast bundling and hot-reload
• Chokidar — File watching for live updates
• react-markdown + remark-gfm + rehype-highlight — Markdown rendering
• highlight.js — Syntax highlighting for tool call content
• Mermaid — Diagram support

┌─────────────────────────────────────┐
│   Electron Main Process             │
│  ┌───────────────────────────────┐  │
│  │ Project Scanner               │  │
│  │ - Reads ~/.claude/projects/   │  │
│  │ - Discovers sessions/subagents│  │
│  │ - Reads team configs          │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │ JSONL Watcher                 │  │
│  │ - Watches .jsonl files        │  │
│  │ - Parses new lines            │  │
│  │ - Streams via IPC             │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
              ▼ IPC
┌─────────────────────────────────────┐
│   Electron Renderer                 │
│  ┌───────────────────────────────┐  │
│  │ React App                     │  │
│  │ - Project List                │  │
│  │ - Session List                │  │
│  │ - Message Stream              │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

# Clone the repository
git clone https://github.com/Xalior/ClaudeOverseer.git
cd ClaudeOverseer

# Install dependencies
pnpm install

# Install Playwright browsers for E2E tests
pnpm exec playwright install

# Unit tests only (~0.3s)
pnpm run test:unit

# Integration tests only (~1.7s)
pnpm run test:integration

# E2E tests (~15s, includes build step)
pnpm run test:e2e

# All tests in sequence (includes build step)
pnpm run test:all

# Watch mode for development
pnpm run test:watch

# Coverage report
pnpm run test:coverage

Current Test Status: 74/74 passing

• Unit: 47 tests (parsers, formatters, team reader)
• Integration: 18 tests (project scanner, session discovery, JSONL watcher)
• E2E: 9 tests (app launch, project discovery, message stream, live watching)

Recommended: Docker Build (Linux + Windows)

# Build for Linux and Windows using Docker (cross-platform)
pnpm run docker:build

This creates 9 artifacts in release/:

Linux (x64 & ARM64):

• ClaudeOverseer-0.2.0-linux-x86_64.AppImage
• ClaudeOverseer-0.2.0-linux-amd64.deb
• ClaudeOverseer-0.2.0-linux-arm64.AppImage
• ClaudeOverseer-0.2.0-linux-arm64.deb

Windows (x64 & ARM64):

• ClaudeOverseer-0.2.0-win-x64.exe (installer)
• ClaudeOverseer-0.2.0-win-x64.zip (portable)
• ClaudeOverseer-0.2.0-win-arm64.exe (installer)
• ClaudeOverseer-0.2.0-win-arm64.zip (portable)
• ClaudeOverseer-0.2.0-win.exe (universal installer, auto-detects architecture)

macOS Build (requires macOS)

# Build macOS packages natively (creates 4 additional artifacts)
pnpm run dist:mac

This creates 4 artifacts:

• ClaudeOverseer-0.2.0-mac-x64.dmg (Intel installer)
• ClaudeOverseer-0.2.0-mac-x64.zip (Intel portable)
• ClaudeOverseer-0.2.0-mac-arm64.dmg (Apple Silicon installer)
• ClaudeOverseer-0.2.0-mac-arm64.zip (Apple Silicon portable)

Total: 13 distribution packages across all platforms and architectures.

Platform-Specific Builds

# Build macOS .zip (requires macOS)
pnpm run dist:mac

# Build Linux AppImage + .deb (works on Linux or in Docker)
pnpm run dist:linux

# Build Windows installers + zips (works on Windows or in Docker via Wine)
pnpm run dist:win

All dist:* scripts automatically run build first.

ClaudeOverseer/
├── src/
│   ├── main/           # Electron main process
│   │   ├── index.ts    # App entry point
│   │   ├── scanner/    # Project/session scanner
│   │   └── watcher/    # JSONL file watcher
│   ├── preload/        # Electron preload (contextBridge)
│   └── renderer/       # React UI
│       ├── components/ # React components
│       │   ├── ProjectList.tsx
│       │   ├── SessionList.tsx
│       │   └── messages/
│       │       ├── MessageStream.tsx
│       │       ├── UserMessage.tsx
│       │       ├── AssistantMessage.tsx
│       │       ├── ToolCallCard.tsx
│       │       └── TokenUsageBar.tsx
│       └── store/      # Zustand state
├── tests/
│   ├── unit/           # Unit tests
│   ├── integration/    # Integration tests
│   ├── e2e/            # Playwright E2E tests
│   └── fixtures/       # Test data
├── docs/               # Documentation
│   └── plans/          # Implementation plans
└── resources/          # App icons and assets

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (pnpm run test:all)
4. Commit your changes (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

We follow Conventional Commits:

• feat: — New features
• fix: — Bug fixes
• docs: — Documentation changes
• test: — Test additions or fixes
• refactor: — Code refactoring
• chore: — Build process or tooling changes

• Phase 1-2: Project scanning, session discovery, basic UI
• Phase 3: JSONL parsing and message stream display
• Phase 4: Live file watching with incremental updates
• Phase 5: UX polish, teams support, keyboard shortcuts
• Phase 6: Packaging and CI/CD
• Windows support
• Dark/light/system theme toggle
• Pinned projects and sort controls
• Resizable panels with persistent preferences
• Radix UI migration (replaced React-Bootstrap)
• Event-driven filesystem monitoring (replaced polling)
• Message search and filtering
• Export session transcripts
• Session comparison view

MIT License — see LICENSE for details.

See CHANGELOG.md for detailed release notes and version history.

Built with Claude Code — the very tool it monitors.

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by the ClaudeOverseer team