AGENTS REVERSE ENGINEER (ARE)

Reverse engineer your codebase into AI-friendly documentation.

Generate .sum files and AGENTS.md for Claude Code, OpenCode, and any AI assistant that supports AGENTS.md.

npx agents-reverse-engineer@latest

"Finally, my AI assistant actually understands my codebase structure."

Why This Exists · How It Works · Commands · Generated Docs

Works with

---

Why This Exists

AI coding assistants are powerful, but they don't know your codebase. Every session starts fresh. You explain the same architecture, the same patterns, the same file locations — over and over.

Some assistants offer built-in initialization (e.g. Claude Code's /init), but these features are shallow — they produce a thin top-level summary that falls short on large brownfield projects with deep module hierarchies. Worse, there is no associated update mechanism: as the codebase evolves, the generated context silently drifts out of date.

agents-reverse-engineer fixes that. It generates rich, multi-level documentation that AI assistants actually read — and keeps it in sync:

• .sum files — Per-file summaries with purpose, exports, dependencies
• AGENTS.md — Per-directory overviews with file organization (standard format)
• CLAUDE.md / GEMINI.md / OPENCODE.md — Runtime-specific project entry points
• Incremental updates — Git-aware change detection regenerates only what changed

The result: Your AI assistant understands your codebase from the first message — and stays accurate as it grows.

---

Who This Is For

Developers using AI coding assistants (Claude Code, Codex, OpenCode, Gemini CLI, or any tool supporting AGENTS.md) who want their assistant to actually understand their project structure — without manually writing documentation or repeating context every session.

---

Getting Started

1. Install Commands

npx agents-reverse-engineer@latest

The interactive installer prompts you to:

1. Select runtime — Claude Code, Codex, OpenCode, Gemini CLI, or all
2. Select location — Global (~/.claude/, ~/.agents/, etc.) or local (./.claude/, ./.agents/, etc.)

This installs:

• Commands — /are-init, /are-discover, /are-generate, /are-update, /are-specify, /are-plan, /are-implement, /are-clean, /are-dashboard
• Codex context rules — local install writes ./AGENTS.override.md; global install writes ~/.codex/AGENTS.override.md with lazy AGENTS hierarchy loading guidance

2. Initialize Configuration

After installation, create the configuration file in your AI assistant:

/are-init

This creates .agents-reverse-engineer/config.yaml with default settings.

3. Generate Documentation

In your AI assistant:

/are-discover
/are-generate

The assistant creates the plan and generates all documentation.

Non-Interactive Installation

# Install for Claude Code globally
npx agents-reverse-engineer@latest --runtime claude -g

# Install for Codex globally
npx agents-reverse-engineer@latest --runtime codex -g

# Install for all runtimes locally
npx agents-reverse-engineer@latest --runtime all -l

Uninstall

npx agents-reverse-engineer@latest uninstall

Removes:

• Command files (/are-* commands)
• ARE permissions from settings.json
• .agents-reverse-engineer folder (local installs only)

Use --runtime and -g/-l flags for specific targets.

Checking Version

npx agents-reverse-engineer@latest --version

---

How It Works

1. Install Commands

npx agents-reverse-engineer@latest

Interactive installer installs commands and hooks for your chosen runtime(s).

Runtimes: Claude Code, Codex, OpenCode, Gemini CLI (or all at once)

---

2. Initialize Configuration

/are-init

Creates .agents-reverse-engineer/config.yaml with exclusion patterns and options.

---

3. Discover & Plan

/are-discover

Scans your codebase (respecting .gitignore), detects file types, and creates GENERATION-PLAN.md with all files to analyze.

Uses post-order traversal — deepest directories first, so child documentation exists before parent directories are documented.

---

4. Generate (in your AI assistant)

/are-generate

Your AI assistant executes the plan:

1. File Analysis — Creates .sum file for each source file
2. Directory Docs — Creates AGENTS.md and CLAUDE.md pointer for each directory

---

5. Update Incrementally

/are-update

Only regenerates documentation for files that changed since last run.

---

6. Generate Specification (Experimental)

/are-specify

Synthesizes all AGENTS.md documentation into a single project specification document (specs/SPEC.md). Use --multi-file to split into separate files, or --dry-run to preview without calling the AI.

---

7. Plan Comparison (A/B Test) (Experimental)

are plan "Add user authentication with JWT"

Runs AI planning twice on the same task — once with ARE documentation and once without — then compares output quality (detail, file references, actionable steps). Use --eval for blind AI quality scoring.

---

8. Implement Comparison (A/B Test) (Experimental)

are implement "Add user authentication with JWT"

Requires a prior are plan run. Executes the AI plans in isolated git worktrees, extracts implementation metrics (files created, lines changed, commits), and optionally runs test/build/lint. Use --eval for blind AI quality evaluation.

are implement "Add auth" --run-tests --run-build --eval
are implement --list                    # List saved comparisons
are implement --show 2026-02-16         # View a comparison

---

Commands

Command	Description
are	Interactive installer (default)
are install	Install with prompts
are install --runtime <rt> -g	Install to runtime globally
are install --runtime <rt> -l	Install to runtime locally
are uninstall	Uninstall (remove files/hooks)
are init	Create configuration file
are discover	Scan files and create GENERATION-PLAN.md
are generate	Generate all documentation
are update	Update changed files only
are specify	Generate project specification (experimental)
are rebuild	Reconstruct project from specs (experimental)
are plan "<task>"	Compare AI planning with vs without docs (experimental)
are implement "<task>"	Compare AI implementation with vs without docs (experimental)
are clean	Remove all generated docs
are dashboard	Show telemetry dashboard (costs, tokens, traces) (experimental)

Runtimes: claude, codex, opencode, gemini, all

General CLI Options

Flag	Description	Applies to
--model <name>	AI model to use (e.g., sonnet, opus, haiku)	generate, update, specify, rebuild
--backend <name>	AI backend (claude, codex, gemini, opencode, auto)	generate, update, specify, rebuild
--concurrency <n>	Number of concurrent AI calls (default: auto)	generate, update, rebuild
--dry-run	Show plan without writing files	generate, update, specify, rebuild, clean
--force	Overwrite existing files	init, install, generate, specify, rebuild
--fail-fast	Stop on first file analysis failure	generate, update, rebuild
--show-excluded	Show excluded files during discovery	discover
--uncommitted	Include uncommitted changes	update
--eval	Run AI quality evaluator on both results	plan, implement
--eval-model <m>	Model for AI evaluator (defaults to --model)	plan, implement
--task-slug <slug>	Override auto-generated task slug	plan, implement
--plan-id <id>	Reference existing plan by ID	implement
--list	List saved comparisons	plan, implement
--show <id>	Show a previous comparison by ID	plan, implement
--run-tests	Run test suite and extract metrics	implement
--run-build	Run build and check success	implement
--run-lint	Run linter and extract metrics	implement
--debug	Show AI prompts and backend details	discover, generate, update, specify, rebuild, plan, implement
--trace	Enable concurrency tracing (.agents-reverse-engineer/traces/)	generate, update, specify, rebuild
--run <id>	Show per-entry detail for a specific run	dashboard
--trends	Show cost & usage trends across runs	dashboard
--format <fmt>	Output format: table (default), json, html	dashboard

AI Assistant Commands

Command	Description	Supported Runtimes
/are-init	Initialize config and commands	Claude, Codex, OpenCode, Gemini
/are-discover	Rediscover and regenerate plan	Claude, Codex, OpenCode, Gemini
/are-generate	Generate all documentation	Claude, Codex, OpenCode, Gemini
/are-update	Update changed files only	Claude, Codex, OpenCode, Gemini
/are-specify	Generate project specification (experimental)	Claude, Codex, OpenCode, Gemini
/are-rebuild	Reconstruct project from specs (experimental)	Claude, Codex, OpenCode, Gemini
/are-plan	Compare planning with vs without docs (experimental)	Claude, Codex, OpenCode, Gemini
/are-implement	Compare implementation with vs without docs (experimental)	Claude, Codex, OpenCode, Gemini
/are-clean	Remove all generated docs	Claude, Codex, OpenCode, Gemini
/are-dashboard	Show telemetry dashboard (experimental)	Claude, Codex, OpenCode, Gemini

---

Telemetry Dashboard (Experimental)

ARE logs telemetry for every run (costs, tokens, latency, traces). Use the dashboard to analyze costs and performance.

are dashboard                           # Summary table of all runs
are dashboard --run 2026-02-14          # Per-entry drill-down for a run
are dashboard --trace 2026-02-14        # ASCII Gantt timeline of execution
are dashboard --trends                  # Cost trends over time
are dashboard --format html > report.html  # Self-contained HTML report with charts

In your AI assistant: /are-dashboard, /are-dashboard --trends, etc.

Tip: For total session costs (not just ARE), use ccusage:

• Claude Code: npx ccusage@latest
• Codex: npx @ccusage/codex@latest
• OpenCode: npx @ccusage/opencode@latest

---

Generated Documentation

.sum Files (Per File)

---
file_type: service
generated_at: 2026-01-30T12:00:00Z
---

## Purpose
Handles user authentication via JWT tokens.

## Public Interface
- `authenticate(token: string): User`
- `generateToken(user: User): string`

## Dependencies
- jsonwebtoken: Token signing/verification
- ./user-repository: User data access

## Implementation Notes
Tokens expire after 24 hours. Refresh handled by client.

AGENTS.md (Per Directory)

Directory overview with:

• Description of the directory's role
• Files grouped by purpose (Types, Services, Utils, etc.)
• Subdirectories with brief descriptions

Pointer Files

• CLAUDE.md — Imports AGENTS.md for Claude Code (auto-loaded per directory)

Root Overview

• AGENTS.md — Root directory overview (universal format)

---

Configuration

Edit .agents-reverse-engineer/config.yaml:

# File and directory exclusions
exclude:
  patterns: [] # Custom glob patterns (e.g., ["*.log", "temp/**"])
  vendorDirs: # Directories to skip
    - node_modules
    - dist
    - .git
  binaryExtensions: # File types to skip
    - .png
    - .jpg
    - .pdf

# Discovery options
options:
  followSymlinks: false # Follow symbolic links during traversal
  maxFileSize: 1048576 # Max file size in bytes (1MB default)

# Output formatting
output:
  colors: true # Use colors in terminal output

# AI service configuration
ai:
  backend: auto # Backend: 'claude', 'codex', 'gemini', 'opencode', 'auto'
  model: sonnet # Model identifier (backend-specific)
  timeoutMs: 300000 # Subprocess timeout in ms (5 minutes)
  maxRetries: 3 # Max retries for transient errors
  concurrency: 10 # Parallel AI calls (1-20, auto-detected from CPU/RAM)

  telemetry:
    keepRuns: 50 # Number of run logs to keep

Key Config Options

Concurrency (ai.concurrency)

• Default: Auto-detected from CPU cores and available memory
• Range: 1-20
• Lower values recommended for resource-constrained environments
• Higher values speed up generation but use more memory

Timeout (ai.timeoutMs)

• Default: 300000 (5 minutes)
• AI subprocess timeout for each file analysis
• Increase for very large files or slow connections

---

Requirements

• Node.js 18+
• AI Coding Assistant — One of:
  • Claude Code (full support)
  • Gemini CLI (full support)
  • OpenCode (AGENTS.md supported)
  • Any assistant supporting AGENTS.md format

---

Contributing

Contributions are welcome! Whether it's bug reports, feature requests, or pull requests — all input is valued.

See CONTRIBUTING.md for development setup and guidelines.

---

License

MIT