Repository files navigation

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 isnot 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.

# Installpip install contextor# Run in interactive mode (default)contextor# Use previously selected files without interactive pickercontextor --use-scope# Specify files directly (skips interactive picker)contextor --files main.py config.yaml

• Simple: One command to create perfect context for AI conversations
• Interactive: Select files with a user-friendly interface right in your terminal
• Smart: Respects .gitignore, handles large files, includes safety checks
• Flexible: Include specific files or let the AI see everything
• Safe: Warns you about size and skips files >10MB
• Binary-aware: Automatically excludes binary files that wouldn't help AI assistants
• Ready to Use: Automatically copies output to clipboard and saves to file

• 🖱️ Interactive file selection with directory grouping
• 💾 Persistent selections via .contextor_scope file
• 📁 Complete project tree generation
• 🔒 .gitignore pattern support
• ⚡ Large file protection
• 🎮 Binary file detection and exclusion
• 📊 Automatic token estimation
• 📋 Clipboard support for easy pasting

Contextor uses a scope file (default:.contextor_scope) to remember your file selections:

• When you run contextor interactively, your selections are saved to this file
• Use--use-scope to skip interactive mode and use previously selected files
• Use--scope-file to specify a custom scope file location
• Use--no-update-scope to prevent updating the scope file after selection

This 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 alsoextracts 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 filecontextor --files-list important_files.txt# Custom exclude patternscontextor --exclude-file exclude_patterns.txt# Ignore .gitignorecontextor --no-gitignore# Copy directly to clipboard for immediate use with AI assistantscontextor --files main.py config.yaml --copy

src/main.pyconfig/settings.yamlREADME.md

*.pyc__pycache__/.env*.log

Contextor looks out for you:

• Calculates total file size
• Shows warning for large directories
• Asks for confirmation
• Skips files >10MB and binary files
• Respects .gitignore by default

# 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 sourcegit clone https://github.com/ergut/contextorpip install -r requirements.txt

We love contributions! Check outREADME.test.md for:

• Running tests
• Test coverage details
• Adding new features
• Contributing guidelines

MIT License - SeeLICENSE file

• 🐛Report issues
• 💡Feature requests
• 📖Documentation

Salih Ergüt

SeeCHANGELOG.md for version history and updates.