📦 contextkit — Codebase Context for LLMs

Stop manually copying files into ChatGPT/Claude.

contextkit scans any codebase and generates clean, token-counted markdown summaries optimized for LLM context windows.

Why?

When asking LLMs about your code, you need to:

1. Copy the relevant files
2. Stay under the token limit
3. Include enough context for good answers

Doing this manually is tedious. contextkit automates it.

Quick Start

pip install contextkit

# Generate context for current directory
contextkit .

# Target a specific model
contextkit . --model claude-3.5-sonnet
contextkit . --model gpt-4o

# Just check token count
contextkit . --count

# Compact overview (tree + key files only)
contextkit . --compact

# Split large codebase into chunks
contextkit . --chunked

# Save to file
contextkit . -o context.md

Features

• Token counting for 30+ LLM models (GPT-4, Claude, Llama, Gemini, etc.)
• Respects .gitignore — skips ignored files automatically
• Smart filtering — skips binaries, lock files, node_modules, etc.
• Chunking — splits large codebases to fit context limits
• Multiple modes — full, compact, tree-only, stats-only
• Extension filtering — only include specific file types
• JSON output — for programmatic use

Supported Models

Model	Context Limit
GPT-4	8K tokens
GPT-4 Turbo / GPT-4o	128K tokens
Claude 3 (all variants)	200K tokens
Gemini 1.5 Pro	1M tokens
Llama 3.1 (all sizes)	128K tokens
Mistral Large	128K tokens
Deepseek V2	128K tokens
Qwen 2	128K tokens

Usage Examples

Basic Context Generation

contextkit .
# Generates full markdown with:
# - Directory tree
# - Codebase statistics
# - All file contents
# - Token count at bottom

Count Tokens Only

contextkit . --count
# Output:
# Model: gpt-4
# Context limit: 8.2K tokens
# Estimated usage: 12.5K tokens (152.4%)
# Remaining: 0 tokens
# Files: 47

Filter by Extension

# Only Python and JavaScript files
contextkit . --ext py js

# Only TypeScript
contextkit . --ext ts tsx

Compact Overview

contextkit . --compact
# Shows:
# - Quick stats
# - Directory tree
# - Key files (README, package.json, main files)

Chunked Output

contextkit . --chunked
# Splits into multiple chunks that each fit context window
# Useful for processing large codebases in parts

Ignore Patterns

# Ignore test files
contextkit . --ignore "*.test.js" "*.spec.py"

# Ignore specific directories
contextkit . --ignore "tests/" "docs/"

JSON Output

contextkit . --stats-only --json
contextkit . --chunked --json

Python API

from contextkit import CodebaseScanner, TokenCounter, ContextGenerator

# Scan a directory
scanner = CodebaseScanner("/path/to/project")
files = scanner.scan()

# Count tokens
counter = TokenCounter("gpt-4o")
print(f"Tokens: {counter.estimate(content)}")

# Generate context
generator = ContextGenerator(scanner, model="claude-3.5-sonnet")
context = generator.generate(instructions="Explain the architecture")

# Generate chunks
chunks = generator.generate_chunked()
for chunk in chunks:
    print(f"Chunk {chunk.index}: {chunk.tokens} tokens, {chunk.file_count} files")

Use Cases

1. Ask LLMs about your codebase

contextkit . -o context.md
# Paste context.md into ChatGPT/Claude
# Ask questions about your code

2. Prepare for code review

contextkit . --ext py --ignore "tests/" -o review.md

3. Generate documentation

contextkit . --compact -o overview.md
# Ask LLM to generate docs from the overview

4. Onboard new developers

contextkit . -o codebase-summary.md
# Share with new team members

5. Feed to AI coding agents

contextkit . --model gpt-4o --chunked
# Feed chunks sequentially to AI agents

Output Format

# Codebase Context

## Codebase Statistics

- **Files:** 47
- **Lines:** 3,842
- **Size:** 156.3 KB

### By Language

- **Python:** 28 files, 2,341 lines
- **JavaScript:** 12 files, 891 lines
- **Markdown:** 7 files, 610 lines

## Directory Structure

myproject/ ├── src/ │ ├── main.py │ └── utils.py ├── tests/ │ └── test_main.py └── README.md

## File Contents

### `src/main.py`

```python
# ... file contents ...

---

Context: 4.2K tokens (51.2% of 8.2K limit)

## System Requirements

- Python 3.8+
- No external dependencies (except pathspec)
- Works on Linux, macOS, Windows

## Contributing

Areas where help is needed:
- [ ] Add tiktoken support for exact OpenAI token counts
- [ ] Support for more file types
- [ ] VS Code extension
- [ ] Watch mode (auto-regenerate on file changes)

## License

MIT — Use it however you want.

---

**Built for developers who talk to AI about their code.**