ctxmap

Codebase context compiler for AI agents. Token-optimized maps + auto-generated instructions.

Why ctxmap?

AI coding agents waste thousands of tokens exploring codebases file-by-file. ctxmap solves this by scanning your project into a compact .ctx format that gives agents instant understanding of your codebase structure, stack, conventions, and patterns.

Quick Start

# Scan your project
npx ctxmap scan

# Generate agent instruction files
npx ctxmap init

# Output to file
npx ctxmap scan --out

.ctx Format

ctxmap outputs a token-optimized format designed for LLM consumption:

@ctx v1
@project recipe-app
@stack next15+react19 mui6 prisma6 vitest3
@pkg lang:typescript pm:pnpm

## tree
src/
  app/
    page.tsx [page,20L] exp:HomePage dep:@mui/material
    layout.tsx [layout,19L] exp:metadata,RootLayout
    api/
      recipes/
        route.ts [api,16L] exp:GET,POST dep:next/server
  components/
    Hero.tsx [comp,17L] exp:Hero props:{title?:str,subtitle?:str}
  hooks/
    useRecipes.ts [hook,22L] exp:useRecipes dep:@tanstack/react-query
  lib/
    db.ts [lib,17L] exp:getRecipes,createRecipe dep:@prisma/client

## conventions
- functions: arrow
- exports: named
- no-html-elements: true
- tests: separate

## patterns
- routing: app-router
- styling: mui
- validation: zod
- orm: prisma

CLI Reference

ctxmap scan

Scan project and output .ctx format.

ctxmap scan                  # Output to stdout
ctxmap scan --out            # Write to .ctxmap/context.ctx
ctxmap scan --out my.ctx     # Write to custom path
ctxmap scan --deep           # Use tree-sitter for deeper analysis
ctxmap scan --lang ts        # Filter by language (ts or py)
ctxmap scan --ignore "*.md"  # Additional ignore patterns
ctxmap scan --no-cache       # Skip cache
ctxmap scan --verbose        # Verbose output

ctxmap init

Generate agent instruction files from your project.

ctxmap init                           # Generate all (CLAUDE.md, .cursorrules, copilot)
ctxmap init --target claude           # Generate only CLAUDE.md
ctxmap init --target cursor copilot   # Generate specific targets

ctxmap sync

Re-scan project using cache for unchanged files.

ctxmap sync            # Update .ctxmap/context.ctx
ctxmap sync --verbose  # Show cache hit/miss info

ctxmap convert

Convert between agent instruction formats.

ctxmap convert --from .ctxmap/context.ctx --to cursor
ctxmap convert --from .ctxmap/context.ctx --to copilot

ctxmap mcp

Start MCP server (stdio transport) for use with Claude Code, Cursor, etc.

ctxmap mcp

MCP Server Setup

Claude Code

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "ctxmap": {
      "command": "npx",
      "args": ["ctxmap", "mcp"]
    }
  }
}

Available MCP Tools

| Tool | Description | Tokens | |------|-------------|--------| | ctxmap_overview | Project summary | ~30-50 | | ctxmap_tree | Full file tree with annotations | ~100-400 | | ctxmap_file | Single file detail | ~20-40 | | ctxmap_related | Imports/imported-by/siblings | ~30-80 | | ctxmap_query | Search by name/export/role | ~20-100 | | ctxmap_conventions | Conventions + patterns | ~20-40 |

Supported Languages

• TypeScript/JavaScript (.ts, .tsx, .js, .jsx, .mts, .mjs)
• Python (.py)

Deep Mode (tree-sitter)

For enhanced parsing with full type resolution, install tree-sitter:

pnpm add tree-sitter tree-sitter-typescript tree-sitter-python
ctxmap scan --deep

Configuration

ctxmap uses sensible defaults with zero configuration. It automatically:

• Reads .gitignore for file exclusions
• Detects your stack from package.json or pyproject.toml
• Identifies conventions from code patterns
• Caches results in .ctxmap/cache.msgpack

Add .ctxmap/ to your .gitignore.

Programmatic API

import { scan, formatCtx } from 'ctxmap';

const map = await scan('./my-project');
const ctx = formatCtx(map);
console.log(ctx);

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT