{"id":29806256,"url":"https://github.com/jimmc414/cctrace","last_synced_at":"2025-09-17T22:48:32.099Z","repository":{"id":302575043,"uuid":"1012911007","full_name":"jimmc414/cctrace","owner":"jimmc414","description":"Claude Code Trace - Export Claude Code chat sessions into markdown and XML","archived":false,"fork":false,"pushed_at":"2025-07-07T14:29:25.000Z","size":211,"stargazers_count":94,"open_issues_count":1,"forks_count":8,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-28T14:16:32.556Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimmc414.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-03T04:43:25.000Z","updated_at":"2025-07-28T02:41:43.000Z","dependencies_parsed_at":"2025-07-03T05:33:10.335Z","dependency_job_id":"2a2d5842-42f3-4edf-a4a2-3fdef78bc2ea","html_url":"https://github.com/jimmc414/cctrace","commit_stats":null,"previous_names":["jimmc414/cctrace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jimmc414/cctrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmc414%2Fcctrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmc414%2Fcctrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmc414%2Fcctrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmc414%2Fcctrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimmc414","download_url":"https://codeload.github.com/jimmc414/cctrace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimmc414%2Fcctrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275680297,"owners_count":25508570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-28T14:05:55.071Z","updated_at":"2025-09-17T22:48:32.047Z","avatar_url":"https://github.com/jimmc414.png","language":"Python","funding_links":[],"categories":["监控与分析","Tools \u0026 Utilities"],"sub_categories":[],"readme":"# Claude Code Trace\n\nA command-line tool that exports Claude Code chat sessions with conversation history, internal reasoning blocks, tool usage, and comprehensive metadata in XML and in markdown.\n\n## Features\n\n- **Automatic Session Detection**: Intelligently identifies your current Claude Code session, returns the session id, transcript and all session metadata, even with multiple concurrent sessions.\n- **Complete Export**: Captures all messages, thinking blocks, tool uses, and responses\n- **PID Cross Reference Validation**: Cross reference PID to ensure the correct session is exported\n- **Multiple Output Formats**: Generates Markdown, JSON, and raw JSONL files\n- **Session Statistics**: Provides detailed metrics about your conversation\n- **Slash Command Integration**: Export directly from Claude Code with `/export`\n- **Timestamped Archives**: Each export is saved with timestamp and session ID\n- **Auto-Copy to Working Directory**: Automatically copies export to your current directory (configurable)\n\n![image](https://github.com/user-attachments/assets/b316bd46-94f0-44ef-8030-e73b393cb119)\n\n![image](https://github.com/user-attachments/assets/5c3ff16a-7470-408c-87de-a6a1aabd33b3)\n\n\n\n## Requirements\n\n- Python \u003e 3.6\n- Claude Code running on Linux or WSL\n- Access to `~/.claude/projects/` directory\n\n## Quick Start\n\n```bash\n# Clone or download this repository\ngit clone https://github.com/jimmc414/cctrace.git\ncd cctrace\n\n# Run the installer\nchmod +x setup.sh\n./setup.sh\n\n# Use in Claude Code\n/user:export\n# Or\n/export\n```\n\n## Installation\n\n### Automated Installation\n\n1. Run the installation script:\n   ```bash\n   ./setup.sh\n   ```\n\n2. The installer will:\n   - Create necessary directories\n   - Copy files to appropriate locations\n   - Set up the slash command\n   - Verify the installation\n\n### Manual Installation\n\n1. Copy the export script:\n   ```bash\n   mkdir -p ~/claude_sessions\n   cp export_claude_session.py ~/claude_sessions/\n   chmod +x ~/claude_sessions/export_claude_session.py\n   ```\n\n2. Install the slash command:\n   ```bash\n   mkdir -p ~/.claude/commands\n   cp export.md ~/.claude/commands/\n   ```\n\n## Usage\n\n### Using the Slash Command (Recommended)\n\nIn any Claude Code session, simply type:\n```\n/user:export\n```\nor \n```\n/export\n```\n\nThis will:\n1. Automatically detect your current session\n2. Export all conversation data\n3. Display a summary directly in Claude Code\n\n### Using the Command Line\n\n```bash\n# Export current active session\npython3 ~/claude_sessions/export_claude_session.py\n\n# Export with custom options\npython3 ~/claude_sessions/export_claude_session.py --max-age 600\n\n# Export specific session by ID\npython3 ~/claude_sessions/export_claude_session.py --session-id f33cdb42-0a41-40d4-91eb-c89c109af38a\n\n# Export to custom directory\npython3 ~/claude_sessions/export_claude_session.py --output-dir /path/to/exports\n```\n\n### Command Line Options\n\n- `--session-id \u003cuuid\u003e`: Export a specific session by ID\n- `--max-age \u003cseconds\u003e`: Set the maximum age for active session detection (default: 300)\n- `--output-dir \u003cpath\u003e`: Specify custom output directory\n- `--format \u003cmd|xml|all\u003e`: Choose output format (default: all)\n- `--no-copy-to-cwd`: Do not copy export to current directory\n\n## Export Contents\n\nEach export creates a timestamped directory containing:\n\n```\n~/claude_sessions/exports/2025-07-02_16-45-00_f33cdb42/\n├── session_info.json      # Complete session metadata including SESSION ID\n├── conversation_full.md   # Human-readable conversation with all content\n├── conversation_full.xml  # Fully labeled XML with complete metadata\n├── raw_messages.jsonl     # Original JSONL data with all fields\n└── summary.txt            # Quick overview with session ID and statistics\n```\n\n### Detailed File Contents\n\n#### **session_info.json** - Complete Session Metadata\nContains ALL session metadata including:\n- **Session ID** (unique identifier for your chat session)\n- Project directory path\n- Start and end timestamps\n- Total message counts by type\n- Models used\n- Token usage statistics\n\nExample:\n```json\n{\n  \"session_id\": \"f33cdb42-0a41-40d4-91eb-c89c109af38a\",\n  \"project_dir\": \"/mnt/c/python/myproject\",\n  \"start_time\": \"2025-07-02T20:06:59.614Z\",\n  \"end_time\": \"2025-07-02T21:39:11.037Z\",\n  \"total_messages\": 145,\n  \"user_messages\": 58,\n  \"assistant_messages\": 87,\n  \"tool_uses\": 42,\n  \"models_used\": [\"claude-opus-4-20250514\"]\n}\n```\n\n#### **conversation_full.xml** - Complete XML Export\nComprehensive XML format with FULL metadata labeling:\n- **Session-level metadata**: Session ID, version, timestamps, working directory\n- **Message-level metadata**: \n  - UUID and parent-UUID for message relationships\n  - Event types and request IDs\n  - Role (user/assistant) and model information\n- **Content preservation**:\n  - Text messages with proper encoding\n  - Thinking blocks with cryptographic signatures\n  - Tool uses with complete input/output data\n  - Tool execution metadata (response codes, duration, bytes)\n- **Token usage per message**: Input/output tokens, cache tokens, service tier\n\nExample XML structure:\n```xml\n\u003cclaude-session xmlns=\"https://claude.ai/session-export/v1\" export-version=\"1.0\"\u003e\n  \u003cmetadata\u003e\n    \u003csession-id\u003ef33cdb42-0a41-40d4-91eb-c89c109af38a\u003c/session-id\u003e\n    \u003cworking-directory\u003e/mnt/c/python/myproject\u003c/working-directory\u003e\n    \u003cstart-time\u003e2025-07-02T20:06:59.614Z\u003c/start-time\u003e\n    \u003cexport-time\u003e2025-07-02T22:15:00.000Z\u003c/export-time\u003e\n  \u003c/metadata\u003e\n  \u003cmessages\u003e\n    \u003cmessage uuid=\"492b16e4-af89-408f-b144-ae571d4047b5\" \n             parent-uuid=\"null\" \n             timestamp=\"2025-07-02T20:06:59.614Z\"\u003e\n      \u003crole\u003euser\u003c/role\u003e\n      \u003ccontent\u003e\n        \u003ctext\u003eYour message here\u003c/text\u003e\n      \u003c/content\u003e\n    \u003c/message\u003e\n    \u003cmessage uuid=\"6892a3b3-63cf-4052-8f3f-850dca83d50c\" \n             parent-uuid=\"492b16e4-af89-408f-b144-ae571d4047b5\"\n             timestamp=\"2025-07-02T20:07:07.357Z\"\u003e\n      \u003crole\u003eassistant\u003c/role\u003e\n      \u003cmodel\u003eclaude-opus-4-20250514\u003c/model\u003e\n      \u003ccontent\u003e\n        \u003cthinking signature=\"Es0ICkYIBRgCKkCeXs4...\"\u003e\n          Internal reasoning content\n        \u003c/thinking\u003e\n        \u003ctext\u003eAssistant response\u003c/text\u003e\n        \u003ctool-use id=\"toolu_01ABC...\" name=\"Bash\"\u003e\n          \u003cinput\u003e{\"command\": \"ls -la\", \"description\": \"List files\"}\u003c/input\u003e\n        \u003c/tool-use\u003e\n      \u003c/content\u003e\n      \u003cusage\u003e\n        \u003cinput-tokens\u003e1500\u003c/input-tokens\u003e\n        \u003coutput-tokens\u003e750\u003c/output-tokens\u003e\n        \u003ccache-creation-tokens\u003e0\u003c/cache-creation-tokens\u003e\n        \u003cservice-tier\u003estandard\u003c/service-tier\u003e\n      \u003c/usage\u003e\n    \u003c/message\u003e\n  \u003c/messages\u003e\n\u003c/claude-session\u003e\n```\n\n#### **conversation_full.md** - Human-Readable Export\nMarkdown format including:\n- Session ID prominently displayed at the top\n- All user messages and assistant responses\n- Collapsible thinking/reasoning blocks\n- Tool usage with inputs and outputs\n- Timestamps for each interaction\n\n#### **raw_messages.jsonl** - Original Data\nComplete, unmodified JSONL file containing:\n- Every field from the original Claude Code session\n- Session IDs, UUIDs, parent relationships\n- All metadata exactly as stored by Claude Code\n- Perfect for programmatic processing or analysis\n\n#### **summary.txt** - Quick Reference\nPlain text summary featuring:\n- Session ID for easy reference\n- Export timestamp\n- Key statistics\n- File locations\n\n### Export Formats\n\nBy default, the tool exports **both** Markdown and XML formats to give you maximum flexibility.\n\n#### Markdown (`--format md`)\nProvides a clean, human-readable view of your conversation with collapsible sections for internal reasoning. Perfect for reviewing conversations and sharing with others.\n\n#### XML (`--format xml`)\nPreserves all available data fields in a structured format:\n- Session metadata and statistics\n- Message hierarchy with UUID relationships\n- Complete tool usage information including execution times and response codes\n- Thinking blocks with cryptographic signatures\n- All token usage statistics\n- Suitable for XSLT transformations and automated processing\n\n#### All Formats (`--format all`) - **Default**\nGenerates both Markdown and XML outputs in the same export, giving you the best of both worlds:\n- Human-readable Markdown for easy review\n- Machine-parseable XML with complete data preservation\n\n## Auto-Copy to Working Directory\n\nBy default, the export tool automatically copies the complete export folder to your current working directory with the name `claude_export_YYYY-MM-DD_HH-MM-SS_sessionid`. This makes it easy to:\n- Include exports in your project repository\n- Access exports without navigating to `~/claude_sessions/exports/`\n- Keep exports with the relevant project code\n\n### Disabling Auto-Copy\n\nYou can disable this feature in three ways:\n\n1. **Command line flag:**\n   ```bash\n   python3 export_claude_session.py --no-copy-to-cwd\n   ```\n\n2. **Environment variable:**\n   ```bash\n   export CLAUDE_EXPORT_COPY_TO_CWD=false\n   python3 export_claude_session.py\n   ```\n\n3. **In your shell configuration:**\n   ```bash\n   # Add to ~/.bashrc or ~/.zshrc\n   export CLAUDE_EXPORT_COPY_TO_CWD=false\n   ```\n\nThe copied folders are automatically excluded from git via the `.gitignore` pattern `claude_export_*/`.\n\n## How It Works\n\n### Session Detection Process\n\n1. **Project Mapping**: Converts your current directory to Claude's naming convention\n2. **Session Discovery**: Finds all JSONL files in `~/.claude/projects/\u003cproject-name\u003e/`\n3. **Active Session Detection**: Identifies sessions modified within the last 5 minutes\n4. **PID Validation**: When multiple active sessions exist:\n   - Detects the parent Claude process PID\n   - Creates a temporary marker file\n   - Identifies which session file responds to the marker\n   - Ensures the correct session is exported\n\n### Multiple Concurrent Sessions\n\nThe tool handles multiple Claude Code sessions running in the same directory by:\n- Using process hierarchy to identify the calling Claude instance\n- Employing file activity detection to correlate sessions\n- Providing clear feedback about which session is being exported\n- Falling back gracefully when automatic detection isn't possible\n\n## Troubleshooting\n\n### \"No Claude Code sessions found\"\n- Ensure you're running from a directory with active Claude Code sessions\n- Check that `~/.claude/projects/` exists and contains your project\n\n### \"Could not identify specific session\"\n- The tool will default to the most recently active session\n- Use `--session-id` to manually specify a session\n- Ensure the session file has been recently modified\n\n### Permission Errors\n- Verify you have read access to `~/.claude/projects/`\n- Ensure write permissions for the export directory\n\n### Session Not Updating\n- Claude Code writes to JSONL files in real-time\n- If a session appears stale, try sending a message to trigger an update\n\n\n### Development\n\nThe tool uses only Python standard library modules, making it dependency-free and easy to deploy.\n\nKey functions:\n- `get_parent_claude_pid()`: Detects if running inside Claude Code\n- `identify_current_session()`: Correlates process with session file\n- `parse_jsonl_file()`: Extracts and processes conversation data\n- `format_message_markdown()`: Converts messages to readable format\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmc414%2Fcctrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimmc414%2Fcctrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimmc414%2Fcctrace/lists"}