tld watch

This is the big one. tld watch connects your source code directly to your architecture diagrams and keeps them in sync.

It’s a three-stage pipeline: scan → represent → watch. It runs locally and offline.

tld watch

Caution

This feature is in early stages of development. It is currently experimental. Expect rough edges, performance issues on large codebases, and frequent updates. We recommend trying it on small projects or branches until it’s more mature.

What it does

When you run tld watch, four things happen in sequence:

1. It scans your codebase, parsing source files with Tree-sitter, extracting symbols (classes, functions, modules) and their references
2. It filters and represents, applying thresholds and visibility rules to turn raw symbols into clean architecture elements
3. It launches the local web app, so you can see your diagrams immediately
4. It watches for changes, any file you modify gets rescanned, and diagrams update in real time
5. If you git commit your changes, the diagram state is committed too, and your tld workspace will get cleaned like your git worktree.

You get a live, code-driven architecture map. Right on your machine. As you or your agent codes.

Basic usage

# Watch the current directory
tld watch .
# Watch a specific path
tld watch ./src

# Open the web app in your browser automatically
tld watch --open

When watch starts, you’ll see something like:

tld v2.0.0
────────────────────────────────────
  Watching            /Users/you/project
  Repository          github.com/org/project
  Branch              main
  HEAD                abc123def
  tlDiagram available at  http://127.0.0.1:8060
────────────────────────────────────
  Press Ctrl-C to stop watching.

Then, as you save files:

source modified src/services/auth.go: representation updated
  elements +2 ~1, connectors +3 ~0, views +1, tags +0-0

Tip

If you have the required LSP you can click on the bottom right View Source button on a structural element and open the file or symbol directly in your editor.

Embedding support

Vector embeddings group related components semantically. Two services that work together conceptually end up near each other in the diagram, even if they live in different directories.

tld watch --embedding-provider openai --embedding-model text-embedding-3-small

Any OpenAI-compatible endpoint works:

tld watch --embedding-provider openai \
  --embedding-endpoint https://my-llm.internal/v1 \
  --embedding-model custom-model \
  --embedding-dimension 768

The CLI verifies the embedding provider’s health on startup. If it can’t reach the endpoint, it fails early with a clear error.

To disable embeddings: either set the provider to none, or just don’t pass any embedding flags at all. They’re off by default.

Thresholds and noise control

Dense codebases produce dense symbol graphs. A single utility file imported by 100 components shouldn’t pollute your diagram. Thresholds give you control.

tld watch \
  --max-elements-per-view 30 \
  --max-connectors-per-view 60 \
  --max-incoming-per-element 10 \
  --max-outgoing-per-element 10

Each threshold caps how much detail gets expanded before collapsing into a group. Read more in the configuration guide.

Watcher backends

# Auto-detect (default, works great on macOS and Linux)
tld watch

# Force fsnotify (event-based, low CPU)
tld watch --watcher fsnotify

# Force polling (for network drives, Docker volumes, etc.)
tld watch --watcher poll --poll-interval 2s

The auto mode picks fsnotify on platforms that support it, falling back to polling. You usually don’t need to think about this.

Watcher vs analyze

Both tld watch and tld analyze scan source code. They serve different purposes:

• tld analyze one-shot scan, writes directly to your workspace YAML files. Build-focused workflow.
• tld watch continuous pipeline, writes to a local SQLite database. Shows results in the local web app. Live-development workflow.

Which one should you use? If you’re actively coding and want to see how changes impact architecture, use tld watch. If you’re preparing diagrams for a release or a review, use tld analyze → tld plan → tld apply.

They can coexist. You can tld analyze your codebase, push to the cloud, and also keep tld watch running locally for exploration.

The —rescan flag

Watch caches parsed files for speed. Only modified files get rescanned. If you want to force a full rescan from scratch:

tld watch --rescan

This clears all cached parse results and rebuilds everything. Useful if you’ve changed thresholds, changed embedding models, or suspect stale data.

What happens under the hood

The pipeline has three distinct phases, all happening locally:

Phase 1: Scan: Tree-sitter parses every source file. It extracts named symbols (functions, classes, structs, interfaces) and reference edges (imports, calls, type references). Results go into a local SQLite database keyed by git commit hash. Incremental, only changed files get rescanned.

Phase 2: Filter & Represent: The raw symbol graph is massive. Filters remove noise: test files, generated code, vendored dependencies (controlled by your exclude patterns). Thresholds collapse high-degree connections. Visibility scores determine what’s important enough to show. The output is clean architecture elements and connectors.

Phase 3: Watch: A file watcher monitors your source tree. When files change, they’re rescanned. The delta between the old and new representation is computed. Changes are pushed to the local web app via WebSocket, updating diagrams in real time for any connected browser.

All of this runs locally. Nothing gets sent to the cloud unless you explicitly tld apply.