repo2ai

repo2ai packs a local code repository into a clean, structured, token-aware Markdown context file for ChatGPT, Claude, Codex, and other AI coding agents.

It helps developers give an AI coding assistant the right project context without manually copying files.

repo2ai .

By default, this writes repo-context.md in the current working directory. repo2ai is local-first: it scans files on your machine and does not upload code, call external APIs, or integrate with AI APIs.

Features

• Scans a local repository directory.
• Respects default ignore rules, .gitignore, and .repo2aiignore.
• Writes repo-context.md by default.
• Uses a 30000 token budget by default.
• Generates a directory tree, included files table, omitted files table, suggested prompt, and file contents.
• Skips binary files, real .env files, lock file contents, and very large files by default.
• Redacts common secrets before writing output.
• Has no backend, no uploads, no external API calls, and no AI API integration.

Install

npm install -g @c.v.e/repo2ai

The npm package is scoped as @c.v.e/repo2ai, but the installed CLI command is still repo2ai.

For local development:

npm install
npm run build
npm link

Usage

repo2ai .
repo2ai ./my-project --out context.md
repo2ai . --max-tokens 30000
repo2ai . --include src,README.md,package.json
repo2ai . --exclude tests,dist,node_modules
repo2ai . --tree-depth 3

By default, repo2ai . writes repo-context.md in the current working directory. It does not print the full context to stdout.

If the output file already exists, repo2ai refuses to overwrite it:

$ repo2ai .
Output file already exists: /path/to/repo-context.md. Use --force to overwrite or choose a different --out path.

Use --force to overwrite intentionally:

repo2ai . --force

Options

| Option | Default | Description | | --- | --- | --- | | --out <file> | repo-context.md | Output Markdown file. | | --force | false | Overwrite an existing output file. | | --max-tokens <number> | 30000 | Approximate token budget. | | --include <patterns> | none | Comma-separated include patterns. | | --exclude <patterns> | none | Comma-separated exclude patterns. | | --tree-depth <number> | 4 | Maximum directory tree depth. | | --max-file-size <bytes> | 250000 | Maximum file size to include. |

Text Demo

$ repo2ai .
Wrote /Users/me/project/repo-context.md
Files included: 18
Approx tokens: 24782
Omitted files: 6

Example generated Markdown:

# Repository Context

Generated by repo2ai.

## Metadata

- Root: /Users/me/project
- Files included: 18
- Approx tokens: 24782

## Suggested Prompt

You are analyzing this codebase. Please understand the project structure first, then answer my question.

## Directory Tree

```text
.
|-- src
|   `-- index.ts
`-- package.json
```

Ignore And Safety Behavior

repo2ai applies default ignore rules for common dependency, build, cache, and coverage directories such as .git, node_modules, dist, build, coverage, .next, .nuxt, .turbo, .cache, .venv, __pycache__, .pytest_cache, target, and vendor.

It also reads .gitignore and .repo2aiignore from the scanned root.

Real env files such as .env, .env.local, and .env.production are skipped by default and listed in the omitted files table. Safe templates such as .env.example, .env.template, and .env.sample may be included, but still pass through redaction.

Lock files such as package-lock.json, pnpm-lock.yaml, yarn.lock, and Cargo.lock are not included as full contents by default. Manifest files such as package.json, pyproject.toml, Cargo.toml, and go.mod remain high priority.

Limitations

• Token counts are approximate and use Math.ceil(text.length / 4).
• repo2ai does not call AI APIs, summarize code, or rank files with a model.
• Binary files, real env files, lock file contents, and files above --max-file-size are skipped by default.
• Redaction is best-effort and should not replace reviewing generated context before sharing it.
• The MVP is CLI-only and does not include a backend, hosted service, or GUI.

Development

npm install
npm run typecheck
npm test
npm run build