Terrain

A local-first platform for understanding codebases. Point Terrain at a TypeScript/JavaScript project and it maps the code into an interactive graph you can explore in your browser — files, functions, classes, components, and how they connect. Everything runs on your machine; your code never leaves it.

---

What is Terrain?

Reading an unfamiliar codebase is slow: you jump between files trying to build a mental model of what exists and how it fits together. Terrain builds that model for you.

It scans your project with tree-sitter, extracts every meaningful code entity and the relationships between them, stores the result as a graph in a local SQLite database, and serves an interactive explorer. You get a bird's-eye map of the project plus a click-to-inspect view of any entity's signature, docs, and source.

Local-first by design — all data lives in a .terrain/ folder in your project. No cloud, no network calls, no code leaving your machine.

---

Screenshots

Explore the graph. The mind-map view expands from directories down to individual entities. Select anything to inspect it.

Search across the whole project. Fuzzy-search every node by name and jump straight to it.

Inspect any entity. Type, signature, source location, tags, extracted JSDoc, and syntax-highlighted source — all in one panel.

---

Features (built today)

• Multi-language parsing — tree-sitter AST parsing for TypeScript, JavaScript (and JSX/TSX)
• Code graph — nodes for files, functions, classes, methods, variables, and React components; edges for contains, imports, and extends
• Real import resolution — uses the TypeScript compiler's ts.resolveModuleName to resolve imports accurately (not guesswork)
• Documentation extraction — pulls JSDoc/TSDoc comments and surfaces them in the inspector and a dedicated Docs panel
• Interactive explorer — a React mind-map with progressive disclosure (expand directories → files → entities), a source inspector, live search, resizable panels, and light/dark themes
• Local SQLite store — every scan is saved as an immutable snapshot in .terrain/store.db; resilient to per-file parse errors
• Optional AI explanations — plain-English summaries of directories and entities, powered by the LLM of your choice (see below). Off by default; nothing is sent anywhere unless you opt in.

---

Quick start

Requirements: Node ≥ 20 and pnpm 10+.

pnpm install        # install dependencies
pnpm build          # build all packages

# Scan a project and open the explorer in your browser
node packages/cli/dist/index.js scan /path/to/your/project

# Or scan the current directory
node packages/cli/dist/index.js scan .

The scan runs in seconds, saves a snapshot to .terrain/store.db, and opens the explorer at http://localhost:3847. To re-open the last scan without re-scanning:

node packages/cli/dist/index.js view

Tip: after building, the CLI is also exposed as a terrain binary within the workspace (bin in packages/cli). The node packages/cli/dist/index.js … form above always works and needs no linking.

---

CLI commands

Command	What it does	Key options
scan [path]	Scan a directory, build the graph, and open the viewer	--no-view (skip browser), --no-ai (skip AI step), -p, --port <n>, -i, --include <globs…>, -e, --ignore <globs…>, -y, --yes
view	Open the explorer for the most recent scan	-p, --port <n> (default 3847), --no-open
config show	Print the merged LLM configuration	—
config set <key> <value>	Set a value in ~/.terrain/config.json (e.g. llm.provider openai)	—
config providers	List available LLM providers and their status	—

---

Optional: AI explanations

Terrain can annotate directories and entities with short natural-language explanations. It's model-agnostic and opt-in — with no provider configured, Terrain simply skips the AI step and works exactly as shown above.

Three tiers:

• None (default) — fully static analysis, zero LLM calls.
• Local (free) — point Terrain at Ollama running on your machine; nothing leaves your computer.
• Bring your own key — OpenAI, Anthropic, or Google, using your own API key.

Configuration is layered: .terrainrc (project) → ~/.terrain/config.json (user) → environment variables (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, or TERRAIN_* equivalents). API keys should live in env vars or the user config file — never committed to a project. Terrain estimates token cost before enriching so there are no surprise bills.

node packages/cli/dist/index.js config providers   # see what's available
node packages/cli/dist/index.js config set llm.provider ollama

---

How it works

scan → store → serve → explore

Scanner        file discovery (fast-glob) → tree-sitter parse →
               function / class / import / export / markdown visitors
Graph builder  raw file data → nodes + edges, imports resolved via
               ts.resolveModuleName()
Store          SQLite (better-sqlite3, WAL) at .terrain/store.db,
               immutable per-scan snapshots
Server         Fastify REST API + static UI (port 3847)
Explorer       React 19 + Tailwind 4 mind-map, served in your browser

It's a pnpm workspace monorepo:

Package	Responsibility
@terrain/scanner	File discovery + tree-sitter parsing + visitors
@terrain/graph	Canonical node/edge types + graph builder
@terrain/store	SQLite persistence (repository pattern)
@terrain/server	Fastify REST API + UI serving
@terrain/ui	React explorer front-end
@terrain/ai	Model-agnostic LLM enrichment
@terrain/cli	terrain command-line entry point

Node IDs are deterministic SHA-256 hashes of filePath::name::type, which makes entities stable across scans — groundwork for future incremental updates and diffing.

---

Roadmap

Terrain is early. Milestone 0 ("Scan & See") — the full scan → store → serve → explore pipeline — is complete, along with M1a documentation extraction and search. Planned next:

• M1 — call-graph edges (entity-to-entity calls relationships)
• M2 — flow tracing and flowchart views
• M3 — pattern / architecture detection
• V1 — semantic search and static HTML export
• V2 — a VS Code extension

The static-analysis pipeline is designed to deepen over time: tree-sitter for universal parsing today, layering in the full TypeScript type-checker for scope-resolved call graphs later.

---

Tech stack

tree-sitter · TypeScript compiler API · better-sqlite3 · Fastify · React 19 · Tailwind CSS 4 · Vite · pnpm workspaces · tsup

---

For the full product spec, architecture, and design decisions, see terrain-prd.md.