Codemap.Cli 1.0.3

codemap

codemap scans codebases and turns selected files into focused, deterministic context for AI tools and developers. It filters files, can include Git history, enforces token and size limits, and excludes files with security findings before producing the output.

Contents

• Install
• Features
• Quick start
• Command reference
• Configuration
• Advanced capabilities
• C# library

Installation

codemap is distributed as a .NET tool. Install the published package globally with:

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.

Features: What codemap Provides

Quick Start

1. Install

dotnet tool install --global Codemap.Cli

2. Pack a repository

codemap --format markdown --output repository.md

3. Keep output within a model context window

codemap --include "src/**/*.cs" --token-budget 12000 --output compact-context.md

How to Run codemap

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 Ignore

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

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

codemap also reads .gitignore and .ignore automatically.

🛡️ 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.

📝 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

🌐 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.

Requirements

• .NET SDK 10 or newer.
• Git only when using --remote, --include-diffs, or --include-logs.
• Node.js and npm are not required. Security scanning is implemented with DevSkim for .NET.

Command Reference

General form:

codemap [options]

Show the built-in command reference at any time:

codemap --help

Boolean options are enabled by writing the flag.

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"],
	"ignorePatterns": ["**/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 --ignore, the command-line value replaces the configured list.

Advanced Capabilities

The sections below explain behavior that is useful when tuning output for a larger repository or an automated workflow.

🎯 Include and Ignore Rules

codemap always skips these generated or repository directories:

.git  bin  obj  node_modules  dist  coverage

It also reads these files from the source root, in this order:

.gitignore
.ignore

Patterns are evaluated in order. A pattern ignores a matching path; a pattern beginning with ! re-includes it.

# Ignore generated files
generated/

# Keep one useful fixture
!generated/example.cs

# Ignore all logs
*.log

Include patterns are applied after ignore rules. Common examples:

**/*.cs       all C# files at any depth
src/**        everything under src
*.md          Markdown files at any directory depth

🛡️ Security Scanning

--security-check uses Microsoft DevSkim embedded rules. codemap scans the original UTF-8 source before cleanup transformations. Files with actionable DevSkim findings are excluded from the packed result instead of causing the entire operation to fail.

Excluded paths are reported on the console and exposed through the result model. Use this mode when creating context from repositories that may contain credentials, weak cryptography, or other known security patterns.

📝 Output Formats

Markdown

Markdown includes a repository summary, file listing, per-file token counts, language-aware code fences, and optional Git sections. It is the most convenient format for humans and chat-based AI tools.

XML

XML contains a codemap root, summary attributes, directory structure, file elements, and optional Git metadata. It is useful for structured downstream processing.

JSON

JSON contains summary data, file records, excluded security paths, and optional Git metadata. Each file includes its relative path, content, character count, line count, and token count.

Plain text

Plain text emits each file under a clear path separator. It is useful for tools that do not parse Markdown, XML, or JSON.

🔢 Token Counts and Limits

codemap uses the GPT-4-compatible cl100k_base tokenizer from Microsoft.ML.Tokenizers. Each packed file has a token count, and the final rendered output has an aggregate count.

--token-budget validates the final rendered output. If the output is too large, codemap returns an error rather than silently producing an incomplete result. Use --include, --ignore, --max-file-size, or --split-output to control size.

🌐 Remote Repositories, Git Metadata, and Watch Mode

Clone and pack a GitHub repository:

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

Use a normal URL when preferred:

codemap \
	--remote https://github.com/microsoft/TypeScript.git \
	--include-diffs \
	--include-logs \
	--include-logs-count 10

For a local repository:

codemap --include-diffs --include-logs

Watch mode reports changes but does not automatically repack:

codemap --watch

🌟 Support

If you like my work, feel free to:

• ⭐ this repository. And we will be happy together 😃

Thanks a bunch for supporting me!

🤝 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.