Codectx
Codebase context compiler for AI agents. Graph-ranked, token-budgeted, tier-compressed output. Smarter than the existing ones.
What is Codectx?
Codectx is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to codebase context compiler for ai agents. graph-ranked, token-budgeted, tier-compressed output. smarter than the existing ones.
Codebase context compiler for AI agents. Graph-ranked, token-budgeted, tier-compressed output. Smarter than the existing ones.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Codebase context compiler for AI agents. Graph-ranked, token
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx codectxConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Codectx
Codectx is a Python CLI tool and MCP server that compiles a codebase into a single, token-budgeted context document for AI agents. It uses tree-sitter to parse source files across nine languages, graph-ranks them by relevance to a query or task profile, and applies tier compression to fit within a configurable token budget — producing far more useful context than naive directory concatenation. Developers feed its output to AI coding assistants when they need the agent to understand a large repository without blowing the context window.
Prerequisites
- Python 3.10 or higher
- pip, uv, or pipx for installation
- An MCP-compatible client such as Claude Desktop or Cursor
- Optional: OpenAI or compatible API key for the --llm AI-summary feature
Install codectx
Install codectx from PyPI using your preferred Python package manager. Use the [llm] extra if you want AI-powered summaries.
pip install codectx
# or with LLM summary support
pip install codectx[llm]
# or with uv
uv add codectxCreate an optional project configuration file
Add a .codectx.toml to your project root to set default token budget, output filename, and patterns to ignore. All keys are optional.
[codectx]
token_budget = 120000
output_file = "CONTEXT.md"
extra_ignore = ["**/generated/**", "*.draft.py"]Run a basic codebase analysis
Run codectx analyze from your project root. It will parse all supported source files, rank them, and write a token-budgeted CONTEXT.md.
codectx analyze .
# Limit to 60k tokens
codectx analyze . --tokens 60000
# Output as machine-readable JSON
codectx analyze . --format json --output context.jsonUse task profiles for better ranking
Specify a --task profile to bias the graph-ranking toward files relevant to a specific kind of work: architecture, refactor, debug, or feature.
codectx analyze . --task debug
codectx analyze . --task feature --query "authentication flow"Enable watch mode for live updates
Watch mode regenerates the context file automatically when source files change, keeping AI agents up to date during active development.
codectx watch . --debounce 1.5Configure as an MCP server in Claude Desktop
Register codectx as an MCP server so Claude can call it as a tool to analyse any repository path on demand.
{
"mcpServers": {
"codectx": {
"command": "python",
"args": ["-m", "codectx", "serve"]
}
}
}Codectx Examples
Client configuration
Claude Desktop configuration to run codectx as a Python-based MCP server.
{
"mcpServers": {
"codectx": {
"command": "python",
"args": ["-m", "codectx", "serve"]
}
}
}Prompts to try
Prompts that use codectx to give Claude deep codebase awareness.
- "Use codectx to analyse this repo and then explain the overall architecture."
- "Compile the authentication-related files into context and identify security gaps."
- "Run codectx with the debug task profile and find the most likely source of the payment processing bug."
- "Generate a 60k-token context of the API layer and write API documentation for each endpoint."Troubleshooting Codectx
tree-sitter fails to parse certain files or raises ImportError
Ensure Python 3.10+ is in use (python --version). Some tree-sitter language wheels require a Rust toolchain to compile on first install; run pip install codectx --no-binary codectx if wheels are unavailable for your platform.
Output context file exceeds the expected token budget
The --tokens flag overrides the config file value. Pass --tokens with an explicit number and add high-noise directories (node_modules, .git, build) to extra_ignore in .codectx.toml.
Watch mode misses file changes in Docker or WSL environments
File-system events may not propagate across bind mounts. Increase the --debounce value to 3 or 5 seconds, or use polling mode if your platform supports it via the underlying watchdog library.
Frequently Asked Questions about Codectx
What is Codectx?
Codectx is a Model Context Protocol (MCP) server that codebase context compiler for ai agents. graph-ranked, token-budgeted, tier-compressed output. smarter than the existing ones. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Codectx?
Follow the installation instructions on the Codectx GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Codectx?
Codectx works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Codectx free to use?
Yes, Codectx is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Codectx Alternatives — Similar Developer Tools Servers
Looking for alternatives to Codectx? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Codectx in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Codectx?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.