Radical.Tools, explained

Getting started

Radical.Tools runs in the browser at studio.radical.tools, with no account and nothing uploaded, or as a desktop app. The Welcome screen asks one thing: a new model or an existing one.

• New model — pick the metamodel (Radical, or plain C4), its views and where to keep it: this browser, one .radical file, or a folder of Markdown files. Views of the metamodel (the default) starts the model with All elements as a structure and a view of each of the metamodel's viewpoints in the folders Conceptual, Logical and Governance, a viewpoint that draws one element as a group of views per element; Customise… leaves any out, and Empty starts with none. With an AI provider set up, Create with Radical Forge starts the model from a description instead.
• Open — a recent model, a file, a folder, a Structurizr DSL workspace or the sample.
• Try the sample — the Fintech Banking Platform used in this guide: 283 elements, with a domain model and two state machines, needs, requirements, scenarios, ADRs, eight concern packs from the Hub, mockups, a process, 36 views in four folders, four milestones and a presentation.

Studio opens a model in Viewer, read-only. Switch to Designer in the top bar to edit. A model you have just created opens in Designer.

The workspace

• Top bar — Undo and Redo, Back and Forward with a History, Quick Search in the middle (⌘/Ctrl+P), the Forge button, and the four perspectives: Designer edits, Viewer explores read-only, Presenter plays slide decks, Inspector shows what radical check says. The logo opens About Radical Studio with the version to quote in a bug report.
• Activity rail — along the left edge, as in VS Code. At the top the three sections of the left panel: Views, Milestones, Sequences. At the foot the menus: Models, the metamodel editor, AI, Export (PNG, SVG, clipboard) and Settings (theme, Smart fit, line style, the connect key, wizards on create).
• Left panel — the open section. Views starts with All elements, the whole model as a table, then one card per view, in folders if you made any. Drag its inner edge to widen it.
• Canvas — the palette stands down its left side: drag a type onto the canvas. At the bottom: Fit All, zoom, Focus and Smart Layout. The chip in the top-left names the view, or the milestone you are looking at. Zoomed far out, elements are drawn as coloured blocks with large names so a big model stays readable.
• Properties card — double-click an element, a relation or a row (or pick a sequence) and its card slides over the right side; a click only selects, and an open card then shows what you select, until ✕ or a click on the empty canvas. The head has the type, the name and where it sits; each attribute is a row you edit in place; long texts are Markdown sections. The foot stays in sight: Views lists every view that shows the element (a click opens it there), then the element's Actions, then Delete.

Models & files

A model is a document, kept in one of three places. Every change is autosaved to wherever it lives.

• This browser — browser storage. Export a file to share it.
• A file — one .radical JSON file. In the desktop app and in Chromium browsers every change is saved back to it; other browsers import and download.
• A folder — a Markdown folder: one .md per element, nested directories for containment, JSON sidecars for relations, views and layout. Readable without the app, diff-friendly, and the place where coding agents work through the MCP server. See File formats.

Open… → Structurizr DSL… converts a .dsl workspace into a new C4 model: its elements, groups, relationships and views, with a dynamic view played as a sequence. A notice lists what the import left out (includes, deployment views, custom elements).

Elements & relations

The metamodel decides what may sit where and which pairs a relation may join. Studio refuses what it does not allow, with a message, so the model stays valid.

Add an element

• Drag a type from the palette onto the canvas. Drop it on a container (a system, a domain, a group) to make it a child. On a view with a filter, the types it would not show are greyed out. Hold the special key as you drop to add it without its wizard. In a container it goes to the next cell of a grid of what the container holds: the first centred, the next beside it, then a new row.
• Double-click an empty spot for a new Software System.
• Add a row in a table, write a line on a wiki page, import a pack from the Hub, or ask the AI assistant.

Containment

• Change a parent with the Parent field in the card or Move to… among the actions, or as you connect: hold the special key with an element selected, and every element it may go into reads inside (beside any relation it could take): the places its Parent field lists, never an external element. Its container reads holds. Drag onto one to nest the element there; drop on the empty canvas to take it out to the top, where the metamodel lets it stand there (else it stays, and a notice says where it may go). With several elements selected, the gesture relates each of them to the target, or nests them all, at once, as one step for Undo. In Viewer and Presenter the special key only selects. A plain drag moves an element on the canvas; it does not re-parent it.
• Collapse a container with − in its header. Its relations re-attach to the container, so a context view stays readable while the detail is one click away. Collapsing is per view.
• A Group is a labelled boundary with no meaning of its own, as in Structurizr. It holds only what its place allows.

Connect

• Hold the special key (Alt/⌥ Option by default, Settings → Special key), press on the source, drag to the target, release. Esc cancels.
• With an element selected, holding the key marks every element a relation from it can go to, with the relation's type over it, and dims the rest; on a view with a filter, only where the filter would draw it.
• An element is not connected to what holds it by a structural relation (a container does not use its system): containment already joins them, and moving an element into one it relates to removes such relations. A governance relation says what containment does not, so it may join them and stays on a move: a requirement inside the system that satisfies it, an ADR inside the system it constrains. The metamodel editor marks a relation type as Governance. A state machine's transition to a state that holds its source is allowed too.
• Over each element it can go to, a pill names each way: the relation's type, inside where it may go in. Drop on a pill to make that one; where one way fits, drop anywhere on the element.
• A relation goes by how its type reads from its source, on its line, in menus and in the card: uses, delivers to (to a person, as in Structurizr), partners with. A metamodel can give a pair of types its own reading.
• Select a relation and drag one of its ends onto another element to move it; it keeps its type, and a place where the type does not fit is refused. Hold the special key while you drag to see where the end can go.
• Double-click a relation to edit its label, type and fields in the card.

Visibility per view

An element exists once in the model and appears in as many views as you like. An element created while a view is open joins that view. Hide from view takes it out of the view without touching the model. A view's filter decides the rest.

Properties & wizards

• Every element has a name, a description and a parent. Containers and components add a technology; C4 elements have an External flag. The rest comes from the type: text, number, boolean, enum and reference fields.
• The description and every long text are Markdown, rendered in the wiki and in table summaries.
• A reference field points at other elements (a transition's event, say). Renaming the element never breaks the link.

Wizards

Needs, requirements, scenarios, ADRs, fitness functions and mockups open a wizard when you create them: one field a step, with a prompt, ending with the relations that give the element its meaning. ⌘/Ctrl+Enter creates it from any step; Esc discards it. Wizard in the head of the card reopens it later. Turn the automatic wizard off under Settings → Wizard on create.

Needs, requirements, decisions

The Radical metamodel keeps why the architecture is the way it is, next to the architecture itself.

• Need — raw input in the stakeholder's words, kept verbatim: a brief, a user story, a regulation. Kind says what it is, Source where it came from. A need has no status: being in the model means it was heard.
• Requirement — one thing the system shall do, as an EARS sentence. Pick the pattern (ubiquitous, When…, While…, If…, then…, Where…, complex) and fill the slots, or type the whole sentence and let Studio split it. The subject of the sentence is the element that satisfies the requirement. Each requirement derives from a need.
• Scenario — an acceptance example in Gherkin: Given, When, Then. It verifies a requirement and names the automated tests that run it, one file › title per line, which radical check looks up.
• ADR — a decision record with status, date, context, decision, consequences and alternatives. It constrains the elements it governs and supersedes the decision it replaces.
• Fitness function — an automated check that the architecture keeps a property: category, threshold and tests. It implements an ADR and constrains the elements it guards.

Needs with their requirements read best in a table or wiki whose filter follows Refined into, as the sample's Requirements Register does.

From a need to a test

Read one requirement through the model, from the words someone wrote to the code that keeps it. Every arrow is a relation type with a fixed direction.

1. A Need keeps the stakeholder's text as written.
2. A Requirement derives from it: one EARS sentence the system must make true.
3. A Scenario verifies the requirement, ready to become a test.
4. A State machine, the lifecycle of a domain Entity, shows the states the scenario walks through.
5. A Mockup illustrates the requirement or the scenario, and is presented by the web app that renders it.
6. A Container satisfies the requirement, implements the state machine and realises the entity whose data it owns.
7. An ADR records the decision the requirement led to and constrains the containers it governs. A Fitness function implements the ADR as an automated check.

The Inspector and radical check walk this chain and report where it breaks. Every type and relation is listed in the Reference.

Domain model

The domain model holds what the requirements talk about, in the language of the business (palette group Domain).

• Domain — a bounded context or subdomain. Kind is core, supporting or generic; Vision says what it is for. Domains nest. A Software System placed inside a domain is the bounded context that realises it.
• Entity — a thing with an identity: a reservation, an order. An aggregate root (solid border) is changed as a whole; an entity (dashed) is part of exactly one root. Aggregates refer to each other with References, never as parts.
• Depends on and Partnership between domains draw the context map. The partnership's Pattern names how the two teams' models meet.
• Realises links the system or container that serves a domain, or the element that owns an entity's data.

State machines

A State machine (palette group States) models the lifecycle of one entity as a hierarchical statechart with SCXML semantics. On the canvas it is a frame named after its entity; drop its parts into it.

• State — a rounded box with optional entry, exit and do actions. States in a state make it compound. Kind parallel makes its children regions active at the same time; final ends the machine, drawn as a bullseye.
• Pseudostate — the initial dot (one per machine and per compound state), history (H, H*) and choice (a diamond).
• Event — what happens: a user action, a message, a timer. Events can live in a system or domain, so several machines share them.
• Transition — state → state, with its Event, a Guard, Actions and the events it Raises. The arrow reads PaymentReceived [amount ≥ total] / reserve stock ^OrderPaid.
• Lifecycle of links the machine to its entity; Implements the container that runs it; a scenario verifies the machine, and a While… requirement can point at the state it holds in.

Processes

A Process (palette group Process) is a procedure, workflow or algorithm. It holds Steps, and a step holds steps of its own. A process reads best as a Warnier–Orr diagram: the viewpoint Process (Warnier) draws every process with its steps.

• Order — where a step stands among its siblings. Steps run in this order.
• Repeat — once, optional (0,1), or repeated (1,n) / (0,n), with its Condition: for each order line.
• Children run — in sequence, as a choice (⊕, exactly one of them) or concurrent (+).
• A step is performed by a person, system or container. A process satisfies requirements and scenarios verify it.

Mockups & screen flows

A Mockup (palette group UX) is one screen of the product, with a Screen / route and a Design link to Figma or Penpot. Three relations tie it to the model:

• Illustrates — the requirements, scenarios or states the screen shows.
• Presented by — the web app or container that renders it.
• Navigates to — the next screen, labelled with the trigger (Pay). Chains of these are screen flows; record one as a sequence to replay it.

With AI enabled, Generate wireframe in the card drafts a low-fi wireframe from the model around the screen. It is plain SVG, stripped of scripts and shown as an image, on the canvas and on wiki cards.

Selections & actions

• Click selects one element. A click with the special key adds more (or takes one out); a drag with it on the empty canvas draws a box.
• A selection brings its relations forward: the rest of the canvas dims, and the camera frames what stays. A click on the empty canvas clears it. Focus, at the bottom of the canvas, turns this off while you lay a view out, and back on; the browser remembers it.
• One element's actions are in its card. With several selected, the selection bar over the canvas offers what applies to them all.

• Wrap into… — a new container around the selection. What it wraps stays where it is; the new container fits snugly round it, and the containers it is in grow only as far as needed to hold it. Only what the new container lies on is pushed clear. Other views keep their layout: there the new container goes round the same elements where they stand. Unwrap removes a container and keeps its children.
• Move to… — re-parent the selection.
• Align… — keep the elements in a row, a column or a grid on this canvas (see Layout).
• Hide from view — take them out of this view only.
• Delete — remove from the model, with children. The Delete key asks first: remove from the model, hide from this view, or cancel. On a dashed line drawn to a folded container, it asks about the relations the line stands for, by name.

Views

A view is a saved reading of the model: which elements it shows, how they are laid out, and how it renders them. Nothing in a view changes the model; deleting a view deletes no elements.

• Create with + New view. It offers the metamodel's viewpoints, or a blank view: a table of the whole model, named View 1, with its properties open.
• Properties (the gear on the card): name, folder, viewpoint, View type and Filter. A structure view adds its line style, auto-layout and layout rules; a wiki its depth; a flow view its sequence.
• Folders keep a long list in order: type a path such as C4/Components under Folder. A folder's gear renames it and moves it up or down.
• Per view: positions, camera, collapsed containers and hidden relations. Arrange a container map one way and a context diagram another.

Viewpoints

A viewpoint is a view type with a filter, under a name, for a question asked of the model again and again. The Radical metamodel ships twenty-five in seven groups: C4, Domain, Requirements, Decisions, UX, States and Process. The Reference lists them.

• A view of a viewpoint follows it: change the viewpoint in the metamodel editor and every view of it changes. Its filter is read-only; Detach makes it the view's own.
• Save as viewpoint… in any view's filter keeps that view type and filter in the metamodel under a name.
• Some viewpoints are a view per element: Components of a container, State machine, Process. Pick one and the list gets a group with a view of each such element, named after it. Add a container and its view appears; delete it and its view goes. A group is never a canvas of its own: it opens on its first view. Picked for a view you have, the view becomes the group; when you picked its elements by hand, Studio asks first, as they are no longer listed.

Filter

A view's filter says what it shows, as a chain of levels. Every view type shows exactly what the chain gives, so its count and the view agree.

• Start with — the first level: every element, or the elements of one type.
• Level under — the next level, along a relation in either direction (Refined into → Requirement), along any relation, or the children it contains.
• or — another way to a level's elements: a second type, or a second relation.
• Filter — keep a level's elements by property (EARS type is event-driven), relation (Has no Verified by), place (Inside Billing) or text. Each one shows how many come in and go through; its dot switches it off to try without it. An element that stores no value of a property has its type's default, as its card shows (a step's Repeat is 1).
• Sort — by name, type or a property, within each level.

A table and a wiki show the chain as a tree. A canvas, a matrix and a hierarchy draw its elements and only the relations the chain follows; tick Draw every relation between them for all of them. Every change applies at once and is one undo step; Reset removes the filter.

Structure

The classic diagram. Relations to elements hidden inside a collapsed container are drawn to the container. Set Auto-layout to Hierarchical nested tree for deep containment: the button on the canvas then reads Tree Layout and lays the view out top-down.

Lines are curved or orthogonal, per view or for the whole model (Settings → Lines in this model). Smart Layout scores the lines as the view draws them.

Explore from here

To see what an element touches without building a view, select it and choose Explore in the head of its card. A temporary view opens with that element alone, and its + menu opens at once.

• + on an element's right edge counts the neighbours not shown yet. Its menu lists them by relation, out and in, with the children and the parent last. Pick a row or tick several; what you add goes on the level below, and the whole exploration is laid out again, top-down.
• − takes back what that element's + added.
• Save as view… keeps the exploration as a view of type Explore, with its levels and + buttons still working. × closes it.

An exploration is never saved on its own: a reload drops it. In Viewer it explores the model shown, a milestone's included.

Flow & sequences

A sequence is an ordered list of existing relations. Open Sequences on the activity rail, click + New sequence, then click relations on the canvas to append them as steps.

• Reorder with the arrows, add a note per step, or turn a step with ⇄ to run the other way, as a response. A Flow view draws a response dashed, as UML draws a reply.
• Create Flow view from sequence makes the view in one click. A Flow view is linked to exactly one sequence; its participants are the elements involved, in order of first appearance.
• Sequences are stored with milestones, so the diff on a Flow view shows how a scenario changed over time.

Hierarchy

• Size — by number of descendants, uniform, or by connectivity.
• Levels — how many levels below the focus are drawn, 1 to 4 or all.
• Drill — a double-click focuses a subtree; Esc or Backspace goes up. Focus, size and levels are remembered per view.

Table

A table lists what the filter gives, as a tree. Each row has the element's type, its name and a one-line summary its type's template makes of its data: a requirement's obligation first, a scenario's outcome, an ADR's status and decision. Hover for the whole text.

• A click on a row selects the element, a double-click opens its card; F2 or Enter renames it in place.
• Elements are added where they will show: a + row after the rows under each element (+ Requirement · refined into) and one at the end for the top level. The new element is linked the way the level hangs under its parent, and gets the values the level's filters ask for.
• Where there is a choice, the + row opens Add or link: a sentence says what goes there (Account is realised by a software system ▾), the field names a new element and searches the model, New adds one by that name and Existing lists the elements the model has that may be linked there instead; picking one adds only the relation. Existing lists only what the model accepts linked that way (not what holds the element by a structural relation, no aggregate root as part of another), and follows edits made meanwhile, by an agent or another program.
• A table of hundreds of rows opens at once: only the rows in sight are drawn.

Matrix

A filled cell means at least one relation from the row element to the column element. Click it to select the relation. In Designer, click an empty cell to add one, and click a selected cell again to remove it. Rows and columns follow containment, and relations of hidden children count for their container. With a filter chain, the matrix draws only the relations the chain follows.

Wiki

A wiki page reads as an encyclopedia article. The type and place stand under the title, the short facts in a box beside the lead, long fields as sections. Relations are sentences: “Uses Event Bus and Transactions DB. Used by API Gateway. Constrained by ADR-001.”

• Pages follow the view's filter: a need's page has its requirements as children, each with its scenarios. Without a chain they follow containment. Elements are grouped by type under headings with their count.
• Single page names the children and links to their pages. Multi page writes them as chapters of one article, as deep as the view's Depth says.
• Overview is the page about the whole view; Glossary says what each type and relation means, from the metamodel. The search on the left looks through names and text.

Writing the model on a page

• Every text is edited in place. [edit] beside a title, or a right click, offers Add or link…, Edit facts and Delete.
• Each group of elements ends with an empty line: type in it and press Enter, and the next element is there. A requirement is written as its sentence and split into its EARS fields; [rewrite] opens it as text again.
• A page offers what the view's filter shows under its element, linked the way that level hangs under it: a requirement's page in the Specification wiki writes its scenarios and mockups. The Overview offers the first level's types; one its filter shows only once it is named or linked (a text or relation filter) is offered all the same, with the filter won't show it, as the table's + row says.
• Paste a list and the page shows what its lines will become before it adds them, as one undo step.
• Add or link… opens the same panel as the table's + row: a new child or one the model has, linked; its list also holds the element's other relationships (uses…, is constrained by…), each with the elements it may name. Only what the metamodel allows, and the view's filter shows, is offered.
• The empty line under a heading suggests the elements of its type whose name holds what is written: pick one to link it instead of writing a new one.

Warnier

A Warnier view draws the view as a Warnier–Orr diagram: each element on the left of a brace that holds what is under it, read left to right like an outline. Any view can be switched to it: a system with its containers, needs with their requirements, a process with its steps. Steps show their repetition and condition, ⊕ stands between alternatives and + between parts that run at once.

In Designer the diagram is written where it is drawn, as an outline:

The selected card shows its actions in its type line: repetition, move, indent, outdent, delete. A click on a brace, or on its ⊕ or +, changes how the steps in it run.

Layout

Smart Layout

Smart Layout tidies the canvas the way you would: it starts from what is there and improves it one move at a time — a database pulled out beside its service, a person put above what it uses, an outside system moved below or to the right of what calls it, a queue set between its producer and consumer, two neighbours swapped, an element slid until its line runs straight, a row put in the order of what it relates to, an element centred over what it relates to or set midway between its neighbours, the rest drawn in — and stops when no move helps. Each move is kept only when the diagram reads better: fewer crossings, fewer lines through or brushing elements, fewer slanted lines and lines against the flow, shorter lines, even rows and columns, room for labels. Lines are judged as the canvas draws them, from their ports.

It knows what it lays out. Each element type has a layout role in the metamodel (actor, store, note, start, end, broker, screen) and each relation type a reading direction (forward, reverse or side, along a vertical, horizontal or free axis): a statechart's initial state goes on top and its final state at the bottom, a need above the requirements derived from it, an aggregate root above its parts, screens in a row. The built-in types come set; Metamodel → Layout role and Reads set them for your own types.

What you pinned stays where you put it, and the rest is tidied around it: correct a layout by hand, pin it by dropping it, and run Smart Layout again. Tidy around on a selected element (or several) moves only it and what it relates to — for an element you have just added among others that stand well. Elements without relations gather in the margin, a column per type. ⓘ beside the button opens Why this layout? with the moves in order and what each gained. The layout you get is the one that stays: nothing moves it until you do.

Smart Layout runs in the background: the button counts the moves as they are made, and clicking it again stops the run with the canvas as it was. A large view gets ten seconds; what was done by then is applied, and another run continues — never a layout worse than the one it started from. A view of more than about 120 elements, or one whose elements lie on each other, is sketched first (people on top, outside systems at the edge, containers as blocks with their contents in layers) and tidied from the sketch. On a view drawn with orthogonal lines, Smart Layout judges crossings, covered elements and bends along the route the canvas draws.

A view's Auto-layout can be set to Ensemble instead: eleven algorithms (layered layouts in several directions, stress, force-directed and tree), the two best refined by simulated annealing, each scored on crossings, relations through elements, edge lengths, compactness and room for labels, and the best one wins. Why this layout? then lists every algorithm tried and its score.

Dragging and pins

• A drag moves only what you drag. The containers it is in stay where they are and grow only as far as needed to hold it. On the drop, what it now covers is pushed just clear; the rest of the diagram stays. A drop leaves nothing overlapping.
• A dropped element is pinned: the live physics leaves it there. Select it to see the pin; click the pin to unpin. A view's pins are listed in its properties, with Unpin all.
• Hold ⌘/Ctrl as you start a drag to let the physics nudge neighbours out of the way while you drag.
• Smart Layout leaves pinned elements where they are and tidies the rest around them; the Ensemble mode rearranges the whole canvas and unpins everything on it.

Live physics

A light force simulation keeps containers hugging their children. It runs after an edit and comes to rest by itself within a few seconds. A container that opens pushes its neighbours aside just enough; one that collapses shrinks where it stands. A diagram you open or lay out is left exactly as it is.

Alignments

• Select two or more elements and choose Align… → Keep in a row, Keep in a column or Keep in a grid. The rule belongs to the view, and every later layout keeps it: drag one member and the others follow; Smart Layout picks its best arrangement with the alignment applied.
• Keep their order also keeps the order you selected them in. Dashed guides show each alignment; select a member for the buttons that switch order-keeping or remove it.
• Select a single container for Align children…, which does the same for what is inside it.

Fit

Fit All frames the visible elements. Smart Fit (Settings) keeps the camera fitted as the diagram changes, zoomed in no further than 100 %; an element added where everything stays in sight leaves the camera where it is. Scroll to zoom, drag the background to pan.

Search & navigation

• Quick Search is in the middle of the top bar on every view. Results are ranked across names, types, descriptions and technology. Enter selects the element on the view you are in, or on a view that shows it; Shift+Enter picks it in All elements. With an AI provider configured, ✨ turns the box into the assistant.
• Back and Forward (‹ › beside the search, Alt+← / Alt+→) walk the places you have been: views, perspectives, selected elements. The clock lists them.
• From the card: the Views list at its foot opens any view that shows the element, with it selected and in sight.
• Deep links: the URL always names the place on screen, so any view, element, milestone or slide can be bookmarked or shared. See Deep links.

Milestones

A milestone is a named snapshot of the whole model: elements, relations and sequences. Keep an As-is and a Target 2027, or show how the architecture grew.

• Capture. + New milestone in the left panel, name it, Enter. It always saves the live model.
• Travel. Click a milestone to see the model as it was. Every view still works, and shows what the milestone holds, also elements deleted since; the chip at the top names the milestone.
• Diff. The toggle on the chip colours what changed since the previous milestone. Removed elements are drawn as ghosts.
• Present. A slide can be pinned to a milestone, so a presentation tells the story in order.
• Restore or delete. Both in the milestone's properties (the gear on its card).

Viewer & Presenter

Viewer is a sandbox. Drag, collapse, re-layout, switch views and milestones, explore from an element: all of it is thrown away when you return to Designer. Studio opens every model in Viewer, and the Hub shows its packs in it.

Presenter adds the slide dock along the bottom.

• Pick or create a presentation, then Add slide to capture what is on screen: the view, the camera, the collapse state, the wiki page or drill level, and the milestone shown.
• Double-click a slide's name to rename it; Capture takes what is on screen now; link a slide to another view or milestone from its card.
• Click a slide's card to show it: its milestone becomes the one shown, and a slide of the live model (or of its own copy) shows no milestone. The chip, the URL and the Milestones list name what the canvas draws.
• Present (or F5) fills the window. → Space advance, ← goes back, Esc exits. The URL follows the slide, so a listener can open the same one.

Inspector

The Inspector shows what radical check says about the model. Every element it names is a link: open its findings, then Show on canvas or Open wiki page. Its button in the top bar counts the errors and warnings.

• Model quality — how good the model is on its own, in four dimensions: Consistency (it follows its metamodel), Completeness (every requirement a whole sentence, every accepted ADR its context and consequences), Traceability (needs → requirements → what satisfies them → scenarios → tests) and Decisions (accepted ADRs with a fitness function). Below them the traceability chain, the gaps by group and every finding.
• Implementation — how faithfully the code follows the model, by what the tests say: requirements and ADRs verified, named tests passing, and the tests the model names among those it should. A note says how old the test results are.
• Settings — the folder's check.json as a form: a goal in percent per metric, a severity and a baseline per rule. The bar above says which unsaved changes loosen the CI gate. Ratchet lowers each baseline to what the check finds now.

Changes on branch

When the model folder lives in a git repository, Studio can show what the branch changed in the model, without git on your side.

• A base, the model where the branch left main, is saved to .radical/base.json by radical diff --save-base, by an agent's get_changes, or by the git hooks radical hooks install adds (after a checkout, commit or pull).
• With a base beside the model, the Changes on branch button in the top bar counts the changed elements and relations. Turned on, it marks new and changed elements on every view, draws removed ones as ghosts, and lists each changed field in the card.
• The Inspector opens on a Changes tab listing everything added, changed and removed, and starts its Implementation tab with This change: each requirement and ADR changed since the base, with what the tests say of it.

Moving elements and editing views are not changes to implement, so they are left out. A Radical Forge run on a folder outside git saves the model before it as the base, so the run's whole output shows as changes. Details are in the Reference.

Metamodel

The metamodel is the rulebook of the model: which element types exist, what each may sit inside, which relations join which types, and which fields each has. It travels with the model, so whoever opens it gets the same rules. The palette, the drop targets, the connection menu, the properties card, the wizards, the AI and the MCP server all consult it.

Metamodel editor

The editor on the activity rail changes the model's metamodel. The first change makes a copy, Radical (custom), so the built-in rules are never edited in place. An unedited built-in metamodel is updated each time the model opens, so models get new types as Studio ships them.

• Node types — colours, description, size, min and max instances, allowed parents, and properties: text, long text, number, boolean, enum or reference. Summary in tables is the template the table makes an element's one-line summary from.
• Relation types — the allowed pairs of source and target, their own properties, and how the relation reads in a sentence from each end (Constrains / Constrained by), which the wiki uses.
• Viewpoints — name, group, view type, description and View per element. The filter itself is set in a view and saved with Save as viewpoint…. A viewpoint deleted leaves its views with their view type and filter; deleting one whose views are a group, or taking away what it draws a view per element of, deletes the group's views per element, so it asks first and lists them. Undo brings them back.
• Validation — everything the model breaks now, each with Open in Designer. Built-in types can be extended but not deleted.

Concern Hub

The Hub holds concern packs. Each settles one concern every system of a certain shape has to decide: who is calling, how long personal data is kept, what happens when a partner system is down. A pack asks a few questions; the answers pick what comes into the model: the need, the requirements with a scenario each, the decision as an ADR, and the fitness functions that check it, all linked. Only the tests are left to you to name.

Packs come in nine groups by where the decision is made: Architecture, Identity & access, Security, Data, Integration, Reliability, Operations, Maintainability and Technology. Browse them by group, tag or search; open a pack as a wiki page, a diagram or a table.

• Import — Models → Import from Hub…, or Add to Studio on the Hub. The wizard asks first where the decision applies, then one question a step, the details and a review. The decision and its checks constrain the elements you chose; one Undo takes it all back. Each pack brings a view of its own in the Concerns folder.
• The critic — the Inspector and radical check know which concerns a model of this shape has to decide. concern-unaddressed lists each one no accepted decision covers, with Answer the questions…; concern-unbound lists a decision that constrains nothing yet.
• In Forge and over MCP — Radical Forge asks the questions of the packs your description calls for and binds them in its C4 stage; an agent sees the open concerns in get_issues.

AI assistant

Bring your own model: Ollama (local, no key), OpenAI, Anthropic Claude or Google Gemini. Enable AI, pick the provider, paste a key, Test connection. Nothing is proxied through radical.tools.

Then open Quick Search and switch to ✨ AI mode (Tab on an empty box). The assistant sees the model and its metamodel and can:

• Answer questions — “what depends on the Event Bus?”. It queries the model rather than guessing.
• Change the model — “add a Redis cache between the API gateway and the accounts service”. It uses the same tools as the MCP server; every change is checked against the metamodel and undone like any edit.
• Draft governance — turn a paragraph into EARS requirements linked to their need, or into an ADR with its fields filled.

Radical Forge

Radical Forge turns a plain-language description into a model, one reviewable stage at a time: Requirements → Domain model → Fitness functions → Scenarios → State machines → Processes → Mockups → C4 model → Review. Start it with Create with Radical Forge on the Welcome screen, or AI → Radical Forge….

• The description becomes a Need. Every requirement the run writes derives from it. Start from loads an existing need instead.
• Views first. Under Views you choose where the run files its output: the Radical structure (a view of each viewpoint, in the folders Conceptual, Logical and Governance) or Layer canvases (one canvas per stage). The structure is fixed once the run starts.
• Concerns, settled early. The Requirements stage picks the Hub packs your description calls for. What the description already settles, Forge answers itself and shows for you to accept; the rest it asks. Each pack comes in whole, and later stages are told the concern is decided.
• Each stage asks first. A stage may ask a few clarifying questions, and can be regenerated before you continue.

• Each stage refines the whole model. A stage looks at the model from a new side and finds what the stages before it missed: a step no requirement asks for, a timeout no scenario covers. It pauses on Add this to earlier stages? with exactly what it would write. Add it writes it; Don't add writes nothing; a reply steers it. A stage never writes to earlier stages without asking, and never deletes.
• Open gaps under each result list what the completeness rules still find; the next stage gets the list.
• Arrange after each stage. Keep the new elements in a row, a column or a grid, and run Smart Layout, or leave them.
• Review comes last: it reads the whole model against your description and makes the parts agree. Finish here ends the run at any stage and exports the scenarios as .feature files.

From your own agent

The same run, with the same stages and questions, works in Claude Code, Claude Desktop or any other MCP client, with the agent's model instead of a key in Studio. Ask the agent for Radical Forge; it first asks which language to talk in and which to model in. While it runs on the folder Studio has open, the Forge button pulses, blue while a stage generates and amber while it waits for you, and Follow on the canvas has Studio open the view that shows what the agent just added.

MCP server

The MCP server lets a coding agent work on your model directly: Claude Code, Claude Desktop, Codex or any client that speaks the Model Context Protocol. It runs locally, bound to one Markdown folder, with the same tools as the AI assistant. The agent reads the architecture, ADRs and requirements before it writes code, and updates the model when the design changes. Nothing leaves your machine except what the agent sends to its own provider.

Set it up

With Node.js 20.11 or newer, register the published package with your client, using absolute paths:

# Claude Code
claude mcp add radical-folder -- npx -y @radicaltools/mcp --folder /path/to/my-model

# Codex
codex mcp add radical-folder -- npx -y @radicaltools/mcp --folder /path/to/my-model

Claude Desktop takes the same command under mcpServers in its config file, with the full path to node. A missing or empty folder becomes a new model; --metamodel c4 picks plain C4. Pin a version (@radicaltools/mcp@0.2.0) and keep it at the version of your Studio. The Reference has the Desktop config and every tool.

Working alongside Studio

• Open the same folder in Studio. It reloads when the agent writes, marks new and changed elements for a few seconds, and draws removed ones as ghosts, so you can follow the agent.
• Studio writes what you select to .radical/selection.json; the agent reads it with get_selection. Say “fix the selected mockup” instead of naming it.
• You can keep editing while the agent writes. Changes are merged element by element and field by field; where both changed one value, a notice says which was kept. Your Undo takes back only your own steps.
• A change can start in the model: add a requirement in Studio, then ask the agent to implement it. get_changes lists what changed since the branch left main, with the elements and tests each change relates to.

What the agent can do

• Read — the model summary with the metamodel rules, a query language over elements and relations, the issues, the selection, the changes on branch.
• Write — elements, relations, views, sequences, slides, milestones, alignments, Smart Layout and the metamodel. Writes are validated like Studio's: an invalid parent or pair is refused with a message the agent can act on; warnings come back with the result.
• Run Radical Forge — the whole run, stage by stage, with the Hub's concern packs.

Command line

radical check checks a Markdown folder with the rules the Inspector runs, so CI can fail when the model is broken or a test it names fails. It reads the files and never changes the model.

npx -y @radicaltools/cli check path/to/my-model --report reports

• It checks the folder (files that read, ids, references), the metamodel (the Validation list) and completeness (requirements without a scenario, ADRs without a check, open concerns).
• With --report it reads test reports (Vitest, Jest, Playwright, JUnit) and looks up the tests that scenarios and fitness functions name. The results are kept beside the model for the Inspector.
• check.json in the model folder sets each rule's severity and a baseline, and goals in percent. --ratchet lowers baselines to what the check finds now, never raises them.
• Exit status 0 means no errors, 1 errors, 2 the check could not run. --format github writes annotations for GitHub Actions.

radical diff prints the changes on branch and saves the base; radical hooks install adds the git hooks that keep it fresh. Every option is in the Reference. The commands that test the product itself (radical fuzz, harden and explore) are documented for contributors in docs/CRUCIBLE.md.