repo2ai

Generate sanitized, AI-ready repository context bundles from a local codebase.

Installation

npm install -g repo2ai

You can also run it without a global install:

npx repo2ai pack

Quick Start

npx repo2ai pack
npx repo2ai pack --format json
npx repo2ai pack --output repo-context.md
npx repo2ai pack --token-mode balanced
npx repo2ai pack --token-mode condensed
npx repo2ai pack --token-mode ast
npx repo2ai inspect
npx repo2ai inspect --json
npx repo2ai inspect --token-mode condensed
npx repo2ai doctor
npx repo2ai init
npx repo2ai pack --condense
npx repo2ai pack --condense aggressive
npx repo2ai pack --max-total-tokens 50000
npx repo2ai pack --target copilot --condense balanced

What repo2ai Does

repo2ai scans a local repository and writes a single transferable context file for ChatGPT, Claude, Codex, GitHub Copilot, Cursor, local Ollama agents, or another developer. The bundle includes a tree, package metadata, scripts, dependency summaries, selected file contents, framework hints, git metadata when available, excluded file notes, security notes, and deterministic token estimates.

Why It Exists

AI coding tools work better with clean context. Copying a repository by hand is slow, noisy, and risky. repo2ai gives you a repeatable local command that keeps generated output readable while excluding secrets, dependencies, build output, binaries, and other noise by default.

Terminal Usage

repo2ai --help
repo2ai --version
repo2ai init
repo2ai inspect
repo2ai inspect --json
repo2ai doctor
repo2ai pack
repo2ai pack --path .
repo2ai pack --output repo-context.md
repo2ai pack --format markdown
repo2ai pack --format json
repo2ai pack --include "src,tests,README.md,package.json"
repo2ai pack --exclude "dist,coverage,.next"
repo2ai pack --max-file-size-kb 100
repo2ai pack --max-total-tokens 80000
repo2ai pack --target copilot
repo2ai pack --condense
repo2ai pack --condense light
repo2ai pack --condense balanced
repo2ai pack --condense aggressive
repo2ai pack --no-redact
repo2ai pack --no-gitignore

Markdown Output

Markdown is the default format and writes repo-context.md unless --output is provided. It is designed to be readable as a single AI-friendly file with metadata, tree structure, file contents, exclusions, and security notes.

JSON Output

repo2ai pack --format json

JSON output writes repo-context.json by default and contains parseable bundle metadata, project metadata, tree text, included file records, excluded file records, security notes, and estimated tokens.

Config File

Create a config with:

repo2ai init

This writes .repo2airc.json. CLI flags override config values.

Example .repo2airc.json with all supported fields:

{
  "output": "repo-context.md",
  "format": "markdown",
  "include": [],
  "exclude": [],
  "respectGitignore": true,
  "redactSecrets": true,
  "maxFileSizeKb": 200,
  "maxTotalTokens": 120000,
  "includeTree": true,
  "includeContents": true,
  "includePackageMetadata": true,
  "includeDependencySummary": true,
  "includeSecurityNotes": true,
  "includeGitMetadata": true,
  "binaryHandling": "omit",
  "largeFileHandling": "omit-with-note",
  "condense": "none",
  "target": "generic",
  "tokenMode": "full",
  "enableAstSummaries": true,
  "astLanguages": ["ts", "tsx", "js", "jsx", "mts", "cts", "mjs", "cjs"],
  "preferAstForLargeFiles": true,
  "astSummaryMaxItems": 50
}

Include and Exclude Options

Use comma-separated patterns:

repo2ai pack --include "src,tests,README.md,package.json"
repo2ai pack --exclude "dist,coverage,.next"

Security exclusions always win. Including .env will not include .env.

Target Presets

Supported targets are generic, chatgpt, claude, cursor, and copilot. They set practical default token budgets for common workflows. They are not official model context limits. --max-total-tokens overrides the preset.

Token Budget Explanation

repo2ai estimates tokens with Math.ceil(text.length / 4). It sorts files by priority, keeps high-priority files first, and omits lower-priority files when the configured token budget is reached.

Condense Mode

Condense mode reduces output size with deterministic local heuristics. It does not call AI APIs or network services.

npx repo2ai pack --condense
npx repo2ai pack --condense aggressive
npx repo2ai inspect --condense balanced

Supported modes are none, light, balanced, and aggressive. The default is none. Passing --condense with no value uses balanced.

• light removes obvious whitespace and trims noisy long sections while keeping most content.
• balanced keeps imports, exports, type/interface declarations, function/class signatures, short useful content, and replaces long bodies with clear placeholders.
• aggressive keeps compact summaries, public signatures, imports/exports summaries, and omits most bodies.

Token Modes and AST Summaries

Token modes control how repo2ai represents file content in the output bundle. AST summaries reduce token usage by replacing full source code with a compact code map containing imports, exports, functions, classes, types, tests, and route hints. This is useful when you want another AI agent to understand the shape of a repo without sending every implementation line.

repo2ai pack --token-mode full
repo2ai pack --token-mode balanced
repo2ai pack --token-mode condensed
repo2ai pack --token-mode ast
repo2ai inspect --token-mode condensed

When to use each mode

• full (default): Use full file content for all included files. Identical to existing behavior. Best when the receiving AI needs exact implementation details.

• balanced: Full content for small files (≤ 10 KB) and important config files. AST summaries for large supported source files. Best for most use cases when context is large.

• condensed: AST summaries for all supported JS/TS source and test files. Full content only for README, package.json, and important config files. Produces significantly smaller output than full. Best when you need a project overview.

• ast: AST summaries for all supported JS/TS files. Full content only for README, package.json, and key config files. Everything else is omitted. Produces the smallest useful code-understanding output.

AST summary contents

AST summaries extract:

• Imports
• Exports
• Functions and async functions (with parameter names)
• Classes and class methods
• Interfaces and type aliases
• Enums
• React components and hooks
• Test suites and test cases (describe/it/test)
• HTTP route hints (Express, Next.js route handlers)
• Database call hints (Prisma, db.query, SQL tagged templates)
• Top-level constants

Enabling and disabling AST summaries

repo2ai pack --ast           # enable AST summaries
repo2ai pack --no-ast        # disable AST summaries

AST summaries are enabled by default.

Supported file extensions

AST parsing is supported for: .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs

AST limitations

AST summaries are best-effort. They are designed to preserve code structure, not exact runtime behavior. Use --token-mode full when the receiving AI needs exact implementation details.

Security and AST Summaries

Security exclusions are applied before AST parsing. Excluded files such as .env, private keys, .npmrc, .git, and node_modules are never parsed for AST summaries. AST summaries extract only symbol names (functions, classes, types, etc.), never values — so secret strings stored in constants are not captured.

Secret Safety Explanation

Repo2AI redacts obvious secrets and excludes sensitive files by default, but no automated tool can guarantee perfect secret removal. Always review generated context files before sharing them externally.

Repo2AI excludes sensitive files and redacts obvious secrets by default, but no automated tool can guarantee perfect secret removal. Always review generated context files before sharing them externally.

Secret protection includes default exclusion of .env, .env.*, private keys, certificates, .npmrc, cloud credential folders, .git, node_modules, binaries, build output, generated output, lockfiles, logs, databases, and large noisy files.

Default Exclusions

Default exclusions include .git, node_modules, .pnpm-store, .yarn, bower_components, vendor, dist, build, out, .next, .nuxt, .svelte-kit, .angular, .vercel, .netlify, .turbo, .output, coverage reports, Playwright reports, caches, temporary folders, .env, .npmrc, private keys, certificates, cloud credential folders, database files, logs, lockfiles, and generated repo2ai outputs such as repo-context.md and repo-context.json.

Doctor Command

repo2ai doctor

Doctor prints local environment checks, package manager detection, config status, output writability, redaction status, binary handling, and estimated token count. It exits with code 0 for success or warnings and 1 for fatal problems.

Inspect Command

repo2ai inspect
repo2ai inspect --json

Inspect runs the same discovery and classification logic as pack but does not write an output file. Use it to see included files, excluded files, token estimates, and redaction status before creating a bundle.

npm Package Safety

The package uses a files allowlist and .npmignore so published package contents are limited to dist, README.md, LICENSE, and CHANGELOG.md. Do not publish generated repo-context files or local .env files.

Preview package contents with:

npm pack --dry-run

Limitations

Redaction is pattern-based and cannot guarantee every possible secret format. Token estimation is deterministic but approximate. Large file truncation is available, but omission with notes is the default. repo2ai does not call AI APIs, cloud services, or external network services.

Roadmap

• More language and framework hints.
• Additional safe output presets.
• Better monorepo summaries.
• Optional custom priority rules.