# Claude Conversation Extractor
A powerful command-line tool to extract specific conversations from Claude export files and convert them to readable markdown format.
## 🚀 Status: Production Ready
This tool is **fully implemented and tested** with real Claude export data. It successfully processes large export files (tested with 728+ conversations) using memory-efficient streaming JSON parsing.
## Features
- 🎯 **UUID-based Extraction**: Find and extract conversations by their unique identifier
- 📝 **Markdown Conversion**: Convert conversations to clean, readable markdown
- 🔍 **Conversation Discovery**: List available conversations in export files
- 🚀 **High Performance**: Efficiently handle large export files using streaming JSON parsing
- 🎨 **Rich CLI**: Beautiful terminal interface with progress indicators and emojis
- 🛡️ **Error Handling**: Graceful error handling and validation
- 💾 **Memory Efficient**: Processes large files without loading everything into memory
- 🧪 **Fully Tested**: Comprehensive test suite with 100% pass rate
## Quick Start
### Installation
#### Option 1: From PyPI (Recommended)
```bash
# Install system-wide
pip install claude-chat-extractor
# Or install for current user only
pip install --user claude-chat-extractor
```
#### Option 2: From Source
```bash
# Clone the repository
git clone <repository-url>
cd claude-conversation-extractor
# Install dependencies
uv sync
# Install the tool
pip install .
```
#### Option 3: Platform-Specific
- **macOS**: `pipx install claude-conversation-extractor` (recommended) or `brew install claude-conversation-extractor`
- **Linux**: Use distribution package managers or build scripts
- **Windows**: Use Chocolatey, Scoop, or build executable
📖 **See [Installation Guide](docs/installation.md) for detailed instructions**
### Basic Usage
```bash
# List available conversations (shows first 10 by default)
claude-extract list-conversations -i data/conversations.json
# Extract a specific conversation
claude-extract extract \
-u 28d595a3-5db0-492d-a49a-af74f13de505 \
-i data/conversations.json \
-o my_conversation.md
```
## Available Commands
After installation, the tool is available system-wide and can be invoked using any of these names:
- `claude-extract` (recommended)
- `cce` (shortest)
- `claude-conversation-extractor` (full name)
### System-wide Availability
Once installed, you can use the tool from any directory:
```bash
# From anywhere on your system
cce --help
cce list -i /path/to/conversations.json
cce extract -u <uuid> -i /path/to/conversations.json
```
### Extract Command
Extract a conversation by UUID and convert to markdown:
```bash
claude-extract extract -u <uuid> -i <input.json> -o <output.md>
# or
cce extract -u <uuid> -i <input.json> -o <output.md>
```
**Options:**
- `-u, --uuid`: UUID of the conversation to extract (required)
- `-i, --input`: Path to the Claude export JSON file (required)
- `-o, --output`: Output markdown file path (optional, defaults to `<uuid>.md`)
- `-v, --verbose`: Enable verbose output
### List Command
List available conversations in an export file:
```bash
claude-extract list-conversations -i <input.json> -l 10
# or
cce list-conversations -i <input.json> -l 10
```
**Options:**
- `-i, --input`: Path to the Claude export JSON file (required)
- `-l, --limit`: Maximum number of conversations to list (default: 10)
## Input Format
The tool expects a JSON file with Claude export data containing:
- Conversation metadata (UUID, name, timestamps)
- Chat messages with sender information
- Content with timestamps and citations
- File attachments and references
## Output Format
Generated markdown includes:
- Conversation header with metadata
- Chronological message flow
- Clear sender identification (Human/Claude) with emojis
- Timestamps and formatting
- Attachment information
## Performance & Scalability
- **Streaming Processing**: Uses `ijson` for memory-efficient JSON parsing
- **Large File Support**: Successfully tested with 44MB+ export files
- **Fast UUID Lookup**: Efficient conversation search without loading entire file
## 📦 Distribution & Installation
### Package Managers
- **PyPI**: `pip install claude-chat-extractor`
- **Homebrew**: `brew install claude-chat-extractor` (macOS)
- **Chocolatey**: `choco install claude-chat-extractor` (Windows)
- **Scoop**: `scoop install claude-chat-extractor` (Windows)
### Build Scripts
- **Linux**: `./scripts/build-linux.sh` - Creates .deb, .rpm, and Arch packages
- **Windows**: `python scripts/build-windows.py` - Creates standalone executable
### Docker
```bash
docker run --rm -v $(pwd):/work yourusername/claude-conversation-extractor --help
```
📖 **See [Distribution Guide](docs/distribution.md) for detailed build instructions**
- **Memory Usage**: Constant memory usage regardless of file size
## Development
### Project Structure
```
claude-conversation-extractor/
├── src/claude_conversation_extractor/
│ ├── __init__.py
│ ├── models.py # Pydantic data models
│ ├── extractor.py # Core extraction logic with streaming
│ ├── markdown_converter.py # Markdown formatting
│ └── cli.py # Command-line interface with Rich
├── tests/ # Test suite (7 tests, 100% pass rate)
├── docs/ # Documentation
└── pyproject.toml # Project configuration with UV
```
### Running Tests
```bash
# Run all tests
uv run pytest tests/ -v
# Run with coverage (if pytest-cov is installed)
uv run pytest tests/ --cov=src/
```
### Development Setup
```bash
# Install in development mode
uv sync --dev
# Run the tool
uv run claude-extract --help
```
## Requirements
- Python 3.12+
- UV package manager
- Claude export JSON file
## Dependencies
- **Click**: Command-line interface framework
- **Pydantic**: Data validation and serialization
- **Rich**: Enhanced terminal output with colors and formatting
- **ijson**: Streaming JSON parser for memory efficiency
- **Pytest**: Testing framework
- **MyPy**: Static type checking
- **Ruff**: Fast Python linter and formatter
## Documentation
- [Requirements](docs/requirements.md) - Detailed project requirements and specifications
- [Usage Guide](docs/usage.md) - Comprehensive usage instructions and examples
- [Implementation Status](docs/implementation-status.md) - Current implementation details and technical overview
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: `uv run pytest tests/ -v`
6. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For issues and questions, please open an issue on GitHub.
## Recent Updates
- ✅ **v0.1.0**: Initial release with full functionality
- ✅ Streaming JSON processing for large files
- ✅ Complete CLI with extract and list commands
- ✅ Comprehensive test suite
- ✅ Type-safe implementation with Pydantic models
- ✅ Memory-efficient processing architecture
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-chat-extractor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "anthropic, claude, cli, conversation, extractor, markdown",
"author": null,
"author_email": "Jorge MB <jmorenobl@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/11/38/d3e11aeab0c8d7f51a4050db923e2c62ebdcd59d3de247fca63288bd3396/claude_chat_extractor-0.2.1.tar.gz",
"platform": null,
"description": "# Claude Conversation Extractor\n\nA powerful command-line tool to extract specific conversations from Claude export files and convert them to readable markdown format.\n\n## \ud83d\ude80 Status: Production Ready\n\nThis tool is **fully implemented and tested** with real Claude export data. It successfully processes large export files (tested with 728+ conversations) using memory-efficient streaming JSON parsing.\n\n## Features\n\n- \ud83c\udfaf **UUID-based Extraction**: Find and extract conversations by their unique identifier\n- \ud83d\udcdd **Markdown Conversion**: Convert conversations to clean, readable markdown\n- \ud83d\udd0d **Conversation Discovery**: List available conversations in export files\n- \ud83d\ude80 **High Performance**: Efficiently handle large export files using streaming JSON parsing\n- \ud83c\udfa8 **Rich CLI**: Beautiful terminal interface with progress indicators and emojis\n- \ud83d\udee1\ufe0f **Error Handling**: Graceful error handling and validation\n- \ud83d\udcbe **Memory Efficient**: Processes large files without loading everything into memory\n- \ud83e\uddea **Fully Tested**: Comprehensive test suite with 100% pass rate\n\n## Quick Start\n\n### Installation\n\n#### Option 1: From PyPI (Recommended)\n```bash\n# Install system-wide\npip install claude-chat-extractor\n\n# Or install for current user only\npip install --user claude-chat-extractor\n```\n\n#### Option 2: From Source\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd claude-conversation-extractor\n\n# Install dependencies\nuv sync\n\n# Install the tool\npip install .\n```\n\n#### Option 3: Platform-Specific\n- **macOS**: `pipx install claude-conversation-extractor` (recommended) or `brew install claude-conversation-extractor`\n- **Linux**: Use distribution package managers or build scripts\n- **Windows**: Use Chocolatey, Scoop, or build executable\n\n\ud83d\udcd6 **See [Installation Guide](docs/installation.md) for detailed instructions**\n\n### Basic Usage\n\n```bash\n# List available conversations (shows first 10 by default)\nclaude-extract list-conversations -i data/conversations.json\n\n# Extract a specific conversation\nclaude-extract extract \\\n -u 28d595a3-5db0-492d-a49a-af74f13de505 \\\n -i data/conversations.json \\\n -o my_conversation.md\n```\n\n## Available Commands\n\nAfter installation, the tool is available system-wide and can be invoked using any of these names:\n- `claude-extract` (recommended)\n- `cce` (shortest)\n- `claude-conversation-extractor` (full name)\n\n### System-wide Availability\nOnce installed, you can use the tool from any directory:\n```bash\n# From anywhere on your system\ncce --help\ncce list -i /path/to/conversations.json\ncce extract -u <uuid> -i /path/to/conversations.json\n```\n\n### Extract Command\nExtract a conversation by UUID and convert to markdown:\n```bash\nclaude-extract extract -u <uuid> -i <input.json> -o <output.md>\n# or\ncce extract -u <uuid> -i <input.json> -o <output.md>\n```\n\n**Options:**\n- `-u, --uuid`: UUID of the conversation to extract (required)\n- `-i, --input`: Path to the Claude export JSON file (required)\n- `-o, --output`: Output markdown file path (optional, defaults to `<uuid>.md`)\n- `-v, --verbose`: Enable verbose output\n\n### List Command\nList available conversations in an export file:\n```bash\nclaude-extract list-conversations -i <input.json> -l 10\n# or\ncce list-conversations -i <input.json> -l 10\n```\n\n**Options:**\n- `-i, --input`: Path to the Claude export JSON file (required)\n- `-l, --limit`: Maximum number of conversations to list (default: 10)\n\n## Input Format\n\nThe tool expects a JSON file with Claude export data containing:\n- Conversation metadata (UUID, name, timestamps)\n- Chat messages with sender information\n- Content with timestamps and citations\n- File attachments and references\n\n## Output Format\n\nGenerated markdown includes:\n- Conversation header with metadata\n- Chronological message flow\n- Clear sender identification (Human/Claude) with emojis\n- Timestamps and formatting\n- Attachment information\n\n## Performance & Scalability\n\n- **Streaming Processing**: Uses `ijson` for memory-efficient JSON parsing\n- **Large File Support**: Successfully tested with 44MB+ export files\n- **Fast UUID Lookup**: Efficient conversation search without loading entire file\n\n## \ud83d\udce6 Distribution & Installation\n\n### Package Managers\n- **PyPI**: `pip install claude-chat-extractor`\n- **Homebrew**: `brew install claude-chat-extractor` (macOS)\n- **Chocolatey**: `choco install claude-chat-extractor` (Windows)\n- **Scoop**: `scoop install claude-chat-extractor` (Windows)\n\n### Build Scripts\n- **Linux**: `./scripts/build-linux.sh` - Creates .deb, .rpm, and Arch packages\n- **Windows**: `python scripts/build-windows.py` - Creates standalone executable\n\n### Docker\n```bash\ndocker run --rm -v $(pwd):/work yourusername/claude-conversation-extractor --help\n```\n\n\ud83d\udcd6 **See [Distribution Guide](docs/distribution.md) for detailed build instructions**\n- **Memory Usage**: Constant memory usage regardless of file size\n\n## Development\n\n### Project Structure\n```\nclaude-conversation-extractor/\n\u251c\u2500\u2500 src/claude_conversation_extractor/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 models.py # Pydantic data models\n\u2502 \u251c\u2500\u2500 extractor.py # Core extraction logic with streaming\n\u2502 \u251c\u2500\u2500 markdown_converter.py # Markdown formatting\n\u2502 \u2514\u2500\u2500 cli.py # Command-line interface with Rich\n\u251c\u2500\u2500 tests/ # Test suite (7 tests, 100% pass rate)\n\u251c\u2500\u2500 docs/ # Documentation\n\u2514\u2500\u2500 pyproject.toml # Project configuration with UV\n```\n\n### Running Tests\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Run with coverage (if pytest-cov is installed)\nuv run pytest tests/ --cov=src/\n```\n\n### Development Setup\n```bash\n# Install in development mode\nuv sync --dev\n\n# Run the tool\nuv run claude-extract --help\n```\n\n## Requirements\n\n- Python 3.12+\n- UV package manager\n- Claude export JSON file\n\n## Dependencies\n\n- **Click**: Command-line interface framework\n- **Pydantic**: Data validation and serialization\n- **Rich**: Enhanced terminal output with colors and formatting\n- **ijson**: Streaming JSON parser for memory efficiency\n- **Pytest**: Testing framework\n- **MyPy**: Static type checking\n- **Ruff**: Fast Python linter and formatter\n\n## Documentation\n\n- [Requirements](docs/requirements.md) - Detailed project requirements and specifications\n- [Usage Guide](docs/usage.md) - Comprehensive usage instructions and examples\n- [Implementation Status](docs/implementation-status.md) - Current implementation details and technical overview\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass: `uv run pytest tests/ -v`\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues and questions, please open an issue on GitHub.\n\n## Recent Updates\n\n- \u2705 **v0.1.0**: Initial release with full functionality\n- \u2705 Streaming JSON processing for large files\n- \u2705 Complete CLI with extract and list commands\n- \u2705 Comprehensive test suite\n- \u2705 Type-safe implementation with Pydantic models\n- \u2705 Memory-efficient processing architecture\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A command-line tool to extract and convert Claude conversations to markdown format efficiently.",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/jmorenobl/claude-conversation-extractor#readme",
"Homepage": "https://github.com/jmorenobl/claude-conversation-extractor",
"Issues": "https://github.com/jmorenobl/claude-conversation-extractor/issues",
"Repository": "https://github.com/jmorenobl/claude-conversation-extractor.git"
},
"split_keywords": [
"anthropic",
" claude",
" cli",
" conversation",
" extractor",
" markdown"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a8811be542e401007a2ca5ca1d5e24dbb0e8354cf5c2b1c993a84f446fe7425e",
"md5": "b75ba67f2421eb3e16a0135b9f87c13c",
"sha256": "3e56a08e437191a3cf0269202220157bf879979385bc0a9febaf578052ad80ad"
},
"downloads": -1,
"filename": "claude_chat_extractor-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b75ba67f2421eb3e16a0135b9f87c13c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10719,
"upload_time": "2025-08-13T07:38:43",
"upload_time_iso_8601": "2025-08-13T07:38:43.113545Z",
"url": "https://files.pythonhosted.org/packages/a8/81/1be542e401007a2ca5ca1d5e24dbb0e8354cf5c2b1c993a84f446fe7425e/claude_chat_extractor-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1138d3e11aeab0c8d7f51a4050db923e2c62ebdcd59d3de247fca63288bd3396",
"md5": "2d08dea09ff04fe0e5ae77670e59faf6",
"sha256": "8ad0ed1b44ec017d0de820a9db64d49a31b7f7b23a7955fc2b687f21473c3d50"
},
"downloads": -1,
"filename": "claude_chat_extractor-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "2d08dea09ff04fe0e5ae77670e59faf6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 72575,
"upload_time": "2025-08-13T07:38:44",
"upload_time_iso_8601": "2025-08-13T07:38:44.268671Z",
"url": "https://files.pythonhosted.org/packages/11/38/d3e11aeab0c8d7f51a4050db923e2c62ebdcd59d3de247fca63288bd3396/claude_chat_extractor-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 07:38:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jmorenobl",
"github_project": "claude-conversation-extractor#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-chat-extractor"
}
JSON
