Agent skill

Codemap

by JordanCoin in JordanCoin/codemap

Gives an agent a quick map of a codebase's structure, dependencies, changes and handoffs, and tunes per-project config so the output stays code-first.

MITAuto-check passedAgent Workflows

Install Codemap

skills CLI
$ npx skills add JordanCoin/codemap --skill codemap -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install JordanCoin/codemap codemap --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/JordanCoin/codemap.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/codemap .claude/skills/codemap && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
codemap
GitHub stars
704
Token cost
~1.8k tokens
SKILL.md length
724 words
Files
1
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Gives an agent a quick map of a codebase's structure, dependencies, changes and handoffs, and tunes per-project config so the output stays code-first.

  • Works in 3 steps: Check .codemap/config.json. → If it is missing, clearly boilerplate,… → After writing or improving config, rerun…
  • Getting oriented in an unfamiliar repository before starting a task
  • SKILL.md covers Commands, First-Use Setup, When to Use and Hook Output, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Codemap classifies the intent of your prompt, detects risk, matches relevant skills and tracks your working set through hooks. Its commands show project structure and top files, dependency flow with hub files, changes against the main branch and which files import a given file, so the agent can judge the blast radius before editing. A `codemap skill show` command prints guidance for a matched task such as hub editing, refactoring or testing.

On first use in a repo, or when output is noisy, the agent checks `.codemap/config.json` and, if it is missing or boilerplate, follows the `config-setup` guidance to filter out assets, generated files, fixtures and other non-code directories, then reruns the structure and dependency views. The skill lists when to run each command, such as at the start of any task, when asked where something is, before refactoring or when summarizing a branch, and it supports cross-agent handoffs for resuming work.

When your agent uses it

  • Getting oriented in an unfamiliar repository before starting a task
  • Checking which files import a file before editing it
  • Summarizing what changed on a branch against main
  • Resuming work handed over from another agent

Example prompts

  • “Where is the authentication logic in this project?”
  • “What depends on utils/format.ts? I want to know the blast radius before I change it.”
  • “Summarize what I changed on this branch compared with main.”

Requirements

  • The `codemap` CLI installed

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Check .codemap/config.json.
  2. If it is missing, clearly boilerplate, or obviously too noisy for the stack, run codemap skill show config-setup and follow it.
  3. After writing or improving config, rerun codemap . and codemap --deps.

What it can do on your machine

Read from SKILL.md and the folder at commit 253c8d6. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Codemap loads about 1.8k tokens when it runs. Until then it costs about 94 tokens; SKILL.md has 724 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~94
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from JordanCoin/codemap at commit 253c8d6, republished under its MIT licence (© JordanCoin). 724 words, ~1,822 tokens.

Download SKILL.mdSave it as .claude/skills/codemap/SKILL.md (or your agent's skills folder).
name
codemap
description
Analyze codebase structure, dependencies, changes, cross-agent handoffs, and get code-aware intelligence. Use when user asks about project structure, where code is located, how files connect, what changed, how to resume work, before starting any coding task, when you need risk analysis and skill guidance, or when Codemap should tune project config before analysis.

Codemap

Codemap gives you instant architectural context about any codebase. It classifies your intent, detects risk, matches relevant skills, and tracks your working set — all automatically via hooks.

Codemap should also keep its own per-project config healthy. On first use in a repo, or when output is obviously noisy, tune .codemap/config.json before doing deeper analysis so future calls stay code-first instead of asset-first.

Commands

bash
codemap .                       # Project structure and top files
codemap --deps                  # Dependency flow (imports/functions/hubs)
codemap --diff                  # Changes vs main branch
codemap --diff --ref <branch>   # Changes vs specific branch
codemap --importers <file>      # Who imports this file? Is it a hub?
codemap handoff .               # Build + save handoff artifact
codemap handoff --latest .      # Read latest saved handoff
codemap handoff --json .        # Machine-readable handoff payload
codemap skill list              # Show available skills with descriptions
codemap skill show <name>       # Get full skill instructions
codemap skill init              # Create custom skill template
codemap config show             # Show current project config
codemap context                 # Universal JSON context envelope
codemap context --for "prompt"  # With pre-classified intent + matched skills
codemap context --compact       # Minimal for token-constrained agents
codemap serve --port 9471       # HTTP API for non-MCP integrations

First-Use Setup

Before deeper Codemap analysis in a repo:

  1. Check .codemap/config.json.
  2. If it is missing, clearly boilerplate, or obviously too noisy for the stack, run codemap skill show config-setup and follow it.
  3. After writing or improving config, rerun codemap . and codemap --deps.

Treat config as repo memory. Once tuned, future Codemap calls should benefit automatically.

Signals that config needs setup or tuning:

  • .codemap/config.json is missing
  • config only contains generic auto-detected only values with no real project shaping
  • large non-code directories dominate the tree output
  • stack-specific noise is overwhelming source structure (.xcassets, screenshots, PDFs, training-data, fixtures, generated files, models, vendor directories)
  • the repo stack is obvious, but the config does not reflect it

When to Use

ALWAYS run codemap . when:
  • Starting any new task or feature
  • User asks "where is X?" or "what files handle Y?"
  • User asks about project structure or organization
  • You need to understand the codebase before making changes
ALWAYS run codemap --deps when:
  • User asks "how does X work?" or "what uses Y?"
  • Refactoring or moving code
  • Need to trace imports or dependencies
  • Finding hub files (most-imported)
ALWAYS run codemap --diff when:
  • User asks "what changed?" or "what did I modify?"
  • Reviewing changes before commit
  • Summarizing work done on a branch
ALWAYS run codemap --importers <file> when:
  • About to edit a file — check if it's a hub
  • Need to know the blast radius of a change
  • Deciding whether to refactor or leave alone
Run codemap skill show <name> when:
  • The prompt-submit hook shows matched skills in <!-- codemap:skills [...] -->
  • You need guidance for a specific task (hub editing, refactoring, testing)
  • Risk level is medium or high
Run codemap skill show config-setup when:
  • The repo has no .codemap/config.json
  • The config looks like a bare bootstrap and not a real project policy
  • Codemap output is cluttered by large non-code directories
  • You want Codemap to make better future decisions for this specific repo
Run codemap context when:
  • Piping codemap intelligence to another tool
  • Need a structured JSON summary of the project state
  • Building automation that consumes code-aware context
Run codemap handoff when:
  • Switching between agents (Claude, Codex, Cursor)
  • Resuming work after a break
  • User asks "what should the next agent know?"
Show full SKILL.md (299 more words)Show less

Hook Output

The prompt-submit hook fires on every message and provides:

<!-- codemap:intent {"category":"refactor","risk":"high",...} -->
<!-- codemap:skills [{"name":"hub-safety","score":5},...] -->
Skills matched: hub-safety, refactor — run `codemap skill show <name>` for guidance
  • Intent categories: refactor, bugfix, feature, explore, test, docs
  • Risk levels: low (no hubs), medium (1 hub), high (2+ hubs or 8+ importers)
  • Skills are pull-based: only names are shown, run codemap skill show for full body

Builtin Skills

SkillWhen to Pull
config-setupMissing, boilerplate, or noisy .codemap/config.json
hub-safetyEditing files imported by 3+ others
refactorRestructuring, renaming, moving code
test-firstWriting tests, TDD workflows
exploreUnderstanding how code works
handoffSwitching between AI agents

Output Interpretation

Tree View (codemap .)
  • Stars (⭐) indicate top 5 largest source files
  • Directories flattened when containing single subdirectory
Dependency Flow (codemap --deps)
  • External dependencies grouped by language
  • Internal import chains showing how files connect
  • HUBS section shows most-imported files (3+ importers)
Diff Mode (codemap --diff)
  • (new) = untracked, ✎ = modified, (+N -M) = lines changed
  • Warning icons show hub files (high impact)
Importers (codemap --importers <file>)
  • Shows all files that import this file
  • Flags hub status (3+ importers = high impact)
Context Envelope (codemap context)
  • JSON with project metadata, intent, working set, matched skills, handoff ref
  • --compact strips skills and limits working set for token savings

MCP Tools

If codemap MCP server is configured, these tools are available:

ToolUse For
get_structureProject tree
get_dependenciesDependency flow + hubs
get_diffChanged files with impact
find_fileSearch by filename
get_importersWho imports a file
get_hubsList all hub files
get_file_contextFull context for one file
get_handoffBuild/read handoff artifact
get_working_setFiles edited this session
list_skillsAvailable skills (metadata)
get_skillFull skill instructions
get_activityRecent coding activity
start_watch / stop_watchControl daemon
statusVerify MCP connection
list_projectsDiscover projects

HTTP API

When codemap serve is running:

EndpointReturns
GET /api/context?intent=...Context envelope
GET /api/skillsAll skills metadata
GET /api/skills/<name>Full skill body
GET /api/working-setCurrent working set
GET /api/healthServer health

© JordanCoin, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/codemap of JordanCoin/codemap.

Open the folder on GitHubat commit 253c8d6

Compare with similar skills

Codemap next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Codemap compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Codemap this skillJordanCoin/codemap704—~1.8kAutomated safety check: PassMIT
Ripwire Subsystem Handoffredhat-et/ripwire2.4k—~1.8kAutomated safety check: NotesApache-2.0
ccc Semantic Code Searchcocoindex-io/cocoindex-code2.7k—~938Automated safety check: PassApache-2.0
Repomix Codebase Packeryamadashy/repomix29k—~1.3kAutomated safety check: NotesMIT
Codebase Handbook BuilderRuhan-Wang/Harness_Handbook332—~2.2kAutomated safety check: PassApache-2.0
Codebase SearchHelweg/open-codebase-index217—~1.3kAutomated safety check: PassMIT

Similar skills

  • Ripwire Subsystem Handoff

    redhat-et/ripwire

    Produces a short brief for handing a code subsystem to a teammate or fresh session, using ripwire to rank symbols, expand bodies and surface design docs.

    2.4k GitHub stars~1.8k tokensUpdated today
    Agent WorkflowsAuto-check: notes
  • ccc Semantic Code Search

    cocoindex-io/cocoindex-code

    Semantic code search and index management with the ccc CLI: the agent initializes, indexes and queries the project by concept, filtering by language or path.

    2.7k GitHub stars~938 tokensUpdated yesterday
    Agent WorkflowsAuto-check passed
  • Repomix Codebase Packer

    yamadashy/repomix

    Packs a local directory or remote GitHub repository into one AI-friendly file with Repomix, then searches it to explore structure, find patterns and count tokens.

    29k GitHub stars~1.3k tokensUpdated 4 days ago
    Agent WorkflowsAuto-check: notes
  • Codebase Handbook Builder

    Ruhan-Wang/Harness_Handbook

    Generates, refreshes, validates and uses a compact handbook that maps where a change touches in a repository, using the active Codex session and no external LLM API.

    332 GitHub stars~2.2k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed
  • Codebase Search

    Helweg/open-codebase-index

    Chooses the right retrieval tool for code questions: compact context for unfamiliar repos, direct lookup for known symbols, call graphs for relationships and grep for exhaustive matches.

    217 GitHub stars~1.3k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed
  • Codebase Search Workflow

    Helweg/open-codebase-index

    Directs an agent to use a local codebase index for repository orientation, definition lookups, call graphs and semantic search before turning to web lookups.

    217 GitHub stars~822 tokensUpdated yesterday
    Agent WorkflowsAuto-check passed

More from JordanCoin/codemap

  • Codemap Config Setup

    JordanCoin/codemap

    Writes or tunes .codemap/config.json so Codemap output centers on a repository's real source code instead of assets, fixtures and generated files.

    704 GitHub stars~650 tokensUpdated yesterday
    Auto-check passed

Questions about Codemap

What does Codemap do?

Gives an agent a quick map of a codebase's structure, dependencies, changes and handoffs, and tunes per-project config so the output stays code-first. Codemap classifies the intent of your prompt, detects risk, matches relevant skills and tracks your working set through hooks. Its commands show project structure and top files, dependency flow with hub files, changes against the main branch and which files import a given file, so the agent can judge the blast radius before editing.

When should I use Codemap?

Codemap fits situations like: getting oriented in an unfamiliar repository before starting a task; checking which files import a file before editing it; summarizing what changed on a branch against main; resuming work handed over from another agent.

How do I install Codemap in Claude Code?

Run `npx skills add JordanCoin/codemap --skill codemap -a claude-code`. Or copy the skill folder (.claude/skills/codemap in JordanCoin/codemap) into .claude/skills/codemap in your project. Claude Code loads it when a task matches its description.

How do I install Codemap in Codex?

Run `npx skills add JordanCoin/codemap --skill codemap -a codex`. Or copy the skill folder (.claude/skills/codemap in JordanCoin/codemap) into .agents/skills/codemap in your project. Codex loads it when a task matches its description.

Can I use Codemap in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add JordanCoin/codemap --skill codemap -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/codemap, .gemini/skills/codemap, .github/skills/codemap and .opencode/skills/codemap in your project.

What does Codemap need to run?

SKILL.md names no scripts, command-line tools or credentials: Codemap is instructions for the agent only. Our summary lists: The `codemap` CLI installed.

Does Codemap access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Codemap safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Codemap use?

Codemap is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Codemap use?

About 1.8k tokens (SKILL.md is roughly 7.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Codemap?

Skills that share tags, products or a category with Codemap: Ripwire Subsystem Handoff (redhat-et/ripwire, 2.4k stars), ccc Semantic Code Search (cocoindex-io/cocoindex-code, 2.7k stars), Repomix Codebase Packer (yamadashy/repomix, 29k stars) and Codebase Handbook Builder (Ruhan-Wang/Harness_Handbook, 332 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Codemap?

JordanCoin (a GitHub user) maintains it in JordanCoin/codemap, which has 704 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 7, 2026.

Source: JordanCoin/codemap on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.