blamewise

Blame smarter. Ramp up faster.

中文 | English

A CLI tool that helps new team members understand code ownership and change history using local git data. Zero cloud dependencies, fully private.

Install

npm:

npm install -g blamewise

Binary:

Download the binary for your platform from GitHub Releases.

Usage

Who knows this file?

Rank authors by expertise on a file (lines owned + commit frequency + recency):

blamewise who-knows <path>
blamewise who-knows src/index.ts -n 5

Why did this file change?

Show recent commits with reasons for changes:

blamewise why <path>
blamewise why src/index.ts -n 10

Explain this file

Summarize a file's history — when it was created, activity status, key milestones, and contributors:

blamewise explain <path>
blamewise explain src/index.ts

Which files change the most?

Identify files with the highest change frequency (commit count + author diversity):

blamewise churn <path>
blamewise churn src/ --since "6 months ago" -n 10

Who should review this code?

Recommend the best reviewers for a file or set of changed files:

blamewise review <file> [files...]
blamewise review src/auth/middleware.ts
blamewise review $(git diff --name-only main...) -n 5
blamewise review src/cli.ts src/render.ts --inactive-threshold "3 months ago"

Generate an onboarding report

Create a Markdown knowledge map for a project — module owners, high-churn files, stale files, and activity trends:

blamewise onboarding <path>
blamewise onboarding . --output report.md --since "3 months ago"

Generate a setup checklist

Scan a project and generate an onboarding checklist with prerequisites, installation steps, dev commands, and common tasks:

blamewise setup <path>
blamewise setup . --output checklist.md

Detected from:

| Data | Sources | |------|---------| | Language & version | .nvmrc / .node-version / package.json engines (JS), .python-version / pyproject.toml (Python), go.mod (Go), rust-toolchain.toml (Rust), .sdkmanrc / .java-version (Java), .ruby-version (Ruby), .php-version (PHP) | | Package manager | bun.lockb / pnpm-lock.yaml / yarn.lock / package-lock.json (JS), poetry.lock / uv.lock / Pipfile.lock (Python), lock files (Go/Rust/Ruby/PHP) | | Docker | docker-compose.yml / docker-compose.yaml / Dockerfile | | Required env vars | .env.example / .env.sample / .env.template | | Commands (dev, test, lint, format, build) | Makefile / justfile > language scripts (package.json, pyproject.toml) > convention (tool config files) | | Contributing guide | CONTRIBUTING.md |

JSON output

All commands support --json for machine-readable output:

blamewise who-knows src/index.ts --json
blamewise explain src/index.ts --json
blamewise churn src/ --json | jq '.files[] | select(.churnScore > 0.7)'

<path> can be a relative path, an absolute path, or even a path into a different git repository — blamewise automatically detects the repo root.

blamewise who-knows src/index.ts -n 5
blamewise who-knows /other/repo/src/main.ts

Options

| Flag | Default | Description | |------|---------|-------------| | -n, --num | 10 (who-knows/review) / 5 (why) / 20 (churn) | Number of results to show | | --since <date> | — | Start date for churn/onboarding (e.g. "6 months ago", "2025-01-01") | | --until <date> | — | End date for churn | | --inactive-threshold <duration> | 6 months ago | Filter out authors inactive since (review command) | | --output <file> | ONBOARDING.md (onboarding) / SETUP.md (setup) | Output file path | | --stale-threshold <duration> | 6 months ago | Stale file threshold for onboarding | | --json | — | Output as JSON (all commands) |

Development

git clone https://github.com/gtn1024/blamewise.git
cd blamewise
bun install
bun test
bun run src/cli.ts --help

License

MIT