Skip to content

t1k:code-graph

FieldValue
Modulet1k-knowledge
Version2.7.50
Effortlow
Tools—

Keywords: blast-radius, code-graph, dead code, pr impact, what-depends-on, who-calls

/t1k:code-graph
<question about code structure>

Code Graph — Structural Retrieval Across Every Enrolled Repo

Section titled “Code Graph — Structural Retrieval Across Every Enrolled Repo”

Two merged graphs, one per engine, built nightly from every repo carrying the enrolment topic plus its engine topic. Where a corpus search answers “does this exist?” by reading prose and signatures, the graph answers “what is connected to this?” by walking an AST — a question no text search can answer reliably.

scopereposnodesedgescommunitiesextraction quality
cocos41184,875327,6426,82996% extracted / 4% inferred
unity56112,000242,3232,68694% extracted / 6% inferred

Measured 2026-10-05. Re-read them with graph_stats rather than trusting this table — the nightly moves these numbers, and this table does not move with it. Growth since 2026-09-18 is enrolment breadth (more repos; nodes per repo fell), and label-level duplication across repos is by design (dedup gates label merging off for code nodes), so node counts are not comparable across dates without the repo count.

The graph is published. All three scopes are live on the1studio.org and verify the studio bearer (audience code-graph); Cloudflare Access is gone from these hosts.

ScopeEndpoint
cocoshttps://graph-cocos.the1studio.org/mcp
unityhttps://graph-unity.the1studio.org/mcp
unity-gameshttps://graph-unity-games.the1studio.org/mcp (live)

Local mode. Each scope also runs on loopback (127.0.0.1:8091 cocos, 8092 unity, 8093 unity-games) with an X-API-Key read from a 0600 file by a headersHelper. Register either mode with install-code-graph.sh, then check with scripts/graph-smoke.cjs; see t1k-mcp-management/references/code-graph-registration.md.

One gate: the app verifies the studio bearer. A client with no token gets 401 with a WWW-Authenticate: Bearer challenge and never reaches the graph.

These endpoints authenticate with the studio bearer. A NEW internal graph or MCP service authenticates through studio-auth, not a new Access app (docs/studio-auth.md).

Any member of the The1Studio GitHub organisation connects with gh auth login alone. No key, no manual login:

Terminal window
claude mcp add --transport http code-graph-cocos https://graph-cocos.the1studio.org/mcp
claude mcp add --transport http code-graph-unity https://graph-unity.the1studio.org/mcp

A headersHelper sends the studio bearer from your gh auth login on each connection; there is no browser or /mcp login. The graph verifies it (signature, audience, expiry) and logs each call under your GitHub identity. Register with install-code-graph.sh (see code-graph-registration.md) for the helper to be wired.

  • Check the tool is actually in your session. No mcp__code-graph-* tool in your list means this session is not connected, whatever the endpoint’s status. Say so rather than substituting a guess.
  • A 403 (instead of the 401/302 above) means the human Access policy is gone and only service tokens are admitted. That is a configuration regression, not “the graph is down” — report it as such.
  • A 421 (“Invalid Host header”) on connect, while a direct curl returns 401, is a host-header mismatch in how the client reached the endpoint — not an outage and not an auth failure (core#2503). Re-register with the exact URL above (no alias, port or tunnel rewrite), and if it persists report it as a transport defect with the URL used.
  • Do not read a grep miss as a graph verdict. The graph’s zero-caller result is a real signal; a grep miss is not. If you cannot reach the graph, the question stays open.
  • The known gaps below still bind once connected. Reachable is not the same as right: read them before trusting a number.

Reach for the graph when the question is structural and cross-repo:

  • Who calls this? — incoming neighbours on the symbol.
  • What breaks if I change this? — the same, then widened transitively.
  • Is this actually unused? — a graph zero-caller result is a real signal; a grep miss is not, because grep cannot follow aliasing, re-export or dynamic wiring.
  • How does A reach B? — shortest path, which finds indirection grep cannot follow at all.
  • What are the load-bearing types here? — god nodes, the most-connected symbols in a scope.

Stay on grep when the question is textual: a string literal, a comment, a config key, a filename in a manifest — anything the AST does not model. The graph indexes code structure, not the whole repository.

Ten tools, from the service’s own tools/list:

toolwhat it is for
graph_statsnode/edge counts, extraction quality — always cheap, ask it first
query_graphfree-form structural query
get_nodeone symbol’s record
get_neighborscallers and callees — the blast-radius workhorse
god_nodesmost-connected types in a scope
shortest_pathhow one symbol reaches another
get_communitymembership of one community
list_prs, get_pr_impact, triage_prsPR-oriented: what a diff touches, what it puts at risk

Known gaps — do not present these as working

Section titled “Known gaps — do not present these as working”
  • Community names are placeholders. Clustering runs unlabelled, so every community comes back as Community N rather than a meaningful name: naming needs a model call and a network round trip per community, which a nightly build must not depend on. Read membership, not the label.
  • The merge does not dedupe symbols across repos. god_nodes on Cocos returns MotionHandle six times at an identical edge count — six repos vendoring the same type, entered as six nodes. Read a god-node list as “this NAME is load-bearing”, never as a count of distinct types, and confirm with get_node before acting on one.
  • limit is not honoured by god_nodes. Asking for 5 returns 10 rows. Assume a tool argument is advisory until you have watched it change the output.
  • Unity symbols are mostly untyped — 22,994 of 23,255 C# nodes in the unity-dots-library scope carry no type. A type-dependent answer on the unity scope is weaker than the node count makes it look.
  • No dead-code verdicts on Cocos. @ccclass components are attached in prefabs, not imported, so an import-graph reading of “unreferenced” is simply wrong there — three such wrong verdicts were recorded before the graph was narrowed. Do not answer a Cocos dead-code question from this graph at all until prefab __uuid__ edges are indexed.
  • Ambiguous labels and vendored copies. A label shared by several nodes may resolve to one, and caller counts are a lower bound when repos vendor a library: see references/known-gaps.md.
  • The graph is nightly, not live. It reflects each repo’s default branch at the last successful build. A symbol added today is not in it. Anything date-sensitive goes through graph_stats before it goes into an answer.

Two retrievers, two questions, one order:

  1. /t1k:knowledge-retrieval first — the corpus of prose and API docs across the Unity/.NET and Cocos worlds. “Have we built this? Does this type exist?”
  2. The graph second — structure. “What connects to it, who calls it, what breaks if it changes?”

Sweeping the corpus first is not a preference: a graph query presumes you already know which symbol to ask about, and the corpus is what tells you the symbol exists and what it is called. Query technique belongs to the knowledge-retrieval skill — cite it, do not restate it here.

Status: promising, not proven. Graph retrieval is an unproven hypothesis with a kill criterion — it must beat the docs corpus on code-generation context by a wide margin over a scored question set, or the layer is retired. It is served ahead of that result by explicit instruction. Treat its answers as promising rather than settled, and do not re-file that evaluation as done.

The scoped evaluation exists: plans/261005-graph-vs-grep-benchmark/ fixes the question set, the grep baseline, the numeric WIN/LOSE margins, the overall verdict table, and the follow-up row for a FALSE or NO-VALUE result (a batched user decision; retirement is never auto-decided).

Measured 2026-10-08 (plans/261005-graph-vs-grep-benchmark/results/REPORT.md, row R5, see DECISION.md): over 66 runs on one Cocos repo the graph was no more accurate than grep plus Read (four types tie, one inconclusive) at about 1.1x to 1.4x the cost per run, and agents chose it unprompted in 0 of 20 runs. That is the benchmark’s result, taken before the 2026-10-08 nudges; the kill-criterion evaluation above is still open.

Is the graph actually used? Measure it, do not assume:

Terminal window
bun .claude/skills/t1k-code-graph/scripts/graph-adoption-meter.cjs [--days 7] [--json] [--list]

Read-only; scans ~/.claude/projects/**/*.jsonl and counts real tool_use blocks named mcp__code-graph-* (never text matches: system prompts and skill listings name every tool). Subagent transcripts count toward their parent session.

  • SWEEP — a scripted pass: the session used 8+ distinct graph tools, or its main transcript is headless (entrypoint: sdk-cli, a claude -p script or delegation).
  • ORGANIC — everything else: an agent that chose the graph.

The headline is organic sessions over sessions in projects where code-graph-* is registered (~/.claude.json), minus SWEEP sessions. The denominator is printed beside it, and the rate is hidden below 20. Review it weekly; --list shows each graph session.

scripts/graph-adoption-meter.cjs is a read-only deterministic script with no judgment in it. The caller (main session or any agent) runs it on demand and reads the output itself; no agent is delegated to.

  • /t1k:knowledge-retrieval — the corpus half. Corpus first, graph second.
  • t1k-graphify — the general “any input to a knowledge graph” skill. Different tool, different graph; not a substitute for this one.