Auto-documentor is a TypeScript CLI that scans a codebase and generates a structured NEW_README.md using OpenAI.

• Crawls source files using fast-glob
• Respects .gitignore, plus node_modules and .git
• Builds a project-level analysis prompt from:
  • package.json
  • README.md (if present)
  • discovered entry points
  • key source files
• Calls OpenAI to synthesize:
  • Mission
  • Architecture
  • Features
  • API Reference
• Writes output to NEW_README.md in the target repository

• Node.js 20+
• npm
• OpenAI API key

npm install

npm run build

PowerShell:

$env:OPENAI_API_KEY="your_api_key_here"

macOS/Linux:

export OPENAI_API_KEY="your_api_key_here"

From this project root:

npm run dev -- --path "/absolute/path/to/target-repo"

Or using built output:

node dist/index.js --path "/absolute/path/to/target-repo"

You can also pass API key directly:

node dist/index.js --path "/absolute/path/to/target-repo" --api-key "your_api_key_here"

After building, link it locally:

npm run build
npm link

Then run from anywhere:

auto-documentor --path "/absolute/path/to/target-repo"

• --path <path>: required, path to repository to analyze
• --api-key <key>: optional, overrides OPENAI_API_KEY

• Generates: NEW_README.md
• Location: inside the target repo passed via --path

• npm run dev: run CLI with tsx (no build step needed)
• npm run build: compile TypeScript to dist/
• npm run start: run compiled CLI from dist/index.js
• npm run typecheck: TypeScript checks only

npm run dev -- --path "D:/work/my-service"

Expected console output:

Scanned <N> files.
Root nodes in tree: <M>
Generated README: <target>/NEW_README.md

If you see:

Missing OpenAI API key. Set OPENAI_API_KEY or pass --api-key.

Set OPENAI_API_KEY in your shell or use --api-key.

Run:

npm run build
npm link

Then open a new terminal and retry.

• Add --output <file> to customize the generated file path/name.
• Add --dry-run mode to preview analysis without writing files.
• Improve API reference extraction with lightweight static analysis.
• Add tests for scanner, analyzer prompt-building, and README rendering.
• Add CI checks for typecheck/lint/test on pull requests.

Contributions are welcome.

1. Fork the repo and create a feature branch.
2. Install dependencies: npm install
3. Run checks: npm run typecheck
4. Validate behavior locally: npm run dev -- --path .
5. Open a pull request with a clear summary of changes.

Please keep changes focused and include updates to docs when behavior changes.

• TypeScript
• Commander
• fast-glob
• OpenAI Node SDK