https://github.com/georgiosnikitas/commit-whisper
🕵️ I know what you did last commit
https://github.com/georgiosnikitas/commit-whisper
ai cli code-analysis code-metrics command-line-tool developer-tools git git-history llm metrics nodejs repository-health terminal typescript version-control
Last synced: 12 days ago
JSON representation
🕵️ I know what you did last commit
- Host: GitHub
- URL: https://github.com/georgiosnikitas/commit-whisper
- Owner: georgiosnikitas
- License: mit
- Created: 2026-06-06T11:54:45.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T12:45:00.000Z (27 days ago)
- Last Synced: 2026-06-27T14:20:05.896Z (27 days ago)
- Topics: ai, cli, code-analysis, code-metrics, command-line-tool, developer-tools, git, git-history, llm, metrics, nodejs, repository-health, terminal, typescript, version-control
- Language: TypeScript
- Homepage:
- Size: 2.51 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# commit-whisper
[](https://sonarcloud.io/summary/overall?id=georgiosnikitas_commit-whisper)
[](https://github.com/georgiosnikitas/commit-whisper/actions/workflows/ci.yml)
[](https://github.com/georgiosnikitas/commit-whisper/actions/workflows/release.yml)
[](https://www.npmjs.com/package/commit-whisper)
[](https://www.typescriptlang.org/)
[](LICENSE)
[](https://buymeacoffee.com/georgiosnikitas)
> 🕵️ **I know what you did last commit.**
Deterministic git history analysis with a grounded, bring-your-own-key AI narrative — a
terminal-native CLI.
commit-whisper analyzes a local or remote git repository, computes a catalog of deterministic
metrics (no AI), and — when a provider is configured — adds a grounded AI narrative and
coaching report. It renders to HTML, Markdown, terminal, and JSON from a single canonical
Report JSON.
> Status: v1 — all seven epics delivered. See
> [docs/planning-artifacts/](docs/planning-artifacts/) for the PRD, architecture, epics, and
> UX design.
## Requirements
- Node.js 22 LTS or newer
- npm (bundled with Node.js)
- A system `git` on `PATH` (retrieval shells out to it)
## 🚀 Installation
### 🍺 Homebrew (macOS)
```bash
brew trust georgiosnikitas/commit-whisper
brew tap georgiosnikitas/commit-whisper
brew install commit-whisper
```
> The `brew trust` line is only required when your Homebrew enforces tap trust
> (`HOMEBREW_REQUIRE_TAP_TRUST`, available in Homebrew 6+). On a default setup you can skip
> it and run just the `brew tap` + `brew install` steps.
### 📦 From npm
```bash
npm install -g commit-whisper
```
Or run it once without installing:
```bash
npx commit-whisper .
```
### 📦 From GitHub Packages
```bash
npm install -g @georgiosnikitas/commit-whisper --registry=https://npm.pkg.github.com
```
> **Note:** GitHub Packages requires authentication even for public packages. Add a
> [personal access token](https://github.com/settings/tokens) with `read:packages` scope
> to your `~/.npmrc`:
>
> ```
> //npm.pkg.github.com/:_authToken=YOUR_TOKEN
> ```
### 💾 Prebuilt binaries (no Node.js required)
Self-contained executables for macOS, Linux, and Windows are attached to each
[GitHub Release](https://github.com/georgiosnikitas/commit-whisper/releases).
After installing via Homebrew, npm, GitHub Packages, or a prebuilt binary, run it from
anywhere:
```bash
commit-whisper .
```
### 🛠️ From source
```bash
git clone https://github.com/georgiosnikitas/commit-whisper.git
cd commit-whisper
npm install
npm run build
node dist/index.js .
```
## Getting started (development)
```bash
npm install # install pinned toolchain + runtime deps
npm run build # bundle src/ → dist/ (tsup / esbuild)
npm test # run the test suite (vitest)
```
## npm scripts
| Script | Purpose |
| --- | --- |
| `npm run build` | Bundle `src/` to `dist/` via tsup (ESM, Node 22 target). |
| `npm run bundle:sea` | Bundle `src/sea-entry.ts` to a single self-contained CJS file in `dist-sea/`. |
| `npm run build:sea` | Build a Node SEA single-executable binary (see [the 7.4 spike findings](docs/implementation-artifacts/7-4-sea-packaging-spike-findings.md)). |
| `npm test` | Run the test suite once (`vitest run`). |
| `npm run test:watch` | Run vitest in watch mode. |
| `npm run typecheck` | Type-check with `tsc --noEmit` (strict, nodenext). |
| `npm run lint` | Lint with ESLint (enforces the architecture patterns). |
## Project structure
```
src/
├── index.ts # entrypoint (bootstrap → cli)
├── cli/ # CLI shell, menu, arg parsing, exit-code mapping
├── config/ # two-phase resolver, RunConfig, the only reader of process.env
├── retrieve/ # git clone shell-out, retrieval, temp-workspace lifecycle
├── analyze/ # normalized model + deterministic metric functions (Groups A–F)
├── narrate/ # AI client, reachability preflight, grounding check
├── assemble/ # canonical Report JSON assembly + schema
├── render/ # HTML / Markdown / Terminal / JSON renderers
├── license/ # license validation and tier resolution
└── shared/ # errors, ui (stderr), Secret, ports, types
```
Only `cli/` and `config/` may touch `argv` / `env` / prompts; every stage from `retrieve/`
onward receives a frozen `RunConfig` (the hexagonal boundary). These conventions are
enforced by ESLint.
## License
[MIT](LICENSE) © Georgios Nikitas. The CLI and its source are MIT-licensed; paid
tiers are enforced at runtime via an online license check (BYOK AI keys and git
tokens stay on your machine).