Maximum Context

Maximum Context is a Go-based MCP (Model Context Protocol) server that gives AI coding assistants deep, always-current awareness of a codebase. It indexes a project's structure, symbols, dependencies, and architecture, then exposes that knowledge through a focused, decisive MCP tool interface.

Why max-context

AI coding agents waste 30–60% of their context window grepping and re-reading files to figure out where things are. max-context pre-computes that understanding and serves it on demand.

• Always current — file changes reflected in < 2 seconds via OS-native watchers
• No LLM at index time — deterministic tree-sitter parsing; no API keys, no token spend on indexing
• Minimal surface, no breaking changes — a small set of focused MCP tools, stable schema

See BENCHMARK.md for per-tool-call token savings vs naive and skilled Grep+Read baselines, measured over the same file set the index covers. The most robust result is 32–47× fewer tokens on "where is X defined?" across four repos in three languages (max-context, cobra, flask, zod) — that band holds because a lookup costs ~300–470 tokens whatever the repo, while grep grows with it. Blended per-repo figures range from 11× to 94×, but they are dominated by question mix and by how greppable a given symbol is, so BENCHMARK.md reports per category and explains which number to quote. Both sides are measured by running them: real greps for the baselines, real tool calls for max-context.

For agent-session quality and cost — does an LLM actually do better with these tools? — see the causal A/B in experiments/eval/benchmarks/in-house/FINDINGS.md (same model, same tasks, only the toolset differs; blind different-model judge; pre-registered). On the tasks measured so far it finds equal answer quality to a skilled grep agent, at materially lower cost — up to 94% fewer tokens (≈90% in aggregate) on call-graph / "what-calls-this" questions — plus a structural edge on aliased imports (from m import f as g; g()), where text search can't connect the call site to the definition and max-context can. Honest scope: small sample (1 repo family, 1 replicate); quality is a tie, not a win, except the alias case.

How it works

                                  ┌─────────────────────────────────┐
                                  │       max-context binary        │
    ┌─────────────┐ fsnotify      │   ┌─────────────────────────┐   │
    │ Codebase    │───────────────┼─▶ │   tree-sitter parser    │   │
    └─────────────┘               │   └────────────┬────────────┘   │
                                  │                ▼                │
                                  │   ┌─────────────────────────┐   │
                                  │   │SQLite FTS5 + call graph │   │
                                  │   └────────────┬────────────┘   │
    ┌─────────────┐               │                ▼                │
    │ AI CLI / IDE│ stdio MCP     │   ┌─────────────────────────┐   │
    └─────────────┘◀──────────────┼───│  MCP server · 5 tools   │   │
                                  │   └─────────────────────────┘   │
                                  └─────────────────────────────────┘

Tree-sitter parses every supported language deterministically. Symbols and call edges land in a SQLite database with FTS5 indexes on function/type names. Recursive CTEs power call-chain and impact queries. No LLM is involved at index time — the host CLI's model does all the reasoning, with max-context feeding it pre-computed structure.

Features

• Focused MCP tools: get_definition (exact-name, canonical definition), query_codebase (BM25 fuzzy symbol search with explicit next action), get_call_chain (recursive caller/callee traversal), get_impact (change blast radius), get_architecture (pre-computed project summary)
• Real-time index: File watcher keeps the index current within 2 seconds of changes
• Multi-language: TypeScript, JavaScript, Python, Go, Rust, Java (and more via Tree-sitter). Full call-graph resolution for Go, TypeScript/TSX, and Python; other languages are parsed with name-based call resolution — see docs/LANGUAGES.md for the honest parsed-vs-resolved matrix.
• Universal harness support: One max-context setup <name> configures Claude Code, VS Code Copilot, Codex CLI, Antigravity, Cursor, Windsurf, opencode, Hermes, and pi. Harnesses live in a registry (internal/setup/harness.go) — adding one is a table entry, not new code
• Small always-on footprint: the five tool definitions total ~875 tokens, re-sent every request. A CI step prints the number and a test fails if it grows

Install

Pick one:

Method	Command
Homebrew (macOS/Linux)	brew tap maxcontext/tap && brew install maxcontext/tap/max-context
npm (global CLI)	npm install -g @maxcontext/cli
Install script	curl -fsSL https://raw.githubusercontent.com/maxcontext/max-context/main/scripts/install.sh | sh
GitHub Release	Download the binary for your OS/arch from Releases; verify with checksums.txt (SHA256).
From source	make build then make install (copies to ~/.local/bin) or make install-path (install + add that dir to your shell PATH). On Windows, make install-path installs to %LOCALAPPDATA%\max-context\bin and prints instructions to add it to your user PATH.

Note

Ensure the binary is on your PATH after install.

• macOS/Linux: make install-path appends ~/.local/bin to your PATH in .bashrc, .zshrc, or .profile if it isn't already there — run source ~/.bashrc (or your rc file) to apply.
• Windows: add the install directory to your user PATH (Settings → Environment Variables), or use the PowerShell one-liner printed by make install-path.
• The install script defaults to ~/.local/bin; set MAX_CONTEXT_INSTALL_DIR to override.

Add to your editor (one click)

With the binary on your PATH, these deeplinks register the MCP server in one click (see docs/DISTRIBUTION.md — link formats drift, verify at release time):

• Cursor: Add max-context to Cursor
• VS Code: Add max-context to VS Code

Or add it manually to any MCP client config:

{
  "mcpServers": {
    "max-context": { "command": "max-context", "args": [] }
  }
}

Quick Start

# Build from source (optional)
make build

# Full index (builds the index and exits; the watcher runs in server mode)
max-context --index

# MCP server mode (stdio; used by IDEs)
max-context

# Status
max-context --status

# Setup for a specific CLI
max-context setup cursor
max-context setup all

Quickstart by CLI

After installing max-context and ensuring it’s on your PATH:

CLI	Steps
Claude Code	1. Add MCP server (e.g. max-context setup claude-code or put max-context in .mcp.json). 2. Install plugin: /plugin marketplace add <path-to-repo> then /plugin install max-context@max-context-local (see Claude Code Plugin below). 3. In project: max-context --index then start Claude Code.
VS Code Copilot	1. max-context setup vscode (writes .vscode/mcp.json, .github/hooks/, skills). 2. max-context --index in project. 3. Open VS Code; MCP and hooks load.
Codex CLI	1. max-context setup codex (adds [mcp_servers.max-context] to .codex/config.toml, skill to .codex/skills/max-context/). 2. max-context --index. 3. Use Codex in the project. Codex loads project config only for trusted projects — setup prints the trust_level snippet if you need it.
Antigravity	1. max-context setup antigravity (MCP config, .agent/skills/max-context/, rules). 2. max-context --index. 3. Run Antigravity in the project.
Cursor	1. max-context setup cursor (.cursor/mcp.json, .cursor/rules/max-context.md, AGENTS.md). 2. max-context --index. 3. Use Cursor; MCP and rules apply.
Windsurf	1. max-context setup windsurf (user MCP config, .windsurf/rules/max-context.md, workflows, AGENTS.md). 2. max-context --index. 3. Use Windsurf in the project.
opencode	1. max-context setup opencode (adds the server to opencode.json under mcp, writes .opencode/max-context.md and lists it under instructions). 2. max-context --index. 3. Run opencode in the project.
Hermes	1. max-context setup hermes (adds the server to the global ~/.hermes/config.yaml under mcp_servers, plus a project skill). 2. max-context --index. 3. Run Hermes in the project.
pi	1. max-context setup pi (writes .pi/skills/max-context/SKILL.md and an AGENTS.md block). 2. max-context --index. 3. Run pi in the project. pi ships no MCP client by design, so it drives max-context through the one-shot CLI below.

Commands

Flag / Subcommand	Description
(none)	Run MCP server on stdin/stdout
--index	Build full index and exit
--reindex	Force full rebuild of index
--status	Report index health, file count, symbol count
--watch	Start only the file watcher
--version	Print version and exit
setup <cli>	Generate config for claude-code, vscode, codex, antigravity, cursor, windsurf, or all
query / def / calls / impact / arch / tool	One-shot CLI access to the MCP tools (below)

CLI tool access

Every MCP tool is also a one-shot subcommand that prints the same JSON to stdout — handy for shell scripts, hooks, and code-executing agents that prefer a CLI over MCP tool definitions:

max-context query "resolver cache" -n 5 -scope docs   # query_codebase
max-context def IndexFile                              # get_definition
max-context calls Migrate -direction callers -depth 3  # get_call_chain
max-context impact -from-git main..HEAD                # get_impact
max-context arch                                       # get_architecture
max-context tool get_call_chain --json '{"function_name":"Migrate"}'  # generic form

Global flags go before the subcommand (max-context -project /repo query …); subcommand flags may go on either side of the positional argument. Build the index first with max-context --index.

This CLI is also the whole integration for harnesses that do not speak MCP — pi deliberately ships without an MCP client ("No MCP. Build CLI tools with READMEs"), so max-context setup pi installs a skill documenting these commands instead of tool definitions.

Configuration (.max-context/config.json)

Optional per-project settings, all keys optional:

{
  "languages": ["go", "typescript"],
  "include": ["src/*.go"],
  "exclude": ["generated/"],
  "watchDebounceMs": 500,
  "maxFileSize": 1048576
}

• languages — restrict indexing to these languages (default: all supported). Accepts names or aliases (ts, py, golang, …).
• include — index only files matching at least one glob (full relative path, or basename for patterns without /). No ** support.
• exclude — extra gitignore-style exclude patterns on top of .gitignore/.contextignore.
• watchDebounceMs — file-watcher debounce (default 500).
• maxFileSize — skip files larger than this many bytes (default 1 MB).

Non-code files (markdown, YAML, JSON, TOML, proto, GraphQL, SQL, XML, Dockerfiles) are indexed as plain-text documents regardless of languages, searchable via query_codebase with scope: "docs" (lock files are skipped automatically).

Claude Code Plugin

When used as a Claude Code plugin (install from this repo), you get:

• PreToolUse hook — Suggests using query_codebase instead of Grep/Read for codebase search
• SessionStart hook — Injects .max-context/summary.md and architecture.md into context
• PreCompact hook — Appends a session-preserved note to summary.md before context compaction
• /reindex — Slash command to run max-context --reindex or touch .max-context/.reindex-queue

max-context setup <cli> also generates reindex, index, and status commands for each editor in its native format — slash commands for Claude Code (.claude/commands/), Cursor (.cursor/commands/), and VS Code Copilot (.github/prompts/*.prompt.md); workflows for Windsurf (.windsurf/workflows/); and a documented Commands section in the skill file for Codex and Antigravity.

Install (local): This repo is a local marketplace. In Claude Code, run:

1. Add marketplace: /plugin marketplace add ./max-context — use the path to the repo root (e.g. ./max-context, ~/max-context, or /home/.../max-context). Valid formats: ./path, owner/repo, or https://....
2. Install plugin: /plugin install max-context@max-context-local

Ensure the max-context binary is on your PATH so the MCP server can start. The running server watches .max-context/.reindex-queue; writing that file triggers a full reindex in the background.

VS Code Copilot Hooks

Run max-context setup vscode to create .github/hooks/hooks.json and .github/hooks/scripts/ (SessionStart, PreCompact, PreToolUse) so VS Code Copilot gets the same grep-interception and session-start context as Claude Code. The hook format is shared; script paths use ${CLAUDE_PROJECT_DIR}/.github/hooks/scripts/. In this repo, the same hook definitions live under hooks/ (Claude Code plugin) and .github/hooks/ (VS Code / project).

MCP Resources

The server advertises the resources capability and exposes two read-only resources:

URI	Description
maxcontext://project/summary	Pre-computed project summary (text/markdown)
maxcontext://project/architecture	Tech stack, directory map, entry points (text/markdown)

IDEs that support MCP Resources (e.g. VS Code Copilot) can list and read these in the chat panel.

Project Layout

• cmd/max-context/ — Entry point and flag parsing
• internal/config/ — CLI flags and .max-context/config.json
• internal/db/ — SQLite schema, migrations, FTS5
• internal/indexer/ — Tree-sitter parsing, full/incremental index
• internal/watcher/ — fsnotify file watcher, debounce, git-aware invalidation
• internal/mcp/ — JSON-RPC 2.0 server (stdio)
• internal/tools/ — the MCP tools: get_definition, query_codebase, get_call_chain, get_impact, get_architecture
• internal/artifacts/ — architecture.md, summary.md, status.json
• internal/setup/ — Per-CLI config writers
• pkg/treesitter/ — Tree-sitter bindings and language queries
• .claude-plugin/ — Claude Code plugin + marketplace manifests (source: "./" — the repo root is the plugin)
• hooks/ — Claude Code plugin hooks (PreToolUse, SessionStart, PreCompact)
• commands/ — Plugin slash command (e.g. /reindex)
• skills/ — Plugin skills (index-codebase, show-call-chain)
• internal/setup/guidance/ — the skill text max-context setup writes, embedded into the binary (MCP-tool and CLI variants)
• npm-package/ — npm wrapper @maxcontext/cli with postinstall binary download + SHA256
• scripts/install.sh — Install script for curl|sh
• Formula/ — Homebrew formula template; update SHA256 from checksums.txt after each release

Requirements

• Go 1.22+
• CGO enabled (for Tree-sitter grammars)

License

Licensed under the Apache License, Version 2.0. See NOTICE for attribution requirements when redistributing.

Contributions are welcome — see CONTRIBUTING.md.