Scaffld

See how data flows through any codebase. Paste a GitHub URL and Scaffld clones the repo, traces how data moves through it (where it enters, what transforms it, where it ends up), and draws an interactive architecture diagram you can explore and export. Every node carries the real module or class name from the code.

Two things make it different:

• The diagram is deterministic. It's computed from the code's AST, not generated by a model. The same commit produces the same diagram, every time. No account or API key is needed to get a full diagram.
• It's built to pair with Claude. Connect your own Claude and every label and description on the board gets rewritten in plain English. This is the recommended setup. See Connect your Claude.

Install & run

One command (once published to npm), no clone, no setup:

npx @fskulimo/scaffld                     # open the app in your browser
npx @fskulimo/scaffld mwaskom/seaborn     # open and analyze a repo straight away

From source (works today):

git clone https://github.com/fskulimo/scaffld.git
cd scaffld
npm install
npm start                   # builds once, serves the app, opens your browser
# or target a repo directly:  npm start psf/requests

Scaffld runs on one local port (default 8799, change it with --port). It opens your browser automatically, and Ctrl+C stops it. Past analyses are cached in ~/.scaffld/.

If you have Claude Code installed and logged in, Scaffld detects it and uses your Claude for the labels automatically. Without it, you still get the full deterministic diagram.

How it works

 paste github URL
        │
        ▼
 ┌─ server/analyze · deterministic ───────────────────────────────┐
 │  fetch.ts   shallow git clone (public + private via gh auth)    │
 │  scan.ts    walk source → tree-sitter AST (py/js/ts/java/go/cpp)│
 │  kinds.ts   imports → role signals (db/cache/queue/api/storage) │
 │  flow.ts    ⇒ a complete GraphData: real names, files, edges    │
 └───────────────────────────────┬────────────────────────────────┘
                                  │  readability pass (auto, uses your Claude)
                                  ▼
 ┌─ server/ai · your own Claude ───────────────────────────────────┐
 │  enrich.ts  rewrites node/edge *labels & descriptions* only,    │
 │             never the nodes or edges. Provider unreachable, or   │
 │             enrichment off? ⇒ the deterministic labels stand.   │
 └───────────────────────────────┬────────────────────────────────┘
                                  ▼
 ┌─ src (React Flow) ──────────────────────────────────────────────┐
 │  typed color-coded nodes · grouped layers · labeled data-flow    │
 │  edges · overview + per-node detail panels · Mermaid + PNG export│
 └──────────────────────────────────────────────────────────────────┘

The AST layer is the source of truth. tree-sitter finds the real files and symbols, and the role rules classify them (a redis import becomes a Cache node). The AI layer only rewrites human-readable text on top of that fixed structure. It cannot invent, add, or remove a node or an edge.

Connect your Claude

Scaffld is designed to be used with Claude. The deterministic engine draws an accurate map; your Claude is what makes it readable, turning raw symbol names into plain-English labels and per-component descriptions ("Remembers who you are between requests").

The good news: if you already use Claude Code, there is nothing to set up. Scaffld detects your local claude CLI and uses it automatically, on your account and your plan, at no extra cost. It prints a one-line notice at startup so you always know it's active.

| SCAFFLD_AI | Provider | Cost | | --- | --- | --- | | (unset) / claude-code | your local claude CLI, headless (rides your Claude plan) | $0 | | api | @anthropic-ai/sdk (needs your own ANTHROPIC_API_KEY) | metered |

You stay in control with SCAFFLD_ENRICH: unset = auto (on when Claude is available), on = force, off = never. Enrichment sends short code excerpts to Anthropic under your account, and it only rewrites labels, never the graph structure. If the provider isn't reachable, Scaffld quietly keeps the deterministic labels. All options are documented in .env.example.

Claude is the only supported model right now. We're working on making the AI layer model-agnostic so you can plug in other providers; the provider interface (server/ai/provider.ts) is already the seam, and contributions are welcome.

Security & privacy

• Repo code is never executed. It's parsed with tree-sitter, never run.
• The clone can't be hijacked. The target is rebuilt from a strictly validated owner/name (github.com only) and git runs with an argument array, no shell.
• Local by default. The server binds to 127.0.0.1. Clones are shallow, land in a temp dir, and are deleted after analysis.
• Nothing leaves your machine except the git clone itself, unless you've connected your Claude. In that case short label excerpts go to your own account, it's announced at startup, and SCAFFLD_ENRICH=off turns it off.

Full details and how to report a vulnerability: SECURITY.md.

Languages

Python · JavaScript/JSX · TypeScript/TSX · Java · Go · C/C++ (tree-sitter WASM grammars).

Development

npm run dev:all     # API + web, hot reload
npm test            # vitest: schema, coerce, mermaid, url-parse, analyzer
npm run typecheck   # tsc (app + server)
npm run lint        # eslint
npm run test:e2e    # playwright (mocks /api in-browser)

Contributions welcome, see CONTRIBUTING.md.

License

MIT © Filip Skulimowski

Lineage

Reproduces the archmap tool from Mariana Antaya's Emergent demo reel (an AST + Claude repo visualizer), rebuilt from scratch on a local-first toolchain. Local-first, inspectable, rebuildable. No third-party app, no telemetry.