tld CLI
A CLI and web UI for C4-style architecture diagrams where the agent maps the codebase itself
- 294 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Runs a local server listening on port 8060
- Indexes repository sources, and after cloud sign-in syncs diagrams with tldiagram.com
- The skill lets the agent run tld commands and write diagram files
Install
- Works in
Manual install
curl -LsSf https://tldiagram.com/install.sh | sh -s serve --openmacOS and Linux: installs the binary and starts the web UI at 127.0.0.1:8060.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Runs a local server listening on port 8060
- Indexes repository sources, and after cloud sign-in syncs diagrams with tldiagram.com
- The skill lets the agent run tld commands and write diagram files
This is third-party code. Review the repository files before installing.
What it does
tld is a tool for architecture diagrams in the spirit of the C4 model. It ships as one binary containing a server and web UI, plus a CLI for the terminal and CI. Diagrams are stored as YAML next to the code and sync with the local interface and the cloud version at tlDiagram.com. From a diagram you can jump to the code in an editor or on GitHub, and the VS Code extension opens a symbol on a diagram. For agents the repository includes the create-diagram skill. It teaches Claude Code or Codex to read the sources, find responsibilities, data paths and dependencies, and build a navigable map with `tld add`, `tld connect` and `tld import`. Each relationship must be backed by code: file and symbol links go into the elements. `tld index` builds a map from sources without the agent. Locally the server runs on SQLite, and shared setups get PostgreSQL and Docker Compose files.
Who it is for. For teams that keep architecture diagrams as code and want an agent to build and update them from the sources.
Good fit when
- You need an architecture map of an existing repository with drill-down from overview to details
- Diagrams should live in git as YAML and update with the code
- You want changes between commits or in a pull request shown on the diagram
- An agent needs access to diagrams over MCP
- You need the root diagram exported to Mermaid for documentation
Not a fit when
- You need a quick one-off picture: a skill that outputs a ready file is simpler
- You do not want a local server and a program from an install script
- You need a prose explanation of the architecture without diagrams
- Indexing needs languages missing from the code indexer's supported list
Example request
Read this repository and build an architecture map in tld: an overview of 8–12 components and a separate view for the API layerLimitations
By default tld installs via a script from the internet: curl and sh on macOS and Linux, PowerShell on Windows. On Windows 11 Smart App Control may block the install. Building from source needs Go 1.26.2 or newer and Node.js 24. The code indexer supports a limited set of languages, listed in the .go-build-tags file. The native macOS and Windows apps and the mobile clients are built around a cloud account at tldiagram.com.
How to disable. Stop the server with `tld stop` and delete the tld binary. Data and settings live in ~/.config/tldiagram (the `TLD_CONFIG_DIR` and `TLD_DATA_DIR` variables change the path), and the .tld folders in projects can be deleted by hand.
FAQ
How do I install tld?
On macOS and Linux run `curl -LsSf https://tldiagram.com/install.sh | sh -s serve --open`. On Windows use the PowerShell command from the repository. The web UI opens at http://127.0.0.1:8060.
How do I connect tld to an agent?
The repository ships the create-diagram skill and plugins for Claude Code and Codex. The `tld mcp` command also runs an MCP server over stdio.
Where are diagrams stored?
Locally in a SQLite database, or in PostgreSQL if you set database.driver. Diagrams are also described as YAML files in the project and sync with the interface and the cloud.
Can I see changes between commits?
Yes. `tld git compare` compares revisions and shows the edits on the diagrams. A separate bot, tld-pr-bot, covers pull requests.
How do I export a diagram to Mermaid?
With `tld render root`. Syncing with Mermaid blocks in markdown files is set up in the interface.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI that keeps RFCs, ADRs and work items as TOML in your repo and stops an agent from closing work until checks pass
CodeGraph (Rust)
codegraph-rust
A Rust code graph for agents: four MCP tools show what an edit will touch, how the architecture fits together and where the fragile spots are
A CLI that builds a map of your repo's code and keeps team decisions in .trail, so Claude Code, Cursor and Codex stop re-exploring the project
Local code graph for agents: an MCP server returns entry points, symbol links and change impact in one call
Code graph and project memory in one Rust program: the agent gets excerpts with file and line citations
An MCP server and CLI in Go: the agent keeps an index of code and database schema in the repository, versions it in Git and reads it whole before each task
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| tld (this entry) | no | 294 | |
| Architecture Diagram Generator | no | 7,504 | outputs a finished diagram as one HTML file, while this has a server, UI and CLI with diagrams as code |
| Excalidraw Diagram Skill | no | 5,133 | draws free-form Excalidraw diagrams, while this builds structured architecture views tied to code |
README in short
The README introduces tld as a flexible C4-style tool and lists its features, from markdown notes to a pull request bot. Installation, self-hosting with PostgreSQL and Docker and a CLI command reference follow.