Every time I onboarded someone onto a codebase, I'd watch them hit the same wall. They'd stare at git log, scroll through Slack threads trying to figure out why a decision was made, and ask "which files are related to the auth feature?" β questions that Git simply doesn't answer.
Git is brilliant at tracking what changed. But it doesn't know why. It doesn't know that these 12 files belong to the OAuth feature, or that the team decided to use JWT over sessions back in March, or that the new developer should read the auth module before touching the API layer.
So I built GOT.
What is GOT?
GOT sits on top of Git as a thin layer. It doesn't replace Git. It doesn't fork Git. It doesn't even modify Git internals. All it does is add capabilities that Git leaves on the table:
- Workspaces β group related files, branches, decisions, and PRs into logical contexts
- Decisions β structured architecture decision records (ADRs) linked to commits and code
- Notes β quick context that stays attached to the work, not buried in Slack
- Onboarding β guided sessions so new devs don't have to "just read the code"
- GitHub integration β manage PRs and issues without leaving the terminal
- Snapshots β automatic recovery points before destructive operations
-
Safe commands β
got safe reset,got safe push,got safe rebasewith a safety net
Everything lives in a .got/ directory. Add it to .gitignore and your repo stays clean. Your teammates can keep using plain Git and nothing breaks.
The philosophy
Five principles guided every design decision:
- Git is the source of truth. GOT never modifies Git in ways you didn't ask for.
-
Metadata is isolated. Everything in
.got/. Remove it and Git doesn't notice. - Offline-first. No network calls except the ones you initiate.
- Plugin-first. Core features use the same event bus and plugin API available to extensions.
- Recoverable. Destructive operations create automatic snapshots first.
What it actually looks like
# Initialize in any Git repo
cd your-project
got init
# Create a workspace to track a feature
got workspace create oauth --description "OAuth 2.0 implementation"
got workspace add-file oauth src/auth/oauth.go
got workspace add-branch oauth feat/oauth2
# Record an architectural decision
got decision create "Use JWT tokens for auth" --status accepted
got decision link <id> --auto # links to your current commit
# See everything about a feature in one place
got workspace show oauth
# Safe operations β automatic snapshot before destructive git ops
got safe reset --mode hard HEAD~3
got safe push origin main
The got workspace show command is probably my favorite. It pulls together files, branches, decisions, PRs, and recent commits β all in one view. No more context-switching between git log, gh pr list, and scattered notes.
The technical bits
GOT is written in Go. A few things I'm proud of:
-
Pure Go SQLite via
modernc.org/sqliteβ no CGo, so cross-compilation just works. Binary runs on macOS, Linux, and Windows. -
Interface-based Git adapter β all Git operations go through a
GitAdapterinterface that shells out togitviaos/exec. Mockable in tests, swappable to libgit2 later. - Event-driven architecture β an in-memory pub/sub bus connects all modules. When a commit happens, the workspace engine, plugins, and integration layer all react automatically.
- Plugin system β external binaries that communicate via JSON over stdin/stdout. A failing plugin never crashes GOT. 21 event types they can subscribe to.
- 130+ tests with the race detector, running on every push via GitHub Actions.
Building it was the hard part (and the fun part)
This project started as a spec β a 24-section design document that mapped out every feature, every data model, every CLI flag before a single line of code was written. Some people think that's overkill for a side project. But having that spec meant I never had to stop and wonder "how should this work?" The answer was already written down.
The hardest part wasn't the code. It was deciding what not to build. The spec had ideas for TUI dashboards, AI-powered commit suggestions, full-text search across decisions, and GitLab/Bitbucket integrations. All of those are future work. v1.0 ships what's solid and tested.
The most satisfying part? The test suite. There's something deeply comforting about running go test -race ./... on 130+ tests and seeing them all pass. Especially when you're building tooling that people will trust with their Git repositories.
What's next
The roadmap for v1.1 includes an interactive TUI dashboard built with Bubbletea and a full E2E test suite using testscript. Beyond that, I'm thinking about full-text search across decisions (SQLite FTS5), workspace templates, and maybe an AI layer for drafting decision records.
But honestly? I'm just excited to see if this is useful to other people. That's the real test.
Try it
go install github.com/supunhg/got/cmd/got@latest
Or clone and build from source:
git clone https://github.com/supunhg/got.git
cd got
make build
Then in any Git repo:
got init
got status
got workspace create my-feature
The repo is at github.com/supunhg/got. Issues, PRs, and stars are all welcome. If you build a plugin, I'd love to hear about it.
GOT is MIT licensed. It works offline. It doesn't phone home. And it won't touch your Git repo unless you ask it to.
