ran

Search and browse your Claude Code bash command history.

"What was that docker command I ran yesterday?"

$ ran search docker --limit 4

[ok] docker build --no-cache --platform linux/amd64 -t ghcr.io/user/api-service:latest .
     Rebuild without cache for production
     12/30/2025, 12:46 AM | ~/projects/api-service

[ok] docker build -t api-service:test .
     Build test image
     12/30/2025, 12:45 AM | ~/projects/api-service

[ok] docker run --rm api-service:test npm test
     Run tests in container
     12/30/2025, 12:46 AM | ~/projects/api-service

[ok] docker push ghcr.io/user/api-service:latest
     Push to registry
     12/30/2025, 12:48 AM | ~/projects/api-service

Every bash command Claude Code runs is logged in session files. ran indexes them into a searchable database so you can find that command you ran last week, see what worked, and avoid repeating mistakes.

Install

# With Bun (recommended)
bun add -g clauderan

# With npm
npm install -g clauderan

# Or build from source
git clone https://github.com/Michaelliv/clauderan
cd clauderan
bun install
bun run build  # Creates ./ran binary

Usage

# Search for commands containing "docker"
ran search docker

# Use regex patterns
ran search "git commit.*fix" --regex

# Filter by project directory
ran search npm --cwd /projects/myapp

# List recent commands
ran list
ran list --limit 50

# Manually sync (usually automatic)
ran sync
ran sync --force  # Re-index everything

Examples

Find a failing build command:

$ ran search "npm run build" --limit 5
# Look for [error] entries to see what failed

What commands did I run in a specific project?

$ ran search "" --cwd /projects/api --limit 20
# Empty pattern matches everything, filtered by directory

Re-run something from last week:

$ ran list --limit 100
# Scroll through recent history, copy what you need

Commands

ran search <pattern>

Search command history by substring or regex.

Flag	Description
--regex, -r	Treat pattern as regular expression
--cwd <path>	Filter by working directory
--limit, -n <N>	Limit number of results
--no-sync	Skip auto-sync before searching

ran list

Show recent commands, newest first.

Flag	Description
--limit, -n <N>	Number of commands (default: 20)
--no-sync	Skip auto-sync before listing

ran sync

Index new commands from Claude Code sessions.

Flag	Description
--force, -f	Re-index all sessions from scratch

How It Works

Claude Code stores conversation data in ~/.claude/projects/. Each session is a JSONL file containing messages, tool calls, and results.

ran scans these files, extracts Bash tool invocations, and indexes them into a local SQLite database at ~/.ran/history.db. It tracks file positions so subsequent syncs only process new content.

Auto-sync: By default, search and list automatically sync before returning results. Use --no-sync to skip this if you want faster queries.

Privacy: ran is read-only and local-only. It reads Claude's session files but never modifies them. No data is sent anywhere.

Data Model

Each indexed command includes:

Field	Description
command	The bash command that was executed
description	What Claude said it does (e.g., "Build the project")
cwd	Working directory when command ran
timestamp	When the command was executed
is_error	Whether the command failed
stdout	Command output (stored, not displayed by default)
stderr	Error output (stored, not displayed by default)
session_id	Which Claude session ran this command

For AI Agents

Run ran onboard to add a section to ~/.claude/CLAUDE.md so Claude knows how to search its own history:

ran onboard

This adds:

## ran - Claude Code bash history

Use the `ran` CLI to search commands from previous Claude Code sessions:

- `ran search <pattern>` - Search by substring or regex (`--regex`)
- `ran list` - Show recent commands
- `ran search "" --cwd /path` - Filter by directory

Example: "What docker command did you run?" → `ran search docker`

Now Claude knows how to search its own history.

When to use ran

• User asks "what was that command I/you ran?"
• User wants to find a command from a previous session
• User needs to recall commands from a specific project
• User wants to see commands that failed

When NOT to use ran

• Finding files by name → use Glob
• Searching file contents → use Grep
• Checking recent conversation context → already in your context
• User's personal shell history → not indexed, only Claude's commands

Development

# Install dependencies
bun install

# Run directly
bun run src/index.ts search docker

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Build binary
bun run build

About the name

ran — past tense of "run." It shows you what commands ran.

---

MIT License