Contexta

The right context, inside your token budget, safe by default.

Contexta reads a codebase, keeps the files that matter for the task, fits them into the token budget you set, and strips likely secrets before anything leaves your machine. Paste the pack into any assistant, or serve it over MCP to Claude Code, Cursor, and Windsurf.

Install with pip · Windows build · Linux build

What Contexta does

Dumping a whole repo into a chat wastes tokens and leaks things. Contexta does three jobs instead:

Measured on pinned commits of Flask, Requests and FastAPI, against Repomix and Gitingest (benchmarks/, reproducible with one command):

It loses on raw speed (the unbudgeted FastAPI pack takes 9 s, Repomix 1.3 s), an unbudgeted pack is still 168k tokens on Flask, and focus matching is by keyword, so it misses class Depends for "dependency injection". The full table shows all of it.

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", "--root", "/path/to/your/code"]
    }
  }
}

Or if running from source:

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

The server reads only inside the folders you pass with --root (repeat the flag for more), or CONTEXTA_ROOT, or the folder it was started in. Paths outside, .. escapes, symlinks that leave the project, and credential files such as .env or id_rsa are refused. generate_context accepts a budget argument.

Available tools

Agent setup in one command

contexta install cursor      # .cursor/rules/contexta.mdc
contexta install claude      # a managed block in CLAUDE.md
contexta install copilot     # a managed block in .github/copilot-instructions.md
contexta install mcp         # .mcp.json (--client cursor|vscode for the other editors)

Safe to run twice: identical content is left alone, existing files are never overwritten without --force, and a file that already has other content only gets the Contexta block appended. --dry-run shows what would change.

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
# or, for a clean isolated CLI:
pipx install contexta-ai
contexta --help

Optional extras:

pip install "contexta-ai[syntax]"  # tree-sitter symbol maps for JS/TS/Go/Rust (a regex fallback is used without it)
pip install "contexta-ai[gui]"     # the same, for desktop users. Tk itself comes with Python (apt install python3-tk)

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

  Windows 11: right-click the downloaded .exe → Properties → check Unblock → OK before running.

• 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 .                                                   # default pack, or contexta.toml
contexta . --for onboard --copy                              # understand a repo, then paste it
contexta . --for review --stdout                             # this branch against main, with impacted tests
contexta . --for bugfix --focus "login timeout" --budget 20000
contexta graph impact src/app.py                             # what a change touches, and which tests to run
contexta install cursor                                      # agent rules for this project
contexta . --pack onboarding --copy                         # same as --for onboard
contexta . --pack bugfix --focus "login timeout"            # fix a bug with a coding agent
contexta . --pack pr_review --base main --stdout            # review this branch against main
contexta . --pack refactor --format json -o pack.json       # hand a refactor pack to another tool
contexta . --pack raw_files                                 # clean path + content dump
contexta . --budget 20000                                   # best files that fit 20k tokens
contexta . --focus "session cookie signing" --budget 8000  # a small pack about one topic
contexta . --dry-run                                        # list what would be redacted, write nothing

# First-time project setup
contexta --init                                              # writes contexta.toml and .contextaignore

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

# Configure AI API keys
contexta --configure-ai

CLI flags

CLI flags override contexta.toml, which overrides ~/.contexta/config.toml. An explicit flag also wins over a pack preset, so --pack pr_review --compression lean stays lean.

Daily handoff

The pack footer reports whether the export fits the selected profile. Planning windows include GPT-4o (128k), GPT-4.1 (about 1M), Claude Sonnet and Opus (200k), Gemini Flash and Pro (about 1M), and Copilot Chat / coding agent (64k / 128k). Contexta reserves 20% of each window for the question and the reply. These are planning numbers, not a provider quota.

Set max_tokens in contexta.toml, or pass --budget, and Contexta ranks the files, keeps the best ones that fit, and tightens compression only if it must. The pack gets a "Token Budget" section naming what was left out.

Before the pack is written, likely secrets are replaced with [REDACTED]: API keys, private keys, known token prefixes, bearer tokens, passwords in URLs, password: ... lines in JSON and YAML, and random-looking strings under secret-like names. Placeholders such as your-api-key are kept. Run --dry-run to see what would change. To keep a value, list it in redact_allow in contexta.toml, or put contexta:allow on its line. Files such as .env, private keys, .npmrc and .netrc are never read at all. This is best-effort and does not replace keeping secrets out of the tree. --no-redact disables redaction.

contexta --init writes a starter contexta.toml and .contextaignore. .gitignore is always applied. .contextaignore and the config ignore list add pack-only exclusions, using gitignore syntax, without changing what git tracks. A sample project file lives at docs/contexta.toml.example.

Project graph

Contexta keeps a local SQLite index of files, symbols, tests and how they connect (imports, calls, tests, git co-change) in .contexta/graph.db. It updates incrementally while it reads your project and answers questions the files alone cannot: who uses this function, what does this change reach, which tests should I run, which files change the most.

contexta graph impact src/app/session.py     # impacted files, plus tests to run
contexta graph map --budget 1500             # ranked repo map in about 1.5k tokens
contexta graph export -o graph.json          # JSON, JSONL or Markdown for other tools

Packs use it: with --budget, files the project depends on most are kept first, and on repos over 800 files a budgeted or focused run analyses the highest-ranked files instead of all of them. It never stores file contents, credential files or authors, and it is gitignored by default. Details in docs/graph.md.

Project memory in the app

The desktop app has a Project memory card under the project folder. It shows whether the project has a memory (files, symbols, edges, last update) and has five buttons: Update memory (runs in the background, the window never freezes), Hot files, Symbols, Impact (asks for a file) and Open map (saves a Markdown map next to your packs and opens it). Answers appear in the Memory tab on the right. It needs no model and no network.

Each analysis has two controls. Save this analysis to Contexta memory (on by default) lets the run update the memory; turned off, the run may still read an existing memory to rank files but never writes it. Memory to use picks this project's memory, the memory kept in another folder you browse to, or none. Your choice is remembered in ~/.contexta/gui.json. The command line has the same switches: --no-memory, --memory PATH, --memory-read-only.

In the pull request

The GitHub Action posts one comment per PR with the changed files, the tests worth running and what the change reaches, plus a redacted context pack within your token budget as an artifact. The comment is edited in place on later runs and lists paths only, never source. Details in docs/github-action.md.

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, with one exception: Contexta never modifies your files. It does keep its project graph in .contexta/ (names, signatures and relations, never file contents; it ignores itself with a * .gitignore). Turn it off with --no-graph or graph = false, move it with CONTEXTA_GRAPH_DIR
• No runtime telemetry or network requirement (except optional --ask AI calls)
• Scan limit of 2000 files by default, raised with --max-files
• Embedded binary/blob payloads are suppressed automatically
• Likely secrets are redacted in exports and in MCP read_files unless --no-redact is set. --dry-run shows what would be redacted
• Credential files (.env, private keys, cloud and package-manager credentials) are skipped by the scan and refused by MCP
• The MCP server reads only inside --root / CONTEXTA_ROOT / its working directory
• Symlinks that point outside the project are not followed
• 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