Notes your coding agent reads before it edits
sgx keeps a team's decisions, rules and gotchas as Markdown notes anchored to the code, and hands an agent the ones for a file when it opens it. Built on tree-sitter and SQLite, it also reads what each agent did from its own transcripts and checks a change against the notes, callers and tests it touches.
For agents
Currently v0.1.0 · Local · Markdown notes in git · hooks, MCP, CLI and a web UI
Write it, read it, check it
Run bunx sgx.sh init --claude once in a repository. These three commands are then what you, and the agent through its hooks and tools, use every day.
Write down what the code doesn't say
A decision, a rule, a gotcha, a concept or a question for a person, anchored to the symbols it is about and committed with the code in
.sgx/notes/.sgx note decision "Don't retry store.set inside login" --on src/auth/login.ts#login --body "A retry once created two sessions for one login. Callers retry the whole login instead."Read it back before changing the file
Notes, owners, callers outside the file and the tests that reach it. An agent gets the notes without asking: the hook adds them when it opens the file.
sgx brief src/auth/login.tsCheck the change against it
What the change reaches, which tests ran after the last edit, and the notes whose code it touched.
sgx uishows the same, with every agent session beside it.sgx review
Notes arrive with the file
The PreToolUse hook adds a file's notes to the agent's context the first time it reads or edits the file in a session. Nothing is pasted into every turn, so a hundred notes cost what the notes for the open files cost.
It is a file in the repository
Front matter for kind, status and anchors, Markdown for the why. It is reviewed in a pull request like the code it governs, and git log is its history.
It knows when its code moved
Each anchor carries the symbol's body hash. When the code under a note changes, the note says so in briefs and reviews, and a moved symbol can be followed with sgx reanchor.
An agent proposes, a person decides
A note an agent writes starts proposed. Questions wait on a person; sgx answer turns one into an accepted decision, and Now lists them under Needs you.
Measured
On two tasks whose answer was only in a note, Claude Code without sgx passed 0 of 12 runs and with the hooks 12 of 12, at the same cost per run.
The notemarkdown---
kind: decision
title: "Don't retry store.set inside login"
status: proposed
anchors:
- src/auth/login.ts#login@1ak66d7n
by: claude df3fe11b 2026-10-19
created: 2026-10-19
---
A retry once created two sessions for one login. Callers retry the whole login instead.What the agent seestextsgx notes for src/auth/login.ts:
- decision: Don't retry store.set inside login (proposed) [.sgx/notes/dont-retry-store-set-inside-login.md]
A retry once created two sessions for one login. Callers retry the whole login instead.Top: a note in .sgx/notes/. Bottom: what the hook added when the agent read the file.
Ask how, where and why
The same answers reach a person and an agent: sgx <command>, the MCP tools ask, brief, graph, review and note, and the web UI. Each answer says where it came from.
sgx ask "how does a note reach an agent"captured outputNotes
decision · Knowledge lives in .sgx/notes as Markdown in git, not in a shared service [proposed] .sgx/notes/knowledge-lives-in-sgx-notes-as-markdown-in-git-not-in-a-shared.md
Context: v1 kept notes in graph.db (deleted by eject, never shared) and the map in one JSON file (ids collide on merge). The earlier redesign proposed a PostgreSQL service with membership and rol…
Code
file brief.ts src/v2/brief.ts:98
98: /** Which notes each session has already been shown, so a note reaches an agent once per session. */
function initV2 src/v2/init.ts:195
233: // opencode 2 calls only a plugin's setup(), and its setup API for tool results is not published;
function createV2Server src/v2/mcp.ts:38How and where
ask searches the notes, the areas of the code, the code, git history, saved reviews and earlier agent sessions. --explain has Claude write a short answer that cites them.
sgx brief src/auth/login.tscaptured outputsrc/auth/login.ts (src/auth)
- decision: Don't retry store.set inside login (proposed) [.sgx/notes/dont-retry-store-set-inside-login.md]
A retry once created two sessions for one login. Callers retry the whole login instead.
owners: Test Author (4)
callers outside the file: 2 in 2 files: main src/cli.ts:3; testLogin tests/login.ts:3
tests that reach it: tests/login.tsBefore changing a file
Notes, owners, callers outside the file and the tests that reach it. Callers come from import-bound edges only, so a name that matches elsewhere doesn't count.
sgx graph src/auth/login.ts#logincaptured outputsymbol login
function in login.ts:17
Defined in
src/auth/login.ts
Called by
main function in cli.ts:3 (src)
testLogin function in login.ts:3 (tests)
Calls
validate function in login.ts:9
formatName function in format.ts:3
Tests that reach it
tests/login.ts
Notes about it
Don't retry store.set inside login
Commits that changed its file
auth tweak 3 d0ac0ba by Test Author (+1 −0, 288d ago)
auth tweak 2 e496837 by Test Author (+1 −0, 289d ago)
auth tweak 1 e99edba by Test Author (+1 −0, 290d ago)
initial import c97ebbd by Test Author (+27 −0, 291d ago)
People who changed its file
Test Author (4 commits)Everything connected to it
Callers, tests, notes, the commits that changed it, the people and agents who made them, reviews and pull requests. --mermaid prints it as a flowchart.
Review against what the team knows
sgx review reads the working tree against the merge-base of the default branch and says what it reaches, which tests ran after the last edit, and which notes it touches.
sgx reviewcaptured outputchange against HEAD on main: 1 file, 1 symbol, 1 area
Needs attention
- 1 test file that reaches this change was not run after the last edit
Areas
- src/auth: 1 file, 1 symbol
Reach
- login (src/auth/login.ts:17): 2 callers in 2 files, areas src, tests
Checks
- not run: tests/login.ts
Notes this change touches
- decision: Don't retry store.set inside login [proposed] (anchor changed: confirm it still holds) on login (src/auth/login.ts)- 1Reach is callers you can trust. Only import-bound and same-scope edges count, so the list is short and every line is real.
- 2A test ran when its output says it passed. sgx reads the agent's own transcript: the run has to come after the last edit, and a run piped into
tailis judged by its summary, not the pipe's exit code. - 3A note whose code changed asks to be confirmed. The decision anchored to
loginis flagged becauseloginchanged under it. - 4It travels.
--prprints Markdown for a pull request;--savewrites the packet to.sgx/reviews/with a verdict, and the graph shows it on every file it covered.
What each agent did
sgx reads the session files Claude Code and Codex already write (~/.claude/projects, ~/.codex/sessions): what was asked, the files edited, the commands run and whether a test passed after the last edit. Nothing has to be logged for it.
Hand work to the next agent
sgx handoff <session> writes a session as Markdown another agent or person can start from: what was asked, what changed, the checks, the notes on those files and where it ended.
The week, in one page
sgx digest --days 7: sessions per agent, commits and how many an agent co-authored, the busiest areas, notes added, open questions and notes whose code changed.
Where notes are missing
sgx gaps lists the busy areas with no decision, rule or gotcha. sgx distill <session> drafts up to three proposed notes from a finished session.
Teammates' agents
sgx relay serve and relay join share session summaries between clones, no code, so an agent opening a file a teammate's agent is editing is told whose and on which branch.
sgx handoff 01a15179captured output...
## What changed
7 files in `docs`:
- `docs/redesign/2026-10-18-guided-understanding.md` (2 edits)
- `docs/redesign/2026-10-18-validation.md` (2 edits)
- `docs/redesign/prototype.html` (1 edit)
- `docs/redesign/2026-10-18-spatial-workspace.md` (1 edit)
- `docs/redesign/README.md` (2 edits)
- `docs/redesign/2026-10-18-redesign-proposal.md` (1 edit)
- `docs/redesign/2026-10-18-project-audit.md` (1 edit)
## Checks
- passed: `bun run typecheck > /tmp/sgx-redesign-typecheck.log 2>&1`
- passed: `bun test > /tmp/sgx-redesign-tests.log 2>&1`
- Only docs and config edited.A Codex session in this repository, as a handoff.
What holds, and what does not
The index, the notes, the sessions and the UI are on your machine. Four things reach further, each only when you run it: ask --explain and distill call the claude CLI, github sync reads GitHub, and the relay you join gets session summaries.
Holds7
- Notes are files in git
- The UI binds 127.0.0.1 only
- Hooks never deny or rewrite a tool call
initwrites only inside the repositoryejectremoves exactly whatinitadded- The relay never receives code
- Tests reach no model and no network
A judgement4
- Edges are syntactic, with a confidence each
- Commit-to-symbol links use today's line numbers
- A session's commits are matched by time and files
askis lexical
Not yet4
- A hook for opencode 2
- Edits made through shell commands
- Accounts on the relay
- Type-accurate resolution
Before you wire anything
Does anything leave my machine?
Only when you ask: ask --explain and distill send what sgx found to the claude CLI, sgx github sync reads GitHub, and a relay you joined receives session summaries without code.
What does it write into my repository?
.sgx/ with the index (ignored), .sgx/notes/ and .sgx/reviews/ (committed), and with init the entries in .claude/settings.json, .mcp.json, .codex/config.toml or opencode.json and AGENTS.md. eject removes those entries.
Why not put everything in CLAUDE.md?
That works, and every note then rides on every turn. With twenty notes it cost about 1.9 times as much per run in our benchmark, and the gap grows with the notes. A hook pays only for the notes of the files opened.
Which agents does it work with?
Claude Code (hooks and MCP), Codex (hooks and MCP, once the project is trusted) and opencode (MCP and a notes index in AGENTS.md). Sessions are read from Claude Code and Codex.
What happens when I rename something?
The note's anchor stops resolving and the note says its code is gone. sgx reanchor moves it to the one symbol with the same body or name, and reports anything ambiguous instead of guessing.
Install and start
Run bunx sgx.sh init --claude in a repository; there is nothing to install first. It needs Bun 1.4+ and git.
Pick your agent
sgx init takes --claude, --codex or --opencode, alone or together. Existing hooks, servers and instructions are kept.
Take it back out
sgx eject removes the hooks, MCP entries and the AGENTS.md block, and nothing else. Notes stay; they are yours.
Install and startshbunx sgx.sh init --claude # hooks and the MCP server for Claude Code, in this repository
bunx sgx.sh init --codex # the same for Codex (.codex/config.toml)
bunx sgx.sh init --opencode # opencode: the MCP server and a notes index in AGENTS.md
bunx sgx.sh ui # the web UI on 127.0.0.1:4827, or the next free portsgx brief src/auth/login.tscaptured outputsrc/auth/login.ts (src/auth)
- decision: Don't retry store.set inside login (proposed) [.sgx/notes/dont-retry-store-set-inside-login.md]
A retry once created two sessions for one login. Callers retry the whole login instead.
owners: Test Author (4)
callers outside the file: 2 in 2 files: main src/cli.ts:3; testLogin tests/login.ts:3
tests that reach it: tests/login.ts