This repository documents in-depth investigations into how Claude Code works internally and how to use it effectively. We analyze Claude Code’s source code, features, and capabilities to understand its architecture and provide comprehensive documentation for advanced usage.

.
├── archive/             # Claude Code source versions
│   └── changelog/       # Generated changelogs for each version
├── tools/               # Archive management tools
│   └── sync.py          # Automated sync tool for all operations
├── features/            # User-facing features and capabilities
│   ├── background-shells.org
│   ├── github-actions.org
│   ├── mcp.org
│   ├── hooks.org
│   ├── keyboard-shortcuts.org
│   ├── notifications.org
│   ├── queued-prompts.org
│   ├── thinking.org
│   ├── settings.org
│   ├── environment-variables.org
│   ├── spinner-words.org
│   └── security-review.org
├── internals/           # Technical internals and protocols
│   ├── websocket-protocol.org
│   ├── diff-spec.org
│   ├── session-log-format.org
│   ├── microcompaction.org
│   ├── recursion-stack.org
│   ├── caching.org
│   ├── telemetry.org
│   └── root-detection.org
└── CLAUDE.md           # Instructions for Claude Code when working here

• Settings - Multi-layered configuration system
• MCP - Model Context Protocol for tool extensions
• GitHub Actions - CI/CD integration
• Background Shells - Long-running command execution
• Hooks - Custom command triggers
• Security Review - Advanced vulnerability detection
• Thinking - AI reasoning optimization
• Keyboard Shortcuts - Interactive mode navigation
• Notifications - Desktop alerts
• Queued Prompts - Batch prompt execution
• Environment Variables - Configuration options
• Spinner Words - CLI animation customization

• WebSocket Protocol - MCP communication layer
• Session Log Format - Conversation persistence
• Telemetry - Usage tracking and privacy
• Diff Spec - Code change visualization
• Caching - Performance optimization
• Microcompaction - Context optimization
• Recursion Stack - Task management
• Root Detection - Security measures

The `tools/sync.py` script automates the entire process of downloading, prettifying, diffing, and generating changelogs for Claude Code versions.

# Download and process all new versions
python tools/sync.py --all

# Process only the latest version
python tools/sync.py --all --latest

# Generate changelogs for versions since v1.0.70
python tools/sync.py --changelog --since v1.0.70

# Redo changelog for a specific version (creates iteration -2, -3, etc.)
python tools/sync.py --redo 69 --changelog

# Process versions in chronological order
python tools/sync.py --all --oldest-first

1. **Download originals**: Fetches missing versions from npm
2. **Prettify**: Formats files for readability using prettier
3. **Generate diffs**: Creates diffs between consecutive versions (uses astdiff if available)
4. **Generate changelogs**: Uses Claude SDK or CLI to analyze changes

Individual phases can be run separately:

python tools/sync.py                    # Download only
python tools/sync.py --prettier         # Download and prettify
python tools/sync.py --prettier --diff  # Also generate diffs
python tools/sync.py --changelog        # Generate changelogs from existing diffs

1. Investigate a specific feature or internal mechanism
2. Create or update documentation in appropriate features/ or internals/ directory
3. Follow org-mode format for consistency
4. Include code references with line numbers when applicable
5. Submit PR with findings

• Official Claude Code Documentation
• Model Context Protocol Specification
• Claude Code GitHub Repository
• astdiff - JavaScript-aware semantic diff tool (improves diff quality)