---

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.

agents-reverse-engineer fixes that. It generates documentation that AI assistants actually read:

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

The result: Your AI assistant understands your codebase from the first message.

---

Who This Is For

Developers using AI coding assistants (Claude Code, 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

$3

`bash
npx agents-reverse-engineer@latest
`

The interactive installer prompts you to:

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

This installs:

- Commands — /are-init, /are-discover, /are-generate, /are-update, etc.
- Session hook — Auto-updates docs when session ends (Claude/Gemini)

$3

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

`bash
/are-init
`

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

$3

In your AI assistant:

`
/are-discover
/are-generate
`

The assistant creates the plan and generates all documentation.

$3

`bash


Install for Claude Code globally

npx agents-reverse-engineer@latest --runtime claude -g

Install for all runtimes locally

npx agents-reverse-engineer@latest --runtime all -l
`

$3

`bash
npx agents-reverse-engineer@latest uninstall
`

Removes:
- Command files (/are-* commands)
- Session hooks (Claude/Gemini)
- ARE permissions from settings.json
- .agents-reverse-engineer folder (local installs only)

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

$3

`bash
npx agents-reverse-engineer@latest --version
`

---

How It Works

$3

`bash
npx agents-reverse-engineer@latest
`

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

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

---

$3

`
/are-init
`

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

---

$3

`
/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.

---

$3

`
/are-generate
`

Your AI assistant executes the plan:

1. File Analysis — Creates .sum file for each source file
2. Directory Docs — Creates AGENTS.md for each directory
3. Root Docs — Creates CLAUDE.md, GEMINI.md, OPENCODE.md

---

$3

`
/are-update
`

Only regenerates documentation for files that changed since last run.

---

Commands

| Command | Description |
| ------------------------------- | -------------------------------- |
| are | Interactive installer (default) |
| are install | Install with prompts |
| are install --runtime -g | Install to runtime globally |
| are install --runtime -l | Install to runtime locally |
| are install -u | Uninstall (remove files/hooks) |
| are init | Create configuration file |
| are discover | List files that will be analyzed |
| are discover --plan | Create GENERATION-PLAN.md |
| are discover --show-excluded | Show excluded files with reasons |
| are generate | Generate all documentation |
| are update | Update changed files only |
| are clean | Remove all generated docs |

Runtimes: claude, opencode, gemini, all

$3

| Command | Description | Supported Runtimes |
| --------------- | ------------------------------ | ------------------------ |
| /are-init | Initialize config and commands | Claude, OpenCode, Gemini |
| /are-discover | Rediscover and regenerate plan | Claude, OpenCode, Gemini |
| /are-generate | Generate all documentation | Claude, OpenCode, Gemini |
| /are-update | Update changed files only | Claude, OpenCode, Gemini |
| /are-clean | Remove all generated docs | Claude, OpenCode, Gemini |

---

Generated Documentation

$3

`yaml
---
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.
`

$3

Directory overview with:

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

$3

- CLAUDE.md — Project entry point for Claude Code (auto-loaded)
- GEMINI.md — Project entry point for Gemini CLI
- OPENCODE.md — Project entry point for OpenCode
- AGENTS.md — Root directory overview (universal format)

---

Configuration

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

`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
verbose: true # Show each file as processed

AI service configuration

ai:
backend: auto # Backend: 'claude', '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: 5 # Parallel AI calls (1-10, lower for WSL/constrained envs)

telemetry:
keepRuns: 50 # Number of run logs to keep
costThresholdUsd: 10.0 # Optional: warn when cost exceeds this (USD)

# Optional: Custom model pricing (override defaults)
pricing:
claude-opus-4:
inputCostPerMTok: 15.0 # USD per 1M input tokens
outputCostPerMTok: 75.0 # USD per 1M output tokens
`

$3

Concurrency (ai.concurrency)
- Default: 5 (changed from 5 to 2 in WSL environments)
- Range: 1-10
- 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 + session hooks)
- Gemini CLI (full support + session hooks)
- OpenCode (AGENTS.md supported)
- Any assistant supporting AGENTS.md` format

---

License

MIT