{"id":36934502,"url":"https://github.com/jordancoin/codemap","last_synced_at":"2026-04-08T20:04:41.473Z","repository":{"id":325977090,"uuid":"1102890152","full_name":"JordanCoin/codemap","owner":"JordanCoin","description":"a project brain for your AI. Give LLMs instant architectural context without burning tokens","archived":false,"fork":false,"pushed_at":"2026-02-28T20:54:33.000Z","size":9542,"stargazers_count":454,"open_issues_count":6,"forks_count":41,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-28T23:42:19.977Z","etag":null,"topics":["claude","claude-code","cli","codex","codex-cli","context","cursor","developer-tools","llm","openai","project-management"],"latest_commit_sha":null,"homepage":"","language":"Go","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/JordanCoin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","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":"2025-11-24T07:08:15.000Z","updated_at":"2026-02-28T20:50:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JordanCoin/codemap","commit_stats":null,"previous_names":["jordancoin/codemap"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/JordanCoin/codemap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanCoin%2Fcodemap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanCoin%2Fcodemap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanCoin%2Fcodemap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanCoin%2Fcodemap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JordanCoin","download_url":"https://codeload.github.com/JordanCoin/codemap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanCoin%2Fcodemap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29960238,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["claude","claude-code","cli","codex","codex-cli","context","cursor","developer-tools","llm","openai","project-management"],"created_at":"2026-01-13T09:48:01.291Z","updated_at":"2026-04-02T16:07:23.596Z","avatar_url":"https://github.com/JordanCoin.png","language":"Go","readme":"# codemap 🗺️\n\n\u003e **codemap — a project brain for your AI.**\n\u003e Give LLMs instant architectural context without burning tokens.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Go](https://img.shields.io/badge/go-1.21+-00ADD8.svg)\n![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/JordanCoin/6ffe3276ddb8a7a7f08d50d649e567bd/raw/codemap-coverage.json)\n[![Run in Smithery](https://smithery.ai/badge/skills/jordancoin)](https://smithery.ai/skills?ns=jordancoin\u0026utm_source=github\u0026utm_medium=badge)\n\n![codemap screenshot](assets/codemap.png)\n\n## Install\n\n```bash\n# macOS/Linux\nbrew tap JordanCoin/tap \u0026\u0026 brew install codemap\n\n# Windows\nscoop bucket add codemap https://github.com/JordanCoin/scoop-codemap\nscoop install codemap\n```\n\n\u003e Other options: [Releases](https://github.com/JordanCoin/codemap/releases) | `go install` | Build from source\n\n## Recommended Setup (Hooks + Daemon + Config)\n\nNo repo clone is required for normal users.\nRun setup from your git repo root (not a subdirectory), or hooks may not resolve project context.\n\n```bash\n# install codemap first (package manager)\nbrew tap JordanCoin/tap \u0026\u0026 brew install codemap\n\n# then run setup inside your project\ncd /path/to/your/project\ncodemap setup\n```\n\n`codemap setup` is the default onboarding path and configures the pieces that make codemap most useful with Claude:\n- creates `.codemap/config.json` (if missing) with auto-detected language filters\n- installs codemap hooks into `.claude/settings.local.json` (project-local by default)\n- hooks automatically start/read daemon state on session start\n\nUse global Claude settings instead of project-local settings:\n\n```bash\ncodemap setup --global\n```\n\nWindows equivalent:\n\n```bash\nscoop bucket add codemap https://github.com/JordanCoin/scoop-codemap\nscoop install codemap\ncd C:\\path\\to\\your\\project\ncodemap setup\n```\n\nOptional helper scripts (mainly for contributors running from this repo):\n- macOS/Linux: `./scripts/onboard.sh /path/to/your/project`\n- Windows (PowerShell): `./scripts/onboard.ps1 -ProjectRoot C:\\path\\to\\your\\project`\n\n## Verify Setup\n\n1. Restart Claude Code or open a new session.\n2. At session start, you should see codemap project context.\n3. Edit a file and confirm pre/post edit hook context appears.\n\n## Daily Commands\n\n```bash\ncodemap .          # Fast tree/context view (respects .codemap/config.json)\ncodemap --diff     # What changed vs main\ncodemap handoff .  # Save layered handoff for cross-agent continuation\ncodemap --deps .   # Dependency flow (requires ast-grep)\ncodemap skill list # Show available skills\ncodemap context    # Universal JSON context for any AI tool\ncodemap mcp        # Run Codemap MCP server on stdio\ncodemap plugin install # Install the Codemap Codex plugin\ncodemap serve      # HTTP API for non-MCP integrations\n```\n\n## Other Commands\n\n```bash\ncodemap --only swift .\ncodemap --exclude .xcassets,Fonts,.png .\ncodemap --depth 2 .\ncodemap github.com/user/repo\n```\n\n## Options\n\n| Flag | Description |\n|------|-------------|\n| `--depth, -d \u003cn\u003e` | Limit tree depth (0 = unlimited) |\n| `--only \u003cexts\u003e` | Only show files with these extensions |\n| `--exclude \u003cpatterns\u003e` | Exclude files matching patterns |\n| `--diff` | Show files changed vs main branch |\n| `--ref \u003cbranch\u003e` | Branch to compare against (with --diff) |\n| `--deps` | Dependency flow mode |\n| `--importers \u003cfile\u003e` | Check who imports a file |\n| `--skyline` | City skyline visualization |\n| `--animate` | Animate the skyline (use with --skyline) |\n| `--json` | Output JSON |\n\n\u003e **Note:** Flags must come before the path/URL: `codemap --json github.com/user/repo`\n\n**Smart pattern matching** — no quotes needed:\n- `.png` → any `.png` file\n- `Fonts` → any `/Fonts/` directory\n- `*Test*` → glob pattern\n\n## Modes\n\n### Diff Mode\n\nSee what you're working on:\n\n```bash\ncodemap --diff\ncodemap --diff --ref develop\n```\n\n```\n╭─────────────────────────── myproject ──────────────────────────╮\n│ Changed: 4 files | +156 -23 lines vs main                      │\n╰────────────────────────────────────────────────────────────────╯\n├── api/\n│   └── (new) auth.go         ✎ handlers.go (+45 -12)\n└── ✎ main.go (+29 -3)\n\n⚠ handlers.go is used by 3 other files\n```\n\n### Dependency Flow\n\nSee how your code connects:\n\n```bash\ncodemap --deps .\n```\n\n```\n╭──────────────────────────────────────────────────────────────╮\n│                    MyApp - Dependency Flow                   │\n├──────────────────────────────────────────────────────────────┤\n│ Go: chi, zap, testify                                        │\n╰──────────────────────────────────────────────────────────────╯\n\nBackend ════════════════════════════════════════════════════\n  server ───▶ validate ───▶ rules, config\n  api ───▶ handlers, middleware\n\nHUBS: config (12←), api (8←), utils (5←)\n```\n\n### Skyline Mode\n\n```bash\ncodemap --skyline --animate\n```\n\n![codemap skyline](assets/skyline-animated.gif)\n\n### Remote Repos\n\nAnalyze any public GitHub or GitLab repo without cloning it yourself:\n\n```bash\ncodemap github.com/anthropics/anthropic-cookbook\ncodemap https://github.com/user/repo\ncodemap gitlab.com/user/repo\n```\n\nUses a shallow clone to a temp directory (fast, no history, auto-cleanup). If you already have the repo cloned locally, codemap will use your local copy instead.\n\n## Supported Languages\n\n18 languages for dependency analysis: Go, Python, JavaScript, TypeScript, Rust, Ruby, C, C++, Java, Swift, Kotlin, C#, PHP, Bash, Lua, Scala, Elixir, Solidity\n\n\u003e Powered by [ast-grep](https://ast-grep.github.io/). Install via `brew install ast-grep` for `--deps` mode.\n\n## Claude Integration\n\n**Hooks (Recommended)** — Automatic context at session start, before/after edits, and more.\n→ See [docs/HOOKS.md](docs/HOOKS.md)\n\n**MCP Server** — Deep integration with project analysis + handoff tools.\n→ See [docs/MCP.md](docs/MCP.md)\n\n## Multi-Agent Handoff\n\ncodemap now supports a shared handoff artifact so you can switch between agents (Claude, Codex, MCP clients) without re-briefing.\n\n```bash\ncodemap handoff .                 # Build + save layered handoff artifacts\ncodemap handoff --latest .        # Read latest saved artifact\ncodemap handoff --json .          # Machine-readable handoff payload\ncodemap handoff --since 2h .      # Limit timeline lookback window\ncodemap handoff --prefix .        # Stable prefix layer only\ncodemap handoff --delta .         # Recent delta layer only\ncodemap handoff --detail a.go .   # Lazy-load full detail for one changed file\ncodemap handoff --no-save .       # Build/read without writing artifacts\n```\n\nWhat it captures (layered for cache reuse):\n- `prefix` (stable): hub summaries + repo file-count context\n- `delta` (dynamic): changed file stubs (`path`, `hash`, `status`, `size`), risk files, recent events, next steps\n- deterministic hashes: `prefix_hash`, `delta_hash`, `combined_hash`\n- cache metrics: reuse ratio + unchanged bytes vs previous handoff\n\nArtifacts written:\n- `.codemap/handoff.latest.json` (full artifact)\n- `.codemap/handoff.prefix.json` (stable prefix snapshot)\n- `.codemap/handoff.delta.json` (dynamic delta snapshot)\n- `.codemap/handoff.metrics.log` (append-only metrics stream, one JSON line per save)\n\nSave defaults:\n- CLI saves by default; use `--no-save` to make generation read-only.\n- MCP does not save by default; set `save=true` to persist artifacts.\n\nCompatibility note:\n- legacy top-level fields (`changed_files`, `risk_files`, etc.) are still included for compatibility and will be removed in a future schema version after migration.\n\nWhy this matters:\n- default transport is compact stubs (low context cost)\n- full per-file context is lazy-loaded only when needed (`--detail` / `file=...`)\n- output is deterministic and budgeted to reduce context churn across agent turns\n\nHook integration:\n- `session-stop` writes `.codemap/handoff.latest.json`\n- `session-start` shows a compact recent handoff summary (24h freshness window)\n\n**CLAUDE.md** — Add to your project root to teach Claude when to run codemap:\n```bash\ncp /path/to/codemap/CLAUDE.md your-project/\n```\n\n## Project Config\n\nSet per-project defaults in `.codemap/config.json` so you don't need to pass `--only`/`--exclude`/`--depth` every time. Hooks also respect this config.\n\n```bash\ncodemap config init          # Auto-detect top extensions, write config\ncodemap config show          # Display current config\n```\n\nExample `.codemap/config.json`:\n```json\n{\n  \"only\": [\"rs\", \"sh\", \"sql\", \"toml\", \"yml\"],\n  \"exclude\": [\"docs/reference\", \"docs/research\"],\n  \"depth\": 4,\n  \"mode\": \"auto\",\n  \"budgets\": {\n    \"session_start_bytes\": 30000,\n    \"diff_bytes\": 15000,\n    \"max_hubs\": 8\n  },\n  \"routing\": {\n    \"retrieval\": { \"strategy\": \"keyword\", \"top_k\": 3 },\n    \"subsystems\": [\n      {\n        \"id\": \"watching\",\n        \"paths\": [\"watch/**\"],\n        \"keywords\": [\"hook\", \"daemon\", \"events\"],\n        \"docs\": [\"docs/HOOKS.md\"],\n        \"agents\": [\"codemap-hook-triage\"]\n      }\n    ]\n  },\n  \"drift\": {\n    \"enabled\": true,\n    \"recent_commits\": 10,\n    \"require_docs_for\": [\"watching\"]\n  }\n}\n```\n\nAll fields are optional. CLI flags always override config values.\nHook-specific policy fields are optional and bounded by safe defaults.\n\n## Skills\n\ncodemap ships with a **skills framework** — markdown files that provide context-aware guidance to AI agents. Skills are automatically matched against your intent, the files you mention, and the languages in your project.\n\n```bash\ncodemap skill list              # Show all available skills\ncodemap skill show hub-safety   # Print full skill content\ncodemap skill init              # Create a custom skill template\n```\n\n### Builtin Skills\n\n| Skill | Activates When |\n|-------|---------------|\n| `hub-safety` | Editing hub files (3+ importers) |\n| `refactor` | Restructuring, renaming, moving code |\n| `test-first` | Writing tests, TDD workflows |\n| `explore` | Understanding how code works |\n| `handoff` | Switching between AI agents |\n\n### Custom Skills\n\nDrop a `.md` file in `.codemap/skills/` with YAML frontmatter:\n\n```yaml\n---\nname: my-skill\ndescription: When this skill should activate\nkeywords: [\"relevant\", \"keywords\"]\nlanguages: [\"go\"]\n---\n\n# Instructions for the AI agent\n```\n\nProject-local skills override builtins. No Go code needed — just markdown.\n\n### MCP Tools\n\nSkills are also available via MCP: `list_skills` (metadata) and `get_skill` (full body).\n\n## Intelligent Routing\n\nThe prompt-submit hook performs **intent classification** on every prompt — detecting whether you're refactoring, fixing a bug, exploring, testing, or building a feature. It then:\n\n- Surfaces **risk analysis** based on hub file involvement\n- Shows your **working set** (files edited this session)\n- Emits **structured JSON markers** (`\u003c!-- codemap:intent --\u003e`) for tool consumption\n- Matches **relevant skills** and tells you which to pull (`codemap skill show \u003cname\u003e`)\n- Warns about **documentation drift** when docs are stale\n\n## Context Protocol\n\nA single command that gives **any AI tool** codemap's full intelligence:\n\n```bash\ncodemap context                       # Full JSON envelope\ncodemap context --for \"refactor auth\" # With pre-classified intent + matched skills\ncodemap context --compact             # Minimal for token-constrained agents\n```\n\nThe output is a `ContextEnvelope` containing project metadata, intent classification, working set, matched skills, and handoff reference. Cursor, Windsurf, Codex, custom agents — anything that can shell out gets code-aware intelligence.\n\n## HTTP API\n\nFor tools that prefer HTTP over CLI:\n\n```bash\ncodemap serve --port 9471\n```\n\n| Endpoint | Returns |\n|----------|---------|\n| `GET /api/context?intent=refactor+auth` | Full context envelope |\n| `GET /api/context?compact=true` | Minimal envelope |\n| `GET /api/skills` | All skills with metadata |\n| `GET /api/skills?language=go\u0026category=refactor` | Filtered skill matches |\n| `GET /api/skills/\u003cname\u003e` | Full skill body |\n| `GET /api/working-set` | Current session's active files |\n| `GET /api/health` | Server health check |\n\nBinds to `127.0.0.1` by default. Use `--host 0.0.0.0` to expose to network.\n\n## Agent-Aware Handoff\n\nWhen you switch between AI agents (Claude → Codex → Cursor), codemap tracks who worked and what they did:\n\n```json\n{\n  \"agent_history\": [\n    {\"agent_id\": \"claude-code\", \"files_edited\": [\"cmd/hooks.go\", \"main.go\"], \"ended_at\": \"...\"},\n    {\"agent_id\": \"codex\", \"files_edited\": [\"scanner/types.go\"], \"ended_at\": \"...\"}\n  ]\n}\n```\n\nAgent detection is automatic via environment variables. History is carried across sessions (capped at 20 entries) in the handoff artifact.\n\n## Roadmap\n\n- [x] Diff mode, Skyline mode, Dependency flow\n- [x] Tree depth limiting (`--depth`)\n- [x] File filtering (`--only`, `--exclude`)\n- [x] Project config (`.codemap/config.json`)\n- [x] Claude Code hooks \u0026 MCP server\n- [x] Cross-agent handoff artifact (`.codemap/handoff.latest.json`)\n- [x] Remote repo support (GitHub, GitLab)\n- [x] Intelligent routing (intent classification, risk analysis, working set)\n- [x] Skills framework (builtin + custom skills, CLI, MCP tools)\n- [x] Context protocol (`codemap context` — universal JSON envelope for any AI tool)\n- [x] HTTP API (`codemap serve` — REST endpoints for non-MCP integrations)\n- [x] Agent-aware handoff (multi-agent history tracking)\n- [ ] Community skill registry (GitHub-hosted, `codemap skill add \u003cname\u003e`)\n- [ ] Enhanced analysis (entry points, key types)\n\n## Contributing\n\n1. Fork → 2. Branch → 3. Commit → 4. PR\n\n## License\n\nMIT\n","funding_links":[],"categories":["CLIs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordancoin%2Fcodemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjordancoin%2Fcodemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordancoin%2Fcodemap/lists"}