scout

Scout

Scout explores your codebase so you don't have to.

Scout is an AI-powered codebase exploration and documentation tool. It reads an unfamiliar repository, works out how the pieces fit together, generates useful Markdown documentation with Mermaid diagrams, and keeps that documentation in sync as the code changes.

Scout. Explore your codebase. Understand how it works.

The problem

Joining an unfamiliar project means hours of the same questions: where does it start, how are modules organised, where are the APIs, what database models exist, how does auth work, which external services are used, what changed recently, and which docs are now stale.

Scout answers those questions from the repository itself, and writes the answers down.

How it works

Scout is deliberately split into a deterministic engine and a thin AI skill layer:

Skill (/scout) ┐
CLI (scout)    ┼──► Scout Core
GitHub Action ─┘        │
                        ├─ scan repo (respect .gitignore, skip node_modules/…)
                        ├─ run analyzers (detectors for stack/APIs/DB/auth/infra)
                        ├─ build a typed Repository Knowledge Model
                        ├─ plan · generate · diagram · impact · drift  ──► docs/
                        └─ compose docs as a Markdown AST (src/prose)   ──► human prose

Documentation is not concatenated as strings. Scout composes each document as a Markdown syntax tree (src/prose) and renders it once, so the output reads like prose a person wrote — sentences with topic sentences, lists only where they earn their place, and tables that line up. The same prose toolkit is available as the Scribe skill for writing documents by hand.

• Deterministic code handles filesystem traversal, ignore rules, git diffing, framework and database detection, source-to-doc mapping, and metadata. These are testable and need no LLM.
• The AI layer (the Claude Code Skill) adds semantic explanation on top of what the engine already found. It always cites evidence and never invents behaviour.

The core never imports Claude Code, so the same engine can back a CLI, a GitHub Action, or future agents such as Codex and Gemini CLI.

Core principles

• Never invent behaviour the repository cannot support.
• Source code is authoritative when it conflicts with existing docs.
• State uncertainty instead of guessing.
• Never leak secrets. Record env var names only, never values.
• Never destroy human writing. Scout only owns its managed sections.

Installation

Requirements: Node 18 or newer and pnpm.

git clone <this-repo> scout && cd scout
pnpm install
pnpm build

Make the CLI global (either option):

# option A: pnpm global link
pnpm link --global        # then ensure pnpm's global bin dir is on PATH

# option B: symlink into a bin dir already on PATH
ln -sf "$PWD/dist/cli.js" /opt/homebrew/bin/scout

Install the Claude Code Skill:

mkdir -p ~/.claude/skills
cp -R skill/scout   ~/.claude/skills/scout
cp -R skill/scribe  ~/.claude/skills/scribe
cp -R skill/narrate ~/.claude/skills/narrate

/scout (explore + document), /scribe (write documents as prose), and /narrate (rewrite Scout's docs as prose guides) are now available in every project, and scout works on the command line. After editing Scout's source, run pnpm build to refresh the global CLI.

Commands

Add --cwd <dir> to target another directory. In Claude Code, run /scout (or just ask it to map or document the project) to drive the same commands.

Writing documents with Scribe

Scribe is the prose engine, exposed through the same scout binary. Give scout render a JSON outline and it renders a document — no repository needed:

scout render outline.json --out doc.md

Add --out <file> to write to a file instead of stdout. The outline is a title plus sections, each holding blocks such as say, narrate, bullets, numbered, table, code, quote, and rule. In Claude Code, run /scribe to draft documents this way, or /narrate to rewrite Scout's docs as prose.

Example

$ scout init

Scout - Repository explored.

Stack:
  typescript
  node
  express
  mongodb

Discovered:
  8 modules
  34 API routes
  12 database models
  3 external integrations

Generated:
  + docs/overview.md
  + docs/api.md
  + docs/database.md
  + docs/authentication.md
  ...

Scout has mapped the repository.

$ scout impact src/payments/payment.service.ts

Scout - Impact Analysis

Changed:
  src/payments/payment.service.ts

Potentially affected:
  docs/integrations.md
      Reason: src/payments/payment.service.ts is a documented source of this file.
  docs/modules/payments.md
      Reason: Part of the payments module.

Generated documentation

Scout only writes the documents a repository actually supports. No empty files.

docs/
├── overview.md          stack + counts + entry points
├── architecture.md      modules and their relationships
├── api.md               routes grouped by module
├── database.md          models and the systems behind them
├── authentication.md    mechanisms + evidence + confidence
├── integrations.md      external services and where they're used
├── deployment.md        infra tooling + env var names
├── testing.md           frameworks + test files
├── modules/<name>.md    per discovered module
└── diagrams/*.md        focused Mermaid diagrams

Every generated file carries frontmatter linking it to its source files, and wraps generated content in managed markers:

---
scout:
  generatedBy: scout
  sources:
    - src/auth/middleware.ts
    - src/auth/token.service.ts
---

<!-- scout:start authentication -->

Generated content, safe to regenerate.
<!-- scout:end authentication -->

Anything you write outside the markers is yours and is preserved on every run.

The sources: list is the source-to-doc map that powers impact and check.

Architecture

Scout's own internals are documented in ARCHITECTURE.md, which explains what every source file does. In short:

• src/core: scanning, ignore rules, git.
• src/model: the typed knowledge model and the merge logic.
• src/analyzers: the detector registry (stack, frameworks, databases, auth, integrations, infrastructure, docs).
• src/prose: the Markdown AST, renderer, and prose composer that docs are built from.
• src/docs: documentation planning and generation (via src/prose), diagrams, metadata, writer.
• src/engine: orchestration and the init/update/impact/check/diagram runners.
• src/cli.ts: the command-line interface.
• skill/scout: the Claude Code Skill for exploring and documenting a repo.
• skill/scribe: the Claude Code Skill for writing documents as a prose AST.
• skill/narrate: the Claude Code Skill that rewrites Scout's docs as prose guides under docs/guide/ (Scout facts → Scribe prose).

Configuration

Configuration is optional. Scout works with zero config on common repositories. To customise, add scout.config.json at the repo root:

{
  "docsDir": "docs",
  "include": ["**/*"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "coverage/**"],
  "diagrams": true
}

Contributing

See CONTRIBUTING.md. The friendliest place to start is a new analyzer. The interface is small and each analyzer is independent.

License

MIT.