Claude Run

Browse your Claude Code conversation history in a beautiful web UI

This is a fork of kamranahmedse/claude-run that adds the ability to restrict server exposure to localhost only (default: 127.0.0.1).

Run the project simply by executing

bunx @teddysc/claude-run

Installing or upgrading globally via bun:

# https://www.npmjs.com/package/@teddysc/claude-run
bun install -g @teddysc/claude-run@latest

The browser will open automatically at http://localhost:12001.

Deep links

You can link directly to a session using URL query params:

• ?session=<uuid> selects that session.
• ?session=<uuidPrefix> also works (e.g. ?session=3e47321c); the app picks the newest matching session and rewrites the URL to the full UUID.
• ?s=<...> is a short alias for session and is expanded to session on load.

Specifications

See spec.md

Changelog

0.15.0

• Add support for selecting sessions with partial UUIDs
• Add URL aliasing (?s= short alias for ?session=)

0.14.1

• Include spec.md in npm package files

0.14.0

• Add session deletion preview endpoint to see what files will be removed
• Enhance session deletion to remove related files and directories from disk

0.13.0

• Display message count, duration, and JSONL size in conversation header
• Sidebar shows compact message count, duration, and JSONL size per session
• Add sorting options for sessions (by duration or JSONL size, asc/desc)

0.12.0

• Rename sessions directly from the web UI
• Searchable project dropdown with fuzzy matching on name and path
• Session summary caching for improved performance

0.11.0

• Display session metadata (model, start/end times) in conversation header
• Show full project path with ~ shorthand in header and sidebar tooltips
• Add "Hide Unknown model" filter to hide sessions without detected models
• Add "Delete Unknown" button to remove blank/orphaned sessions from disk
• Automatic cleanup of orphaned history entries on startup
• Add comprehensive logging for delete operations
• Fix URL state sync when unchecking checkboxes

0.10.0

• Enhance message handling: add message ID to ConversationMessage
• Normalize content blocks in message processing
• Merge sidechain text in getConversation functions

0.9.1

• Fix favicon response handling
• Enhance server response handling for static assets
• Update Vite configuration for public directory

0.9.0

• Add Claude Code mascot favicon and app icons

0.8.0

• Add URL state synchronization - share links to specific searches, sessions, or projects
• Browser back/forward navigation now works with app state
• Full-text search options (case sensitivity, regex mode, word match) now persist in URL

0.7.0

• Add --rg-executable CLI option to override ripgrep location
• Log the exact rg command in both server logs and browser console
• Ensure full-text search includes gitignored .jsonl logs under ~/.claude

0.6.0

• Add full-text search using ripgrep
• Search across all conversation content including tool calls
• Include debug command in search response for troubleshooting
• Always search ignored files for comprehensive results

0.5.0

• Add conversation export to Markdown
• Export modes: Full conversation or tools only
• Truncation options: By lines or characters
• Batch export multiple conversations

0.4.0

• Add copy message buttons to chat messages

Features

• Full-text search - Search across all conversation content including tool calls using ripgrep
• Export conversations - Download conversations as Markdown with customizable options
• Export modes - Choose between full conversation or tools-only export
• Truncation options - Limit long tool outputs by line count or character count
• Batch export - Export multiple conversations at once
• Real-time streaming - Watch conversations update live as Claude responds
• Filter by project - Searchable dropdown with fuzzy matching on project name and path
• Resume sessions - Copy the resume command to continue any conversation in your terminal
• Copy messages - Click the copy button on any message to copy its text content
• Session metadata - See model, message count, duration, and JSONL size in the conversation header
• Sidebar stats - Compact message count, duration, and JSONL size per session
• Sidebar sorting - Sort sessions by duration or JSONL size (asc/desc)
• Rename sessions - Click the conversation title to rename a session
• Collapsible sidebar - Maximize your viewing area
• Dark mode - Easy on the eyes
• Clean UI - Familiar chat interface with collapsible tool calls
• Filter & cleanup - Hide Unknown-model sessions and delete blank sessions from disk

Usage

Install globally via bun:

bun install -g @teddysc/claude-run

Then run it from any directory:

claude-run

The browser will open automatically at http://localhost:12001, showing all your Claude Code conversations.

claude-run [options]

Options:
  -V, --version           Show version number
  -p, --port <number>     Port to listen on (default: 12001)
  -H, --host <address>    Host address to listen on (default: 127.0.0.1)
  -d, --dir <path>        Claude directory (default: ~/.claude)
  --rg-executable <path>  Path to rg (ripgrep) executable (default: /opt/homebrew/bin/rg)
  --no-open               Do not open browser automatically
  -h, --help              Show help

How It Works

Claude Code stores conversation history in ~/.claude/. This tool reads that data and presents it in a web interface with:

• Session list - All your conversations, sorted by recency
• Project filter - Focus on a specific project
• Conversation view - Full message history with tool calls
• Session header - Shows conversation title, project name, and timestamp
• Resume command - Copies the command to resume the conversation
• Real-time updates - SSE streaming for live conversations

Requirements

• Node.js 20+
• Claude Code installed and used at least once

Development

# Clone the repo
git clone https://github.com/kamranahmedse/claude-run.git
cd claude-run

# Install dependencies
bun install

# Start development servers
bun run dev

# Build for production
bun run build

License

MIT © Kamran Ahmed, Teddy