Claude Code Viewer tackles a common pain point for developers working with Claude Code AI agent sessions: how to interactively monitor, browse, and engage with conversations beyond the command line. It offers a browser-based UI that supports real-time conversation streaming, session history exploration, and chat interaction, all while navigating the tricky waters of Anthropic’s usage restrictions.
what claude code viewer does and how it works
Claude Code Viewer is a Node.js-based web server built with TypeScript that acts as a UI layer over Claude Code sessions. Under the hood, it connects to the Claude Code Agent SDK to stream conversation data and session logs in real time. The server runs on Node.js version 22.13.0 or later and supports macOS and Linux, explicitly excluding Windows.
The UI is designed as a Progressive Web App (PWA), which means it can be installed on mobile devices for an app-like experience, complete with push notifications when sessions complete. This is particularly useful for developers who want to monitor their AI agent sessions on the go.
A standout architectural feature is the dual authentication mode the viewer supports:
- API Key authentication: provides full access to all features, including real-time chat interaction.
- Subscription authentication: restricted by Anthropic’s Terms of Service for Agent SDK usage, this mode disables direct chat features and replaces them with a ‘copy CLI command’ fallback. However, all read-only features such as session history browsing remain fully functional.
This dual-mode design is a pragmatic solution to legal and policy constraints often neglected in AI tooling. It ensures the tool remains useful even when full interactive features are not permitted.
The server also includes a built-in terminal emulator for CLI-style interaction and supports remote access through Tailscale, enabling secure exposure of the UI with password protection. This allows persistent servers to be accessed from mobile devices or other machines without complex network setup.
technical strengths and design tradeoffs
The core technical strength lies in the intelligent handling of Anthropic’s usage restrictions. Instead of blocking or removing features wholesale, Claude Code Viewer gracefully degrades chat interactions when using subscription authentication. This design respects policy constraints while maximizing usability.
The codebase leverages TypeScript for type safety and maintainability, with a clean separation between server logic and UI components. The PWA approach enhances developer experience by enabling offline caching and push notifications, which are not common in many AI session tools.
Running on Node.js 22.13.0+ and targeting macOS/Linux keeps the stack modern and performant, but it does limit Windows users. The choice of Tailscale for remote access is pragmatic — it sidesteps firewall and NAT traversal issues without requiring advanced network configuration.
The terminal emulator embedded in the UI is a nice touch for users who prefer or need CLI-style interaction alongside graphical features. However, the project depends on Claude Code v1.0.125 or later, meaning users must keep their Claude Code installation up to date to avoid compatibility issues.
The tradeoff is clear: the tool prioritizes compliance and usability over offering full chat capabilities under all authentication modes. This is a real-world constraint that many AI developers face but often ignore in tooling.
quick start
system requirements
- Node.js version 22.13.0 or later
- Claude Code v1.0.125 or later
- macOS or Linux (Windows not supported)
installation & usage
Run directly without installation:
npx @kimuson/claude-code-viewer@latest --port 3400
Or install globally:
npm install -g @kimuson/claude-code-viewer
claude-code-viewer --port 3400
This starts the server on port 3400 (default is 3000). Open http://localhost:3400 in your browser to access the interface.
Available command-line options include setting port, hostname, verbose logging, password for authentication, specifying Claude Code executable path, and running in API-only mode.
remote access with tailscale
To expose the viewer remotely (e.g. from a mobile device), set up HTTPS on your Tailscale node following their certificates guide. Then run:
claude-code-viewer --hostname 0.0.0.0 --port 3400 --password your-secret
Access the UI via your Tailscale HTTPS URL (e.g., https://your-machine.ts.net:3400). On mobile, add the PWA to your home screen for push notifications and optimized UI.
verdict
Claude Code Viewer is a practical, well-structured tool for developers who want a richer UI for monitoring and interacting with Claude Code sessions. Its dual-authentication design is its most noteworthy feature, showing a pragmatic approach to navigating legal restrictions without sacrificing core usability.
While the lack of Windows support and degraded chat in subscription mode are limitations, these are reasonable tradeoffs given the context. The PWA support and Tailscale integration make it versatile for both desktop and mobile workflows.
If you work with Claude Code agents and want a persistent, accessible UI with real-time session insights, this is worth trying. The project isn’t a full chat client under all modes but excels as a session management and monitoring dashboard that respects real-world API usage policies.
→ GitHub Repo: d-kimuson/claude-code-viewer ⭐ 1,153 · TypeScript