gps — repo memory for coding agents

Teach your coding agent how your repo works once. GPS brings that memory back when the relevant code is touched.

gps is a memory layer for Claude Code, Codex, Cursor, and shell-based coding agents. It stores the things humans usually have to repeat: repo conventions, best practices, user preferences, invariants, decisions, TODOs, test commands, and hard-won lessons from past edits. Then it retrieves the relevant slice before the agent edits.

Product page → useinvariance.com/product/gps — what it is, the command reference, and setup docs.

Pairs with tars. gps gives your agent memory of your code; tars teaches it how to work — it learns the orchestration method from your cleanest sessions (explore before editing, test before done) and feeds it back on the next prompt. Knowledge + method.

Contents

• Quickstart
• Why gps
• The core loop in action
• Commands
• Agent integration
• Capture & promotion policy
• Concepts: notes, invariants, decisions
• How it compares
• Benchmarks
• Experimental: live docs
• Status & limitations
• License

Quickstart

One command from the repo root. Pick the agent you use:

cd your-repo
npx -y @invariance/gps setup --yes --with-claude   # Claude Code
npx -y @invariance/gps setup --yes --with-codex    # Codex CLI
npx -y @invariance/gps setup --yes --with-cursor   # Cursor

Install several integrations at once: npx -y @invariance/gps setup --yes --with-claude --with-codex --with-cursor. Prefer a global install? npm install -g @invariance/gps && gps setup --yes --with-claude.

setup does the full first-run path: writes .gps/config.yml and .gps/invariants.yml, builds .gps/index/symbols.json, lifts TODO(symbol): and FIXME(symbol): comments into notes, and installs the selected agent integration.

Then it’s normal agent usage. This is the core loop to remember:

gps next                                                  # first useful commands after install
gps prepare  --intent "what I am about to change"   # decision-ready brief before edits
gps remember "hard-won fact worth reusing"                  # save a durable lesson
gps save-this "use the shared errors module here" --symbol createRefund   # preview a save command
gps remember "still need to update the fixture" --reminder --symbol createRefund
gps done                                                    # post-edit self-audit: changed symbols, tests, invariants
gps doc --base HEAD                                         # optional shareable review doc for the diff