The VS Code extension
The CRAYON-C4 extension for VS Code brings the document-from-code workflow into your editor: generate a model from the workspace, explore it in the full interactive viewer beside your code, fill descriptions with AI, and hand the result to the web app when you want to curate or share it. It bundles the exact same extraction engine and viewer as the web app and the crayon-c4 CLI — one engine, three surfaces.
It supports the same stacks as the CLI: Next.js, React, .NET, and Java (Maven & Gradle).
Install
The extension ships as a VSIX package (it is in preview). In VS Code, open the Extensions view, choose ⋯ → Install from VSIX…, and pick crayon-c4-vscode-<version>.vsix. It requires VS Code 1.85 or newer.
Generate, the viewer, and Send to Web App are fully offline. Only the three AI commands need anything extra: an agent CLI on your PATH (default: Claude Code as claude; point the crayonC4.agentCommand setting at another CLI if you prefer).
Commands
All commands live in the command palette under the CRAYON-C4: prefix.
| Command | What it does |
|---|---|
| Generate Model | Detects the projects in your workspace, lets you pick one or more (plus an Other folder… browse entry), asks for a model depth (System Context / Container / Component / Code), and writes each project's model files into that project's own folder. |
| Open Architecture Viewer | Opens the interactive C4 viewer in a panel beside your editor — the same viewer as the web app, with layers, drill-down, and the detail side panel. Generates a model first if none exists. |
| Regenerate | Re-runs the generator for a project and refreshes the viewer. Re-runs merge in place: your on-disk curation is preserved, never overwritten. |
| Enrich with AI | Reads the open enrichment tasks (elements with empty descriptions) and launches your agent CLI in a terminal with a prompt that fills them. You approve the agent's edits in the terminal, then re-open the viewer. |
| Model Flows & Deployment with AI | An opt-in AI pass that models behavioral flows (F4) and deployment topology. It is separate from Enrich on purpose — the default enrichment never touches the structural slices of your model. |
| Send to Web App | Generates a model if needed, then opens the web app's import page in your browser. Choose From code (new project) or Update from code (existing project) there and pick the generated files — your manual edits are preserved by the merge. |
The viewer's title bar adds two buttons of its own: Regenerate (re-runs the project the viewer is showing) and Fill with AI (enriches only the elements currently visible on screen that still have empty descriptions).
The generated files
Generate writes three files into each selected project's folder — the same files as npx crayon-c4 .:
crayon-c4-project.json— the model, validated against the published schemacrayon-c4-provenance.json— the sidecar that makes re-runs and merges rename-safecrayon-c4-enrichment.json— the open AI-enrichment task list
Settings
Under Settings → Extensions → CRAYON-C4:
| Setting | Default | Purpose |
|---|---|---|
crayonC4.modelDepth | component | Default depth for generated models. component keeps diagrams readable; code goes down to individual classes. Generate Model still lets you pick per run. |
crayonC4.agentCommand | claude | The CLI launched for the AI passes. The prompt is passed as a single shell-quoted argument (use a {prompt} placeholder to control where it lands, e.g. aider --message {prompt}). |
crayonC4.promptAppend | empty | Extra user-level instructions appended to every AI prompt. Project-specific conventions belong in the repo's own .crayon/config.json instead, so they travel with the project — this setting is appended after those. |
crayonC4.webAppUrl | https://crayon-c4.com/projects | The web app import page opened by Send to Web App (change it for self-hosting). |
Per-repository configuration — prompts, project exclude/bundle shaping, traced F4 flows — lives in the repo's .crayon/config.json, which the extension and the CLI read identically. See Document from code for the config reference.
Multiple projects in one workspace
The extension scans all open workspace folders and detects every supported project in them. Generate Model is multi-select, and each project's model files land in its own folder, so several apps in one workspace never collide. The other commands ask which project to act on — and skip the question when there's only one candidate.
Where next
- Document from code — the CLI, the
.crayon/config.jsonreference, and the update-and-merge loop in the web app. - Manage projects — bring a generated model into the web app as a new project.
- The three views of a system — what the generated C4, deployment, and F4 slices mean.