Skip to content
Trail-code Docs
Unofficial community docs. Content pulled on 2026-10-24 from Trail-Code@d205ac3. For the latest, see the official repo.

Your first graph

Once you’ve run trail init, you have a graft map of your repo in graft/. This tutorial shows you how to explore and orient yourself. ask, grep, skeleton, callers and map need no LLM and no key.

  1. View the repo map

    Terminal window
    trail map

    trail map is a token-budgeted first look at a repo: directory clusters with file/symbol counts, each dir’s local hubs, and the global hotspots, all ranked by in-degree:

    Terminal Output
    repo map — 313 files · 2349 symbols · 8148 edges · javascript, typescript
    

    src/                157 files · 1804 symbols   hubs: wiringPath (write.ts, 48←), cmd (brand.ts, 45←), buildGraph (build.ts, 39←)
    test/               144 files · 467 symbols   hubs: tmpRepo (helpers.ts, 46←), fetch (app-identity.test.ts, 7←), fakeProviders (helpers.ts, 5←)
    viewer/             5 files · 71 symbols   hubs: $ (main.ts, 9←), cvar (data.ts, 6←), activeGraph (main.ts, 5←)
    scripts/            7 files · 7 symbols   hubs: bump (graph-quality.mjs, 1←), defaultTranscriptDir (tally-audit.mjs, 1←), flush (tally-audit.mjs, 1←)
    

    hotspots: wiringPath · function · src/graph/write.ts:L20-L22 · 48←  tmpRepo · function · test/helpers.ts:L30-L32 · 46←  cmd · function · src/brand.ts:L63-L70 · 45←  ...

  2. Ask for the code that matches a task

    Terminal window
    trail ask "<task>"

    Returns the matching code and learnings: ranked nodes and exact file:line.

  3. Search every occurrence of a pattern

    Terminal window
    trail grep "NEEDLE"

    trail grep is exhaustive over every indexed file and groups hits by enclosing symbol, ranked by the same in-edge coupling trail map uses. It’s built for “every occurrence of this pattern” tasks where trail ask’s ranked top-N isn’t enough:

    Terminal Output
    "NEEDLE" — 2 hits in 2 symbols across 1 files (searched 1 indexed files)
    

    heavilyCalled · function · src/a.ts:L1-L3 · 3 in-edges
      L2: console.log("NEEDLE hit in heavilyCalled");
    

    rarelyCalled · function · src/a.ts:L4-L6 · 0 in-edges
      L5: console.log("NEEDLE hit in rarelyCalled");

  4. See a file’s API surface

    Terminal window
    trail skeleton <file>

    Every signature in one file, no bodies: the API surface for about a tenth of the tokens.

  5. Trace who calls a symbol

    Terminal window
    trail callers <symbol>
    trail callers <symbol> -d N

    Find who calls, references, imports, implements or extends a symbol. Add -d N to walk transitively out to depth N: the full blast radius.

  6. Check the status

    Terminal window
    trail status

    The graft map, learnings and tokens saved, on one screen.

  7. Visualize the graph

    Terminal window
    trail viz

    Serves an interactive viewer on localhost. See Visualize your codebase.

What’s in graft/

Section titled “What’s in graft/”
  • Markdown nodes (graft/*.md): linked nodes your agent opens and greps like any other file. See Graph structure.
  • Code graph (graft/.graph/wiring.json): the per-symbol code graph, plus a per-file wiring card mirroring your source tree.
© 2026 Sharon Wang