C4X - C4 Model Diagrams for VS Code

Fast, offline C4 architecture diagrams with real-time preview and AI-powered generation via Google Gemini. Mermaid-inspired DSL, C4-compliant SVG rendering, PNG export, and 1500+ cloud icons.

Features

• Instant Preview -- Sub-50ms rendering for 30-node diagrams, live as you type
• AI Generation (Gemini) -- Code-to-diagram, text-to-diagram, and visual PNG generation
• All C4 Levels -- System Context, Container, Component, Deployment, and Dynamic views
• 6 Themes -- C4 Standard (default), Classic, Modern, Muted, High Contrast, Auto
• Export -- PNG (1x/2x/4x), SVG, Copy SVG with theme preservation
• 1500+ Icons -- AWS, Azure, GCP with IntelliSense autocomplete ($sprite syntax)
• Markdown Integration -- Render c4x blocks directly in README and architecture docs
• Auto-Layout -- Smart direction selection: horizontal for small, vertical for large diagrams
• Self-Correcting AI -- Parser-validated output with automatic retry and self-remediation
• MCP Server -- Built-in validator for Claude, Cursor, and other AI assistants

Watch 30s Demo

Quick Start

Install

VS Code Marketplace (recommended): Search "C4X" in Extensions (Cmd+Shift+X) and install.

Command line: code --install-extension jpantsjoha.c4x

Create a Diagram

1. Create a file architecture.c4x
2. Write your diagram:

%%{ c4: system-context }%%
graph TB

Customer[Customer<br/>Person]
Banking[Banking System<br/>Software System]
Email[Email System<br/>Software System<br/>External]

Customer -->|Uses| Banking
Banking -->|Sends notifications| Email

1. Open preview: Cmd+K V (or Ctrl+K V)

No Java, no servers, no configuration needed.

Embed in Markdown

```c4x
%%{ c4: system-context }%%
graph TB
    User[User<br/>Person]
    System[My System<br/>Software System]
    User -->|Uses| System
```

The extension renders c4x code blocks as visual diagrams in VS Code's Markdown Preview.

DSL Syntax

Elements

%% Bracket syntax
Admin[Administrator<br/>Person]
API[Payment API<br/>Software System<br/>External]

%% Function syntax (supports icons, technology, description)
Container(WebApp, "Web App", "React", $sprite="c4xicons.aws.elastic-beanstalk-application")
ContainerDb(DB, "Database", "PostgreSQL")
Person(User, "End User")

Types: Person, Software System, Container, ContainerDb, Component, ComponentDb, plus *_Ext variants for external elements.

Relationships

A -->|Label| B        %% Standard dependency
A ==>|Label| B        %% Synchronous / blocking
A -.->|Label| B       %% Asynchronous / event-driven

Boundaries

%%{ c4: container }%%
graph TB
    User[User<br/>Person]

    subgraph BankingSystem {
        WebApp[Web App<br/>Container]
        Database[DB<br/>Container]
    }

    User -->|Uses| WebApp
    WebApp ==>|Reads/Writes| Database

View Types

%%{ c4: system-context }%%      %% C1
%%{ c4: container }%%           %% C2
%%{ c4: component }%%           %% C3
%%{ c4: deployment }%%          %% C4
%%{ c4: dynamic }%%             %% Sequence/interaction

Full reference: Syntax Guide

AI Generation (Gemini)

C4X uses Google Gemini to generate diagrams from code, text, or selections.

Setup: Get a free API key from Google AI Studio or use a Google Cloud Vertex AI key for enterprise compliance. Keys are stored in VS Code's encrypted SecretStorage.

Default model: gemini-3-flash-preview (free tier) with automatic fallback to gemini-3.1-pro-preview. Configure any Gemini model via c4x.ai.model in settings.

All AI-generated diagrams are parser-validated with up to 3 self-correction retries.

Full guide: Gemini AI Guide | Visual Diagram Guide

Icons

1500+ built-in cloud and technology icons with IntelliSense autocomplete.

Container(S3, "Storage", "AWS S3", $sprite="c4xicons.aws.simple-storage-service-bucket")
ContainerDb(DB, "Database", "Cloud SQL", $sprite="c4xicons.gcp.cloudsql")

Full icon catalog: Icons & Examples

Export

Exported diagrams preserve your selected theme.

Themes

Change via Command Palette (C4X: Change Theme) or settings ("c4x.theme": "modern").

Examples & Documentation

MCP Server

C4X includes a Model Context Protocol server for AI assistant integration.

{
  "mcpServers": {
    "c4x-validator": {
      "command": "node",
      "args": ["/path/to/c4x-vscode-extension/out/mcp/c4x-mcp-server.js"]
    }
  }
}

Tool: validate_c4x -- validates syntax, returns line/column errors for auto-correction. Resources: c4x://guidelines, c4x://syntax, c4x://examples/*

Works with Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client.

Performance

Tested with 30-node diagrams. 398 unit tests with 94% parser and 98% model coverage.

Roadmap

Shipped: v1.4.0 (May 2026) -- PNG export, auto-layout, 398 tests, C4-compliant renderer, model validation

Next: v1.5.0 "Copilot Chat & Import Bridge" (Q3 2026)

• @c4x VS Code Copilot Chat participant
• Mermaid C4 import bridge
• ELK layout engine for hierarchical boundaries
• Custom local sprites ($sprite="./logo.png")

Full roadmap: docs/ROADMAP.md

Contributing

Contributions welcome via GitHub Issues and pull requests. See CONTRIBUTING.md for guidelines.

More from the Author

• Pine Script (v5) -- Syntax highlighting, snippets, and linting for TradingView's Pine Script

License

MIT -- see LICENSE.

Acknowledgments

• C4 Model by Simon Brown
• Mermaid.js -- DSL syntax inspiration
• Dagre.js -- Graph layout engine

Made with Gemini for architects who value simplicity | Report Issues | Star on GitHub