Stop your coding agent reading whole files.

How it works

seonix reads your repository into a typed graph: the modules, classes, functions, methods and attributes a change touches, and how they connect. It follows the published seonix schema.

1. 1 · Build the graph

   Point seonix at a repository and it derives that typed graph offline. Same commit → the same graph every time. Nothing leaves your machine.

2. 2 · Find the change site

   From your task description, seonix ranks the parts of the graph the change touches, with no human-chosen target. Already know the file? Hand it in directly.

3. 3 · Hand over the digest

   seonix renders a bounded edit digest (the signatures, call sites and insertion regions your agent needs) and hands it over at the start of the session. The agent edits from turn 1 instead of exploring; the render is deterministic and costs $0.

See it run

One real task, run twice on the same rig that produces every number here. It shows the mechanism on one cell. The grid below is the evidence.

=== proof-demo: otb vs seonix, one real task, one cheap model, n=3 (mean) ===
suite=eshoponweb  task=order-service-total  model=claude-haiku-4-5

$ node bench/run.mjs --suite eshoponweb --arms otb --models claude-haiku-4-5 --runs 3 --instance order-service-total
  mean turns=9.0  mean input_tokens=288,796  mean cost=$0.0660  errors=0/3
  run 1 actions (representative):
  · Agent()
  · TaskOutput()
  · Bash("find <repo> -type f -name "*.cs" | grep …")
  · Read(Interfaces/IOrderService.cs)
  · Read(Services/OrderService.cs)
  · Read(Specifications/OrderWithItemsByIdSpec.cs)
  · Read(Interfaces/IOrderService.cs)
  · Read(Services/OrderService.cs)
  · Edit(Interfaces/IOrderService.cs)
  · Edit(Services/OrderService.cs)

$ node bench/run.mjs --suite eshoponweb --arms seonix --models claude-haiku-4-5 --runs 3 --instance order-service-total
  mean turns=6.0  mean input_tokens=263,790  mean cost=$0.0659  errors=0/3
  run 1 actions (representative):
  · Edit(Interfaces/IOrderService.cs)
  · Read(Interfaces/IOrderService.cs)
  · Edit(Interfaces/IOrderService.cs)
  · Read(Services/OrderService.cs)
  · Edit(Services/OrderService.cs)

--- headline (mean of 3 runs per arm) ---
input tokens:  otb 288,796  →  seonix 263,790  (-8.7% fewer)
turns:         otb 9.0  →  seonix 6.0
billed cost:   otb $0.0660  →  seonix $0.0659

(one task, n=3 per arm, one cheap model — illustrative, not the full benchmark grid; solve-status is graded by the real pipeline, not this quick script — see the results table above for the measured, paired-arm numbers this site actually cites.)

Repeatable: npm run proof reruns both arms for real and regenerates this capture. Nothing here is staged or hand-edited.

Ask the graph a question, from a terminal, with no model in the loop:

$ node packages/seonix/bin/cli.mjs cli seonix_ask '{"query":"which modules import walk.mjs"}' | jq -r '.matches[].label'
packages/seonix/src/cs_treesitter.mjs
packages/seonix/src/extract.mjs
packages/seonix/src/java_treesitter.mjs
packages/seonix/src/jsts_tsc.mjs
packages/seonix/src/manifest.mjs
scripts/verify-counts.mjs

seonix_ask runs tmct's deterministic, no-LLM engine over the graph. It returns JSON, so it pipes straight into jq, a script, or another tool.

Or hold a conversation. A real seonix chat transcript against this repo's own index:

tmct> which modules import walk.mjs
packages/seonix/src/cs_treesitter.mjs and packages/seonix/src/extract.mjs and packages/seonix/src/java_treesitter.mjs and packages/seonix/src/jsts_tsc.mjs and packages/seonix/src/manifest.mjs and scripts/verify-counts.mjs.

tmct> where is buildContextBundle defined
function buildContextBundle() is defined in packages/seonix/src/server.mjs at lines 139-261.

tmct> when did walk.mjs change
packages/seonix/src/walk.mjs was last touched by commit 541d91db47f3 on 2026-07-04 ("feat(seonix): seonix.toml config loader […]"); 2 earlier commits recorded.

seonix chat runs tmct (@polycode-projects/the-mechanical-code-talker), a deterministic no-LLM chatbot, over seonix's graph. Every answer is grounded in the graph or an honest miss — no model in the loop.

Quickstart with Claude Code

seonix is a Node package (ESM, Node ≥ 24) that shells out to Python 3 and git, both on PATH. Four steps take Claude Code from grepping the tree to editing from turn 1.

1. Install the seonix CLI:

   npm i -g @polycode-projects/seonix

2. Build the graph (deterministic, offline, $0):

   seonix cli index_repository '{"repo_path":"/abs/path/to/repo"}'

   This writes the typed code graph to .seonix/graph.json (plus a .seonix/TOOLS.md tool catalog). Same commit → byte-for-byte identical graph.

3. Render a bounded edit-digest for the modules a task touches and save it where the agent can read it:

   # which modules does the change touch? (ranked, no LLM)
   seonix cli seonix_locate '{"repo_path":"/abs/path/to/repo","query":"<your task>"}'
   
   # render the digest for those modules → save it under .seonix/
   seonix cli digest '{"repo_path":"/abs/path/to/repo","modules":["src/pkg/module.py"]}' > /abs/path/to/repo/.seonix/digest.txt

4. Put the digest in front of the agent at session start. Wire a Claude Code SessionStart hook that adds the rendered digest to the session context (or paste it at the top of a claude session):

   # .claude/settings.json — inject the digest once, at session start
   { "hooks": { "SessionStart": [ { "hooks": [
     { "type": "command", "command": "cat .seonix/digest.txt" }
   ] } ] } }

   The digest is in context from turn 1, so the agent edits without exploring first. No MCP server, no tool loop: the saving comes from the digest arriving up front rather than from an interactive round-trip.

Copy-paste setup

The same four steps as one block per tool, with the permission rules that let the agent run seonix without prompts.

# install + index (offline, $0)
npm i -g @polycode-projects/seonix
cd /path/to/your/repo
seonix cli index_repository "{\"repo_path\":\"$PWD\"}"

# locate the change site, render the digest
seonix cli seonix_locate "{\"repo_path\":\"$PWD\",\"query\":\"<your task>\"}"
seonix cli digest "{\"repo_path\":\"$PWD\",\"modules\":[\"src/pkg/module.py\"]}" \
  > .seonix/digest.txt

# .claude/settings.json — inject at session start; allow seonix
# to run un-prompted via the permissions framework
cat > .claude/settings.json <<'JSON'
{
  "permissions": {
    "allow": ["Bash(seonix:*)", "Read(.seonix/**)"]
  },
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command",
          "command": "cat \"$CLAUDE_PROJECT_DIR/.seonix/digest.txt\" 2>/dev/null || true" } ] }
    ]
  }
}
JSON

# install + index + digest — same commands
npm i -g @polycode-projects/seonix
cd /path/to/your/repo
seonix cli index_repository "{\"repo_path\":\"$PWD\"}"
seonix cli digest "{\"repo_path\":\"$PWD\",\"modules\":[\"src/pkg/module.py\"]}" \
  > .seonix/digest.txt

# .github/copilot-instructions.md — Copilot reads this file
# automatically at the start of every chat/agent task
cat >> .github/copilot-instructions.md <<'MD'
Before exploring the codebase, read `.seonix/digest.txt` — it is a
pre-built edit digest (signatures, call sites, insertion regions) for
this repository. Re-render it with:
`seonix cli digest '{"repo_path":"<abs repo path>","modules":[...]}'`
MD

# VS Code settings.json — allow seonix in the terminal
# tool without a confirmation prompt
"chat.tools.terminal.autoApprove": { "seonix": true }

Or paste one prompt into chat. It works for Claude Code, Copilot, or any tool-calling agent; the agent reads its own capabilities and skips whatever doesn't apply:

Install seonix globally (`npm i -g @polycode-projects/seonix`), then index
this repository by running `seonix cli index_repository` with
`repo_path` set to this repo's absolute path. Render its edit digest to
`.seonix/digest.txt` with `seonix cli digest`.

Then configure yourself to load that digest automatically, using
whichever of these applies to you — check your own docs/settings and
skip what doesn't exist:
- If you support a session-start hook (e.g. Claude Code's
  `.claude/settings.json` → `hooks.SessionStart`), add one that `cat`s
  `.seonix/digest.txt` into context (no-op if the file is missing), and
  add `"Bash(seonix:*)"` + `"Read(.seonix/**)"` to `permissions.allow`
  so you can re-index/re-locate/re-render yourself without a prompt.
- If you don't have a hook but read a standing instructions file (e.g.
  Copilot's `.github/copilot-instructions.md`), append a note there
  telling yourself to read `.seonix/digest.txt` before exploring the
  codebase, and enable running `seonix` in your terminal/tool-call
  allow-list without a confirmation prompt (e.g. VS Code's
  `chat.tools.terminal.autoApprove`).

Verify by starting a fresh session and confirming the digest text is
present in context or referenced correctly.

Prefer an interactive tool? seonix also runs as a local server. The digest path above is the recommended one, and the one the benchmarks measure. Everything runs against your local checkout with no network calls. The graph rebuilds from source, so keep it out of version control.

seonix, indexing itself

The graph below is a live seonix viz render of seonix's own code graph, the same typed-edge structure it builds for any repo you point it at.

open the graph full-page ↗ · commit timeline ↗