CRAYON-C4 for VS Code

Sketch the system — straight from your code. Generate a CRAYON-C4 architecture model from the workspace, explore it in an interactive C4 viewer inside VS Code, refine it with AI, and hand off to the web app for rich editing — where a non-destructive merge preserves your manual curation across re-runs.

Supported stacks: Next.js · React · .NET · Java (Maven & Gradle).

Commands

• CRAYON-C4: Generate Model — analyze the workspace and write crayon-c4-project.json + provenance + enrichment tasks. Folders and depth come from .crayon/config.json; you are only asked when it cannot answer. Run it again to refresh — re-runs are merge-safe: renames, descriptions, colours, and layout you curated are preserved.
• CRAYON-C4: Open Architecture Viewer — pick a crayon-c4-project*.json from the workspace (or browse for one) and see it in an interactive C4 diagram: drill between levels, select elements, read details. It never generates, always shows the full data, and reloads when the file changes. Also available from the Explorer menu on a .json file and as Open With… → CRAYON-C4 Viewer.
• CRAYON-C4: Edit Project Settings / Improve Project Settings with AI / Validate Model — maintain .crayon/config.json and check a model against the schema.
• CRAYON-C4: Enrich Descriptions with AI — launch your AI agent CLI (default claude) in a terminal, seeded with a prompt that fills the empty description fields from the real source files. You choose which description sub-sections to write (let the AI decide, perspectives such as Security or Physical, a longer Detailed version, or your own). The viewer's Fill with AI button does the same for just the elements on screen, in the file you are viewing.
• CRAYON-C4: Extract Decisions with AI — recovers the architecture decisions the codebase already embodies into the .adr slice: the why is it like this the diagrams cannot show. It transcribes what the repo has already written down (docs/adr, RFCs, design notes) before inferring anything, and marks anything it reconstructed as proposed so nobody mistakes it for a decision a human confirmed.
• Deployment and Flows tabs — when the model carries a deployment model or behavioural flows (the CLI generates both), the architecture viewer gains read-only Deployment and Flows tabs next to Architecture and Decisions: the same viewers as the web app, with the environment and level switchers, the legend, tag filters, process and diagram selection and drill-in. A model without them shows no tab bar change.
• Decisions view (the CRAYON-C4 icon in the activity bar) — find and manage the architecture decisions recorded in the model, at parity with crayon-c4 adr. Decisions are grouped by status (with Needs review on top); Find Decisions… filters by text or status and Show Decisions for Element… answers "what was decided about this?" (including what is inside it and what contains it). New Decision records one linked to the elements it concerns; the row menu changes status, supersedes, links and unlinks elements, renumbers (previewing every mention it will rewrite) and confirms a flagged decision. Opening a decision opens its markdown file in adr/, the natural place to write the prose. The model is the source of truth and adr/ its mirror: edits made in a file are folded back by Import Decisions from adr/ Folder, and a status-bar hint says when the two have drifted — nothing is imported silently. Accepted decisions are records: their content cannot be edited (supersede them), and the viewer's Decisions tab lists them with an Open file action.
• CRAYON-C4: Generate Model with AI — builds the whole model (.c4 + .deployCanvas) by having an AI agent read the repository, with no static extraction at all. For stacks the scanners do not cover. Deployment is grounded in Dockerfiles / compose / K8s / IaC; no .f4 slice is produced; the result must validate against the published schema.
• CRAYON-C4: Open Web App — opens the web import page with the model's path on your clipboard; you pick the file there (nothing is uploaded, and your edits stay protected by the merge).

Per-project settings — .crayon/config.json

Put a .crayon/config.json in the analyzed repo to control generation per project (it travels with the repo — every machine and editor behaves the same):

{
  "schema": 1,
  "prompts": { "append": "Describe everything in payments-domain terms." },
  "projects": {
    "exclude": ["*.Tests", "packages/*"],
    "bundles": [{ "name": "Shared packages", "match": ["Acme.Common*"] }]
  },
  "flows": {
    "entryPoints": [
      { "match": "src/app/api/checkout/**", "name": "Checkout endpoint" },
      { "match": "PaymentController" }
    ]
  }
}

• prompts — project-scoped instructions for every AI pass (the crayonC4.promptAppend user setting is appended after these).
• projects.exclude / projects.bundles — keep clutter projects off the diagrams, or collapse many small projects into one container. The run report always says what was excluded or bundled.
• flows.entryPoints — API endpoints, UI components, or classes that deserve a fully traced F4 flow diagram, at method level (BuyButton → HTTP POST /api/checkout → chargeOrder() → taxFor()), with error boundary events where the code actually catches.

The full reference lives in the crayon-c4 CLI docs on npm — the extension and the CLI share one engine, so the config means the same thing everywhere.

Extension settings

Requirements

• The AI commands need an agent CLI on your PATH (default Claude Code; point crayonC4.agentCommand at Codex, Aider, or any other CLI). Everything else — generate, viewer, send to web — is fully offline and needs nothing.

License

Free to use, for commercial and non-commercial work — see the bundled LICENSE (also shown on this extension's License tab). The source code is proprietary (not open source). The standalone CLI (npx crayon-c4 .) is the same engine; the web app offers a free tier with a subset of its functionality.