git-sentinel

AI-Powered Git Documentation Sentinel — a local daemon that listens to your git hooks. Every time a commit succeeds in a watched repo, the sentinel analyzes the diff, writes a clean plain-English explanation of what changed, and maintains interactive markdown logs plus week-over-week changesets. Your work documents itself.

B2B developer-productivity angle: teams lose the "why" of their codebase within weeks. git-sentinel captures it at the moment of commit, automatically, with zero workflow change.

How it works

 watched repo                     git-sentinel daemon
┌─────────────┐   event JSON    ┌──────────────────────────────┐
│ post-commit ├────────────────▶│ watcher (chokidar on queue/) │
│    hook     │                 │        │                     │
└─────────────┘                 │        ▼                     │
                                │ analyzer (git diff → typed   │
                                │          Changeset)          │
                                │        │                     │
                                │        ▼                     │
                                │ explainer (demo heuristic    │
                                │   or Claude API adapter)     │
                                │        │                     │
                                │        ▼                     │
                                │ docs (log.md + weekly        │
                                │       changesets)            │
                                └──────────────┬───────────────┘
                                               ▼
                                 sentinel-docs/  +  dashboard UI

1. sentinel init <repo> installs a chained post-commit hook (existing hooks preserved).
2. On every commit, the hook drops an event JSON (repo, sha, branch, timestamp) into the sentinel's queue directory.
3. The sentinel watch daemon picks the event up via filesystem watching, runs git against the source repo, and builds a structured changeset (files, stats, languages, touched symbols).
4. The explainer turns the changeset + diff into a concise explanation. Keyless by default (heuristic demo mode); set ANTHROPIC_API_KEY and it upgrades to Claude.
5. Markdown logs and ISO-week changesets are regenerated; the dashboard serves an interactive timeline.

Commands

Command	What it does
sentinel init <repo>	Install hook + register repo
sentinel watch	Run the daemon
sentinel report [--week 2026-W28]	Generate weekly changeset
sentinel dashboard [--port 4321]	Interactive timeline UI
sentinel status	Watched repos + queue health
sentinel remove <repo>	Uninstall hook + unregister

Build stages

• Stage 1 — Tech stack & scaffold: TypeScript strict, commander CLI skeleton, vitest, project docs
• Stage 2 — Git hook installer & event capture: chained post-commit hook, event queue, chokidar daemon
• Stage 3 — Diff analysis engine: git diff → typed Changeset (files, stats, languages, symbols)
• Stage 4 — AI explanation layer: DemoExplainer (keyless heuristic) + ClaudeExplainer (Anthropic SDK), auto-select
• Stage 5 — Markdown documentation generator: per-commit log.md + weekly changeset rollups
• Stage 6 — Interactive dashboard: local server, commit timeline, week-over-week view
• Stage 7 — Polish & multi-repo hardening: status/remove, config file, merge/rebase edge cases

Run it

npm install
npm run build
node dist/cli/index.js --help

# or during development
npm run dev -- --help

Tests:

npm test

Generated output

sentinel-docs/
└── <repo-name>/
    ├── log.md              # every commit, newest-first, with AI explanation + collapsible file table
    └── weeks/
        ├── 2026-W28.md     # weekly rollup: commit count, net lines, top languages, digest
        └── 2026-W29.md

Environment overrides: SENTINEL_HOME (runtime data dir), SENTINEL_DOCS (markdown output dir), ANTHROPIC_API_KEY (upgrades the explainer to Claude).

Design principles

• Keyless demo mode first. Everything runs offline with no API key; the Claude adapter swaps in via ANTHROPIC_API_KEY.
• Zero workflow change. No new commands to remember after init — commits themselves are the trigger.
• The docs are committable. sentinel-docs/ is plain markdown that lives happily inside the repo it documents.

explainationgithub