Here's a secret about AI coding assistants: they're only as good as the context you give them! Forget chasing perfect prompts or waiting for the next big model - what truly transforms an AI assistant into a reliable coding partner is crystal-clear context about your project.
Ever needed to explain your codebase to ChatGPT or Claude? Contextor creates a perfect snapshot of your project in seconds:
# That's it! Just run:
contextor
📋 What is Contextor?
Contextor is not an IDE or code editor like Cursor. It's a zero-friction tool that makes your codebase instantly pasteable into ChatGPT, Claude, or any AI assistant. Think of it as a "make my repo AI-ready" button that creates a single file with your project structure and selected file contents, ready for pasting.
Interactive file selection right in your terminal:
my_project/
├── src/
│ └── main.py # LLMs can request this file if needed!
└── config/
└── settings.yaml
# Key files are included below the tree...
Just paste this into your AI chat and start coding! The AI can see your project structure and request any file it needs.
# Install
pip install contextor
# Run in interactive mode (default)
contextor
# Use previously selected files without interactive picker
contextor --use-scope
# Specify files directly (skips interactive picker)
contextor --files main.py config.yaml
Contextor uses a scope file (default: .contextor_scope) to remember your file selections:
--use-scope to skip interactive mode and use previously selected files--scope-file to specify a custom scope file location--no-update-scope to prevent updating the scope file after selectionThis makes it easy to reuse the same selection across multiple runs, perfect for when you're iterating on your code and need to regenerate context frequently.
Contextor not only includes full file contents but also extracts structure from important files (like Python, JavaScript, SQL, and Markdown) that you didn't fully include.
This helps the AI assistant understand your project's architecture without needing every file!
You can control this with:
--no-signatures (disable signatures)--max-signature-files N (limit the number)--md-heading-depth N (control Markdown TOC depth)Need more control? We've got you covered:
# Include files listed in a text file
contextor --files-list important_files.txt
# Custom exclude patterns
contextor --exclude-file exclude_patterns.txt
# Ignore .gitignore
contextor --no-gitignore
# Copy directly to clipboard for immediate use with AI assistants
contextor --files main.py config.yaml --copy
| Option | Description |
|---|---|
--directory | Project directory (default: current) |
--files | Specific files to include (skips interactive picker) |
--scope-file | Custom scope file path (default: .contextor_scope) |
--use-scope | Use scope file without interactive selection |
--no-update-scope | Don't update scope file after selection |
--output | Output filename (default: project_context.md) |
--no-gitignore | Disable .gitignore patterns |
--exclude-file | Additional exclude patterns file |
--no-tree | Omit tree structure from output |
--no-signatures | Disable file signature extraction |
src/main.py
config/settings.yaml
README.md
*.pyc
__pycache__/
.env
*.log
Contextor looks out for you:
# From PyPI (recommended)
pip install contextor
# For Linux users, clipboard functionality requires xclip or xsel:
# Ubuntu/Debian: sudo apt install xclip
# Fedora: sudo dnf install xclip
# Arch: sudo pacman -S xclip
# From source
git clone https://github.com/ergut/contextor
pip install -r requirements.txt
We love contributions! Check out README.test.md for:
MIT License - See LICENSE file
Salih Ergüt
See CHANGELOG.md for version history and updates.
FAQs
Create context files from your codebase for AI conversations
We found that contextor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.