Codemap.Cli 0.1.0

codemap

codemap packages your repository into clear, AI-ready context. Choose which files to include, add Git history or reusable Skills, control output size, and safely review or apply changes returned as standard Git diffs.

Contents

• Installation
• Features
• How to Run
• Command reference
• Configuration
• Advanced capabilities
• Releases
• Contribution

Installation

Install codemap as a global command-line tool. This lets you run codemap from any terminal and any project folder:

dotnet tool install --global Codemap.Cli

Then run it from any directory with codemap.

Running codemap without options scans the current directory. Change into the repository directory before running it.

The usual AI-assisted workflow is:

<svg role="img" aria-labelledby="codemap-workflow-title codemap-workflow-desc" viewBox="0 0 960 180" width="100%" xmlns="http://www.w3.org/2000/svg"> <title id="codemap-workflow-title">Codemap AI-assisted workflow</title> <desc id="codemap-workflow-desc">Four stages: pack the repository, send context to AI, receive a changes patch, then review and apply it.</desc> <defs> <marker id="codemap-workflow-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"> <polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/> </marker> </defs> <rect width="960" height="180" fill="#f5f5f5"/> <path d="M 212 88 H 268" fill="none" stroke="#4f5d75" stroke-width="2" marker-end="url(#codemap-workflow-arrow)"/> <path d="M 452 88 H 508" fill="none" stroke="#4f5d75" stroke-width="2" marker-end="url(#codemap-workflow-arrow)"/> <path d="M 692 88 H 748" fill="none" stroke="#4f5d75" stroke-width="2" marker-end="url(#codemap-workflow-arrow)"/> <rect x="28" y="48" width="184" height="80" rx="8" fill="#fff" stroke="#2d3142"/> <rect x="268" y="48" width="184" height="80" rx="8" fill="#fff" stroke="#2d3142"/> <rect x="508" y="48" width="184" height="80" rx="8" fill="#fff" stroke="#2d3142"/> <rect x="748" y="48" width="184" height="80" rx="8" fill="#fff" stroke="#eb6c36"/> <text x="120" y="82" text-anchor="middle" fill="#2d3142" font-family="Arial, sans-serif" font-size="16" font-weight="600">Pack repository</text> <text x="360" y="82" text-anchor="middle" fill="#2d3142" font-family="Arial, sans-serif" font-size="16" font-weight="600">Send context to AI</text> <text x="600" y="82" text-anchor="middle" fill="#2d3142" font-family="Arial, sans-serif" font-size="16" font-weight="600">Receive changes.patch</text> <text x="840" y="82" text-anchor="middle" fill="#2d3142" font-family="Arial, sans-serif" font-size="16" font-weight="600">Review and apply</text> <text x="120" y="106" text-anchor="middle" fill="#4f5d75" font-family="monospace" font-size="12">codemap --output</text> <text x="360" y="106" text-anchor="middle" fill="#4f5d75" font-family="monospace" font-size="12">context.md</text> <text x="600" y="106" text-anchor="middle" fill="#4f5d75" font-family="monospace" font-size="12">standard Git diff</text> <text x="840" y="106" text-anchor="middle" fill="#eb6c36" font-family="monospace" font-size="12">codemap --apply</text> </svg>

Codemap produces context. It does not execute AI output, run Skill instructions, or silently modify repository files.

Features

How to Run

codemap's main workflow is simple: choose a source directory, select an output format, and write the generated repository context to a file. The examples below focus on core commands.

❔ Help

Use the built-in help whenever you need to check available commands and options:

codemap --help

🔀 Include and Exclude

Use --include to select files and --exclude to remove paths from that selection:

codemap \
	--include "src/**/*.cs,README.md" \
	--exclude "**/bin/**,**/obj/**" \
	--format markdown \
	--output source-context.md

codemap also reads .gitignore and .ignore automatically.

The same selection can use short aliases: codemap -i "src/**/*.cs" -e "**/bin/**,**/obj/**" -f markdown -o source-context.md.

🩹 Patch and Apply

Generate repository context with patch-generation instructions:

codemap stdout --patch
codemap stdout -p --format markdown

Send that context to an AI provider and ask it to return one standard unified Git diff. Save the response as changes.patch. Do not execute AI output as a shell script.

Review and apply the diff from the repository root:

codemap --apply changes.patch

The command:

1. Prints the complete diff preview.
2. Validates it with git apply --check.
3. Lists each changed repository-relative file.
4. Requests approval for every file.
5. Applies the diff with git apply only after all approvals.

Git is required for patch application. Rejecting any file cancels the operation without applying changes.

🧠 Skills

Load reusable AI instructions from a project or user Skill directory:

codemap stdout --skills review,architecture

Named Skills are searched in this order:

1. .agents/skills/<name>/SKILL.md
2. .agent/skills/<name>/SKILL.md
3. .claude/skills/<name>/SKILL.md
4. The same directories under the current user's home directory.

Load one exact Skill file when a deterministic path is preferred:

codemap stdout --skills .agents/skills/review/SKILL.md

Repeat --skills to load multiple names or explicit files. Use -s as its short alias. Skill files are read as text and never executed. Named Skills use project files before global files; explicit paths do not perform discovery.

📝 Format

The default format is Markdown. Use --format to choose another output format when needed:

# Human- and AI-friendly document
codemap --format markdown --output repository.md

# Structured data for another program
codemap --format json --output repository.json

# XML or simple text output
codemap --format xml --output repository.xml
codemap --format plain --output repository.txt

🛡️ Security Check

Use DevSkim to exclude files with actionable security findings before they enter the generated context:

codemap \
	--security-check \
	--format markdown \
	--output reviewed-context.md

codemap reports excluded files in the terminal. Node.js and npm are not required.

🌐 Remote

codemap can clone a repository and pack a selected branch:

codemap \
	--remote microsoft/generative-ai-for-beginners \
	--remote-branch main \
	--format markdown \
	--output remote-context.md

The same command accepts a complete Git URL. Git must be installed and available on PATH for remote repositories and Git metadata.

🔄 Workflows

🔍 Review a repository

Create a focused Markdown snapshot and send it to an AI tool with a specific request:

codemap \
	--include "src/**/*.cs,tests/**/*.cs,README.md" \
	--exclude "**/bin/**,**/obj/**" \
	--format markdown \
	--output review-context.md

Example request:

Review this repository for correctness, security risks, and missing tests.
Do not propose changes outside the selected files. Reference files by path.

Command Reference

General form:

codemap [options]
codemap stdout [options]
codemap clipboard [options]
codemap --stdout [options]
codemap --clipboard [options]

Show the built-in command reference at any time:

codemap --help

Boolean options are enabled by writing the flag.

Output formats

--patch preserves the selected output format while adding instructions for generating a standard unified Git diff. stdout and clipboard are output destinations; they are not formats.

Configuration

Configuration uses JSON. codemap automatically loads codemap.json or codemap.config.json from the source root. Use --config to select another file.

{
	"outputPath": "artifacts/repository.md",
	"format": "Markdown",
	"includePatterns": ["**/*.cs", "**/*.md"],
	"excludePatterns": ["**/test-data/**"],
	"includeFileSummary": true,
	"includeDirectoryStructure": true,
	"showLineNumbers": false,
	"removeComments": true,
	"removeEmptyLines": true,
	"enableSecurityCheck": true,
	"maxFileSizeBytes": 500000,
	"tokenBudget": 12000,
	"includeGitDiffs": false,
	"includeGitLogs": true,
	"gitLogCount": 10,
	"splitOutputBytes": 200000
}

Command-line values override configuration values. For list options such as --include and --exclude, the command-line value replaces the configured list.

Advanced Capabilities

🚫 Ignore

Use .ignore to keep repository-specific files out of generated context, such as local notes, logs, fixtures, or generated output. Place it in the source root and add one glob per line; codemap also reads .gitignore, supports comments and ordered rules, and uses ! to re-include a matching path. Common generated directories are excluded automatically.

🔢 Token Counts

Token counts help estimate how much context an AI tool will receive. codemap reports per-file and final-output counts using the GPT-4-compatible cl100k_base encoding; use --token-budget to reject oversized output, --max-file-size to skip large files, or --split-output to create smaller parts.

🔄 Workflow

Use --remote when the repository is not available locally; codemap clones it into a temporary directory and packs the selected branch. For repository history, --include-diffs adds current changes and --include-logs adds recent commits. --watch monitors a local source tree and reports changes so you can run codemap again.

Releases

Codemap uses GitHub Release Drafter to keep the next release notes updated from merged pull requests. Release notes are grouped by labels and include the matching NuGet installation command.

Use these labels when opening a pull request:

Release Drafter maintains a draft release automatically. Review and publish the draft from GitHub when ready. Publishing creates a v*.*.* tag, which starts the existing workflow that builds, tests, packs, and publishes Codemap.Cli to NuGet.

🤝 Contribution

Thanks to all contributors, you're awesome and this wouldn't be possible without you! The goal is to build a categorized, community-driven collection of very well-known resources.

Please follow this contribution guideline to submit a pull request or create the issue.