A beautiful web UI for browsing Claude Code conversation history
npm install @teddysc/claude-runBrowse 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
``bash`
bunx @teddysc/claude-run
Installing or upgrading globally via bun:
`bash`https://www.npmjs.com/package/@teddysc/claude-run
bun install -g @teddysc/claude-run@latest
The browser will open automatically at http://localhost:12001.
You can link directly to a session using URL query params:
- ?session= selects that session.?session=
- 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.
See spec.md
short alias for ?session=)$3
- Include spec.md in npm package files$3
- Add session deletion preview endpoint to see what files will be removed
- Enhance session deletion to remove related files and directories from disk$3
- 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)$3
- Rename sessions directly from the web UI
- Searchable project dropdown with fuzzy matching on name and path
- Session summary caching for improved performance$3
- 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$3
- Enhance message handling: add message ID to ConversationMessage
- Normalize content blocks in message processing
- Merge sidechain text in getConversation functions$3
- Fix favicon response handling
- Enhance server response handling for static assets
- Update Vite configuration for public directory$3
- Add Claude Code mascot favicon and app icons$3
- 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$3
- 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$3
- 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$3
- Add conversation export to Markdown
- Export modes: Full conversation or tools only
- Truncation options: By lines or characters
- Batch export multiple conversations$3
- Add copy message buttons to chat messagesFeatures
- 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:
bash
bun install -g @teddysc/claude-run
`Then run it from any directory:
bash
claude-run
`The browser will open automatically at http://localhost:12001, showing all your Claude Code conversations.
bash
claude-run [options]Options:
-V, --version Show version number
-p, --port Port to listen on (default: 12001)
-H, --host Host address to listen on (default: 127.0.0.1)
-d, --dir Claude directory (default: ~/.claude)
--rg-executable 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
. 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
`bash
Clone the repo
git clone https://github.com/kamranahmedse/claude-run.git
cd claude-runInstall dependencies
bun installStart development servers
bun run devBuild for production
bun run build
``MIT © Kamran Ahmed, Teddy