Scan any codebase. Reveal its architecture, health score, technology stack, and actionable improvement suggestions — in one command.

TypeScript · JavaScript · Python · Go · Rust · Java · C# · C++ — 80+ languages, frameworks, and tools detected automatically.

npm i -g @p4inz-code/repo-map
repo-map .

Zero configuration. One command. Full insight.

npm i -g @p4inz-code/repo-map
cd your-project
repo-map .

Or run without installing:

npx @p4inz-code/repo-map .

Requirements: Node.js 18+. Zero native dependencies (only commander + ignore).

The default output answers: What kind of project is this?

╭─ repo-map · my-project ───────────────────────────────────────╮
│                                                                │
│  Classification    CLI Tool                              87%   │
│  Maturity          Active Development                          │
│  Health            ██████████████████░░░░░░░░  65/100           │
│                                                                │
│  Files  42    Dirs  12    Size  15.3 KB    Depth  4             │
│                                                                │
│  TypeScript  30 files (71%)                                     │
│  JavaScript   8 files (19%)                                     │
│  JSON         4 files (10%)                                     │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

Four elements, one scan: Classification (what is it?), Health (0–100 score), Metrics (size), Languages (what it's built with).

Run repo-map --help for full documentation.

• Dashboard redesign — Classification-first layout with health bar and 20-character label alignment
• Suggestions screen — --suggest command with prioritized recommendations (high/medium/low)
• Health scoring — 8-dimension assessment (documentation, testing, consistency, tooling) with composite 0–100 score
• Project intelligence — Automatic classification, maturity estimation, and technology detection
• Architecture analysis — Dependency graphs, coupling, cohesion, circular dependencies, layer violations, complexity scoring, and risk reports
• Narrow terminal support — Graceful degradation below 60 columns (text-only layout)
• Color tokens — 4 semantic colors across 16-color, 256-color, and TrueColor modes
• Theme presets — Default, monochrome, high-contrast, and minimal
• 783+ automated tests — Coverage across all screens, animations, themes, and edge cases

╭─ repo-map · my-project · stats ──────────────────────────────╮
│                                                               │
│  Files  42    Dirs  12    Size  15.3 KB    Depth  4            │
│  Avg files/dir  3.5                                            │
│                                                               │
│  Languages                                                    │
│  TypeScript    30 files  (71.4%)                               │
│  JavaScript     8 files  (19.0%)                               │
│  JSON           4 files  ( 9.5%)                               │
│                                                               │
│  Largest file  src/app.ts (2.5 KB)                             │
│  Largest dir   src/components (15 files)                       │
│                                                               │
│  Completed in 1.2s                                            │
│                                                               │
╰───────────────────────────────────────────────────────────────╯

╭─ repo-map · my-project · suggestions ────────────────────────╮
│                                                               │
│  Strengths                                                    │
│  ✓ Clean project structure with clear separation              │
│  ✓ Comprehensive test coverage                                │
│  ✓ Consistent coding style                                    │
│                                                               │
│  Suggestions                                                  │
│  ✗ Add CI/CD pipeline for automated testing                   │
│  ! Upgrade outdated dependencies (3 high-severity)            │
│  · Consider adding API documentation                          │
│                                                               │
╰───────────────────────────────────────────────────────────────╯

{
  "schemaVersion": "1.0.0",
  "cliVersion": "2.2.0",
  "projectName": "my-project",
  "stats": {
    "totalFiles": 42,
    "totalDirectories": 12,
    "totalSize": 15360,
    "maxDepth": 4
  },
  "technologies": [
    { "name": "TypeScript", "category": "language", "count": 30, "evidence": "Found 30 files (.ts, .tsx)" }
  ],
  "intelligence": {
    "classification": { "category": "CLI Tool", "confidence": 87 },
    "maturity": { "level": "Active Development", "confidence": 72 },
    "health": { "overall": 65, "maxOverall": 100 }
  }
}

When run against a codebase with source files, repo-map performs deep architecture analysis:

See docs/architecture.md for full details.

TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Rust, Go, PHP, Ruby, Swift, Dart, HTML, CSS, SCSS, Less, SQL, Shell, PowerShell, YAML, TOML, JSON, Markdown, Vue, Svelte, Astro, Docker, Make, CMake, Elixir, Erlang, Haskell, Clojure, F#, Scala, R, Lua, Zig, Nim, Perl, Terraform, GraphQL, Prisma, Protocol Buffers, LaTeX, Solidity, INI, Batch, Environment Variables

React, Next.js, Vue.js, Nuxt.js, Angular, Svelte, SvelteKit, Astro, Remix, Gatsby, Express, NestJS, Fastify, Hono, Koa, Socket.IO, Electron, Flask, Django, FastAPI, SQLAlchemy, Tornado, aiohttp, Rails, Sinatra, Laravel, Symfony, Spring Boot, Spring, Gin, Fiber, Axum, Actix, Rocket, Tailwind CSS, Bootstrap

GitHub Actions, GitLab CI, Jenkins, Docker, Docker Compose, Vite, Webpack, Rollup, Parcel, npm, Yarn, pnpm, Turbo, Nx, ESLint, Prettier, Vitest, Jest, Cypress, Playwright, Storybook

Benchmarks on Apple M1 with Node.js 20. Results vary with hardware and filesystem.

Why repo-map is fast:

• Single filesystem walk — Metadata cached, never re-read
• Binary detection — Extension + null-byte heuristic, no full file reads
• Large file skip — Files over 50 MB excluded automatically
• Shared cache — File content cache shared across all analysis passes

CLI Args → Scan (1 walk) → Analyze (cached passes) → Format → Output

1. Scan — Walk the directory tree once, applying .gitignore, exclude, and include filters. Binary files, symlinks, and files over 50 MB handled gracefully.
2. Analyze — Run all analysis passes against cached metadata: technology detection, classification, maturity estimation, health scoring, architecture analysis. No file read twice.
3. Format — Output as Markdown audit report, stable JSON, or compact statistics.

repo-map --json --no-color

Produces deterministic, machine-readable output. The JSON schema is versioned (1.0.0) and stable — fields may be added in minor versions but never removed or renamed without a major bump.

repo-map disables animations and color when stdout is not a terminal. Same input always produces identical output.

Defaults to respecting .gitignore. Use --no-ignore to include all files. Binary files are excluded via extension and content-based heuristics.

repo-map handles these conditions without crashing:

• Permission denied — skipped with warning
• Broken symlinks — detected and skipped
• Invalid encoding — non-UTF-8 detected via null-byte check
• Large files (> 50 MB) — skipped to prevent OOM
• Malformed JSON in config files — parsed with graceful fallback
• SIGINT — graceful interruption (press Ctrl+C twice to force exit)

• Individual developers — Understand a new codebase in seconds
• Open-source contributors — Find where to start before opening a PR
• Engineering teams — Run architecture audits and track health over time
• AI-assisted development — Feed structured JSON to LLMs and coding agents
• Technical writers — Generate documentation scaffolding from real project structure

git clone https://github.com/p4inz-code/repo-map.git
cd repo-map
npm install
npm test

Standards:

• 783+ automated tests — all must pass before merge
• Strict TypeScript — no any, full type safety
• ESM-first — native ES modules with .js extensions
• Product Identity spec — docs/design/PRODUCT_IDENTITY_V2.2.md governs all UI changes

Run npx tsx scripts/analyze-self.ts to scan repo-map with itself.

Does it work with monorepos? Yes. Run at the monorepo root or target a specific package.

Does it modify my code? Never. Strictly read-only. No files are created, deleted, or modified.

What about private repos? Scans your local filesystem only. No network requests. Nothing leaves your machine.

Is the JSON output stable? Yes. Versioned schema (1.0.0). Fields may be added but never removed without a major version.

How does this compare to tree or cloc? tree shows structure. cloc counts lines. repo-map shows structure, tech stack, health scores, architecture analysis, and improvement suggestions — all in one command.

MIT — see LICENSE.

• Commander.js — CLI framework
• ignore — .gitignore support