Contexta

AI-native codebase context engine. Serves intelligent project context to Claude Code, Cursor, Windsurf, and any MCP-compatible tool — or generates curated context packs for manual use.

     

Install via pip, download the portable executable, or run from source.

What is Contexta

Contexta analyzes codebases and serves intelligent, curated context to AI tools. Instead of dumping files blindly, it understands project structure, detects frameworks, ranks files by importance, and delivers exactly what an AI needs.

Three ways to use it:

MCP Server (recommended)

The MCP server is the primary way to use Contexta. AI coding assistants call it as a tool to understand your project — no copy-paste needed.

Setup

Add to your MCP configuration (Claude Code, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "contexta": {
      "command": "contexta",
      "args": ["serve"]
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "contexta": {
      "command": "python",
      "args": ["/path/to/contexta_mcp.py"]
    }
  }
}

Available tools

Smart cache

Results are cached in memory with automatic invalidation. First call analyzes the project (~700ms), subsequent calls return in ~2ms until files change on disk. The cache monitors file mtimes and manifest files — when you edit code, the next call recomputes automatically.

Install

Option A: pip (recommended)

pip install contexta-ai

Optional AI API integrations:

pip install contexta-ai[claude]    # Claude API
pip install contexta-ai[gemini]    # Gemini API
pip install contexta-ai[openai]    # OpenAI API
pip install contexta-ai[all-ai]    # All three

Option B: Portable executables

• Windows: download contexta.exe
• Linux: download contexta-linux.tar.gz

Option C: From source

git clone https://github.com/pablokaua03/Contexta.git
cd Contexta
pip install -r requirements.txt
python contexta.py

CLI usage

# Generate context packs
contexta ./project                                          # default pack
contexta ./project --pack onboarding                        # understand a new codebase
contexta ./project --pack raw_files                         # clean path + content dump
contexta ./project --pack pr_review --diff --copy           # review changes
contexta ./project --mode debug --focus "auth flow"         # debug a specific area

# AI API integration — send context + question directly to an AI
contexta ./project --ask "what are the main security risks?"
contexta ./project --ask "explain the architecture" --provider claude

# Configure AI API keys
contexta --configure-ai

CLI flags

Context packs

What Contexta exports

Depending on pack, mode, and task, the output can include:

• Project summary with detected technologies, entry points, purpose, and central modules
• Read-this-first path through the repository
• Main execution flow narrative
• Core files, supporting files, related tests, and changed-file context
• Relationship maps and risk notes
• Score breakdown explaining why each file was selected
• Curated Markdown payload ready for any AI tool

Main features

Build from source

# Windows (requires Visual Studio C++ Build Tools)
.\build.bat

# Linux / macOS
chmod +x build.sh && ./build.sh

Build outputs: dist/contexta.exe (Windows), dist/contexta (Linux/macOS), dist/contexta-linux.tar.gz (Linux bundle).

Run tests

python -m pytest tests/ -k "not test_relation_score"

Security and behavior

• Read-only: Contexta does not modify the scanned project
• No runtime telemetry or network requirement (except optional --ask AI calls)
• Scan limits prevent runaway exports
• Embedded binary/blob payloads are suppressed automatically
• AI API keys are stored locally in ~/.contexta/ai_config.json when using --configure-ai

Contributing

See CONTRIBUTING.md

Changelog

See CHANGELOG.md

License

MIT © pablokaua03