Skip to content
Graft Docs

Your first graph

Once you’ve run graft init, you have a graft/ directory full of linked Markdown nodes describing your codebase. This tutorial shows you how to explore and orient yourself.

Search & orient

Section titled “Search & orient”

  1. View the codebase map

    Terminal window
    graft map

    graft 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, no LLM, no key:

    Terminal Output
    repo map — 113 files · 687 symbols · 2186 edges · typescript
    

    src/                63 files · 527 symbols   hubs: contextDirFor (node-file.ts, 21←), wiringPath (write.ts, 14←), buildGraph (build.ts, 11←)
    test/               43 files · 102 symbols   hubs: edge (graph-traverse.test.ts, 4←), graphOf (graph-traverse.test.ts, 4←), fileNode (graph-map.test.ts, 3←)
    viewer/             5 files · 58 symbols   hubs: $ (main.ts, 9←), activeGraph (main.ts, 5←), cvar (data.ts, 5←)
    scripts/            2 files · 0 symbols
    

    hotspots: contextDirFor · function · src/context/node-file.ts:L100-L103 · 21←  wiringPath · function · src/graph/write.ts:L20-L22 · 14←  buildGraph · function · src/graph/build.ts:L104-L218 · 11←  ...

  2. Search the graph

    Terminal window
    graft grep "NEEDLE"

    graft grep is exhaustive over every indexed file and groups hits by enclosing symbol, ranked by the same in-edge coupling graft map uses — built for “every occurrence of this pattern” tasks where graft 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");

  3. Trace call sites

    Terminal window
    graft callers MyFunction

    Find out who calls, references, imports, implements, or extends a symbol.

  4. Check graph health

    Terminal window
    graft check

    Verifies if the graft/ directory has drifted from the code (never auto-refreshes — it’s the drift report).

  5. Visualize the graph

    Terminal window
    graft viz

    Serves an interactive viewer on localhost so you can visually explore the nodes and dependencies.

Understand the graft/ directory

Section titled “Understand the graft/ directory”

The generated graph lives in graft/ and consists of:

  • Markdown node files (graft/*.md) — One per subsystem or concept, with typed wikilinks between them.
  • Wiring graph (graft/.graph/wiring.json) — Per-symbol code graph built by tree-sitter.
  • Per-file wiring cards — Mirror your source tree with structural information.

Monorepos & multi-repo folders

Section titled “Monorepos & multi-repo folders”

Graft handles two shapes without any config.

Monorepo with one .git

Section titled “Monorepo with one .git”

A single repo with pnpm-workspace.yaml/package.json workspaces, or per-package go.mod/pyproject.toml/Cargo.toml.

  • graft build discovers each sub-project as a ranking scope
  • ask/map rank every scope on its own terms and fuse the results, so the biggest sub-project can’t drown a small one
  • Hits carry [scope/] labels
  • graft map groups its directory clusters by scope first

Folder of separate git repos

Section titled “Folder of separate git repos”

A folder of separate git repos (no .git at the top).

  • graft build auto-splits: each child gets its own (git-ignored) graft/
  • The parent gets a graft/workspace.json index
  • Queries from the parent federate across every child, always labeled <child>/
  • Run graft build inside a child to work on just that repo
© 2026 Sharon Wang