CodeContext

CodeContext is a cross-platform C# CLI tool and MCP (Model Context Protocol) server for Mac, Windows, and Linux that turns a codebase into text for an LLM to see its context. It's a code context tool built for prompt engineering: feed a project straight into ChatGPT, Claude, or any other LLM-based coding assistant without manually copy-pasting files.

It scans project directories, generates a structured representation of the project, and extracts relevant file contents while intelligently filtering out unnecessary files and directories. Now with token budget optimization and relevance-based file selection for agentic coding workflows!

Update: A more comprehensive tool is code2prompt. I found that CodeContext is more user-friendly, faster, and automatically includes only user code (based on both extension and file contents), but you may have better luck with alternatives.

Features

Core Features

• Hierarchical Project Structure: Generates a clear tree view of your project
• Smart Content Extraction: Extracts contents of relevant source files
• Intelligent Filtering: Automatically filters out binaries, dependencies, build outputs, and more
• Git-Aware: Respects .gitignore rules
• Binary File Detection: Automatically detects and skips binary files
• Generated Code Detection: Excludes auto-generated code
• Highly Customizable: Configure ignored extensions, directories, and file size limits
• Multiple Output Formats: Supports plain text and JSON output
• Well-Architected: Clean separation of concerns with interfaces for testability

🆕 Agentic Coding Features

• MCP Server Mode: Native integration with Claude Code, Cline, and other MCP-compatible agents
• Token Budget Optimization: Intelligently selects most relevant files within token constraints
• Relevance Scoring: Automatically ranks files based on task description
• Multiple Selection Strategies: GreedyByScore, ValueOptimized, and Balanced algorithms
• Dynamic Context Generation: Task-specific context rather than dumping entire codebase

Architecture

The project follows SOLID principles with a modular architecture:

• Configuration/: Filter configuration settings and app configuration
• Interfaces/: Abstraction interfaces (IFileChecker, IConsoleWriter)
• Services/: Core business logic
  • File filtering and scanning (FileFilterService, ProjectScanner)
  • Token counting and budget optimization (TokenCounter, TokenBudgetOptimizer)
  • Relevance scoring (FileRelevanceScorer)
  • Git integration (GitIgnoreParser, GitHelper)
  • Output formatting and content building
• Mcp/: Model Context Protocol server tools
  • MCP tool implementations for agentic coding integration
• Utils/: Utility functions (FileUtilities, Guard)

This design makes the codebase maintainable, testable, and extensible while supporting both CLI and MCP server modes.

Getting Started

Prerequisites

• .NET 9.0 or later

macOS

Install .NET SDK if you haven't already:

brew install --cask dotnet-sdk

Windows

Download and install the .NET 9 SDK

Linux

Follow the official .NET installation guide for your distribution.

Installation

1. Clone the repository:

git clone https://github.com/DavidVeksler/CodeContext.git
cd CodeContext

2. Build the project:

dotnet build

3. (Optional) Publish for your platform:

# Self-contained executable
dotnet publish -c Release -r win-x64 --self-contained  # Windows
dotnet publish -c Release -r osx-x64 --self-contained  # macOS
dotnet publish -c Release -r linux-x64 --self-contained  # Linux

Usage

Run the application with:

dotnet run [path_to_index] [output_file]

Arguments:

• path_to_index: The directory to analyze (optional, will prompt if not provided)
• output_file: The file to write the output (optional, defaults to {foldername}_context.txt in the indexed directory)

If no arguments are provided, the application will prompt for input interactively.

Example

# Interactive mode
dotnet run

# With arguments
dotnet run ./MyProject ./output/context.txt

# Using published executable
./CodeContext ./MyProject ./output/context.txt

🚀 MCP Server Mode (New!)

CodeContext now supports Model Context Protocol (MCP), enabling native integration with agentic coding tools like Claude Code, Cline, and other MCP-compatible clients.

What is MCP Server Mode?

MCP server mode provides:

• Intelligent context generation based on task descriptions
• Token budget optimization - automatically selects most relevant files within token limits
• Dynamic queries - agents can request exactly the context they need
• Multiple strategies - optimize for relevance, value, or balanced coverage

Setup with Claude Code

1. Build CodeContext:

dotnet build

2. Add to your Claude Code MCP configuration (~/.config/claude/mcp.json or project .claude/mcp.json):

{
  "mcpServers": {
    "codecontext": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/CodeContext/CodeContext.csproj",
        "--",
        "--mcp"
      ]
    }
  }
}

3. Restart Claude Code - CodeContext will now be available as an MCP tool!

Available MCP Tools

1. GetCodeContext

Get optimized code context for a specific task within a token budget.

Parameters:

• projectPath (required): Path to project directory
• taskDescription (required): Description of task (e.g., "fix authentication bug", "add payment feature")
• tokenBudget (optional, default: 50000): Maximum tokens to use
• includeStructure (optional, default: true): Include project structure
• strategy (optional, default: "ValueOptimized"): Selection strategy
  • GreedyByScore: Pick highest-scoring files first
  • ValueOptimized: Maximize relevance per token (best bang for buck)
  • Balanced: Mix of high-value and comprehensive coverage

Example:

Agent: Use GetCodeContext with projectPath="/path/to/project",
       taskDescription="implement user authentication",
       tokenBudget=30000,
       strategy="ValueOptimized"

2. GetProjectStructure

Get hierarchical directory tree of the project.

Parameters:

• projectPath (required): Path to project directory

3. ListProjectFiles

List all files with token counts and optional relevance filtering.

Parameters:

• projectPath (required): Path to project directory
• query (optional): Query to filter/rank files by relevance

4. GetFileContent

Get content of specific files.

Parameters:

• projectPath (required): Path to project directory
• filePaths (required): Comma-separated list of relative file paths

How Token Budget Optimization Works

1. Relevance Scoring: Files are scored based on:

   • File name matching task keywords (30% weight)
   • File path matching keywords (20% weight)
   • Content matching keywords (40% weight)
   • File importance indicators (10% weight)

2. Selection Strategies:

   • ValueOptimized (recommended): Maximizes relevance/token ratio - gives you the best context per token
   • GreedyByScore: Picks highest-scoring files until budget is exhausted
   • Balanced: Combines both approaches for comprehensive yet efficient coverage

3. Result: You get the most relevant files for your task within your token budget!

Example Workflow

# Agent asks: "Help me fix the login authentication bug"

# CodeContext MCP server:
# 1. Scans project files
# 2. Scores files for relevance to "login authentication bug"
# 3. Selects optimal files within token budget (e.g., 50K tokens)
# 4. Returns context with:
#    - auth/login.ts (score: 0.95, 2K tokens)
#    - auth/session.ts (score: 0.87, 1.5K tokens)
#    - middleware/auth.ts (score: 0.79, 1K tokens)
#    - tests/auth.test.ts (score: 0.72, 3K tokens)
#    - ... (up to budget)

Benefits for Agentic Coding

• Token Efficiency: Don't waste tokens on irrelevant files
• Task-Specific Context: Get exactly what you need for each task
• Automatic Relevance Ranking: No manual file selection needed
• Scalable: Works with large codebases by intelligently sampling
• Multiple Strategies: Choose optimization approach per task

Configuration

Create a config.json file in the application directory to customize settings:

{
  "DefaultInputPath": ".",
  "DefaultOutputFileName": "context.txt",
  "OutputFormat": "text",
  "IncludeStructure": true,
  "IncludeContents": true
}

Advanced Configuration

Customize filtering behavior by modifying the FilterConfiguration class:

• IgnoredExtensions: File extensions to ignore (e.g., .exe, .dll, .png)
• IgnoredDirectories: Directories to ignore (e.g., node_modules, bin, obj)
• IgnoredFiles: Specific files to ignore (e.g., .gitignore, package-lock.json)
• MaxFileSizeBytes: Maximum file size to process (default: 100KB)
• BinaryThreshold: Threshold for binary file detection (default: 0.3)

Output Formats

Text Format (default)

Plain text output with file paths, separators, and content.

JSON Format

Structured JSON with content and timestamp:

{
  "content": "...",
  "timestamp": "2025-11-21T10:30:00"
}

Error Handling

The application provides clear error messages with appropriate exit codes:

• 1: Directory not found
• 2: I/O error
• 3: Access denied
• 4: Unexpected error

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

The codebase uses:

• C# 12 with modern language features
• Nullable reference types for better null safety
• XML documentation comments on all public APIs
• Dependency injection patterns for testability

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Acknowledgments

Built with ❤️ for the developer community to make working with LLMs more efficient.