Repocontext README

⚡ RepoContext

🌟 Why RepoContext?

When feeding codebases into modern AI coding assistants (Claude Code, Cursor, Windsurf, OpenAI Codex, Antigravity, Cline), developers face three critical bottlenecks:

1. 💥 Token Explosion & High API Costs: Raw code dumps quickly exceed context limits or cost tens of dollars per query.
2. 📉 Low Signal-to-Noise Ratio: 80% of lines are routine implementation details. LLMs only need the semantic API surface (signatures, types, interfaces, docstrings).
3. 🔓 Security Leaks: Accidental exposure of .env credentials, API keys, and database URIs in prompts.

RepoContext solves all three with intelligent AST outline pruning, task-focused semantic file ranking, automated credential redaction, and native Model Context Protocol (MCP) integration.

🚀 Key Features

• ⚡ AST Codebase Map & Skeletonizer: Compresses source files by 70%~85% while retaining 100% of interfaces, types, functions, and JSDoc/docstrings.
• 🎯 Task-Oriented Relevance Pruning: Pass your prompt query (e.g. repocontext pack -q "Fix JWT auth token expiry") to automatically rank and pack only the most critical files.
• 🛡️ Automated Secret Scanner & Redaction: Built-in entropy and regex scanner detects and masks OpenAI keys, GitHub tokens, AWS keys, JWTs, and database URIs.
• 🔌 Native Model Context Protocol (MCP) Server: Directly integrates with Claude Desktop, Cursor, Windsurf, and Antigravity via standard MCP tools.
• 📑 Multi-Format Export: Generates clean Markdown with directory trees, Claude-optimized XML (<documents>), or structured JSON.
• 📊 Multi-Model Token & Cost Analytics: Real-time token counter with cost estimates for GPT-4o, GPT-5, Claude 3.5 Sonnet, and Gemini 1.5 Pro.

📦 Quick Start

1. Run without installation via npx

# Pack entire repository into an optimized Markdown prompt
npx repocontext pack

# Pack only files relevant to a specific task prompt
npx repocontext pack -q "Implement Stripe payment webhook handler" -o prompt.md

# Generate lightweight AST skeleton map (75%+ token reduction)
npx repocontext map -o codebase-map.md

2. Global Installation

npm install -g repocontext

🛠️ CLI Usage & Options

# 1. Pack with direct clipboard copy (ready to paste into ChatGPT/Claude)
repocontext pack -c

# 2. Pack relevant files only based on task query
repocontext pack -q "Fix JWT auth expiration" -o prompt.md

# 3. Generate AST symbol map
repocontext map -c

# 4. Analyze token distribution without writing a file
repocontext analyze .

Options for pack:

🔌 Model Context Protocol (MCP) Integration

RepoContext comes with built-in MCP server support. Add it to your claude_desktop_config.json or Cursor/Windsurf MCP settings:

{
  "mcpServers": {
    "repocontext": {
      "command": "npx",
      "args": ["-y", "repocontext", "mcp"]
    }
  }
}

Exposed MCP Tools (4-Tier Context Pyramid):

• get_codebase_map: Extracts token-efficient AST symbol outline map across the repository (~80% token savings).
• extract_relevant_context: Prunes codebase using semantic ranking to return files pertinent to a task prompt.
• read_file_outline: Reads compressed AST skeleton for an individual file (signatures & docstrings).
• read_file_content: Precise source code reading with optional line-range slicing (startLine/endLine) and automated credential masking.

📊 Benchmark & Comparison

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

📄 License

This project is MIT licensed.