Introduction

tlDiagram is a flexible, modern and feature-rich ecosystem for architecture diagramming. Offers many opt-in features to fit into your workflow. You can use it as a simple browser-based diagramming tool, or you can leverage the numerous features to make mapping your codebase and keeping your diagrams up to date easier.

Features at a glance

• Browser-based editor: A modern, intuitive web interface for creating and editing diagrams visually. Designed to manage complexity in rich diagrams.
• Hierarchical views: Create multiple views of the same system. Start with an overview, then drill down into details. Create them when you need it, if you need it. Re-use elements across views for multiple perspectives.
• Code-driven: Use static analysis to generate diagrams from your codebase. See the diff surface in your diagrams, and view dependencies. Keep them in sync as your code changes. Link diagram elements to code symbols and jump straight to the source.
• Deep Markdown support: Write detailed documentation directly in your diagrams. Copy your diagrams as mermaid or paste them right into canvas for quick import.
• GitHub integration: Link your diagrams to GitHub repositories, or code symbols to elements. View code snippets, preview files. Open the source code directly and jump to line from the diagram in your editor.

How the pieces fit together

tlDiagram is an ecosystem with many parts. Pick the workflow that fits.

The browser only

Simple, modern tool for visual diagramming either self-hosted or in the cloud.

AI empowered

Use the agent skill to give your AI agent the ability to read, create, and modify architecture diagrams directly. Ask it to “map this codebase” and watch it build your diagrams. You don’t need the biggest LLM to get value here.

If it misses something, just tell it to explore it further and add more details about the system. It is great to get you 80% of the way there, and then you can fill in the gaps, fine-tune from the browser if you want.

Code indexing with tld index

Run tld index . to map a codebase into a structured code graph. It parses your source with Tree-sitter, resolves symbols and references through external SCIP indexers, and publishes an immutable snapshot. Add --map to group the graph into architectural components. It’s a great way to get a quick overview of an unfamiliar codebase, or to generate a starting point you can refine in the browser.

The local web app tld serve

tld serve spins up a local tlDiagram on your machine. Same engine that powers the cloud version, using an embedded SQLite database. No Docker. No external dependencies. Just your browser and the binary.

Everything you build locally can be pushed to the cloud version when you’re ready. Or kept private on your machine forever.

Code-driven with tld index --watch

This is designed to be the sentinel of your AI-based development — driven by SCIP and LSPs instead of stochastic LLM slop, giving you a deterministic, real-time link between your code and your diagrams.

Designed like another layer on top of your linting and testing tools. It grants you visual insight into the changes made in a commit, so you can understand their impact on the overall architecture.

--watch runs the same indexing pipeline continuously against your working tree. Requires a git repository.

The cloud tldiagram.com

The cloud version is where you collaborate. Share diagrams with your team. Work together in real time. It’s the same editor as tld serve

Push hand or agent edited workspace YAML with tld sync --target remote. CLI mutations apply immediately to their selected target; refresh YAML after browser edits with tld pull --target remote.

Where to go from here

If you’re new, start with the Quick Start to get the CLI installed and your first diagram published in under five minutes.