Codemap.Cli 1.0.2

codemap

Repository context, compressed. Package source code into deterministic, AI-friendly output from the command line or a reusable .NET library.

Contents

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

codemap is a .NET 10 command-line tool and reusable C# library for turning a repository into compact, AI-friendly output. It provides deterministic discovery, Git-aware filtering, token counting, DevSkim security scanning, and configurable output formats.

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. Use --root when your current directory contains protected system folders, for example codemap --root C:\path\to\repository.

Features: What codemap Provides

Quick Start

1. Install

dotnet tool install --global Codemap.Cli

2. Pack a repository

codemap --root . --format markdown --output repository.md

3. Keep output within a model context window

codemap --root . --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

📁 Root

Pack the current directory into Markdown, which is convenient for sharing with an AI tool:

codemap \
	--root . \
	--format markdown \
	--output repository.md

🎯 Include and Ignore

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

codemap \
	--root . \
	--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 \
	--root . \
	--security-check \
	--format markdown \
	--output reviewed-context.md

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

📝 Format

Use --format to choose the output that fits your workflow:

# 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 --root . --include-diffs --include-logs

Watch mode reports changes but does not automatically repack:

codemap --root . --watch

Using the C# Library

The reusable core can be called without the CLI:

using Codemap.Core;

var result = await new CodePacker().PackAsync(new PackOptions
{
		RootDirectory = ".",
		Format = OutputFormat.Markdown,
		IncludePatterns = ["**/*.cs"],
		EnableSecurityCheck = true,
		TokenBudget = 12000
});

Console.WriteLine(result.Content);
Console.WriteLine($"Files: {result.Files.Count}");
Console.WriteLine($"Tokens: {result.TokenCount}");

The core API returns packed files, rendered content, character and token counts, Git metadata, and security-excluded paths.

Development

dotnet build Codemap.slnx
dotnet test --solution Codemap.slnx

Tests are organized under tests/Codemap.Tests/Unit/ for core behavior and tests/Codemap.Tests/Integration/ for CLI process behavior.

See docs/how-it-works.md for pipeline boundaries and extension guidance. See AGENTS.md for repository conventions.

Troubleshooting

The output is too large

Use narrower --include patterns, more --ignore patterns, --max-file-size, or --token-budget.

A file is missing

Check the default ignored directories, .gitignore, .ignore, and the include patterns. Binary and invalid UTF-8 files are intentionally skipped.

Git metadata is empty

Run from a Git working tree and verify that git is installed and available on PATH.

Remote cloning fails

Verify the repository URL, branch name, network access, and Git installation.

Security files are excluded

Review the DevSkim findings reported by the CLI. codemap excludes actionable findings by design so sensitive or risky content does not enter the generated AI context.