tld index

tld index reads your source code and turns it into a structured code graph with architectural snapshots. It’s the engine behind code-driven diagrams.

tld index .

It runs locally and offline. Scan, index, publish. Then tld index --watch keeps it live as you code.

Caution

The indexing pipeline is under active development. Expect rough edges and long runtimes on large codebases. Start with a small repo or a branch.

What it does

1. Discover: walks the repository and finds source files, skipping excluded paths.
2. Parse: Tree-sitter grammars parse every file into syntax trees.
3. Index symbols: external SCIP indexers resolve precise symbols and references, with LSP-grade accuracy where a language has one.
4. Relationships: builds the edges between symbols, packages, and files.
5. Infrastructure: picks up infrastructure definitions where present.
6. Verify: checks the result before publishing.
7. Publish snapshot: writes an immutable snapshot to the local database.
8. Save diff diagram: computes the change overlay against the previous snapshot.
9. Map graph: optionally groups the dependency graph into architectural components (--map).

Each run publishes a snapshot keyed to the Git revision, so you can compare any two of them later.

Basic usage

# Index the current directory
tld index .

# Index a specific path
tld index ./src

# Index a remote repository (cloned into the tld data dir)
tld index github.com/org/repo
tld index https://github.com/org/repo.git

# Watch for Git changes
tld index . --watch

# Group the graph into architectural components
tld index . --map

When it finishes you’ll see a summary:

snapshot 7f3c9a12...
repository  github.com/org/project
revision    abc123def456
sources     1284
projects    12
facts       8452
edges       19033
map         view 42 (9 components, 14 groups, 3 isolated, modularity 0.61)

Watch mode

--watch keeps the index in sync with your working tree. The current commit is the base, the combined staged, unstaged, and untracked files are the head. Git changes trigger an incremental reindex after a debounce, and every new commit becomes an immutable snapshot. Watch always saves the affected-file change overlay you see under Repositories → Live changes in the web app.

tld index . --watch

It requires a Git repository. Watch runs in the foreground until you stop it with Ctrl-C, or you can detach it:

# Start a background watcher and return
tld index . --watch --detach

# Check what's running
tld index status
tld index status --all

# Stop a watcher
tld index stop .

Watchers are tracked per checkout, so each developer can watch their own clone. A repository can only have one watcher at a time; the second one exits.

The map view

By default tld index publishes the raw code graph. Pass --map to group it into architectural components and materialize a map view you can open in the editor. Grouping and connector budgets come from global map.* config, with per-repository overrides on the repository settings page. With --watch, the map refreshes after each scan.

Remote repositories

tld index accepts github.com/owner/repo, owner/repo, or any Git URL. Remote repositories are cloned into tld’s data directory and treated as managed checkouts. An explicit URL always wins; owner/repo shorthand is only treated as remote when no local directory matches.

Excludes

Keep generated and vendored code out of the graph:

tld index . --exclude vendor/ --exclude "**/*.pb.go"

Workspace exclude patterns in .tld.yaml are applied automatically. tld index --exclude adds to them for a single run.

Polling and debounce

The watcher uses fsnotify with a polling failsafe. Tune it for slow or network filesystems:

tld index . --watch --poll-interval 5s --debounce 1s

Supported languages

Language	Indexer
Go	scip-go
TypeScript / JavaScript	scip-typescript
Python	scip-python
Java	scip-java
C / C++	scip-clang
C# / .NET	scip-dotnet
Rust	rust-analyzer
Dart	scip-dart
PHP	scip-php
Ruby	scip-ruby

Missing indexers are skipped; run tld doctor to see what’s available. Tool paths and the per-indexer timeout are configurable under index.tools.*.

Where the results go

Snapshots live in the local tld database. Run tld serve and open Repositories to browse indexed repositories, inspect the map, and see live changes. To turn snapshots into a diff diagram, use tld git compare.