AI Session Viewer

A lightweight, local-only web viewer for browsing AI session history, designed to grow beyond a single source over time.

中文文档 · Quick Start · Features · Development

Browse, filter, search, and inspect local AI sessions in a compact browser UI with real-time file watching.

Positioning A local AI session viewer with a current Codex-first implementation.

Current status Codex, Codex Archived, Claude Code, and Gemini CLI are supported today. Additional sources may be added in future releases.

Direction Evolve toward a unified local viewer for multiple AI coding assistant histories.

Current Scope

• Current implementation: Codex, Codex Archived, Claude Code, and Gemini CLI session parsing and viewing
• Unified multi-source aggregation in a single interface
• Planned direction: support for additional session sources

Source Support

Source	Status	Notes
Codex	Supported	Reads local session files from ~/.codex/sessions or CODEX_SESSIONS_DIR
Codex Archived	Supported	Reads from ~/.codex/archived_sessions or CODEX_ARCHIVED_SESSIONS_DIR
Claude Code	Supported	Reads session metadata from ~/.claude or CLAUDE_SESSIONS_DIR; only user inputs are available locally
Gemini CLI	Supported	Reads from ~/.gemini/tmp/*/logs.json or GEMINI_SESSIONS_DIR
Other AI tools	Planned	Future expansion area, no compatibility promise yet

Features

• Browse local session list from multiple sources (Codex, Claude Code, Gemini CLI)
• Filter by source kind, provider, date, and working directory
• Search session content, project paths, provider names, source names, and derived titles
• View individual session details
• Switch between "Conversation" and "Raw Events" views
• Chinese-English language switching
• Real-time file system watch with auto-refresh

Use Cases

• Review recent local AI sessions without opening raw JSONL files
• Search previous conversations, tool calls, and event streams
• Inspect session metadata such as provider, working directory, and timestamps
• Keep a lightweight local viewer running while new Codex sessions are written to disk

Requirements

• Node.js 20 or later
• At least one supported session source directory present:
  • Codex: ~/.codex/sessions
  • Claude Code: ~/.claude
  • Gemini CLI: ~/.gemini

Quick Start

pnpm install
pnpm start

The viewer starts at http://127.0.0.1:3210 by default.

Then open the URL in your browser and the app will scan the current Codex session directory automatically.

Environment Variables

Variable	Description	Default
PORT	Server port	3210
HOST	Bind address	127.0.0.1
CODEX_SESSIONS_DIR	Codex session root directory	~/.codex/sessions
CODEX_ARCHIVED_SESSIONS_DIR	Codex archived session directory	~/.codex/archived_sessions
CLAUDE_SESSIONS_DIR	Claude Code session root directory	~/.claude
GEMINI_SESSIONS_DIR	Gemini CLI root directory	~/.gemini

Example:

PORT=4000 CODEX_SESSIONS_DIR=/path/to/sessions pnpm start

Notes

• Local-only: no authentication or remote access control
• Read-only access to the session directory
• Supports Codex, Claude Code, and Gemini CLI session files simultaneously
• Legacy sessions with incompatible formats fall back to raw event view
• Encrypted fields are shown as-is without decryption
• Scans all sessions on startup and caches summaries; details are read on demand
• Provider migration endpoints require the local page's mutation token and reject cross-origin mutation requests

Roadmap

• Keep the current multi-source viewer stable and lightweight
• Add optional support for additional AI tool session formats
• Improve Claude Code conversation reconstruction from local history

Development

# Run tests
pnpm test

# Lint
pnpm lint

# Lint and auto-fix
pnpm lint:fix

# Format code
pnpm format

# Build frontend (outputs to dist/)
pnpm build

License

Apache-2.0