Context Compiler

One-shot project understanding for AI agents. Runs all analyzers at once and compresses their output into a single structured document optimized for AI consumption.

Use this first when dropped into an unfamiliar codebase. Returns enough information for an AI to understand the project, know where everything is, understand dependencies, and start working immediately.

Usage

CLI

python context_compiler.py <project_path>
python context_compiler.py <project_path> --output context.json
python context_compiler.py <project_path> --output context.md --markdown
python context_compiler.py <project_path> --skip-boundaries  # faster
python context_compiler.py <project_path> --budget 5000      # max ~5000 lines

MCP

drydock_context(project_path: str, skip_boundaries: bool = False) -> str

Returns full project context as JSON.

Example Output

{
  "meta": {
    "project": "my-project",
    "root": "/path/to/my-project",
    "compiled_at": "2025-03-26T14:30:00.123456",
    "compiler_version": "1.0.0"
  },
  "structure": {
    "total_files": 247,
    "total_dirs": 42,
    "total_size": 8_500_000,
    "top_level_dirs": ["src", "tests", "docs", "config"],
    "file_types": {
      ".py": 89,
      ".json": 12,
      ".md": 8,
      ".yaml": 6
    },
    "largest_files": [
      {"path": "src/core/engine.py", "size": 45000},
      {"path": "src/api/handler.py", "size": 32000}
    ]
  },
  "platforms": {
    "detected": [
      {
        "name": "Python",
        "version": "3.11",
        "confidence": "high"
      }
    ],
    "is_multi_platform": false
  },
  "frameworks": [
    "FastAPI",
    "Pydantic",
    "SQLAlchemy",
    "pytest"
  ],
  "codemap": {
    "languages": {
      "python": 89,
      "json": 12,
      "markdown": 8
    },
    "entry_points": [
      {
        "path": "src/main.py",
        "type": "module",
        "is_app": true
      }
    ],
    "key_files": [
      {
        "path": "src/core/engine.py",
        "lines": 450,
        "classes": [
          {
            "name": "Engine",
            "methods": 12,
            "bases": []
          }
        ],
        "functions": ["run", "init"]
      }
    ]
  },
  "interfaces": {
    "module_count": 15,
    "modules": {
      "src/api": {
        "classes": [
          {
            "name": "APIRouter",
            "bases": [],
            "methods": ["route", "handle"]
          }
        ],
        "functions": ["create_app"],
        "exports": ["APIRouter", "create_app"]
      }
    }
  },
  "boundaries": {
    "clusters": [
      {
        "name": "core-engine",
        "files": 12,
        "cohesion": 0.92,
        "external_deps": 2,
        "extraction_risk": "low"
      },
      {
        "name": "api-handlers",
        "files": 8,
        "cohesion": 0.85,
        "external_deps": 4,
        "extraction_risk": "medium"
      }
    ],
    "bridge_files": [
      {
        "file": "src/main.py",
        "connects": ["core", "api"]
      }
    ],
    "orphan_count": 2,
    "orphans": [
      "src/utils/helpers.py"
    ]
  },
  "docs": {
    "README.md": "# My Project\n\nDescription here...",
    "ARCHITECTURE.md": "## Architecture\n\n..."
  }
}

Options

Flag	Type	Default	Description
project_path	positional	required	Path to project root
--output, -o	string	stdout	Output file path
--markdown, -m	flag	false	Output as Markdown instead of JSON
--compact, -c	flag	false	Compact JSON (no indentation)
--skip-boundaries	flag	false	Skip boundary detection for faster results
--budget	int	8000	Target output budget in lines