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.

This feature requires external dependencies to function. SCIP indexers and language servers are used to resolve symbols and references.

#Run in project root
tld index .

Indexing runs locally; cloning remote repositories and indexer dependency setup may need network access. 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 lets you track what changes in your working tree, either by you or your agent. 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 saves the affected-file change overlay under Repositories → Watch. See the Repositories guide for snapshots, mapping, and comparisons.

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.

Go, TypeScript, Python, and Rust watches also use language servers (gopls, typescript-language-server, pyright-langserver, and rust-analyzer) for incremental updates. Other languages are reindexed from scratch on each change.

Check availability with tld doctor.

Mapping

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.

This is meant to give you building blocks for your diagrams. They are grounded and derived from source code, with some metadata fields pre-filled. You can copy paste or link to them in your architecture diagrams.

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.