Choosing Your Authentication Mode

On first launch (or from the Settings screen), you will be prompted to select your authentication method:

• API Key (default) — Uses the Anthropic API directly. All features, including chat sending, are fully available.
• Subscription — Opts out of Agent SDK chat features. The chat input switches to a copy mode: configure your session options in the form, then click the Copy button to get the equivalent claude CLI command with the corresponding arguments already set. Paste and run it in any terminal to start or resume your session. Once the session is running, Claude Code Viewer will display the conversation in real-time as usual.

Built-in Terminal

Claude Code Viewer includes an integrated terminal emulator accessible via the panel at the bottom of the screen. Open it, paste the copied command, and launch Claude Code without ever leaving the browser.

Introduction

Claude Code Viewer is a web-based Claude Code client focused on comprehensive session log analysis. It preserves and organizes all conversation data through strict schema validation and a progressive disclosure UI that reveals details on demand.

Core Philosophy: Zero data loss + Effective organization + Remote-friendly design

System Requirements

• Node.js: Version 22.13.0 or later
• Claude Code: v1.0.125 or later
• Operating Systems: macOS and Linux (Windows is not supported)

Installation & Usage

Quick Start (CLI)

Run directly from npm without installation:

npx @kimuson/claude-code-viewer@latest --port 3400

Alternatively, install globally:

npm install -g @kimuson/claude-code-viewer
claude-code-viewer --port 3400

The server will start on port 3400 (or the default port 3000). Open http://localhost:3400 in your browser to access the interface.

Available Options:

claude-code-viewer [options]

Options:
  -p, --port <port>                Port to listen on (default: 3000)
  -h, --hostname <hostname>        Hostname to listen on (default: localhost)
  -v, --verbose                    Enable verbose debug logging
  -P, --password <password>        Password for authentication
  -e, --executable <executable>    Path to Claude Code executable
  --claude-dir <claude-dir>        Path to Claude directory
  --api-only                       Run in API-only mode without Web UI

Remote Access via Tailscale (Mobile / PWA)

Claude Code Viewer works great as a persistent server you access from your phone. A convenient approach is to run it on a always-on machine and expose it over Tailscale with HTTPS:

1. Set up HTTPS on your Tailscale node following the Tailscale HTTPS certificates guide.

2. Start Claude Code Viewer bound to all interfaces with a password:

   claude-code-viewer --hostname 0.0.0.0 --port 3400 --password your-secret
   

3. Access from your phone via the Tailscale HTTPS URL (e.g. https://your-machine.ts.net:3400).

Claude Code Viewer is a PWA (Progressive Web App). On mobile, tap "Add to Home Screen" to get an app-like experience with an optimized UI and push notifications when sessions complete.

Configuration

Command-Line Options and Environment Variables

Claude Code Viewer can be configured using command-line options or environment variables. Command-line options take precedence over environment variables.

| Command-Line Option | Environment Variable | Description | Default | | ------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | -p, --port <port> | PORT | Port number for Claude Code Viewer to run on | 3000 | | -h, --hostname <hostname> | HOSTNAME | Hostname to listen on for remote access | localhost | | -v, --verbose | — | Enable verbose debug logging. Outputs detailed server-side logs to stderr for troubleshooting | (unset) | | -P, --password <password> | CCV_PASSWORD | Password for authentication. When set, enables password-based authentication to protect access to Claude Code Viewer. All /api routes (except login, logout, check, config, and version endpoints) require authentication. If not set, authentication is disabled and the application is publicly accessible | (none) | | -e, --executable <executable> | CCV_CC_EXECUTABLE_PATH | Path to Claude Code installation. If not set, uses system PATH installation, or falls back to bundled version from dependencies | (auto-detect) | | --claude-dir <claude-dir> | CCV_GLOBAL_CLAUDE_DIR | Path to Claude directory where session logs are stored | ~/.claude | | --terminal-disabled | CCV_TERMINAL_DISABLED | Disable the in-app terminal panel when set to 1/true (env) or when the flag is present (CLI) | (unset) | | --terminal-shell <path> | CCV_TERMINAL_SHELL | Shell executable for terminal sessions (e.g. /bin/zsh) | (auto-detect) | | --terminal-unrestricted | CCV_TERMINAL_UNRESTRICTED | When set to 1 (env) or when the flag is present (CLI), disables the restricted shell flags for bash | (unset) | | --api-only | CCV_API_ONLY | Run in API-only mode. Disables Web UI, terminal WebSocket, and non-essential endpoints. Only core API routes (/api/version, /api/config, /api/projects, /api/claude-code, /api/search, /api/sse) are exposed. Us