code-handover

Generate a project handover markdown file from static analysis (structure, configs, dependencies) and optionally enrich it with LLM-written summaries of important codebase features.

Install

npm install -g code-handover

Or run without installing:

npx code-handover generate

Usage

handover generate [path] [options]

| Option | Description | Default | |--------|-------------|---------| | path | Project directory to analyze | . (current directory) | | -o, --output <file> | Output markdown file path | HANDOVER.md | | --llm | Use LLM to add "Important features" and "Conventions and gotchas" | off | | --no-llm | Disable LLM (default) | |

Examples

# Generate HANDOVER.md in current directory
handover generate

# Generate for another project
handover generate ../my-app

# Custom output file
handover generate -o docs/HANDOVER.md

# With optional LLM summaries (requires API key)
handover generate --llm -o HANDOVER.md

Optional LLM enrichment

With --llm, the tool calls an LLM to add two sections:

• Important features – What the codebase does and main modules.
• Conventions and gotchas – Testing style, lint rules, non-obvious pitfalls.

Set one of these environment variables (no secrets are written to the handover file):

• OPENAI_API_KEY – uses OpenAI (e.g. gpt-4o-mini).
• ANTHROPIC_API_KEY – uses Anthropic (e.g. claude-3-5-haiku).

If --llm is set but neither key is set, the tool skips LLM enrichment and prints a warning.

What the handover contains

The generated markdown includes:

1. Project overview – Name, repo URL (from git), one-line description (from README or package.json).
2. Tech stack – Languages, frameworks, key dependencies.
3. Directory structure – High-level tree and folder notes.
4. Entry points and scripts – Main files and npm (or similar) scripts.
5. Environment and config – Env files, config files, referenced env var names (no values).
6. How to run – Install, dev, test, build commands.
7. Important features (optional, with --llm) – Bullet list from the LLM.
8. Conventions and gotchas (optional, with --llm) – Bullet list from the LLM.

License

MIT