# claudeconvo
Reveal the complete conversation history with Claude Code - including everything hidden from normal output
`claudeconvo` is a command-line utility that exposes the full Claude Code session data stored in `~/.claude/projects/`, revealing critical information that Claude Code doesn't display in its normal output. This includes subagent operations, hook executions, system reminders, performance metrics, background process monitoring, complete tool parameters and responses, error stack traces, session metadata, and API request IDs - essential for debugging, understanding Claude's internal decision-making, and troubleshooting issues that would otherwise be completely opaque.
## Quick Start
```bash
# Install claudeconvo
pip install claudeconvo
# Navigate to your Claude Code project
cd /path/to/your/project
# Launch interactive setup to configure your preferences
claudeconvo --setup
# Or just start viewing your most recent session
claudeconvo
```
The interactive setup (`--setup`) helps you:
- Choose a color theme that works with your terminal
- Select a formatting style (default, boxed, minimal, compact)
- Configure what information to display
- Preview your settings with sample output
- Save your preferences as defaults
## Why claudeconvo?
Claude Code intentionally hides most operational details during normal use. While it shows only user messages, assistant responses, and basic tool results, the session logs contain extensive data essential for debugging and optimization:
### Hidden Information Revealed by claudeconvo
- **Subagent/Task Operations** - See when Claude delegates work to specialized subagents and what internal analysis they perform
- **Hook Executions** - Monitor pre-commit, post-save, and user-prompt-submit hooks that modify your code or messages behind the scenes
- **System Reminders** - Internal context updates and state changes Claude receives but doesn't show you
- **Performance Metrics** - Track token usage (tokens-in/out) and request duration to optimize costs and identify bottlenecks
- **Background Process Monitoring** - BashOutput and KillBash operations for long-running commands
- **Complete Tool Details** - Full parameters and responses (normally truncated or hidden)
- **Error Stack Traces** - Complete error messages and warnings Claude handles silently
- **API Request IDs** - Unique identifiers for tracking issues with Anthropic support
- **Session Metadata** - UUIDs, parent/child relationships, and version information for understanding context flow
- **Slash Command Internals** - What `/docs`, `/test`, and other commands actually execute
- **Working Directory Context** - Path changes and file resolution details
- **Message Classification** - Internal priority levels and categorization
Without `claudeconvo`, these details remain completely opaque, making it impossible to understand Claude's decision-making, debug failures, or optimize your workflow.
## Features
- **Complete Conversation Display** - See the full dialogue including hidden system interactions
- **Hidden Information Exposure** - Reveal hooks, errors, metrics, and tool internals
- **Multiple Display Themes** - 8 color themes optimized for different terminals
- **Flexible Formatting** - Choose from default, boxed, minimal, or compact styles
- **Granular Filtering** - 19 display options to show/hide specific message types
- **Live Session Monitoring** - Watch mode (`-w`) for real-time session tracking
- **Performance Analytics** - Token usage and request duration metrics
- **Interactive Setup** - Visual configuration with live preview (`--setup`)
- **Configuration Persistence** - Save preferences as defaults
- **Adaptive Parser** - Handles different Claude log format versions automatically
- **No Dependencies** - Pure Python stdlib for maximum compatibility
## Installation
### Using pip
```bash
pip install claudeconvo
```
### From source
```bash
git clone https://github.com/lpasqualis/claudeconvo.git
cd claudeconvo
pip install -e .
```
## Usage
### Basic Usage
```bash
# 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
# View with specific theme and style
claudeconvo --theme light --style boxed
# View last 2 sessions
claudeconvo -n 2
```
### Message Types
`claudeconvo` can display various types of messages from Claude Code sessions:
- **User Messages** - Your input and questions
- **Assistant Messages** - Claude's responses
- **Tool Executions** - File reads, edits, searches, and other tool uses
- **System Messages** - Session auto-saves, checkpoints
- **Summaries** - Conversation summaries and context
- **Hook Executions** - Pre-commit, post-save, and other hooks
- **Slash Commands** - Commands like `/docs`, `/test`, etc.
- **Errors and Warnings** - Error messages with detailed information
- **Performance Metrics** - Request duration and token usage
### Filtering Options
Use single-letter flags to control what content is displayed:
```bash
# Show default content (user, assistant, and tool executions)
claudeconvo
# Show all content including metadata, performance, errors
claudeconvo -a
# Show summaries and metadata
claudeconvo -sm
# Show tool executions with full details (no truncation)
claudeconvo -ot
# Show performance metrics and token counts
claudeconvo -d
# Show hooks, commands, and errors
claudeconvo -hce
```
#### Available Options
- `q` - Show user messages
- `w` - Show assistant (Claude) messages
- `s` - Show session summaries
- `h` - Show hook executions (pre-commit, post-save, etc.)
- `m` - Show metadata (uuid, sessionId, version, etc.)
- `c` - Show slash command executions (/docs, /test, etc.)
- `y` - Show all system messages (auto-save, checkpoints, etc.)
- `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 (duration, tokens-in, tokens-out)
- `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
- `i` - Show AI model name/version
- `a` - Enable all options
- `?` - Print what will be shown/hidden and exit
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:
```bash
# Use light theme for white/light terminals
claudeconvo --theme light
# Use high contrast theme for accessibility
claudeconvo --theme high-contrast
# List all available themes
claudeconvo --theme
# Disable colors entirely
claudeconvo --no-color
```
Available themes:
- `dark` (default) - Optimized for dark terminal backgrounds
- `light` - Optimized for light/white terminal backgrounds (improved visibility)
- `solarized-dark` - Solarized dark color scheme
- `solarized-light` - Solarized light color scheme (improved for white backgrounds)
- `dracula` - Dracula color scheme
- `nord` - Nord color scheme
- `mono` - No colors (monochrome)
- `high-contrast` - Maximum contrast for accessibility
### Formatting Styles
Control how messages are displayed with different formatting styles:
```bash
# Use boxed style with borders around messages
claudeconvo --style boxed
# Use minimal style for clean, compact output
claudeconvo --style minimal
# Use compact style for condensed spacing
claudeconvo --style compact
# List all available styles
claudeconvo --style
```
Available styles:
- `default` - Standard formatting with clear labels
- `boxed` - Messages in boxes with borders
- `minimal` - Minimal decorations for clean output
- `compact` - Condensed spacing for more content
### Configuration
#### Interactive Setup
Use the interactive setup to visually configure your preferences:
```bash
# Launch interactive configuration
claudeconvo --setup
# Automated setup for testing (non-interactive)
claudeconvo --setup --ai "2 s2 t V /set" # Light theme, boxed style, tool details, view, save
```
The interactive setup provides:
- Side-by-side theme and style selection
- Two-column layout for display options (enabled/disabled)
- Live preview of your configuration with sample messages
- Quick commands: `V` or `Enter` to view sample, `X` to quick exit
- `/set` to save as defaults, `/reset` to restore original defaults
- All 19 display options accessible with single-letter toggles
- Compact command-line format display of current settings
#### Setting Defaults
Save your current settings as defaults:
```bash
# Try out settings
claudeconvo --theme light --style boxed -w
# If you like them, save as defaults
claudeconvo --theme light --style boxed -w --set-defaults
# Reset to original defaults
claudeconvo --reset-defaults
```
#### Config File
Create a `~/.claudeconvorc` file to set persistent preferences:
```json
{
"default_theme": "light",
"default_style": "boxed",
"default_show_options": "qwo",
"default_watch": true
}
```
#### Configuration Priority
Settings are applied in this order (highest to lowest priority):
1. Command-line arguments
2. Environment variables (`CLAUDECONVO_THEME`)
3. Config file (`~/.claudeconvorc`)
4. Built-in defaults
### Help and Available Sessions
```bash
# Show help
claudeconvo --help
# List available sessions
claudeconvo --list
# Show current configuration
claudeconvo --show-config
# Check what options would display (quote to protect ? from shell)
claudeconvo '-saH?'
```
## Requirements
- Python 3.8 or higher
- No external dependencies
## Development
### Setting up development environment
```bash
git clone https://github.com/lpasqualis/claudeconvo.git
cd claudeconvo
pip install -e ".[dev]"
```
### Running tests
```bash
pytest
```
### Code formatting and linting
```bash
black src/
ruff check src/
mypy src/
```
## License
MIT License - see [LICENSE](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](https://github.com/lpasqualis/claudeconvo/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "claudeconvo",
"maintainer": "Lorenzo Pasqualis",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "claude, claude-code, cli, session-viewer, conversation, log-viewer",
"author": "Lorenzo Pasqualis",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6b/ea/32a33923a88c65661b3f2dfae46075e127af7900d890e0591f5bb0b17501/claudeconvo-0.2.0.tar.gz",
"platform": null,
"description": "# claudeconvo\n\nReveal the complete conversation history with Claude Code - including everything hidden from normal output\n\n`claudeconvo` is a command-line utility that exposes the full Claude Code session data stored in `~/.claude/projects/`, revealing critical information that Claude Code doesn't display in its normal output. This includes subagent operations, hook executions, system reminders, performance metrics, background process monitoring, complete tool parameters and responses, error stack traces, session metadata, and API request IDs - essential for debugging, understanding Claude's internal decision-making, and troubleshooting issues that would otherwise be completely opaque.\n\n## Quick Start\n\n```bash\n# Install claudeconvo\npip install claudeconvo\n\n# Navigate to your Claude Code project\ncd /path/to/your/project\n\n# Launch interactive setup to configure your preferences\nclaudeconvo --setup\n\n# Or just start viewing your most recent session\nclaudeconvo\n```\n\nThe interactive setup (`--setup`) helps you:\n- Choose a color theme that works with your terminal\n- Select a formatting style (default, boxed, minimal, compact)\n- Configure what information to display\n- Preview your settings with sample output\n- Save your preferences as defaults\n\n## Why claudeconvo?\n\nClaude Code intentionally hides most operational details during normal use. While it shows only user messages, assistant responses, and basic tool results, the session logs contain extensive data essential for debugging and optimization:\n\n### Hidden Information Revealed by claudeconvo\n\n- **Subagent/Task Operations** - See when Claude delegates work to specialized subagents and what internal analysis they perform\n- **Hook Executions** - Monitor pre-commit, post-save, and user-prompt-submit hooks that modify your code or messages behind the scenes\n- **System Reminders** - Internal context updates and state changes Claude receives but doesn't show you\n- **Performance Metrics** - Track token usage (tokens-in/out) and request duration to optimize costs and identify bottlenecks\n- **Background Process Monitoring** - BashOutput and KillBash operations for long-running commands\n- **Complete Tool Details** - Full parameters and responses (normally truncated or hidden)\n- **Error Stack Traces** - Complete error messages and warnings Claude handles silently\n- **API Request IDs** - Unique identifiers for tracking issues with Anthropic support\n- **Session Metadata** - UUIDs, parent/child relationships, and version information for understanding context flow\n- **Slash Command Internals** - What `/docs`, `/test`, and other commands actually execute\n- **Working Directory Context** - Path changes and file resolution details\n- **Message Classification** - Internal priority levels and categorization\n\nWithout `claudeconvo`, these details remain completely opaque, making it impossible to understand Claude's decision-making, debug failures, or optimize your workflow.\n\n## Features\n\n- **Complete Conversation Display** - See the full dialogue including hidden system interactions\n- **Hidden Information Exposure** - Reveal hooks, errors, metrics, and tool internals\n- **Multiple Display Themes** - 8 color themes optimized for different terminals\n- **Flexible Formatting** - Choose from default, boxed, minimal, or compact styles\n- **Granular Filtering** - 19 display options to show/hide specific message types\n- **Live Session Monitoring** - Watch mode (`-w`) for real-time session tracking\n- **Performance Analytics** - Token usage and request duration metrics\n- **Interactive Setup** - Visual configuration with live preview (`--setup`)\n- **Configuration Persistence** - Save preferences as defaults\n- **Adaptive Parser** - Handles different Claude log format versions automatically\n- **No Dependencies** - Pure Python stdlib for maximum compatibility\n\n## Installation\n\n### Using pip\n\n```bash\npip install claudeconvo\n```\n\n### From source\n\n```bash\ngit clone https://github.com/lpasqualis/claudeconvo.git\ncd claudeconvo\npip install -e .\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# View the most recent session\nclaudeconvo\n\n# View a specific session by number\nclaudeconvo 3\n\n# View previous session\nclaudeconvo -1\n\n# Watch a session for new entries (tail mode)\nclaudeconvo -w\n\n# Watch a specific session\nclaudeconvo -f session-123 -w\n\n# View with specific theme and style\nclaudeconvo --theme light --style boxed\n\n# View last 2 sessions\nclaudeconvo -n 2\n```\n\n### Message Types\n\n`claudeconvo` can display various types of messages from Claude Code sessions:\n\n- **User Messages** - Your input and questions\n- **Assistant Messages** - Claude's responses\n- **Tool Executions** - File reads, edits, searches, and other tool uses\n- **System Messages** - Session auto-saves, checkpoints\n- **Summaries** - Conversation summaries and context\n- **Hook Executions** - Pre-commit, post-save, and other hooks\n- **Slash Commands** - Commands like `/docs`, `/test`, etc.\n- **Errors and Warnings** - Error messages with detailed information\n- **Performance Metrics** - Request duration and token usage\n\n### Filtering Options\n\nUse single-letter flags to control what content is displayed:\n\n```bash\n# Show default content (user, assistant, and tool executions)\nclaudeconvo\n\n# Show all content including metadata, performance, errors\nclaudeconvo -a\n\n# Show summaries and metadata\nclaudeconvo -sm\n\n# Show tool executions with full details (no truncation)\nclaudeconvo -ot\n\n# Show performance metrics and token counts\nclaudeconvo -d\n\n# Show hooks, commands, and errors\nclaudeconvo -hce\n```\n\n#### Available Options\n\n- `q` - Show user messages\n- `w` - Show assistant (Claude) messages\n- `s` - Show session summaries\n- `h` - Show hook executions (pre-commit, post-save, etc.)\n- `m` - Show metadata (uuid, sessionId, version, etc.)\n- `c` - Show slash command executions (/docs, /test, etc.)\n- `y` - Show all system messages (auto-save, checkpoints, etc.)\n- `t` - Show full tool details without truncation\n- `o` - Show tool executions\n- `e` - Show all error details and warnings\n- `r` - Show API request IDs\n- `f` - Show parent/child relationships\n- `u` - Show all content without truncation\n- `d` - Show performance metrics (duration, tokens-in, tokens-out)\n- `p` - Show working directory (cwd) for each message\n- `l` - Show message level/priority\n- `k` - Show sidechain/parallel messages\n- `v` - Show user type for each message\n- `i` - Show AI model name/version\n- `a` - Enable all options\n- `?` - Print what will be shown/hidden and exit\n\nUppercase letters disable options:\n- `aH` - Enable all except hooks\n- `Aqw` - Disable all, then enable only user and assistant messages\n\n### Color Themes\n\nChoose from multiple color themes optimized for different terminal backgrounds:\n\n```bash\n# Use light theme for white/light terminals\nclaudeconvo --theme light\n\n# Use high contrast theme for accessibility\nclaudeconvo --theme high-contrast\n\n# List all available themes\nclaudeconvo --theme\n\n# Disable colors entirely\nclaudeconvo --no-color\n```\n\nAvailable themes:\n- `dark` (default) - Optimized for dark terminal backgrounds\n- `light` - Optimized for light/white terminal backgrounds (improved visibility)\n- `solarized-dark` - Solarized dark color scheme\n- `solarized-light` - Solarized light color scheme (improved for white backgrounds)\n- `dracula` - Dracula color scheme\n- `nord` - Nord color scheme\n- `mono` - No colors (monochrome)\n- `high-contrast` - Maximum contrast for accessibility\n\n### Formatting Styles\n\nControl how messages are displayed with different formatting styles:\n\n```bash\n# Use boxed style with borders around messages\nclaudeconvo --style boxed\n\n# Use minimal style for clean, compact output\nclaudeconvo --style minimal\n\n# Use compact style for condensed spacing\nclaudeconvo --style compact\n\n# List all available styles\nclaudeconvo --style\n```\n\nAvailable styles:\n- `default` - Standard formatting with clear labels\n- `boxed` - Messages in boxes with borders\n- `minimal` - Minimal decorations for clean output\n- `compact` - Condensed spacing for more content\n\n### Configuration\n\n#### Interactive Setup\n\nUse the interactive setup to visually configure your preferences:\n\n```bash\n# Launch interactive configuration\nclaudeconvo --setup\n\n# Automated setup for testing (non-interactive)\nclaudeconvo --setup --ai \"2 s2 t V /set\" # Light theme, boxed style, tool details, view, save\n```\n\nThe interactive setup provides:\n- Side-by-side theme and style selection\n- Two-column layout for display options (enabled/disabled)\n- Live preview of your configuration with sample messages\n- Quick commands: `V` or `Enter` to view sample, `X` to quick exit\n- `/set` to save as defaults, `/reset` to restore original defaults\n- All 19 display options accessible with single-letter toggles\n- Compact command-line format display of current settings\n\n#### Setting Defaults\n\nSave your current settings as defaults:\n\n```bash\n# Try out settings\nclaudeconvo --theme light --style boxed -w\n\n# If you like them, save as defaults\nclaudeconvo --theme light --style boxed -w --set-defaults\n\n# Reset to original defaults\nclaudeconvo --reset-defaults\n```\n\n#### Config File\n\nCreate a `~/.claudeconvorc` file to set persistent preferences:\n\n```json\n{\n \"default_theme\": \"light\",\n \"default_style\": \"boxed\",\n \"default_show_options\": \"qwo\",\n \"default_watch\": true\n}\n```\n\n#### Configuration Priority\n\nSettings are applied in this order (highest to lowest priority):\n1. Command-line arguments\n2. Environment variables (`CLAUDECONVO_THEME`)\n3. Config file (`~/.claudeconvorc`)\n4. Built-in defaults\n\n### Help and Available Sessions\n\n```bash\n# Show help\nclaudeconvo --help\n\n# List available sessions\nclaudeconvo --list\n\n# Show current configuration\nclaudeconvo --show-config\n\n# Check what options would display (quote to protect ? from shell)\nclaudeconvo '-saH?'\n```\n\n## Requirements\n\n- Python 3.8 or higher\n- No external dependencies\n\n## Development\n\n### Setting up development environment\n\n```bash\ngit clone https://github.com/lpasqualis/claudeconvo.git\ncd claudeconvo\npip install -e \".[dev]\"\n```\n\n### Running tests\n\n```bash\npytest\n```\n\n### Code formatting and linting\n\n```bash\nblack src/\nruff check src/\nmypy src/\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Author\n\nLorenzo Pasqualis\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## Support\n\nIf you encounter any problems or have suggestions, please [open an issue](https://github.com/lpasqualis/claudeconvo/issues).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "View Claude Code session history as a conversation",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/lpasqualis/claudeconvo#readme",
"Homepage": "https://github.com/lpasqualis/claudeconvo",
"Issues": "https://github.com/lpasqualis/claudeconvo/issues",
"Repository": "https://github.com/lpasqualis/claudeconvo"
},
"split_keywords": [
"claude",
" claude-code",
" cli",
" session-viewer",
" conversation",
" log-viewer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fb05f284ae2e8a3a167c26d556c6bb4b1b73cd765f9f4874c04e549d5b49f408",
"md5": "53c2ed60a8a4b1fc28b45fb5610ab8e7",
"sha256": "425c8b26a41b892ce9bed002924a8387cdd5f758bec22cf156757c2836d4b47c"
},
"downloads": -1,
"filename": "claudeconvo-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53c2ed60a8a4b1fc28b45fb5610ab8e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 67421,
"upload_time": "2025-09-09T18:05:15",
"upload_time_iso_8601": "2025-09-09T18:05:15.027877Z",
"url": "https://files.pythonhosted.org/packages/fb/05/f284ae2e8a3a167c26d556c6bb4b1b73cd765f9f4874c04e549d5b49f408/claudeconvo-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6bea32a33923a88c65661b3f2dfae46075e127af7900d890e0591f5bb0b17501",
"md5": "2371b1c3330ff9e3ffe8d1d8d384c61e",
"sha256": "d940bba3ebf3db5e720a21b1ab51bc07dd82c26eba031f9fbfa89dbbc4abe01a"
},
"downloads": -1,
"filename": "claudeconvo-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "2371b1c3330ff9e3ffe8d1d8d384c61e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 64225,
"upload_time": "2025-09-09T18:05:15",
"upload_time_iso_8601": "2025-09-09T18:05:15.943528Z",
"url": "https://files.pythonhosted.org/packages/6b/ea/32a33923a88c65661b3f2dfae46075e127af7900d890e0591f5bb0b17501/claudeconvo-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 18:05:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lpasqualis",
"github_project": "claudeconvo#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claudeconvo"
}
JSON
