Agent Session Viewer

A live multi-platform session viewer — browse AI coding assistant conversations across Claude Code, Codex, Cursor, OpenCode, Hermes, Antigravity, and messaging bots (nanoclaw, openclaw, picoclaw, and friends) in a unified dark-mode UI with markdown rendering, tool call cards, fuzzy thread search, and thinking blocks.

Install

npx (no install required)

npx agent-session-viewer@latest

Downloads and runs directly. Builds the sidebar cache on first run, then opens at http://localhost:3001.

npx agent-session-viewer@latest --lan         # LAN access (phone, tablet)
npx agent-session-viewer@latest --tunnel      # internet URL via localtunnel
npx agent-session-viewer@latest --ngrok       # permanent internet URL via ngrok
npx agent-session-viewer@latest --open        # auto-open browser
npx agent-session-viewer@latest --port 4000
npx agent-session-viewer@latest --skip-cache  # skip cache build

Homebrew (macOS)

brew tap dhruv-anand-aintech/tap
brew install agent-session-viewer
agent-session-viewer

From source

git clone https://github.com/dhruv-anand-aintech/agent-session-viewer
cd agent-session-viewer
npm install
npm run setup    # detects platforms, builds sidebar cache
npm run local    # starts at http://localhost:5173

To access from other devices on your network:

npm run local -- --lan

Features

• Multi-platform — Claude Code, Codex, Cursor, OpenCode, Hermes, Antigravity, and claw bots in one place, all auto-detected
• Live updates — sessions appear as you work; SSE streaming keeps the UI current
• Pretty mode — markdown rendering, thinking pills, tool call cards (Bash, Read, Edit, Write, Search…)
• Platform filter — filter the sidebar by platform
• Sub-agent runs — sub-agent sessions are visually distinguished with a ⤷ sub-agent indicator and indented border
• Flat or grouped sidebar — all sessions sorted by last activity, or grouped by project
• Session renaming — give sessions memorable names via the pencil icon
• Thread search — fuzzy in-sidebar search across all sessions
• Mobile-friendly — slide-in sidebar drawer, back button, safe-area aware
• PIN-protected — simple cookie auth for remote access
• Optional rate-limit alerts — a separate machine runner tails new transcript lines/files and shows persistent macOS applet alerts when a coding agent hits a usage limit

Platform support

All platforms are auto-detected from their standard locations — no configuration needed if the directories exist.

| Platform | Default location | Format | |---|---|---| | Claude Code | ~/.claude/projects/**/*.jsonl | JSONL | | Codex | ~/.codex/sessions/**/*.jsonl | JSONL event stream | | Cursor | ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb | SQLite | | Gemini CLI | ~/.gemini/tmp/**/chats/*.jsonl | JSONL | | OpenCode | ~/.local/share/opencode/ | SQLite + JSON | | Hermes | ~/.hermes/state.db | SQLite | | Antigravity | ~/.gemini/antigravity/brain/{uuid}/ | Markdown artifacts |

Platform notes

Codex — rollout transcripts are read from ~/.codex/sessions/. Structured function_call / function_call_output entries render as proper tool-use cards in Pretty mode.

Cursor — sessions are read from the SQLite blob store. Workspace → folder mapping is resolved via workspaceStorage/. macOS only (path is hardcoded to ~/Library/Application Support/Cursor/).

OpenCode — reads from ~/.local/share/opencode/opencode.db (newer releases) with fallback to the flat storage/ directory layout.

Gemini CLI — chat transcripts are read from per-workspace folders under ~/.gemini/tmp/*/chats/.

Antigravity — Google's coding agent stores structured artifacts per session (task.md, implementation_plan.md, walkthrough.md). Each artifact is shown as an assistant message. Full conversation logs use an undisclosed protobuf schema and are not read.

Hermes — reads from ~/.hermes/state.db. Sessions are grouped by source (Telegram channel, WhatsApp number, etc.).

Optional rate-limit alerts

The rate-limit alert system is intentionally separate from the web app. It installs a user LaunchAgent that tails newly-written transcript lines and newly-created transcript files for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Hermes, OpenClaw, and related claw agents.

npm run rate-limit-watch:launchd-install

If installed from npm or Homebrew, the same global command is available:

agent-session-viewer-rate-limit-install

The installer copies the runner into ~/.config/agent-session-viewer/rate-limit/, so it does not depend on the current repo checkout after installation. Runtime cursors are stored under ~/.local/state/agent-session-viewer-rate-limit/; alert/app scheduling state is stored under ~/.local/state/agent-rate-limit-alarm/.

Disable alerts from the Settings panel or by setting:

AGENT_SESSION_VIEWER_RATE_LIMIT_ALERTS=0

To remove the LaunchAgent and copied runner:

npm run rate-limit-watch:launchd-uninstall
# or: agent-session-viewer-rate-limit-uninstall

Claw bot integration

Agent Session Viewer supports claw-type messaging bots — AI agents that run via WhatsApp or Telegram and store session data locally.

Two storage layouts are supported automatically:

• nanoclaw-style (default): {dir}/store/messages.db + {dir}/data/sessions/
• picoclaw-style: {dir}/workspace/sessions/ (JSONL directly, no SQLite DB)

Auto-detected from ~/toolname or ~/.toolname for each of: nanoclaw, openclaw, picoclaw, femtoclaw, attoclaw, kiloclaw, megaclaw, zeroclaw, microclaw, rawclaw.

If your installation is in a non-standard location, configure the path in the Settings panel (⚙) or set {NAME}_DIR as an env var override.

Remote access

The CLI includes built-in sharing options — no cloud account needed:

npx agent-session-viewer@latest --tunnel   # internet URL via localtunnel (changes on restart)
npx agent-session-viewer@latest --ngrok    # permanent URL via ngrok (free account required)
npx agent-session-viewer@latest --lan      # local network only (same WiFi)

Or omit flags to get an interactive menu at startup.

Other commands

npm run build-cache   # rebuild sidebar cache manually (runs automatically during setup)
npm run dev           # Vite frontend only, no API
npm run build         # production build
npm run lint          # eslint

Architecture

~/.claude/projects/**/*.jsonl           Claude Code sessions
~/.codex/sessions/**/*.jsonl            Codex sessions
~/Library/.../Cursor/.../state.vscdb    Cursor sessions (macOS)
~/.local/share/opencode/                OpenCode sessions
~/.hermes/state.db                      Hermes sessions
~/.gemini/antigravity/brain/            Antigravity sessions
~/nanoclaw/store/messages.db            claw bot chat history (auto-detected)
~/nanoclaw/data/sessions/**/*.jsonl     claw bot agent sessions (auto-detected)
         │
         ▼
  local-server.mjs        (reads platform dirs directly)
         │  SSE /api/stream
         ▼
  Browser (React + Vite)  (src/)
         │
  bin/agent-session-viewer.mjs  (CLI: TUI menu, LAN/tunnel/ngrok sharing)