TerraVision

Turn Terraform or JSON into professional cloud architecture diagrams with official AWS, Azure and GCP styles

Ask your AI assistant for a cloud architecture diagram, in plain words, and get the diagram a cloud architect would draw: the official AWS, Azure and GCP icons, with every resource in its VPC, subnet, zone or resource group. From a description, from your Terraform code, or the other way round, with the Terraform written from the diagram. TerraVision runs on your own computer and needs no cloud access.

Get started with your AI assistant

1. Install the prerequisites (once)

TerraVision needs Graphviz (to draw) and Git. uv runs TerraVision for Claude Code, Codex, Gemini CLI and other MCP clients; Claude Desktop brings its own on Windows and macOS, so skip it there. Terraform is only needed to draw from Terraform code.

macOS

With Homebrew:

brew install graphviz git
brew install uv                        # not needed for Claude Desktop
brew install hashicorp/tap/terraform   # optional: to draw from Terraform code

Windows

In PowerShell:

winget install --id Graphviz.Graphviz -e
winget install --id Git.Git -e
winget install --id astral-sh.uv -e    # not needed for Claude Desktop
winget install --id Hashicorp.Terraform -e   # optional: to draw from Terraform code

Then open a new terminal, and restart your AI app, so they see the new programs.

Linux (Debian, Ubuntu)

sudo apt install graphviz git
curl -LsSf https://astral.sh/uv/install.sh | sh   # Claude Desktop on Linux needs it too

On Ubuntu 26.04+ and Debian testing, also sudo apt install libgvplugin-neato-layout8. For Terraform, see HashiCorp's install guide.

2. Connect your assistant

Claude Desktop: download terravision-<version>.mcpb from the latest release and open it (or drag it into Settings → Extensions). Diagrams appear right in the chat, with buttons to open the image, edit it in draw.io, show it in its folder and see its source.

Claude Code (terminal, VS Code or JetBrains):

claude plugin marketplace add patrickchugh/terravision
claude plugin install terravision-cloud-diagrams@terravision

Then start a new Claude Code session. Diagrams are saved in a diagrams folder in your project.

The very first start downloads and installs TerraVision, which can take longer than Claude Code waits. If /mcp shows TerraVision failed to connect, choose Reconnect. To avoid it, install it ahead of time: uvx --from "terravision[mcp]" terravision --version.

OpenAI Codex CLI:

codex plugin marketplace add https://github.com/patrickchugh/terravision
codex plugin add terravision-cloud-diagrams@terravision

Gemini CLI:

gemini extensions install https://github.com/patrickchugh/terravision

VS Code with GitHub Copilot, Cursor and other MCP clients: add TerraVision as an MCP server that runs uvx --from "terravision[mcp]" terravision mcp --output-dir <folder for diagrams>. The setup guide has the configuration for each.

3. Ask for a diagram

You have	Ask something like	You get
An idea	"Draw an AWS three-tier app: React on CloudFront, ECS Fargate behind an ALB in two AZs, SQL Server on RDS Multi-AZ"	The diagram (PNG, SVG, editable draw.io) and its graph. Refine it by asking: "add ElastiCache", "show how a request flows through it"
Terraform code, local or on GitHub	"Draw the architecture of the Terraform in ./infra" or "Show me a cloud architecture diagram of https://github.com/patrickchugh/testcase-bastion//examples"	A diagram of what `terraform plan` says the code deploys
A diagram you like	"Write the Terraform for this architecture"	Terraform for the resources, zones and connections, with the diagram's flows and labels kept
Terraform in a repository	"Keep this diagram up to date in CI"	A workflow that redraws the diagram whenever the Terraform changes

The first diagram takes a little longer while TerraVision installs itself. If anything is missing, the assistant says what to install. To check at any time, ask: "Is TerraVision set up correctly?"

The full guide, with more example prompts: Use TerraVision with AI assistants.

Keep diagrams current in CI/CD

Point the TerraVision GitHub Action at your Terraform, and the diagram redraws itself on every change:

- uses: hashicorp/setup-terraform@v3
- uses: patrickchugh/terravision-action@v2
  with:
    source: ./infrastructure
    outfile: docs/architecture
    format: both

A terravision.yml next to the Terraform adds the title, numbered flows and connection labels to every version. GitLab, Jenkins, Azure DevOps and others: CI/CD Integration.

Watch a 4-Minute Intro

Why TerraVision?

✅ Built for AI assistants — an MCP server and agent skill for Claude, Codex, Gemini, Copilot and Cursor; diagrams appear right in the chat in Claude Desktop (guide)
✅ JSON graph input — describe an architecture in a few lines of JSON and render it, resources match Terraform names so no need to learn a custom DSL (Graph Format)
✅ Always up-to-date — diagrams generated directly from your Terraform code
✅ 100% client-side — no cloud access required, runs locally, your code never leaves your machine
✅ CI/CD ready — automate diagram updates on every PR merge
✅ Free & open source — no expensive diagramming tool licenses
✅ Multi-cloud — AWS (full), GCP, and Azure (core services)
✅ Interactive HTML output — clickable nodes, pan/zoom, search, animated data flow
✅ Editable draw.io export — open in draw.io, Lucidchart, or any mxGraph editor
✅ Optional AI annotations — labels, titles, and flow sequences from Ollama (local) or AWS Bedrock
✅ Terragrunt compatible — auto-detects single- and multi-module Terragrunt projects
✅ MCP server and agent skill — let AI agents generate diagrams from a JSON graph or your Terraform, see the guide

Supported Cloud Providers

Provider	Status	Resource types
AWS	✅ Full support	385 types
Google Cloud	✅ Full support	264 types
Azure	✅ Full support	245 types

Full list: Node types.

Use it from the command line

TerraVision is also a command-line tool, for scripts and for people who prefer to write the graph themselves.

Install

pipx install terravision   # or: uv tool install terravision
                           # or: pip install terravision in a virtual env

You also need Python 3.11+ (uv installs one for you), Graphviz and Git, plus Terraform 1.x (or OpenTofu) when drawing from Terraform code; JSON graphs don't need it. See the Installation Guide for platform-specific instructions, Docker, and Nix.

Diagram from JSON (no Terraform needed)

Describe the architecture as nodes and connections. AWS is shown here; expand the Azure and GCP examples below.

{
  "tv_aws_users.users": ["aws_cloudfront_distribution.cdn"],
  "aws_cloudfront_distribution.cdn": ["aws_s3_bucket.static_site", "aws_alb.api"],
  "aws_vpc.main": ["aws_subnet.public~1", "aws_subnet.private~1"],
  "aws_subnet.public~1": ["aws_alb.api"],
  "aws_subnet.private~1": ["aws_lambda_function.orders"],
  "aws_alb.api": ["aws_lambda_function.orders"],
  "aws_lambda_function.orders": ["aws_dynamodb_table.orders", "aws_sqs_queue.events"]
}

Azure example

{
  "tv_azurerm_users.users": ["azurerm_cdn_frontdoor_profile.edge"],
  "azurerm_cdn_frontdoor_profile.edge": ["azurerm_linux_web_app.api"],
  "azurerm_resource_group.app": ["azurerm_virtual_network.main", "azurerm_mssql_database.orders", "azurerm_servicebus_queue.events", "azurerm_key_vault.secrets"],
  "azurerm_virtual_network.main": ["azurerm_subnet.app"],
  "azurerm_subnet.app": ["azurerm_linux_web_app.api"],
  "azurerm_linux_web_app.api": ["azurerm_mssql_database.orders", "azurerm_servicebus_queue.events", "azurerm_key_vault.secrets"]
}

GCP example

{
  "tv_gcp_users_icon.users": ["google_compute_global_forwarding_rule.lb"],
  "google_compute_global_forwarding_rule.lb": ["google_cloud_run_v2_service.api"],
  "google_cloud_run_v2_service.api": ["google_sql_database_instance.orders", "google_pubsub_topic.events", "google_storage_bucket.assets"],
  "google_pubsub_topic.events": ["google_cloudfunctions2_function.worker"]
}

Render it:

terravision draw --source architecture.tvg.json --format svg

Each key is <terraform_resource_type>.<name>; each value is what it connects to or contains. That is the whole format. Full spec, schema and more examples: Graph Format. Works for AWS (aws_*), Azure (azurerm_*) and GCP (google_*).

Diagram from Terraform

git clone https://github.com/patrickchugh/terravision.git
cd terravision

# EKS cluster example
terravision draw --source tests/fixtures/aws_terraform/eks_automode --show

# Azure VM scale set
terravision draw --source tests/fixtures/azure_terraform/test_vm_vmss --show

# From a public Git repo (note the // for subfolder)
terravision draw --source https://github.com/patrickchugh/terraform-examples.git//aws/wordpress_fargate --show

That's it — your diagram is saved as architecture-aws.dot.png (the provider is appended to the name) and opens automatically.

The diagram is derived from terraform plan, so it shows what the code actually deploys: conditionals, count, for_each and modules are resolved. Eraser and friends draw what the AI imagines; TerraVision proves what the code deploys.

Generate an interactive HTML diagram

terravision visualise --source ./path-to-your-terraform --show

Click any resource to see its Terraform metadata, search resources, pan/zoom, and watch animated data flow on edges. The HTML is a single self-contained file that works fully offline.

Try the Interactive Demos

Click any of these to see the interactive HTML output TerraVision produces:

🟧 AWS demo — Wordpress on ECS Fargate with CloudFront, RDS, EFS
🟦 Azure demo — VM scale set with load balancer and VNet
🟩 GCP demo — Core GCP networking and compute

Advanced Usage Examples

Generate a diagram

# From a local directory
terravision draw --source ./path-to-your-terraform

# From a Git repository
terravision draw --source https://github.com/user/repo.git

# Custom format and filename
terravision draw --source ./path-to-your-terraform --format svg --outfile my-architecture

# Editable draw.io file
terravision draw --source ./path-to-your-terraform --format drawio --outfile my-architecture

Use a pre-generated Terraform plan (no cloud credentials needed)

# Step 1: in your Terraform environment
terraform plan -out=tfplan.bin
terraform show -json tfplan.bin > plan.json
terraform graph > graph.dot

# Step 2: diagram generation, no Terraform or cloud access required
terravision draw --planfile plan.json --graphfile graph.dot --source ./path-to-your-terraform

AI-powered annotations (optional)

terravision draw --source ./path-to-your-terraform --ai-annotate ollama   # local LLM (no data leaves your machine)
terravision draw --source ./path-to-your-terraform --ai-annotate bedrock  # AWS Bedrock via boto3 (uses your AWS credentials)
terravision draw --source ./path-to-your-terraform --ai-annotate restapi  # any OpenAI-compatible endpoint (OpenAI, LiteLLM, vLLM, ...)

Only metadata and the summary graph are sent to the LLM — never your .tf source. The bedrock backend authenticates via the standard AWS credential chain (no infrastructure to deploy); restapi is configured via TV_RESTAPI_URL, TV_RESTAPI_KEY, and TV_RESTAPI_MODEL. See the Annotations Guide and AI-Powered Annotations for the full configuration.

Simplified view

terravision draw --source ./path-to-your-terraform --simplified

Strips VPCs, subnets, and networking plumbing. Great for executive presentations.

Common options

terravision --help shows full help text details.

Option	Description	Example
`--source`	Terraform directory or Git URL	`./path-to-your-terraform`
`--format`	Output format: `png`, `svg`, `pdf`, `drawio`, and more	`svg`
`--outfile`	Output filename	`my-architecture`
`--workspace`	Terraform workspace	`production`
`--varfile`	Variable file (repeatable)	`prod.tfvars`
`--planfile`	Pre-generated plan JSON	`plan.json`
`--graphfile`	Pre-generated graph DOT	`graph.dot`
`--ai-annotate`	AI annotation backend	`ollama`, `bedrock`, `restapi`
`--simplified`	High-level view (no networking)	(flag)
`--show`	Open after generation	(flag)

Documentation

The complete documentation lives at patrickchugh.github.io/terravision.

For users:

For contributors:

FAQ

Common questions — cloud credentials, LLM data privacy, offline use, Terragrunt, output formats, and more — are answered in the FAQ on the documentation site.

Contributing

Contributions are very welcome. See CONTRIBUTING.md for development setup, coding standards, and the PR process.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: patrickchugh.github.io/terravision

License

See LICENSE.

Acknowledgments

Graphviz — diagram rendering
Terraform — infrastructure parsing
Terragrunt — multi-module orchestration
Cloud provider icons from official AWS, GCP, and Azure icon sets

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.devcontainer		.devcontainer
.github		.github
docs		docs
examples/graphs		examples/graphs
hcl2		hcl2
images		images
mcpb		mcpb
modules		modules
resource_classes		resource_classes
resource_images		resource_images
scripts		scripts
skills/terravision-cloud-diagrams		skills/terravision-cloud-diagrams
terravision		terravision
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
clearcache.sh		clearcache.sh
docker-entrypoint.sh		docker-entrypoint.sh
flake.lock		flake.lock
flake.nix		flake.nix
gemini-extension.json		gemini-extension.json
gemini-extension.md		gemini-extension.md
mkdocs.yml		mkdocs.yml
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
server.json		server.json
shiftLabel.gvpr		shiftLabel.gvpr

Navigation Menu

Repository files navigation

TerraVision

Get started with your AI assistant

1. Install the prerequisites (once)

2. Connect your assistant

3. Ask for a diagram

Keep diagrams current in CI/CD

Watch a 4-Minute Intro

Why TerraVision?

Supported Cloud Providers

Use it from the command line

Install

Diagram from JSON (no Terraform needed)

Diagram from Terraform

Generate an interactive HTML diagram

Try the Interactive Demos

Advanced Usage Examples

Generate a diagram

Use a pre-generated Terraform plan (no cloud credentials needed)

AI-powered annotations (optional)

Simplified view

Common options

Documentation

FAQ

Contributing

Support

License

Acknowledgments

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

TerraVision

Get started with your AI assistant

1. Install the prerequisites (once)

2. Connect your assistant

3. Ask for a diagram

Keep diagrams current in CI/CD

Watch a 4-Minute Intro

Why TerraVision?

Supported Cloud Providers

Use it from the command line

Install

Diagram from JSON (no Terraform needed)

Diagram from Terraform

Generate an interactive HTML diagram

Try the Interactive Demos

Advanced Usage Examples

Generate a diagram

Use a pre-generated Terraform plan (no cloud credentials needed)

AI-powered annotations (optional)

Simplified view

Common options

Documentation

FAQ

Contributing

Support

License

Acknowledgments

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages