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.

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.

  1. 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."

  2. 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.ts

  3. Check the change against it

    What the change reaches, which tests ran after the last edit, and the notes whose code it touched. sgx ui shows 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 seestext
sgx 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 output
Notes
  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:38

How 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 output
src/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

Before 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 output
symbol 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 output
change 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)
  1. 1
    Reach is callers you can trust. Only import-bound and same-scope edges count, so the list is short and every line is real.
  2. 2
    A 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 tail is judged by its summary, not the pipe's exit code.
  3. 3
    A note whose code changed asks to be confirmed. The decision anchored to login is flagged because login changed under it.
  4. 4
    It travels. --pr prints Markdown for a pull request; --save writes 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
  • init writes only inside the repository
  • eject removes exactly what init added
  • 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
  • ask is lexical

Not yet4

  • A hook for opencode 2
  • Edits made through shell commands
  • Accounts on the relay
  • Type-accurate resolution

Read the limitations

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 startsh
bunx 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 port
sgx brief src/auth/login.tscaptured output
src/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