How I use Claude to navigate a 200K-line monorepo without getting lost

#!/usr/bin/env python3
# generate-codebase-map.py

import os
import anthropic
from pathlib import Path

client = anthropic.Anthropic()


def get_package_structure(root: str) -> str:
    """Get the top-level packages/apps in a monorepo."""
    lines = []
    for item in sorted(os.listdir(root)):
        item_path = os.path.join(root, item)
        if os.path.isdir(item_path) and not item.startswith('.'):
            package_json = os.path.join(item_path, 'package.json')
            if os.path.exists(package_json):
                import json
                try:
                    pkg = json.loads(Path(package_json).read_text())
                    name = pkg.get('name', item)
                    desc = pkg.get('description', '')
                    lines.append(f"  {name}: {desc}" if desc else f"  {name}")
                except Exception:
                    lines.append(f"  {item}")
    return "
".join(lines)


def summarize_package(package_path: str) -> str:
    """Generate a summary of a single package."""
    
    # Get key files
    key_files = []
    for pattern in ['src/index.ts', 'src/main.ts', 'README.md', 'src/routes']:
        full = os.path.join(package_path, pattern)
        if os.path.exists(full):
            if os.path.isfile(full):
                content = Path(full).read_text()[:3000]
                key_files.append(f"=== {pattern} ===
{content}")
    
    if not key_files:
        return "No key files found"
    
    combined = "

".join(key_files)
    
    response = client.messages.create(
        model="claude-haiku-4-5",  # Fast and cheap for summaries
        max_tokens=300,
        messages=[{
            "role": "user",
            "content": f"Write a 3-5 sentence technical summary of this package:

{combined}"
        }]
    )
    return response.content[0].text


# Generate the map
root = "."
structure = get_package_structure(root)
print(f"# Monorepo Map

## Packages
{structure}

## Package Summaries
")

for item in os.listdir(root):
    if os.path.isdir(item) and not item.startswith('.'):
        if os.path.exists(os.path.join(item, 'package.json')):
            summary = summarize_package(item)
            print(f"### {item}
{summary}
")

def get_service_context(service_path: str) -> str:
    """Generate deep context for a specific service."""
    
    parts = []
    
    # Routes / API surface
    routes_dir = os.path.join(service_path, 'src', 'routes')
    if os.path.isdir(routes_dir):
        for route_file in Path(routes_dir).glob('**/*.ts'):
            parts.append(f"=== {route_file} ===
{route_file.read_text()[:2000]}")
    
    # Database models / schemas
    for schema_pattern in ['src/models', 'src/schemas', 'prisma/schema.prisma']:
        schema_path = os.path.join(service_path, schema_pattern)
        if os.path.isdir(schema_path):
            for f in Path(schema_path).glob('**/*.ts'):
                parts.append(f"=== {f} ===
{f.read_text()[:1000]}")
        elif os.path.exists(schema_path):
            parts.append(f"=== {schema_pattern} ===
{Path(schema_path).read_text()[:3000]}")
    
    context = "

".join(parts[:10])  # Limit to 10 key files
    
    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=800,
        messages=[{
            "role": "user",
            "content": f"Summarize the architecture and API surface of this service:

{context}"
        }]
    )
    return response.content[0].text

# ~/.zshrc

# Ask Claude about specific files
ask-code() {
  local question="$1"
  shift
  local files=("$@")
  
  context=""
  for file in "${files[@]}"; do
    context+="=== $file ===
$(cat $file)

"
  done
  
  echo -e "$context" | claude --print     --system "You are a senior engineer familiar with this codebase. Answer specifically."     "$question"
}

# Usage:
# ask-code "How does auth work?" src/middleware/auth.ts src/services/jwt.ts
# ask-code "What does this query return?" src/queries/user.ts src/models/user.ts