{"id":47268747,"url":"https://github.com/edmundhee/codemap-cli","last_synced_at":"2026-04-14T09:01:29.192Z","repository":{"id":340276100,"uuid":"1164673108","full_name":"EdmundHee/codemap-cli","owner":"EdmundHee","description":"Static analysis CLI that generates relationship maps of codebases for AI-assisted development. MCP server included.","archived":false,"fork":false,"pushed_at":"2026-04-06T15:33:53.000Z","size":346,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T17:31:55.535Z","etag":null,"topics":["ast","claude-code","codemap","developer-tools","mcp","python","static-analysis","typescript","vue"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EdmundHee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T11:00:27.000Z","updated_at":"2026-04-06T15:33:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"57b13de8-23d4-4ff0-baed-0ca8769d5aea","html_url":"https://github.com/EdmundHee/codemap-cli","commit_stats":null,"previous_names":["edmundhee/codemap","edmundhee/codemap-cli"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/EdmundHee/codemap-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdmundHee%2Fcodemap-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdmundHee%2Fcodemap-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdmundHee%2Fcodemap-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdmundHee%2Fcodemap-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EdmundHee","download_url":"https://codeload.github.com/EdmundHee/codemap-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdmundHee%2Fcodemap-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31635969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","claude-code","codemap","developer-tools","mcp","python","static-analysis","typescript","vue"],"created_at":"2026-03-15T08:35:15.058Z","updated_at":"2026-04-10T09:01:00.138Z","avatar_url":"https://github.com/EdmundHee.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# codemap\n\nA static analysis CLI that generates relationship maps of your codebase — classes, functions, imports, call graphs, type dependencies — and exposes them via MCP so AI coding assistants can understand your project without re-scanning it every session.\n\n## Why\n\nEvery time an AI assistant works on your code, it spends tokens exploring the codebase: grepping for functions, reading files, following imports, building mental models from scratch. On large projects this means 10–20 tool calls just to understand how one feature connects.\n\ncodemap does this once, up front. It parses your entire codebase, builds a structured JSON map of all relationships, and serves it on demand via MCP. Instead of:\n\n```\ngrep \"createOrder\" → 8 files → read file 1 → see import → read file 2 → grep again...\n```\n\nThe assistant does:\n\n```\ncodemap_query(\"createOrder\") → defined in orders/service.ts, calls [validatePayment, calculateTotal],\n                                called by [OrderController.create, checkout.handler]\n```\n\nOne call instead of ten.\n\n## Terminology\n\n| Term | Meaning |\n|------|---------|\n| **Codemap** | The generated JSON + Markdown output describing your project's structure and relationships |\n| **Call graph** | A map of which functions call which other functions |\n| **Reverse call graph** | The inverse — which functions are called by which callers (useful for dead code detection and impact analysis) |\n| **Import graph** | File-level dependency tree showing which files import from which other files |\n| **Module** | A directory within your project, treated as a logical unit in the codemap output |\n| **MCP** | Model Context Protocol — a standard for AI tools to discover and use external capabilities |\n| **Framework detection** | Automatic identification of frameworks (Express, FastAPI, etc.) from config files and dependencies |\n\n## Installation\n\n```bash\n# Install globally via npm\nnpm install -g @gingerdev/codemap-cli\n\n# Or install as a project dependency (auto-creates Claude Code commands)\nnpm install @gingerdev/codemap-cli\n```\n\nRequires Node.js \u003e= 18.\n\n## Quick Start\n\n```bash\n# Generate a codemap for your project\ncd /path/to/your/project\ncodemap init          # creates .codemaprc\ncodemap generate      # parses codebase, writes .codemap/\n\n# Query from CLI\ncodemap query --search \"createOrder\"\ncodemap query --function \"validatePayment\"\ncodemap query --callers \"UserService.create\"\ncodemap query --class \"OrderController\"\n\n# Connect to Claude Code via MCP\nclaude mcp add codemap -- codemap-mcp /path/to/your/project\n```\n\n## Commands\n\n### `codemap init`\n\nCreates a `.codemaprc` configuration file with auto-detected include directories and default excludes.\n\n```bash\ncodemap init                  # create config in current directory\ncodemap init --path ./myapp   # create config in a specific directory\ncodemap init --force          # overwrite existing config\n```\n\n### `codemap generate`\n\nParses the codebase and generates the codemap output.\n\n```bash\ncodemap generate              # generate in current directory\ncodemap generate --path ./app # generate for a specific project\n```\n\nOutput is written to `.codemap/`:\n\n```\n.codemap/\n├── codemap.json       # Full structured data (classes, functions, call graphs, etc.)\n├── codemap.md         # Compact root summary (~1500-2000 lines for large projects)\n├── modules/           # Per-directory detailed markdown files\n│   ├── src__core.md\n│   ├── src__api.md\n│   └── ...\n└── .hashes            # Content hashes for change detection\n```\n\n### `codemap query`\n\nSearch and inspect the generated codemap.\n\n```bash\ncodemap query --function \u003cname\u003e     # Query a function by name\ncodemap query --class \u003cname\u003e        # Query a class\ncodemap query --file \u003cpath\u003e         # Query a file (partial match supported)\ncodemap query --module \u003cdir\u003e        # Query a directory/module\ncodemap query --type \u003cname\u003e         # Query a type/interface\ncodemap query --search \u003cterm\u003e       # Search across everything\ncodemap query --callers \u003cname\u003e      # Show what calls a function\ncodemap query --calls \u003cname\u003e        # Show what a function calls\ncodemap query --json                # Output as JSON\n```\n\n### `codemap analyze`\n\nRun structural analysis on the generated codemap to find issues.\n\n```bash\ncodemap analyze --dead-code         # Detect unused functions and methods\ncodemap analyze --duplicates        # Detect redundant/duplicate functions\ncodemap analyze --circular          # Detect circular dependencies\ncodemap analyze --all               # Run all checks at once\ncodemap analyze --all --json        # Output raw JSON for scripting\n```\n\n### `codemap health`\n\nShow a project health score (0–100) with metrics, hotspots, and coupling data.\n\n```bash\ncodemap health                      # Show full health report\ncodemap health --summary            # One-line score only\ncodemap health --json               # Output raw JSON\ncodemap health --gate               # Exit code 1 if below threshold (CI mode)\ncodemap health --gate --threshold 80  # Custom minimum score\ncodemap health --no-degrade         # Fail if score dropped from last run\n```\n\nThe health score factors in complexity, dead code, god classes, nesting depth, and module coupling. Run `codemap generate` at least twice to see trend data.\n\n### `codemap diff`\n\nShow what changed in the codebase since the last codemap generation.\n\n```bash\ncodemap diff                        # Show changes since last generation\ncodemap diff --update               # Show changes, then regenerate\n```\n\n## Configuration\n\nThe `.codemaprc` file controls what gets scanned and how. Created by `codemap init`.\n\n```json\n{\n  \"include\": [\".\"],\n  \"exclude\": [\n    \"node_modules\",\n    \"__pycache__\",\n    \"dist\",\n    \"build\",\n    \"lib\",\n    \".git\",\n    \".codemap\",\n    \"*.test.*\",\n    \"*.spec.*\",\n    \"*.min.*\",\n    \"coverage\",\n    \"vendor\",\n    \".next\",\n    \".nuxt\",\n    \"venv\",\n    \".venv\",\n    \"env\",\n    \".env\",\n    \".tox\",\n    \"eggs\",\n    \"*.egg-info\",\n    \".mypy_cache\",\n    \".pytest_cache\",\n    \".ruff_cache\",\n    \"site-packages\",\n    \"migrations\"\n  ],\n  \"projects\": [\n    \"/path/to/project-a\",\n    { \"name\": \"my-api\", \"root\": \"/path/to/project-b\" }\n  ]\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `include` | Directories to scan. `[\".\"]` scans everything from root. |\n| `exclude` | Patterns to exclude. Supports directory names and glob patterns. |\n| `projects` | (MCP only) List of project paths for multi-project MCP server. |\n| `framework` | Override framework detection (default: auto-detect). |\n| `output` | Output directory (default: `.codemap`). |\n| `detail` | `\"full\"` for complete signatures, `\"names-only\"` for compact output. |\n| `features` | Toggle specific analysis: `call_graph`, `import_graph`, `routes`, `models`, `types`, `data_flow`, `config_deps`, `middleware`. |\n\n## MCP Server (Claude Code Integration)\n\nThe MCP server exposes codemap data as tools that Claude Code can call automatically.\n\n### Setup\n\n```bash\n# Single project\nclaude mcp add codemap -- codemap-mcp /path/to/your/project\n\n# Multiple projects via CLI args\nclaude mcp add codemap -- codemap-mcp ~/Work/project-a ~/Work/project-b\n\n# Multiple projects via .codemaprc (reads \"projects\" field)\nclaude mcp add codemap -- codemap-mcp\n```\n\nFor the config-based approach, add a `projects` array to `~/.codemaprc` or your project's `.codemaprc`.\n\n### Available MCP Tools\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `codemap_projects` | List all registered projects and their status | none |\n| `codemap_overview` | Project summary: modules, frameworks, languages, file counts, dependencies | `project?` |\n| `codemap_module` | Detailed info for a specific directory | `directory`, `project?` |\n| `codemap_query` | Search by function, class, type, or file name (exact + fuzzy) | `name`, `project?` |\n| `codemap_callers` | Find what calls a given function | `name`, `project?` |\n| `codemap_calls` | Find what a given function calls | `name`, `project?` |\n\nThe `project` parameter is optional when only one project is registered. With multiple projects, Claude Code will select the right one based on context.\n\n### Claude Code Commands\n\ncodemap ships with slash commands for Claude Code that orchestrate multi-step workflows using the MCP tools. These are created automatically in `.claude/commands/` when you run `codemap init`, `codemap generate`, or `npm install @gingerdev/codemap-cli`.\n\n| Command | Description |\n|---------|-------------|\n| `/codemap-explore` | Understand the project structure and architecture |\n| `/codemap-find-reusable` | Search for existing code to reuse before writing new functions |\n| `/codemap-impact` | Analyze blast radius before refactoring or modifying code |\n| `/codemap-plan` | Create an implementation plan grounded in actual code structure |\n| `/codemap-health-review` | Review code quality and identify what to refactor next |\n| `/codemap-refresh` | Regenerate codemap when source files have changed |\n\nCommands accept arguments after the name. For example:\n\n```\n/codemap-find-reusable config parsing logic\n/codemap-impact UserService.validate\n/codemap-plan add WebSocket support\n```\n\n## Language Support\n\n| Language | Parser | File Extensions | Features |\n|----------|--------|-----------------|----------|\n| TypeScript | ts-morph | `.ts`, `.tsx` | Classes, functions, imports, exports, types, interfaces, enums, decorators, call expressions, env vars |\n| JavaScript | ts-morph | `.js`, `.jsx`, `.mjs`, `.cjs` | Same as TypeScript |\n| Python | web-tree-sitter (WASM) | `.py` | Classes with inheritance, functions, imports (`import`/`from`), decorators, type hints, `__all__` exports, env vars (`os.environ`, `os.getenv`) |\n| Vue | Vue parser + ts-morph | `.vue` | Extracts `\u003cscript setup\u003e` or `\u003cscript\u003e` blocks for full TS analysis. Captures `\u003ctemplate\u003e` component references (PascalCase and kebab-case) in call graph. |\n\n### Python-Specific Features\n\n- Method access levels from naming conventions (`_protected`, `__private`, `public`)\n- `__all__` export list detection\n- Supports `import x`, `from x import y`, and `from . import z` patterns\n- Async function detection\n\n### Vue-Specific Features\n\n- Prefers `\u003cscript setup\u003e` over `\u003cscript\u003e` when both exist\n- Template component references (`\u003cUserCard\u003e`, `\u003cbase-modal\u003e`) appear in call graph\n- Shares TypeScript parser instance for efficiency\n\n## Framework Detection\n\ncodemap auto-detects frameworks from your config files and dependencies:\n\n| Framework | Detection Method |\n|-----------|-----------------|\n| Express | `express` in package.json (without NestJS) |\n| NestJS | `@nestjs/core` in package.json |\n| FastAPI | `fastapi` in requirements.txt / pyproject.toml |\n| Django | `django` in requirements.txt or `manage.py` exists |\n| Flask | `flask` in requirements.txt / pyproject.toml |\n| Prisma | `prisma/schema.prisma` exists |\n| Sequelize | `sequelize` in package.json |\n| Mongoose | `mongoose` in package.json |\n| TypeORM | `typeorm` in package.json |\n| SQLAlchemy | `sqlalchemy` in requirements.txt / pyproject.toml |\n\n## Noise Reduction\n\ncodemap filters out noise that would bloat the output and waste tokens:\n\n- **Built-in calls filtered**: JS/TS builtins (`map`, `filter`, `push`, `JSON.stringify`, etc.) and Python builtins (`isinstance`, `len`, `str`, `range`, etc.) are removed from call graphs\n- **Test assertions filtered**: `assertEqual`, `pytest.raises`, etc.\n- **Chain expressions collapsed**: `foo.bar().baz().qux()` → `foo.bar`\n- **Type signatures truncated**: Verbose `Annotated[bool, Doc(\"200 lines...\")]` → `bool` (120 char limit)\n- **`self.`/`this.` stripped**: Normalized for cleaner call graphs\n\n## Dependency Tracking\n\ncodemap extracts dependency versions from manifest files without scanning library source code:\n\n- **Node.js**: `package.json` (dependencies, devDependencies, peerDependencies)\n- **Python**: `requirements.txt`, `requirements-dev.txt`, `pyproject.toml`\n\n## Output Structure\n\n### JSON (`codemap.json`)\n\nThe full structured output containing:\n\n```\nproject         → name, languages, frameworks, entry points\nfiles           → per-file: language, hash, exports, imports\nclasses         → per-class: file, extends, implements, decorators, methods, properties\nfunctions       → per-function: file, params, return type, calls, called_by\ntypes           → per-type: file, kind, extends, properties\ncall_graph      → caller → [callees]\nimport_graph    → file → [imported files]\ndependencies    → package versions from manifests\nconfig_deps     → env var usage across files\n```\n\n### Markdown (`codemap.md`)\n\nA compact, directory-level root summary designed for AI context windows. Includes module counts, class/function listings grouped by directory, dependencies, and env var usage. Typically 1500–2000 lines for large projects.\n\n### Module files (`modules/*.md`)\n\nPer-directory detailed files with full function signatures, call/called_by relationships, and import graphs. Used by the MCP `codemap_module` tool for on-demand deep dives.\n\n## Auto-Update with Claude Code Hooks\n\nUse a Claude Code `SessionStart` hook to automatically regenerate the codemap when source files have changed. This runs `codemap check` at the start of each session — if any source files are newer than `codemap.json`, it regenerates before Claude starts working.\n\nAdd this to your project's `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"matcher\": \"startup\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"codemap check || codemap generate\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThis runs on session startup only (not on resume/compact). `codemap check` exits with code 0 if fresh, 1 if stale, 2 if missing — so `||` triggers `codemap generate` only when needed.\n\n### Freshness Check\n\nYou can also check staleness manually:\n\n```bash\ncodemap check              # shows which files changed\ncodemap check --quiet      # exit code only (0=fresh, 1=stale, 2=missing)\n```\n\n## Architecture\n\n```\nsrc/\n├── cli/                  # CLI entry point and commands\n│   ├── index.ts          # Commander setup\n│   └── commands/         # generate, init, query, check, analyze, diff, health\n├── core/                 # Core logic\n│   ├── config.ts         # .codemaprc loading and defaults\n│   ├── scanner.ts        # File discovery (fast-glob)\n│   ├── orchestrator.ts   # Main pipeline: scan → parse → analyze → output\n│   └── query-engine.ts   # Shared query logic (CLI + MCP)\n├── parsers/              # Language-specific AST parsers\n│   ├── parser.interface.ts\n│   ├── typescript/       # ts-morph based\n│   ├── python/           # web-tree-sitter WASM based\n│   └── vue/              # Script extraction + TS delegation\n├── analyzers/            # Structural analysis\n│   ├── call-graph.ts     # Forward + reverse call graph with method resolution\n│   ├── import-graph.ts   # File → imports mapping\n│   ├── coupling.ts       # Module coupling metrics (afferent/efferent/instability)\n│   ├── dead-code.ts      # Dead code detection from reverse call graph\n│   ├── duplicates.ts     # Duplicate function detection\n│   └── circular-deps.ts  # Circular dependency detection\n├── frameworks/           # Auto-detection\n│   └── detector.ts\n├── output/               # Generators\n│   ├── json-generator.ts # Full JSON output\n│   └── md-generator.ts   # Compact MD + per-directory modules\n├── mcp/                  # MCP server\n│   ├── server.ts         # Multi-project MCP with stdio transport\n│   └── formatters.ts     # Markdown formatters for MCP tool output\n└── utils/\n    ├── call-filter.ts    # Noise reduction (built-in filtering, type truncation)\n    ├── logger.ts\n    └── file-utils.ts\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedmundhee%2Fcodemap-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedmundhee%2Fcodemap-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedmundhee%2Fcodemap-cli/lists"}