# sgx for agents

A live code knowledge graph that lets an agent ask in symbols instead of reading files: a location, a signature, an outline, a blast radius, a context pack sized to a budget you set — and, after every edit, what that edit broke elsewhere.

## Install

```sh
bun install
bun run build                 # standalone binary: dist/sgx, with WASM, workers and UI embedded
bun link                      # registers sgx -> src/cli.ts; requires this checkout and Bun
cd /path/to/your/repository
sgx init --claude              # index and merge repository-local Claude Code configuration
sgx init --codex               # the same, for Codex (.codex/config.toml)
sgx init --fx                  # the same, for fx (.mcp.json and AGENTS.md)
sgx find login
sgx source add https://docs.example.com/api.md --covers 'src/api/**'
sgx ui
```

`sgx init --claude` merges the MCP server and both hooks into the repository's own config.

## The smallest useful run

```text
$ sgx find login --limit 3
@twtp1 fn    login(user: User, opts: LoginOpts = {}): Session   src/auth/login.ts:17
@89nj2 iface interface LoginOpts                                src/auth/types.ts:6
@jwcqd fn    testLogin(): void                                  tests/login.ts:3
```

Handles like `@twtp1` are stable ids: pass one back to `show` instead of searching again.

## Tools

| Tool | Inputs | Result |
| --- | --- | --- |
| `find` | `query`, `limit=20` (1–200) | L1 symbol lines |
| `outline` | `path` | File/directory skeleton |
| `show` | `handles[]`, `fresh=false` | L3 source with session deduplication |
| `context` | `task`, `budget=4000` (200–50000), `working_set=false` | Packed text, estimates and dropped handles |
| `impact` | `target` or `diff=true`, `depth=3` (1–6) | Callers, tests and co-change |
| `changes` | none | Feed since this session's last call |
| `check` | `scope="diff"`, `"all"`, or a path | Guard findings |
| `docs` | `target?`, `stale=false` | Which documents cover which code, or what has fallen behind |
| `note` | `handle`, `text` | Stored anchored note |
| `flavors` | `evidence=false` | Ecosystems by package |
| `where` | `query`, `limit=20`, `route=false` | Symbols by concept with calibrated confidence; `route` spends one model call |
| `git` | `what="status"`, `"log"` or `"owners"`, `path`, `limit=20` | Working tree, commit log, or a file's authors |
| `pr` | `number?`, `state="open"` | Pull request list, or one with its changed symbols, callers, tests and downstream repositories |
| `lookup_candidates` | `query`, `kind`, `limit`, `budget`, `expand` | Structured versioned candidates and provenance |
| `lookup_materialize` | `expected`, `handle`, `budget` | Source for the selected snapshot, or stale result |

## Three mistakes that waste the context window

1. Grepping the repository instead of `where` / `find`, and reading a whole file instead of `outline` / `show`. `sgx improve` measures exactly this and rewrites the session instructions.
2. Treating an edge as type-checked. Resolution is syntactic, every edge carries a confidence, and inferred ones print `~`.
3. Asking `where` before `sgx enrich`. Without the semantic layer it reports a finding, not an answer.

Full reference: https://sgx.sh/reference