claudeconvo 0.1.0

View Claude Code session history as a conversation

claudeconvo

View Claude Code session history as a conversation

claudeconvo is a command-line utility that loads and displays Claude Code session files stored in ~/.claude/projects/ for the current working directory, formatted as readable conversations with colored output for different speakers and tool executions.

Features

• Display Claude Code conversations with colored, formatted output
• Multiple color themes optimized for different terminal backgrounds
• Filter messages by type (user, assistant, tools, system, etc.)
• Show or hide metadata, tool details, and system messages
• Support for relative and absolute session references
• Rich formatting with proper indentation and line wrapping
• Configuration file support for persistent settings

Installation

Using pip

pip install claudeconvo

From source

git clone https://github.com/lpasqualis/claudeconvo.git
cd claudeconvo
pip install -e .

Usage

Basic Usage

# View the most recent session
claudeconvo

# View a specific session by number
claudeconvo 3

# View previous session
claudeconvo -1

# Watch a session for new entries (tail mode)
claudeconvo -w

# Watch a specific session
claudeconvo -f session-123 -w

Filtering Options

Use single-letter flags to control what content is displayed:

# Show only user and assistant messages (default)
claudeconvo

# Show all content
claudeconvo -a

# Show summaries and metadata
claudeconvo -sm

# Show tool executions with full details
claudeconvo -ot

Available Options

• q - Show user messages
• w - Show assistant (Claude) messages
• s - Show session summaries
• h - Show hook executions
• m - Show metadata (uuid, sessionId, version, etc.)
• c - Show command-related messages
• y - Show all system messages
• t - Show full tool details without truncation
• o - Show tool executions
• e - Show all error details and warnings
• r - Show API request IDs
• f - Show parent/child relationships
• u - Show all content without truncation
• d - Show performance metrics and token counts
• p - Show working directory (cwd) for each message
• l - Show message level/priority
• k - Show sidechain/parallel messages
• v - Show user type for each message
• a - Enable all options

Uppercase letters disable options:

• aH - Enable all except hooks
• Aqw - Disable all, then enable only user and assistant messages

Color Themes

Choose from multiple color themes optimized for different terminal backgrounds:

# Use light theme for white/light terminals
claudeconvo --theme light

# Use high contrast theme for accessibility
claudeconvo --theme high-contrast

# Disable colors entirely
claudeconvo --no-color

Available themes:

• dark (default) - Optimized for dark terminal backgrounds
• light - Optimized for light/white terminal backgrounds
• solarized-dark - Solarized dark color scheme
• solarized-light - Solarized light color scheme
• dracula - Dracula color scheme
• nord - Nord color scheme
• mono - No colors (monochrome)
• high-contrast - Maximum contrast for accessibility

Set a default theme using:

• Environment variable: export CLAUDECONVO_THEME=light
• Config file: Create ~/.claudeconvorc with {"theme": "light"}

Configuration

Create a ~/.claudeconvorc file to set persistent preferences:

{
  "theme": "light",
  "default_show_options": "qwo"
}

Configuration priority (highest to lowest):

1. Command-line arguments
2. Environment variables
3. Config file (~/.claudeconvorc)
4. Built-in defaults

Help and Available Sessions

# Show help
claudeconvo --help

# List available sessions
claudeconvo --list

# Show what options would display
claudeconvo -?sm

Requirements

• Python 3.8 or higher
• No external dependencies

Development

Setting up development environment

git clone https://github.com/lpasqualis/claudeconvo.git
cd claudeconvo
pip install -e ".[dev]"

Running tests

pytest

Code formatting and linting

black src/
ruff check src/
mypy src/

License

MIT License - see LICENSE file for details.

Author

Lorenzo Pasqualis

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

If you encounter any problems or have suggestions, please open an issue.