DockerComposeVisualizer
Created by Hadi Hajihosseini.
See your docker compose stack boot in dependency order — live health, ports, and logs — inside VS Code and Cursor.
>
> *Live dependency tiers, per-service health and ports, status-bar progress, and auto-tracked `docker compose up` in the integrated terminal.*
Stop guessing which service is blocking the rest. DockerComposeVisualizer parses your compose file, lays out services by dependency tier, and updates each card as containers move through creating → starting → healthcheck → healthy. Dependencies light up when their parents are ready, so you can see why something is still waiting.
Works in Visual Studio Code (1.93+) and Cursor.
Table of contents
Features
- Live dependency tree — Services grouped by
depends_on tiers with color-coded states and optional tier dividers.
- Per-service dependency list — See which upstream services each card is waiting on, with running / in-progress / not-started indicators.
- Auto-track on
compose up — Detects docker compose up (and custom patterns) in integrated terminals and starts tracking automatically.
- Auto-discover running stacks — Polls
docker compose ls and attaches when a stack for your workspace is already up.
- Status bar progress — Segmented bar showing how many services have reached your configured “up” state.
Status bar while running up command
Status bar when the containers are running correctly
Custom service links
Auto-detected port links
- **Boot timer** — Optional per-card timer from “deps ready” until healthy.
- **Run / Stop (optional)** — Start or stop the stack from the sidebar without leaving the editor.
- **Sidebar settings** — Grid columns, legend, logs button, dependency list, and more — saved per workspace.
Requirements
| Requirement |
Notes |
| VS Code ≥ 1.93 or Cursor |
Extension host with webview support |
| Docker |
Engine running; docker CLI on your PATH |
| docker compose |
V2 plugin (docker compose, not legacy docker-compose only) |
| Compose file |
compose.yaml, docker-compose.yml, or a file you select in the sidebar |
Getting started
- Install the extension (from the marketplace when published, or see Development to run from source).
- Open a workspace that contains your compose YAML.
- Open the DockerComposeVisualizer view on the activity bar (graph icon).
- Pick a compose file if prompted, or run your stack:
docker compose -f docker-compose.yml up
- Tracking starts automatically when
dockerComposeFlow.autoTrackOnComposeUp is enabled (default), or use DockerComposeVisualizer: Track Running Stack from the Command Palette.
Click the status bar item to open the sidebar or choose a compose file. Click a service’s logs icon to stream container logs.
How it works
compose.yaml → parse depends_on tiers → poll docker inspect
↓
webview cards + status bar
↓
terminal sniffer (compose up) / compose ls discovery
- Parse — Reads
services and depends_on (including conditions where present) and builds a tiered layout.
- Track — Matches containers by Compose project + service labels (
com.docker.compose.*).
- Reconcile — Polls health on an interval; optional immediate reconcile when the compose terminal closes.
- Unlock — A service’s “can run” state reflects whether dependency conditions are met, so cards pulse when they become runnable.
Service states (legend)
| State |
Meaning |
| Pending |
Not started yet, or waiting on dependencies |
| Creating / Starting |
Container lifecycle in progress |
| Running / Healthcheck |
Up but not yet counted “healthy” (configurable) |
| Healthy |
Reached your configured “up” threshold |
| Stopped / Error |
Exited or failed |
Commands
Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and search for DockerComposeVisualizer.
| Command |
Description |
| DockerComposeVisualizer: Open or Track |
Status bar action — open sidebar or start tracking |
| DockerComposeVisualizer: Open Sidebar |
Focus the Live Dependency Tree view |
| DockerComposeVisualizer: Open Settings |
Jump to dockerComposeFlow.* in Settings |
| DockerComposeVisualizer: Track Compose Stack |
Pick a compose file and prepare tracking |
| DockerComposeVisualizer: Track Running Stack |
Attach to an already-running project |
| DockerComposeVisualizer: Stop Tracking |
Clear tracking and status bar |
Configuration
All settings live under dockerComposeFlow.*. Open Settings and search for DockerComposeVisualizer, or edit settings.json.
Tracking & discovery
| Setting |
Default |
Description |
autoTrackOnComposeUp |
true |
Start tracking when docker compose up is detected in a terminal |
autoDiscoverRunningStack |
true |
Poll for a running stack in this workspace |
discoveryPollIntervalSeconds |
6 |
Poll interval for auto-discover |
composeFile |
"" |
Workspace-relative compose file (also saved in .dockerComposeFlow) |
defaultComposeFilePatterns |
compose.yaml, … |
Filenames tried when resolving the compose file |
projectName |
"" |
Override Compose project name (-p) |
healthPollIntervalSeconds |
3 |
Docker inspect poll interval while tracking |
markHealthyWhen |
healthy |
Count “up” at healthy or running |
| Setting |
Default |
Description |
showDependencyList |
true |
List depends_on services on each card |
showLogsButton |
true |
Per-service logs button |
showPortButtons |
true |
Auto-detected localhost port links |
showBootTimer |
true |
Seconds-to-healthy timer on cards |
showComposeRunButton |
false |
Run / Stop stack from sidebar header |
composeRunExtraArgs |
"" |
Extra args for Run (e.g. --env-file .env up -d) |
gridColumns |
auto |
2, 3, or responsive auto |
showLegend |
true |
State color legend under the tree |
Logs & links
| Setting |
Default |
Description |
logsFollow |
true |
docker logs -f vs last 200 lines |
reuseLogsTerminal |
true |
One terminal per service name |
serviceLinks |
{} |
Map service names → URL buttons (see below) |
showServiceLinksWhen |
healthy |
When custom links appear |
openLinksInExternalBrowser |
false |
System browser vs Simple Browser |
Example — custom service links in settings.json:
{
"dockerComposeFlow.serviceLinks": {
"frontend": [
{ "label": "App", "url": "http://localhost:3000" }
],
"api": "http://localhost:8000/docs"
}
}
Per-project links can also be edited from each card’s settings icon; they are stored in .dockerComposeFlow/service-links.json.
Workspace data
The extension stores workspace-specific data under .dockerComposeFlow/ (gitignored by default):
| File |
Purpose |
sidebar-settings.json |
UI preferences from the in-sidebar settings panel |
service-links.json |
Per-service link overrides from the card editor |
Development
Build & run
npm install
npm run compile
Press F5 in VS Code/Cursor to launch an Extension Development Host with this folder as extensionDevelopmentPath.
Scripts
| Script |
Description |
npm run compile |
One-shot TypeScript build → out/ |
npm run watch |
Watch mode for development |
Package
npm install -g @vscode/vsce
vsce package
Produces a .vsix for local install. out/ must be compiled first; src/ is excluded via .vscodeignore.
License
Copyright © 2026 Hadi Hajihosseini. DockerComposeVisualizer Source License (see LICENSE).
- You may use, modify, and run this project for yourself or your team.
- Contributions are welcome via pull requests to the official repository.
- You may not publish this code (or derivatives) as an extension or plugin for any editor or IDE (VS Code, Cursor, JetBrains, Vim/Neovim, etc.) on any marketplace or registry without permission from the copyright holder.
Feedback
Found a bug or have an idea? Open an issue or pull request on the project repository.
DockerComposeVisualizer — created by Hadi Hajihosseini. Clarity for multi-service local development, without leaving the editor.
