diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ac8345f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+tzst is a next-generation Python library for modern archive management using Zstandard compression. It provides both a Python API and a command-line interface for creating, extracting, listing, and testing .tzst/.tar.zst archives. The library focuses on performance, security, and reliability with features like atomic operations, streaming mode for large archives, and security filtering for extraction.
+
+## Architecture
+
+The codebase is structured as follows:
+
+- `src/tzst/core.py` - Core implementation containing the `TzstArchive` class and convenience functions
+- `src/tzst/cli.py` - Command-line interface built with argparse
+- `src/tzst/exceptions.py` - Custom exception classes
+- `src/tzst/__init__.py` - Public API exports
+
+The library wraps Python's tarfile module with Zstandard compression/decompression streams. It supports both buffered and streaming modes for memory efficiency with large archives.
+
+## Commands
+
+### Development Environment
+
+```bash
+# Development installation with dev dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+pytest --cov=tzst --cov-report=html  # with coverage
+```
+
+### Code Quality
+
+```bash
+# Check code quality
+ruff check src tests
+
+# Format code
+ruff format src tests
+```
+
+### Building and Distribution
+
+```bash
+# Build package
+python -m build
+
+# Upload to PyPI (requires credentials)
+python -m twine upload dist/*
+```
+
+## Key Features to Consider
+
+1. **Streaming Mode**: For archives >100MB, always recommend using streaming mode to reduce memory usage
+2. **Security Filters**: Use 'data' filter by default for extraction to prevent path traversal attacks
+3. **Atomic Operations**: Archive creation uses temporary files by default for safety
+4. **Conflict Resolution**: During extraction, implement proper file conflict resolution strategies
+5. **Compression Levels**: Default to level 3 unless the user has specific performance/size requirements
+
+## Testing Patterns
+
+The project uses pytest with comprehensive test coverage including:
+
+- Unit tests in `tests/unit/`
+- Integration tests in `tests/integration/`
+- CLI-specific tests in `tests/cli/`
+- Edge case handling in `tests/test_core_edge_cases.py`
+
+## Common Tasks
+
+- To add functionality: work in `src/tzst/core.py` following existing patterns
+- To modify CLI behavior: update `src/tzst/cli.py` and adjust argument parsing as needed
+- To add new command: extend `create_parser()` in cli.py and add appropriate handler function
+- For error handling: use appropriate TzstError subclasses from exceptions.py