git-notes

Decentralized code reviews and annotations stored directly in Git.
No database. No vendor. No history rewrites. Just refs/notes/*.

---

---

Why git-notes?

Code review comments die in GitHub. PRs close. Context vanishes. git-notes keeps every discussion inside the repository — synced via standard Git, readable in your editor, terminal, and browser.

The problem	git-notes solves it by
PR comments disappear after merge	Notes live in refs/notes/* — permanent, versioned
Review context is vendor-locked	Portable across GitHub, GitLab, Gitea, Forgejo
No offline access to discussions	Notes clone with the repo — zero network required
Context switches between IDE and browser	Inline annotations in VS Code, TUI, Chrome, git blame
Team knowledge dies with the PR	Notes sync via git push / git fetch like any ref

---

Install in 10 seconds

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/isaim0011/git-notes/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/isaim0011/git-notes/main/install.ps1 | iex

Homebrew (macOS / Linux):

brew install isaim0011/tap/git-notes

Scoop (Windows):

scoop bucket add git-notes-bucket https://github.com/isaim0011/scoop-bucket
scoop install git-notes

Cargo:

cargo install gn-cli --bin git-notes

→ See all platforms & download binaries

---

Quick Start

# 1. Quickie add: anchor a comment to a line in 0.05s
gn a -f src/auth.rs -l 42 -m "Validate JWT expiry before decoding claims"

# 2. Numbered index list with quick single-digit identifiers
gn l

# 3. Quick reply or approve using note numbers [1], [2], [3]
gn r 1 -m "Fixed in commit 8d31ef2"
gn ok 1

# 4. View and customize CLI quickies & keyboard shortcuts cheat sheet
gn shortcuts
gn shortcuts --set c="add -m"    # Bind custom user abbreviation

# 5. Interactive arrow-key note thread picker
gn s

# 6. Check repo health (hooks, refs, stale notes)
gn doc

# 7. Browse notes in the interactive terminal UI (TUI)
git-notes-tui

# 8. See notes inline in git diff & git blame
gn d
gn b -f src/auth.rs

# 9. Auto-heal & re-anchor notes after a git rebase, amend, or cherry-pick
gn heal
gn heal --dry-run

# 10. Offline LAN P2P sync & portable USB bundles
gn sync --p2p                              # Spin up local LAN P2P server on Wi-Fi
gn sync p2p connect 192.168.1.50:9418     # Pull notes directly from peer
gn sync bundle export team_notes.bundle    # Export portable bundle for USB/AirDrop
gn sync bundle import team_notes.bundle    # Import & merge notes bundle

# 11. Multi-provider review importers (GitLab MR, Bitbucket PR, Jira, GitHub)
gn imp gitlab --mr 12
gn imp bitbucket --pr 42
gn imp jira --issue PROJ-101

# 12. Sync bidirectionally with remote origin
gn push && gn pull

# 13. Get an AI summary of open threads before a release (Gemini)
gn sum --namespace review

# 14. CI quality gating & merge-readiness check
gn check --min-approvals 1 --no-unresolved  # Or alias: gn gate

# 15. Data & refspec integrity validator (fsck / audit)
gn validate                                # Or aliases: gn fsck, gn lint

# 16. Shell completions (auto-install to profile/directory)
gn completions --install

---

Features

🔒 Permanent & Portable Notes live in refs/notes/* — never touch your commit history. Clone the repo, get the discussions. ⚡ Stale-Note Detection git-notes doctor warns when commented code has moved or been deleted since the note was anchored. Nobody else does this. 🤖 AI Thread Summarizer git-notes summarize generates an LLM digest of all open discussion threads — the "what's blocking release?" command. 🔀 Conflict-Free Merge Union + Last-Write-Wins strategy means concurrent note editing never blocks your git pull.

🌐 Every Surface CLI → TUI → VS Code → Chrome Extension → GitHub PR comments — one note, everywhere. 🐙 GitHub Action CI Loop Install isaim0011/git-notes in any repo — auto-posts notes as inline PR review comments. 📋 PR Comment Importer git-notes import-pr --pr 42 pulls your existing GitHub PR discussions into notes in seconds. 💬 Threaded Discussions Reply, approve, reject, resolve — full conversation trees anchored to specific lines. ⚡ Quickies & Adaptive Learning Single-letter abbreviations (gn a, gn l, gn r, gn ok, gn s) and a behavioral learning engine that gets faster and smarter the more you use it. ⌨️ Universal Keyboard Shortcuts Interactive TUI navigation, quick reply bars (r), approve (ok), and full CLI shortcut customization (gn shortcuts --set).

---

GitHub Action — CI Viral Loop

Every repo that installs this action links back to git-notes:

# .github/workflows/git-notes.yml
name: Sync git-notes
on: [pull_request, push]
jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: isaim0011/git-notes@v0.1.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          namespace: comments

What it does: Downloads the CLI, fetches refs/notes/*, and posts open notes as inline PR review comments — automatically. → GitHub Marketplace

---

Architecture

SURFACES                   CORE                     DISTRIBUTION
────────                   ────                     ────────────
CLI  (Rust/clap)  ─┐
TUI  (ratatui)    ─┤   ┌───────────┐           ┌────────────────┐
VS Code (TypeScript)┼──▶│  gn-core  │──────────▶│  Sync Layer    │──▶ git remote
Chrome  (TypeScript)┤   │  (gix)    │           │  union + LWW   │
Web Viewer (Vite)  ─┘   └─────┬─────┘           └───────┬────────┘
                               │                         │
                          refs/notes/*            GitHub Bridge
                          /comments               (Go daemon)
                          /review           notes ↔ PR comments
                          /todos

---

Ecosystem

Package	Registry	Install
gn-cli (CLI binary)	crates.io	cargo install gn-cli --bin git-notes
gn-tui (TUI browser)	crates.io	cargo install gn-tui --bin git-notes-tui
gn-core (Rust library)	crates.io	cargo add gn-core
git-notes-hooks (Python)	PyPI	pip install git-notes-hooks
VS Code Extension	Open VSX	code --install-extension isaim0011.vscode-git-notes
GitHub Action	Action Definition	uses: isaim0011/git-notes@main
Docker (bridge daemon)	GHCR	docker pull ghcr.io/isaim0011/git-notes/github-bridge:latest

---

Monorepo Structure

git-notes/
├── crates/
│   ├── gn-core/        # Core engine — reads/writes git note objects (gix)
│   ├── gn-cli/         # CLI binary — clap v4, all subcommands
│   ├── gn-tui/         # TUI browser — ratatui + syntect syntax highlighting
│   └── gn-sync/        # Sync/merge layer — union + LWW strategies
├── packages/
│   ├── vscode-ext/     # VS Code & Cursor extension (TypeScript/Bun)
│   ├── chrome-ext/     # Chrome MV3 extension (TypeScript)
│   ├── homebrew/       # Homebrew formula
│   └── scoop/          # Windows Scoop manifest
├── services/
│   └── github-bridge/  # HTTP bridge daemon — notes ↔ GitHub PR (Go)
├── python/
│   └── gn_hooks/       # Auto-sync git hooks (pip install)
├── action.yml          # GitHub Marketplace action
├── install.sh          # Universal Linux/macOS installer
└── install.ps1         # Universal Windows installer

---

Contributing

git clone https://github.com/isaim0011/git-notes.git
cd git-notes

# Rust (CLI + TUI + core)
cargo build --workspace
cargo test --workspace

# TypeScript (VS Code + Chrome extensions)
bun install && bun run build

# Go (GitHub bridge daemon)
go work sync && go test ./...

# Python (git hooks)
pip install -e "python/gn_hooks[dev]"

Stack: Rust 1.70+ · Bun 1.x · Go 1.21+ · Python 3.11+
PRs welcome. See CHANGELOG.md, CONTRIBUTING.md, and open issues.

---

License

Dual-licensed under MIT or Apache 2.0 at your option.

_{Built with ❤️ by Bimo — Support on Ko-fi}