The documentation, unabridged
The landing page argues a case. This is the README itself: every command and every captured run, in the order the repository keeps them.
Install and start
Requires Bun 1.4+ and git.
shbunx 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 portinit adds only what is missing, so a second run changes nothing; --dry-run prints what it would
change. It also takes out hooks an older sgx left behind, which would run commands that no longer
exist. sgx eject removes everything init added and nothing else. Codex reads a project's
.codex/config.toml only once the project is trusted; init --codex says so.
Every command indexes the repository first if it has to (incrementally: unchanged files are a stat).
sgx help lists them all.
Write down what the code doesn't say
A note is a decision, a rule that must stay true, a gotcha, a concept, or a question for a person,
anchored to the symbols or files it is about. Each one is a file in .sgx/notes/, committed with the
code. In a copy of the test fixture:
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."captured outputwrote .sgx/notes/dont-retry-store-set-inside-login.md (decision, proposed)markdown---
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.The anchor carries the first eight characters of the symbol's body hash, so sgx knows when the code
under a note has changed since it was written. A note an agent writes starts proposed; sgx accept,
sgx retire and sgx answer <slug> "<choice>" (which turns a question into a decision) are for a
person, and so are the same buttons on the Notes screen.
What an agent sees
init --claude wires three hooks. When the agent opens a file, PreToolUse adds that file's notes to
its context, once per session:
textsgx 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.SessionStart says how many notes the repository keeps and whether a question waits on a person;
UserPromptSubmit adds the notes for files the prompt names. Hooks never deny or rewrite a tool call.
Agents that call tools get the same answers from sgx mcp: ask, graph, brief, review and
note.
On two tasks whose right answer was only in a note (Claude Code, sonnet, a copy of the test
fixture), the hooks made the difference at the same cost per run:
| Task | What the note says | Without sgx | With the hooks | Cost per run, with |
|---|---|---|---|---|
| separator | join new token parts with ., never - | 0 of 6 | 6 of 6 | $0.021 (plain $0.020) |
| no-retry | don't retry store.set inside login | 0 of 6 | 6 of 6 | $0.017 (plain $0.018) |
docs/v2/agents.md has the runs, the CLAUDE.md comparison, and how Codex and opencode did.
Ask how, where and why
sgx ask answers from the notes, the areas of the code, the code itself, git history, saved reviews
and earlier agent sessions, and says where each part came from. In this repository:
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:38--explain hands what was found, numbered, to Claude through the claude CLI and prints a short
answer citing those numbers. The Ask box in the UI (⌘K) has the same behind an Explain button.
Brief before changing a file
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.tsCallers and tests come from import-bound and same-scope edges only (confidence 0.9 and up), so a name that happens to match elsewhere doesn't count.
Review a change
sgx review compares the working tree with the merge-base of the default branch, else HEAD. After the
fixture's login gained a retry:
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)A test counts as run when an agent session ran it after the last edit and its output says it passed.
--pr prints Markdown for a pull request; --save --verdict approved|changes|comment writes the
packet to .sgx/reviews/ to commit with the change.
The knowledge graph
sgx graph and the Graph screen show one node (a file, path#symbol, area, commit, person, note,
session, review or pull request) and everything connected to it:
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)Commits are linked to the symbols their hunks touched. --mermaid prints the same neighbourhood as a
flowchart for a doc or a PR description. sgx github sync (with GITHUB_TOKEN) adds pull requests,
reviews and checks.
Agent sessions, handoffs and digests
sgx sessions lists every Claude Code and Codex session for the repository, read from
~/.claude/projects and ~/.codex/sessions: what was asked, files edited, tests run and whether one
passed after the last edit. sgx handoff <session> writes one as Markdown the next agent or person can
start from. On a Codex session in this repository:
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.sgx digest --days 7 is the week: sessions per agent, commits and how many an agent co-authored,
the busiest areas, notes added, open questions, and accepted notes whose code changed. sgx gaps
lists busy areas with no decision, rule or gotcha yet. sgx distill <session> asks Claude for up to
three proposed notes from a finished session.
The web UI
sgx ui serves Now (what the project is, how its areas depend on each other, who worked on it in the
last 30 days, what needs you, and what agents are doing), Atlas, Graph, Sessions, Review and Notes on
127.0.0.1. It keeps the index current while it runs and refreshes the page when the code, the notes or
a transcript changes. Screens from this repository are in docs/v2/previews.
Teammates' agents
shsgx relay serve --port 4830 --token s3cret # on one machine the team can reach
sgx relay join http://that-machine:4830 --token s3cret # in each cloneEach clone posts its sessions from the last day: agent, person, branch, the first line of the prompt,
the files edited and, for working sessions, the symbols changed in the working tree. No code. Clones
meet by the repository's first commit, so the remote URL isn't sent. When an agent opens a file a
teammate's agent is editing, the hook says whose, on which branch and which symbols, and Now lists it
under "Needs you". sgx relay leave stops sending.
How it works
The index is a SQLite file in .sgx/ (ignored by git): files, symbols with body hashes, import and
call edges with a confidence each, the git log with per-file line counts, owners and co-change, and
documents with covers: front matter. Notes and saved reviews are Markdown in .sgx/notes/ and
.sgx/reviews/, which init re-includes in .sgx/.gitignore so they are committed. Sessions are read
from the agents' own transcript files and cached in .sgx/v2/. Nothing leaves the machine except
what ask --explain and distill send to the claude CLI, github sync, and the relay you join.
docs/v2/design.md is the design, docs/v2/graph.md the graph, docs/v2/cut.md what was removed from v1 and what was kept.
Limitations
- opencode 2 gets the MCP tools and the notes index in
AGENTS.md, but no hook, so its agent reads the notes only as instructions. askis lexical: symbol names, docs and lines where two or more of the question's words meet.- Edits made through shell commands (
sed, heredocs) aren't recorded as an agent's edits. - Review analyses the first 60 changed symbols and shows no reach for deleted ones.
- The relay keeps 24 hours in memory (or in
--data <file>) and has one shared token, no accounts.
Development
docs/development.md: building the binary, running the working tree, tests.