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.

sh
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

init 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 output
wrote .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:

text
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.

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:

TaskWhat the note saysWithout sgxWith the hooksCost per run, with
separatorjoin new token parts with ., never -0 of 66 of 6$0.021 (plain $0.020)
no-retrydon't retry store.set inside login0 of 66 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 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

--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 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

Callers 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 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)

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 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)

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

sh
sgx relay serve --port 4830 --token s3cret                  # on one machine the team can reach
sgx relay join http://that-machine:4830 --token s3cret      # in each clone

Each 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.
  • ask is 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.