contextuaize 0.2.0

Smart codebase context extraction for LLMs - with optional AI-powered filtering

Contextuaize

Smart codebase context extraction for LLMs — Transform your codebase into optimized context for Claude, GPT-4, Gemini, and other large language models.

What's New in v0.2

• 🧠 Smart Mode — LLM-powered intelligent file filtering
• 🎯 Query-Driven Context — Focus on specific features or tasks
• 📝 Auto-Summarization — Large files get smart summaries
• 🔍 Respects .gitignore — No more manual exclusion lists
• 🌳 Tech Stack Detection — Automatically identifies your stack

Features

Feature	Basic Mode	Smart Mode (--smart)
.gitignore support	✅	✅
Binary file filtering	✅	✅
Directory tree	✅	✅
Stack detection	✅	✅
Intelligent file selection	❌	✅
Query-driven filtering	❌	✅
Large file summarization	❌	✅

Installation

# From GitHub
pip install git+https://github.com/ohharsen/contextuaize.git

# Local development
git clone https://github.com/ohharsen/contextuaize.git
cd contextuaize
pip install -e .

Quick Start

Basic Usage

# Scan current directory
contextuaize

# Scan specific project
contextuaize /path/to/project -o context.txt

# Only Python files
contextuaize --include "*.py"

# Exclude tests
contextuaize --exclude "test*" --exclude "*_test.py"

# Just see the tree structure
contextuaize --tree-only

Smart Mode (LLM-Powered)

Smart mode uses Claude to intelligently select relevant files and summarize large ones.

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Let AI decide what's important
contextuaize --smart

# Focus on specific functionality
contextuaize --smart --query "authentication and user sessions"

# Focus on a bug
contextuaize --smart --query "database connection handling"

How It Works

Basic Mode

1. Walks the directory tree
2. Respects .gitignore rules automatically
3. Skips universal noise (node_modules, .git, lockfiles, binaries)
4. Concatenates all text files with clear markers

Smart Mode

1. Two-pass scanning: First scans structure, then uses LLM to select files
2. Relevance scoring: Files ranked as essential → important → optional → skip
3. Query-driven: When you specify --query, only files relevant to that task are included
4. Smart summarization: Files over 100KB get intelligent summaries instead of full content

CLI Reference

contextuaize [directory] [options]

Arguments:
  directory              Directory to scan (default: current directory)

Options:
  -o, --output FILE      Output file path (default: codebase_context.txt)
  
Filtering:
  --include PATTERN      Include only matching files (can repeat)
  --exclude PATTERN      Exclude matching files (can repeat)
  --no-gitignore         Ignore .gitignore rules
  
Smart Mode:
  --smart                Enable LLM-powered intelligent filtering
  --query, -q TEXT       Focus on specific task/feature (enables --smart)
  --api-key KEY          Anthropic API key (or use ANTHROPIC_API_KEY env)
  --model MODEL          Model to use (default: claude-sonnet-4-20250514)
  
Output Destination (mutually exclusive):
  -o, --output FILE      Write to file (default)
  -c, --clipboard        Copy to system clipboard
  --stdout               Print to stdout (for piping)
  
Output Control:
  --quiet                Suppress progress output
  --tree-only            Only show project tree, no file contents

Output Modes

File (default)

contextuaize                    # → codebase_context.txt
contextuaize -o context.txt     # → context.txt

Clipboard

contextuaize -c                 # Copy directly to clipboard
contextuaize --clipboard        # Same thing

Works on macOS (pbcopy), Windows (clip), and Linux (xclip/xsel/wl-copy).

Stdout

contextuaize --stdout           # Print to stdout
contextuaize --stdout | head    # Pipe to other commands
contextuaize --stdout | pbcopy  # Manual clipboard on macOS

Progress messages go to stderr, so piping works cleanly.

Examples

Understanding a New Codebase

contextuaize --smart --query "explain the overall architecture"

Preparing to Add a Feature

contextuaize --smart --query "payment processing and Stripe integration"

Debugging an Issue

contextuaize --smart --query "WebSocket connection handling and reconnection logic"

Code Review Context

contextuaize --smart --query "user authentication flow"

Just the Backend

contextuaize --include "*.py" --exclude "test*" --exclude "migrations/*"

Output Format

The generated context file includes:

================================================================================
PROJECT CONTEXT SNAPSHOT
================================================================================

Detected Stack: Python, React, Docker
Context Focus: authentication flow
Total Files: 15

PROJECT STRUCTURE
----------------------------------------
my-project/
├── src/
│   ├── auth/
│   │   ├── login.py
│   │   └── session.py
│   └── api/
│       └── routes.py
└── tests/

================================================================================
FILE CONTENTS
================================================================================

--- START FILE: src/auth/login.py ---
[file content or summary]
--- END FILE: src/auth/login.py ---

...

Configuration

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	API key for smart mode

Patterns

Both --include and --exclude support glob patterns:

• *.py — All Python files
• test* — Files/dirs starting with "test"
• src/**/*.ts — TypeScript files in src/
• !important.py — Negation (in .gitignore)

Using with LLMs

After generating context, upload to your LLM with a prompt like:

"I've attached my project context. Please analyze the architecture and wait for my questions."

Or for focused tasks:

"Here's context focused on authentication. Help me add OAuth2 support."

License

MIT License — see LICENSE for details.

---

Author: Arsen Ohanyan • GitHub