Product/gps

GPS · REPO MEMORY FOR CODING AGENTS

Teach your coding agent how your repo works once.

gps is a memory layer for Claude Code, Codex, and Cursor. It stores the conventions, invariants, decisions, preferences, tests, and hard-won lessons humans usually repeat — anchored to the symbols an agent is about to touch — and retrieves the relevant slice before each edit.

View on GitHub →@invariance/gps on npm →
npm · @invariance/gpsopen sourceClaude Code · Codex · Cursor

WHAT IT IS

Durable, symbol-scoped memory — so you teach the repo once.

Coding agents forget your repo every session. gps brings the lessons you teach back exactly when the relevant code is touched.

Symbol-anchored

Notes, decisions, and tests attach to the exact functions and classes an agent touches — and surface only when that code is in play, not as a wall of context.

Works across agents

Claude Code, Codex, and Cursor read the same memory. The installer writes each agent's native files (CLAUDE.md, AGENTS.md, Cursor rules) and MCP tools.

Captures lessons for you

Lifecycle hooks lift durable lessons — “always run this test twice”, “use the errors module here” — from the session transcript, per your capture policy.

Persistent by default

Todos survive the session as symbol-anchored notes. The CLAUDE.md block is auto-managed. Global lessons land there automatically.

THE COMMANDS

CLI-first. One setup, then a short loop.

Coding agents already know how to run shell commands — so gps is a CLI. Set it up once, then run a tight loop around every non-trivial edit.

gps setup --yes --with-claudeFirst-run path: init .gps/, build the symbol graph, lift TODO/FIXME comments into notes, and wire your agent. Swap --with-codex / --with-cursor.
gps prepare --intent "…"The repo-specific brief before an edit — callers, likely tests, relevant invariants, prior decisions, and notes from past edits.
gps remember "…"Save a durable lesson. Add --reminder --symbol <name> to anchor a TODO to a specific symbol.
gps donePre-handoff check: changed symbols, the tests they touch, and the invariants in play.
gps validate --root "$PWD"Verify the install is wired correctly for your agent.
gps install <agent> --capture=… --promote=…Governance flags that persist to .gps/config.yml — control how captured memory is reviewed and promoted.

GET STARTED

One command from your repo root.

Swap --with-claude for --with-codex or --with-cursor — or hand the prompt below to your agent and let it install GPS for you.

Installbash
cd your-repo
npx -y @invariance/gps setup --yes --with-claude
Copy-paste prompt for your agenttext
Install GPS for this repository and verify it is wired for Claude Code.

GPS npm package: https://www.npmjs.com/package/@invariance/gps
GPS GitHub repo: https://github.com/invariance-ai/gps

Run:
  npx -y @invariance/gps setup --yes --with-claude

Then verify:
  gps validate --root "$PWD"
  test -f CLAUDE.md
  test -f .claude/skills/gps/SKILL.md
  test -f .claude/settings.json
  test -f .mcp.json

After setup, briefly explain what changed and show me the first GPS command I should use before a non-trivial edit.

Prefer a global install? npm install -g @invariance/gps && gps setup --yes --with-claude

Full documentation