Radical.Tools, explained
One model of your architecture. Every diagram, table and wiki page is derived from it. This guide shows how to build the model, read it through views, keep its history and check it in CI. Tables of every type, rule, tool and option are in the Reference.
Screenshots follow the theme you pick in the top bar.
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.
On the first start, the Setup wizard comes first, one step per topic. Each choice applies at once, and Skip setup keeps the defaults. Until you finish it or skip it, it opens again at the next start.
- Theme: System (follows the operating system), Light or Dark.
- Special key: the key held to connect, nest, pick several elements and drop without a wizard.
- Canvas: Focus, Smart fit and Wizard on create.
- AI provider: Ollama, OpenAI, Claude or Gemini, with its key, for Radical Forge and the chat.
- New model — pick the metamodel (Radical, or plain C4), its views and where to keep it: this browser, one
.radicalfile, 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. A folder that holds files, or a model it would replace, is written into only after a question; a repository whose model is in its.radical/modelorarchitecture/is refused with a notice that names that model, since a new model in its root would be opened in its place, and nothing is written. Move to a folder… in the Models dialog does the same. - Open — a recent model, a file, a folder, a Structurizr DSL workspace or the sample. A folder opens the model where the command line finds it: the folder itself, its
.radical/model, or itsarchitecture/(the layout before.radical/). An empty folder starts a new model; a folder of other files with no model in it (a repository's code) is refused with a notice, and nothing is written into it. - 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.
From the terminal
To work on the model with a coding agent (Claude Code, Claude Desktop, Codex, Cursor, VS Code), start in an empty folder. One command finds Node.js or downloads it, starts a model and connects your agent to it:
# macOS, Linux
curl -fsSLO https://radical.tools/radical.sh && sh radical.sh setup
# Windows
curl.exe -fsSLO https://radical.tools/radical.cmd && radical.cmd setup
# With Node.js 20.11 or newer, in your repository
npx @radicaltools/cli setup
Then open the same folder in Studio (Models → Open folder…) to watch the agent work. MCP server says what the agent can do, Command line what else the CLI does. The desktop installers for macOS, Windows and Linux are on the latest release.
The workspace
- Top bar — Quick Search in the middle (⌘/Ctrl+P), Undo and Redo before it, Back and Forward with a History after it, and the two perspectives: Designer edits, Viewer explores read-only.
- Activity rail — along the left edge from top to bottom, as in VS Code. At the top the radical.tools mark, Models: the model open, marked LOCAL (in this browser), FILE or FOLDER (on disk), then Manage models… and Import from Hub…. Below it the sections of the left panel: Views and Sequences, under a line Milestones, and under another line Presentations, with the number of slides. At the foot the Inspector, red with the number of errors or green with none, and under a line Settings: theme (System, Light or Dark), Smart fit, line style, Keep smart by default, the special key, wizards on create, the metamodel editor, Inspector settings…, AI (providers, Radical Forge), Export (PNG, SVG, clipboard), Setup…, the first start's wizard again, and About Radical Studio with the version to quote in a bug report.
- 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. A canvas draws up to 1,000 elements, not counting what lies inside a container folded in the view: a view whose filter gives more says how many, with Show as a table and Edit the filter. One of a group's views per element takes its view type and filter from the group's viewpoint, so its notice offers Edit the viewpoint instead: the Metamodel editor opens on that viewpoint, and a view type of Table (or a narrower filter) there applies to every view of the group. Such a view cannot be switched to Explore, and Smart Layout, from Studio or an agent, leaves it alone.
- Properties card — double-click an element, a relation or a row 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: Verification, when there are test results or measurements beside the model (what the Inspector says of the element: its status, the conditions with what was measured, what checks it, the findings about it, and Path), 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
.radicalJSON 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
.mdper 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).
radical --file model.radical reloads whenever the file changes on disk.
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 stays where you drop it when there is room for it there (inside the frame, below its header, clear of what it holds); otherwise 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 › titleper line, whichradical checklooks 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 — a check that the architecture keeps a property, classified as Building Evolutionary Architectures does: the characteristic it protects, its scope (atomic or holistic), when it runs (on a pull request, every night, continually, every 90 days), whether a sensor or a person runs it, what to measure, and its metrics, the conditions it holds to (a test that has to pass, or a measured value and its threshold). 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.
- A Need keeps the stakeholder's text as written.
- A Requirement derives from it: one EARS sentence the system must make true.
- A Scenario verifies the requirement, ready to become a test.
- A State machine, the lifecycle of a domain Entity, shows the states the scenario walks through.
- A Mockup illustrates the requirement or the scenario, and is presented by the web app that renders it.
- A Container satisfies the requirement, implements the state machine and realises the entity whose data it owns.
- 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/Componentsunder 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.
| View type | What it shows | Best for |
|---|---|---|
| Structure | Node-and-link diagram with nesting | System context, container and component maps |
| Explore | One element and what it reaches, level by level | How one element reaches the rest |
| Flow | Numbered steps of a sequence between participants | Runtime scenarios, “what happens when…” |
| Hierarchy | Drillable treemap of containment | Portfolio overviews, size and ownership |
| Table | The view's elements as a tree, one row each with a summary | Requirement and ADR registers |
| Matrix | Dependency structure matrix | Coupling, cycles, who depends on whom |
| Wiki | One article per element | Reading, reviewing, writing prose |
| Warnier | The hierarchy in braces, left to right | Processes, any decomposition read as an outline |
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. A row that would take the exploration past 1,000 elements, what a canvas draws, is greyed out. Esc closes the menu.
- − 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. A click on a sequence's card shows it and makes it the one steps are added to; the gear on the card shows its properties in the left panel, in place of the list, as a view's are: its name and its steps.
- In its properties, reorder the steps 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:
| Key | What it does |
|---|---|
| Enter | Adds an element of the same type after the selected one, its name open to type |
| Tab / Shift+Tab | Indents it under the element before it / outdents it |
| Alt+↑ / Alt+↓ | Moves it among its siblings |
| F2 | Renames it in place |
| Delete | Asks to delete it, as on the canvas |
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: lines long enough for their labels and arrowheads, fewer crossings, fewer lines through or brushing elements, fewer slanted lines and lines against the flow, shorter lines, elements in line with their neighbours and their kind, even rows and columns, no empty room, 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.
Smart Layout arranges the whole view and takes its pins off: a pin marks where you dropped an element, not a place to keep through a new layout. Tidy around on a selected element (or several) moves only it and what it relates to, and leaves everything else where it is, pinned elements and their pins included — for an element you have just added among others that stand well. A container is fitted round its contents only where something in it moved; a pinned container, and one the selection has no relation into, keep their place and size. Elements without relations gather in the margin, a column per type. ⓘ beside the button opens Why this layout? with the moves in order, what each gained, and the reader's cost part by part (crossings, line length, empty room…) before and after. The layout you get is the one that stays: nothing moves it until you do.
Smart Layout runs in the background: the button turns into Stop, the moves are counted above the canvas controls as they are made, and clicking Stop ends the run with the canvas as it was. A large view gets a fixed amount of work (some ten seconds on a view of 300 elements), counted in moves judged rather than in time, so the same view gets the same layout on any machine and from the MCP server's smart_layout; 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.
Keep smart
While you build a view, switch on Keep smart beside Smart Layout (or choose On under Keep smart in the view's properties). After each change to what the view shows — an element or relation added or removed, an element moved into another container, a container opened or folded, an element dropped — Smart Layout tidies the whole view in the background, and the elements glide from where they were to their new places, their lines following. Elements you drag and drop stay pinned where you put them, and the rest is arranged round them; an element you drop from the palette stays where you drop it while the rest is arranged, and a later change may move it. Changes an agent makes through the MCP server count too, as Studio reads them in. The setting is saved with the view (continuousLayout in create_view and update_view), so a view drawn by hand stays as it is while another keeps itself tidy. Settings → Keep smart by default switches it on for every view that has no setting of its own; Default in the view's properties gives a view back to it. In Viewer the switch keeps the view tidy while you look, an agent's changes included, and saves nothing. Undo takes back a change together with the tidying it brought, and nothing is tidied after an undo, a redo or a switch to another view.
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 over the whole view, in either mode, rearranges the canvas and unpins everything on it; Tidy around and Keep smart leave pinned elements where they are and keep their pins.
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. A view nobody has laid out yet opens on All elements' places, with an element that lies outside its container there placed inside it, beside its siblings; Designer then gives the view its first Smart Layout, while Viewer and Presentations show it still, as it opens. The MCP server's smart_layout lays such a view out from the same places, so an agent and Studio get the same layout.
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. Lining them up pushes aside only what they then cover, and fits only the containers round what moved: a pinned element stays where you dropped it (the others come onto its line), and a container the rule has nothing to do with keeps its place and size. Tidy around leaves a row whose members it does not reach as it stands.
- 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.
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 & Presentations
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.
Presentations, on the activity rail under the sections, show the slides in the left panel and the slide you pick on the canvas. They open over Designer or Viewer, which stays lit; the perspective switch keeps them open over the other one, and a section of the rail goes back. You make presentations over Designer; over Viewer you only look through them and play them. Nothing you do to the canvas there is saved; the slides are.
- Pick 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. The new slide goes after the slide shown.
- Each slide is a card as a view is: its number, its name and, in grey, the view and the milestone it shows. Drag a card to another place (a line shows where it lands), or move it with ⌥/Alt+↑ ⌥/Alt+↓.
- The gear on a card shows the slide's properties in the left panel, as a view's are: its name, its view and milestone, its place with Move up and Move down, Update from canvas (what is on screen now), Duplicate, Present from here and Delete slide. The gear beside the list of presentations shows the presentation's: its name, Duplicate, New presentation and Delete presentation.
- 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. Between slides of one view the camera glides from one framing to the next, panning and zooming together; a slide on another view opens straight at its own framing.
Node discussions
In the desktop app or the web UI in Chrome or Edge, open a model kept in a folder, right-click any graph node and choose Discuss. In the browser, grant the folder read/write access; after a reload, use Reconnect in Models if requested. The panel names that node and stays attached to it while you select other nodes. Write a comment to start a thread, or choose Reply on any comment, including a reply. Markdown is supported; long and deeply nested conversations keep readable reply links.
Email is optional and editable on every submission. Leave it empty to appear as Anonymous. An email you include is saved with that comment in the shared discussions.json and remembered on your device for next time. Changing or clearing it leaves earlier comments unchanged. No account or email verification is required.
A speech-bubble icon at a node's top-right corner marks existing discussions. Click it, or focus it and press Enter, to open that node's panel. Its tooltip shows how many threads exist and how many are open. The icon remains when all threads are resolved and updates when the folder changes, even with the panel closed. These controls stay out of diagram exports.
You can also right-click a node row in Table, or a node's Wiki page, heading, navigation entry or reference, and choose Discuss. A table row also supports Shift+F10. These entry points open the same threads and preserve drafts as you switch views. Viewer can discuss while the model stays read-only. Text editors and ordinary web links keep the browser's context menu.
Resolve thread keeps a thread readable; choose Reopen thread before replying again. If a thread changes while you compose, review its refreshed contents and choose Reply again. A failed post keeps your text. After an uncertain write, Studio checks the submitted IDs before offering a manual retry; it never automatically replays the post. If the discussion file is invalid, conflicted, unreadable or unexpectedly missing, restore or repair it and choose Refresh discussions.
Discussions are kept separately in <model-folder>/discussions.json, created by the first successful post and discovered when the folder is reopened. Move or copy the whole folder to carry them with the model. They attach by node ID: renaming or moving a node keeps them, deletion retains them, and restoring the same ID reattaches them. A duplicate with a new ID starts without discussions. Save a new node in the model to retain its attachment. Posting does not save the model or change its undo history, layout or exports.
Tabs on the same Studio origin serialize discussion writes, and current desktop and browser writers coordinate through temporary lock markers beside the file. External editors, Git and other browser profiles or origins do not share browser Web Locks; refresh and recover conflicting changes before posting. A lock left by a crashed writer must only be removed after that app or tab has stopped.
Drafts remain in this app session when you close the panel or discuss another node; recovery after restarting the app or reloading the page is not provided. Browser-storage and single-file models have no discussion file. VS Code, other object targets and Confluence synchronization are future work.
Inspector
radical check on every push.The Inspector shows what radical check says about the live model, also while a milestone is shown. It works as the Views section does: its button on the activity rail, above Settings, lists its tabs in the left panel and shows the tab you pick in place of the view, in Designer, Viewer and Presenter. Pressed again it folds the left panel; Views or any other section, or ⌘/Ctrl+J, takes you back to the view. Every element it names is a link: it shows the element on a view that has it, selected, with its properties card. Chips in its top bar say how old the test results and the measurements are, and the verdict on the right leads to what needs attention.
- Overview, where it opens — a score for each dimension of the model and for what the tests verify, each leading to its tab, and Needs attention: the findings, errors first, one group per rule with its count and baseline. Each finding has Open, and where the fix is one step the action that starts it: Add scenario for a requirement without one, Add fitness function for an accepted ADR without one, Answer the questions… for an unaddressed concern. The Inspector may do what the perspective may: in Designer a fix is one Undo step; Viewer and Presenter change nothing, so there it reads Add scenario in Designer and takes you to Designer. While a milestone is shown the fixes wait, since they edit the live model. This branch narrows the list to the elements the branch changed. The cards say why what is not verified is not: an ADR with no fitness function, one whose fitness function names no check, one whose checks did not run (those measured nightly or continually counted apart) or one failing. Not run, after the rule groups, lists the scenarios and fitness functions nothing ran in the results and measurements here, each with when it runs; those that run on another event are expected not to have run and are marked so.
- Model — 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.
- Measurements — what the sensors measured, by metric: each value with its labels, source and age, and under it the scenarios and fitness functions whose conditions read it, with the condition and its outcome. Path on one of them shows the whole evaluation flow, from the need or ADR down to this value. The filter narrows the list by metric, label, source or element; Not measured, after the metrics, lists the conditions that still wait for a sensor.
- This branch — what the branch changed, see Changes on branch.
Settings → Inspector settings… shows 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. Unsaved changes wait while the dialog is closed.
- Save writes only what you changed, over
check.jsonand the repository's.radical/radical.jsonas they are then, so a test an agent bound meanwhile stays bound. - Ratchet lowers each baseline to what the check finds now.
Verification path
Path, in the Verification of the properties card of a need, requirement, scenario, ADR or fitness function, in Designer or Viewer, opens every path through it in columns: need (a need inside a broader one, Part of, a column after it) → requirement (one derived from another a column further) → scenario → test, or ADR → fitness function → test and metric condition, a fitness function measured for each element its ADR constrains with each such element. Above the element the path keeps only what leads to it, up to the broadest need; below it, everything. A need's status rolls up from its requirements and the needs inside it, and a need whose inner needs have requirements is not one without a requirement. Failing branches come first and their lines are red.
- A test shows its file and title, its outcome, how long it ran and, when it failed, the message from the report. In the desktop app, Open in VS Code opens the file at the test's line.
- A metric condition shows the value measured, the sensor that measured it and how old the measurement is.
- From the properties card Studio opens the Inspector on the path, and Back returns to the view. Until there are test results, measurements or a base beside the model, Path is greyed out, as the Inspector's button is. The path is the live model's: on a milestone, Path is greyed out for an element only the milestone has.
- A click on an element makes the path that element's, Back returns; Show shows it on a view with its card, and Only what does not pass leaves the rest out; an element kept with nothing left under it is no gap unless the whole path has one there. The path is part of the address, so a link opens it.
- Agents get the same paths:
radical check --trace <id>prints them, and the MCP toolget_tracereturns them.
radical check --report, which keeps the results in .state/test-results.json beside the model, or from CI: radical check --from-ci downloads the reports of the nearest commit CI tested, and the git hooks do it after a checkout, a commit or a pull. The Tests chip in the header says which commit and run they come from; what sensors measured comes from radical sense, which keeps it in .state/measurements.json. Until one of them, or a base, is there, the Inspector button is greyed out. Inspector settings can be saved only for a model kept in a folder, since check.json lies beside it. The rules are listed in the Reference.
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.state/base.jsonbyradical diff --save-base, by an agent'sget_changes, or by the git hooksradical hooks installadds (after a checkout, commit or pull). - The Inspector's This branch tab lists every element added, changed and removed, with the fields that changed by their labels, old and new, and for each requirement and ADR what the tests say of it. Its card counts the changes and the new requirements verified. Without a base it gives the commands that save one.
- Show the changes on the canvas, at the top of the tab, marks new and changed elements on every view, draws removed ones as ghosts, counts the changes beside each view in the list, and lists each changed field in the card.
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 | What it holds | Pick it when |
|---|---|---|
| Radical (default) | Everything in C4, plus the domain, needs and EARS requirements, scenarios, state machines, processes, mockups, ADRs and fitness functions: 21 element types and 19 relation types. | The model should explain why the architecture is the way it is, or act as the harness AI-written code is checked against. |
| C4 | People, software systems, containers (plus databases, web apps and queues), components and groups, joined by Interacts. | The diagram is the whole job. |
Metamodel editor
The editor (Settings → Metamodel 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, what a change to the code must pass before it is merged, how an API answers with an error, who approves a change to production. 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 eight groups, one for each standard a company keeps and the people who keep it: Secure by Design, API Guidelines, Architecture, Coding Standards, SDLC Standard, Tech Radar, Compliance, and Operability & Reliability. API Guidelines start from a published guide (Microsoft Azure, Zalando or Google’s AIPs) and keep its other packs consistent with it. Browse them by group, tag or search; open a pack as a wiki page, a diagram or a table. A pack opens on its default answers, with its questions in the Answers panel beside it: pick another answer and the pack shows only what that answer brings into the model, with the elements it added marked NEW on the canvas for a moment, in the same view and on the same wiki page while that element is still in the pack; each option says how many elements it would add or remove, and All shows every variant at once.
- Import — Models → Import from Hub…, or Add to Studio on the Hub. With no model open yet, the Welcome screen names the pack that waits, and its import opens once you open or create the model it goes into. A reload of the Welcome screen keeps the pack waiting; once its import has opened, a reload asks nothing. The dialog lists the groups on its side, each with how many packs match your search; Add to Model opens the pack's wizard. 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. Added in Designer, it is listed in the view open too; added from Viewer, Presenter or the Inspector, only in its own view, which Designer then shows (from the Inspector you stay there), and the wizard offers the elements of the model the pack goes into, Designer's, not those of a milestone Viewer shows.
- The critic — the Inspector and
radical checkknow which concerns a model of this shape has to decide.concern-unaddressedlists each one no accepted decision covers, with Answer the questions…;concern-unboundlists 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 Settings → 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
.featurefiles.
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. Without that request an agent does not start Forge: it keeps the model current as it works, writing the need, the requirements, the decisions, the elements and the scenarios it learns of as it learns of them, before the code. What you answer its questions goes into the need word for word, each requirement's Derives from relation quotes the words it rests on, and before it writes the code it calls review_requirements: each requirement it changed, next to the words it quotes, with every value it states matched to them, so that a detail you gave (a value of 0, an address kept on the order) does not change on its way into the requirements. In a Forge run the agent leaves out the stages a system of its size does not need (a back end needs no mockups) with one call, forge_skip_stage, saying why; the later stages run without them, and Studio's view of the run marks each one skipped with the reason. A run may finish with stages neither run nor skipped: forge_finish and Studio's view of the run both call those not run. A stage begun is completed before the run finishes: while one is open, or a proposed refinement waits for your answer, forge_finish is refused, and a finished run holds back none of the agent's edits. 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. While you type in a field (an element's name in its card), following waits until you leave it, so the card stays open and nothing you type is lost; a value picked in a drop-down or a box ticked does not hold it back.
Radical Assay
Radical Assay finds the model in code that already exists, in one repository or several (experimental). Forge starts from what you mean; Assay starts from what the code states and works towards what it only suggests. It runs through your coding agent over MCP, because Studio in a browser cannot read a repository. The folder the MCP server is bound to is the central model; the code repositories are local directories, already cloned.
- Facts first. Assay reads each repository the same way every time: its units in any of the stacks it knows (npm, Maven, Gradle, Ant, Go, .NET, Python, PHP, Ruby, Elixir, Rust, Perl, VB6, Dockerfiles, and a database's scripts: Sqitch and Supabase projects, a library of SQL) and their references, what its docker-compose, Kubernetes and Aspire files run, its OpenAPI and gRPC services, the addresses its code and configuration name, the databases its connection strings name and the tables its SQL names (with their columns and foreign keys where a schema or an ORM class declares them), the stored routines its SQL scripts create (Oracle's packages and their members, procedures, functions and triggers) and the code's calls of them, the values its statuses take, where its code is entered (routes, a VB6 application's forms and menus, scheduled jobs, message handlers), the tests its reports name, and the tests its database's code declares (utPLSQL suites, pgTAP scripts and test functions), which count as not run until a report names them. Each fact cites its file and line, and goes into the repository's
.radical/assay/facts.json. It then links units across repositories: a dependency on another unit's package is observed, a path another unit's OpenAPI declares is inferred. - A plan, checked. The agent turns the facts into systems, containers, components and their relations, and hands them over as one plan, each item citing the facts it rests on. A plan with anything no fact backs, or anything the metamodel forbids, is refused whole, with every problem named. Nothing of the evidence goes into the model: it is kept in
.radical/assay/run.jsonbeside it. - Code as you have it. Besides repositories, a folder of code with no
.gitor a.zipfile of code is read the same way, and left as it was; only git repositories get a.radical/radical.json. - The running application. Run your web application on this machine, on a test database, and tell the agent its address. The server opens it in a browser and the agent takes the paths a user takes: signing in, the main lists, creating things. Each screen becomes a mockup joined to the next, and a path you accept as a scenario is written as a Playwright test into the repository's
e2e/assay/. It stays on your application's host and never clicks what pays or deletes an account. - Domain, processes and lifecycles. The tables become the entities of a domain per system, joined only where a foreign key says so, and each container that uses a table realises its entity. From the entry points and the code behind them the agent writes the processes, step by step, and from a status's values and the lines that set them the lifecycle of what the system keeps. These are its reading of the code, marked inferred and written directly, for you to review in the model rather than one question at a time.
- Scenarios no test checks. Behaviour the code shows but no test checks is proposed with scenarios drawn from the code. When you accept one and the repository has a test framework (Vitest, Jest, Mocha, JUnit, pytest, xUnit, NUnit, MSTest, utPLSQL, pgTAP), a pending test of it is written into the repository and bound to the scenario: it shows unverified until your team writes its body. A VB6 application gets the scenario only.
- Documentation as a source. Give the agent folders,
.zipfiles or public links of documentation. Each document is kept as text in.radical/assay/sources/, out of git, so every quotation of it can be checked. From them the agent proposes needs, decisions and requirements no test checks; you accept each. A document never makes anything observed: it says what someone meant, not what the code does. A link that asks for a login is refused: export its pages as PDF, HTML or Markdown and give the folder instead. Links to your own machine or network are not fetched unless the server runs withRADICAL_ASSAY_PRIVATE_LINKS=1. - Desktop screens. A VB6 application need not run: each form file states its screen, so its mockups come with a wireframe drawn from the form's controls at their positions, joined where the code opens one form from another.
- Any language. Where Assay reads no units yet (VB6, COBOL, Delphi), the agent reads the code itself and quotes the lines an element rests on. The server checks each quotation is really in those lines, and such an element is inferred, never observed.
- The code repositories are mapped. Each gets a
.radical/radical.jsonsaying which elements of the central model it builds, in which folders, and which central model that is. - Requirements wait for you. From the tests the agent proposes requirements, each with the scenarios that verify it. You accept, change or leave out each one; only an accepted one is written, derived from a need Found in the code, with its tests bound to its scenarios.
Ask your agent for Radical Assay, or in Claude Code run /mcp__radical-folder__assay. Without an agent, radical assay extract <directory>… reads the facts and prints them with the links.
While the agent runs Assay, Studio open on the central model shows an Assay button beside the Forge button. It pulses blue while the agent works and amber while requirements, needs or decisions wait for your answer, and carries the stage the run is at. Click it for the stages from C4 to Scenarios, the repositories read, the plans the server wrote and refused, and the proposals waiting; Follow on the canvas has Studio open the view that shows what the agent just added, waiting while you type in a field. The server tells the stage from what the agent calls, so a stage the agent passes without a plan shows as skipped. Answer the proposals in the agent's chat. The Forge and Assay panels show one at a time: a click on either button shows its panel in place of the other. Studio's own Radical Forge, put aside between two stages, comes back on the stage it was at; while a stage generates, its panel stays.
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, run the guided setup in your repository. It asks for the model folder (an empty one becomes a new model) and the agents to connect, writes the server into each agent's configuration, offers the git hooks for Changes on branch, and checks that the server answers:
npx @radicaltools/cli setup
Everything Radical keeps in the repository goes into one folder at its root, .radical/: the model in .radical/model, the repository's own sensors and Radical Crucible's files beside it. The command line and the agents' server find the model there from any folder of the repository. A repository set up before .radical/ (a model in architecture/, radical.sensors.json and crucible.json at the root) keeps working; setup offers to move it, with git mv so the history follows, and points .mcp.json and the git hooks at the moved model. What Studio and the command line keep beside a model out of git is in its .state/.
No Node.js yet? In a new, empty folder, fetch the launcher and run the same setup through it. It finds Node.js, or asks and downloads it, and the agents you connect start the server through it. In a folder that is not yet a git repository, setup offers to start one:
# macOS, Linux
mkdir my-system && cd my-system
curl -fsSLO https://radical.tools/radical.sh && sh radical.sh setup
# Windows
mkdir my-system && cd my-system
curl.exe -fsSLO https://radical.tools/radical.cmd && radical.cmd setup
Several models. One server serves one folder. To give an agent more models, run setup once per folder, each with a name of its own:
radical setup payments/architecture --name radical-payments
radical setup billing/architecture --name radical-billing
The agent sees each server's tools under its name, so they never collide; a name that says which model it is helps it pick the right one, as does saying it: “in the payments model, add…”. Without --name the second setup finds a server named radical already there and replaces it, asking first in a terminal. Keep to one server per folder: two servers writing one folder get in each other's way, while Studio open on the same folder is fine.
Restart the agents it connected. Later, radical setup --status says what stops an agent from reaching the model: a moved folder, a missing node, a server of another version. The Reference lists where each agent keeps its servers. To register the package by hand instead, use 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 npx. A missing or empty folder becomes a new model; --metamodel c4 picks plain C4. Pin a version (@radicaltools/mcp@0.3.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, keeping what you type meanwhile, 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
.state/selection.json; the agent reads it withget_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_changeslists what changed since the branch leftmain, 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.
get_model_summary first; the server's instructions tell it to as well. New elements show in All elements until a view lists them. Unrelated files in the folder are left as they are, so the agent's changes show up as small git diffs.
Command line
The radical command works on a Markdown model folder: it connects agents, checks the model in CI, lists what changed on a branch and exports it. Run it with npx, which needs Node.js 20.11 or newer, or through the launcher, which does not:
npx @radicaltools/cli <command> # or: npm install -g @radicaltools/cli, then radical <command>
sh radical.sh <command> # radical.cmd <command> on Windows
| Command | What it does |
|---|---|
setup [folder] | Connects your coding agents to the folder, step by step: a new model in an empty folder, the MCP server in each agent's configuration, the git hooks. See MCP server. |
setup --status | Changes nothing: checks Node, the folder, each agent's entry, and that each server answers. |
check [folder] | Checks the model with the Inspector's rules, and the tests and measured values it names, for CI. Below. |
sense <adapter> | Measures with a sensor (a command's exit code, values from a JSON file) for the model's conditions. Below. |
diff [folder] | Lists what changed in the model on this branch; --save-base keeps the base for Changes on branch. |
hooks install [folder] | Adds the git hooks that save that base after a checkout, a commit or a pull, and fetch the test results of CI and the other models in the background. |
federation fetch [folder] | Fetches the models its deps.json names, for Studio and agents to show beside its own. See Federation. |
export confluence | Exports a wiki view as Markdown or HTML, or publishes it to Confluence Cloud. |
assay extract <directory or .zip>… | Reads the facts of code repositories, folders of code or .zip files, for an agent to find their model. See Radical Assay. |
Check in CI
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
--reportit 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, with why each test failed, how long it ran and its line where the report says (Vitest writes the line with--includeTaskLocation). --trace <id>prints every verification path through one element, from its need or ADR to the tests and metric conditions, as the Inspector's Verification path draws it.- With
--from-ciit reads those of CI instead: the reports GitHub Actions kept for the commit checked out, or the nearest one before it that CI tested, downloaded with the GitHub CLI (gh). Test results never go into git: a commit cannot hold the results of its own tests. - It compares the values sensors measured with the conditions in the model: what
radical sensekeeps beside it, and the files--metricsnames (from another CI job). check.jsonin the model folder sets each rule's severity and a baseline, and goals in percent.--ratchetlowers baselines to what the check finds now, never raises them; in a repository that judges only its part of a model kept elsewhere it leaves the model's baselines alone, and with--aloneor--trigger, which leave part of the model out, it lowers none.- Exit status 0 means no errors, 1 errors, 2 the check could not run.
--format githubwrites annotations for GitHub Actions.
Sensors
A fitness function often rests on more than one tool: a load test, a script, a production metric. Each scenario and fitness function says when it passes in its Metrics, one condition per line. A sensor only measures; the condition in the model holds the threshold, so a tool can be swapped without touching the model.
The tests that check a scenario or fitness function are not in the model either: the repository binds them in .radical/radical.json, and it passes when every test bound to it passed and its Metrics hold. A moved test changes that file, not the model, and in a model shared by many repositories each binds its own. radical check warns about a scenario the repository must verify (an element it builds satisfies its requirement) with nothing that checks it.
radical verify "Pays by card" --test "tests/pay.test.ts › pays"
Your agent does the same over MCP (set_verification, each test it binds beside those bound) when it writes a test for a scenario, and the scenario's card in Studio lists its tests with what they did in the last run. A model from before, with test(…) passed lines in its Metrics, still checks: radical setup moves them into the file.
workspaces.exit_code == 0
api.latency.p95{env=staging} <= 300 ms
api.latency.p95{env=staging} <= baseline + 20%
A limit can also be stated against earlier measurements: baseline is the median of the latest seven given with radical check --baseline (a nightly run hands on its last seven nights), so one slow run neither fails it nor moves it. Keep an absolute limit beside it, for a slow drift the median follows.
radical sense runs one adapter and keeps what it measured beside the model, or writes it to a file with --out for the job that runs the check:
radical sense command --name workspaces -- node tools/check-workspaces.mjs
radical sense json k6-summary.json --metric 'api.latency.p95=/metrics/http_req_duration/p(95)@ms' --label env=staging
What to measure belongs to the fitness function: its Measure names a sensor, and its Cadence says when. Which tool runs, with which files and options, is the repository's: a sensor of .radical/sensors/sensors.json names a command, or one of the adapters and its arguments, so the model carries no path of the repository:
{ "sensors": { "studio-scale": { "adapter": "playwright", "args": ["tests/studio/scale.spec.ts", "--cwd", "apps/e2e"] } } }
A workflow then only says when it runs, and runs what the model measures:
radical sense run --trigger nightly --out reports/metrics
radical check --metrics reports/metrics --trigger pull-request
A fitness function added with a sensor radical sense has is run the next night, with no change to the workflow; --trigger keeps the gate from asking for what runs at night. A manual one is a review a person records, kept in git in the repository's .radical/reviews.json:
radical sense review "Security review" --passed --by jane --note "threat model of 2.4"
An adapter for another tool is one module in the radicaltools repository; see radical sense --list for the ones there are. The conditions, adapters and file format are in the Reference.
Federation: one model across many repositories
Each repository keeps the model of what it implements, next to its code, and names the models it depends on in deps.json in the model folder: for each its name, its git repository (an address, or a path relative to the model folder), the model folder in that repository and the ref it is pinned to. A pinned ref is changed in a pull request like code, so everyone sees the same versions. A branch follows its newest commit; latest follows the repository's releases: its newest version tag (v1.10.0 after v1.2.0), or its default branch when it has none, taken at each fetch, which names the version it took (latest → v1.10.0).
{
"name": "payments",
"dependencies": [
{ "name": "orders", "repo": "git@github.com:acme/orders.git", "path": "architecture", "ref": "v2.3.0" }
]
}
radical setup asks for them, offering each repository's newest version tag, and writes deps.json; without a terminal, --depends-on standards=../standards#v1.0.0 names one. radical federation fetch [folder] fetches each dependency at its ref into a cache (one partial clone per repository, so only the model files travel), and the models they depend on in turn, and writes their elements and relations into .state/federation.json in the model folder, out of git, each marked with its origin, orders@abc1234. A model pinned twice comes at the nearest pin: the folder's own deps.json first, then its dependencies'; the command names the pin it left. A model is known by its repository and model folder, whatever name a deps.json gives it: a dependency back to this model is left out as a cycle, and one model that two deps.json files name differently is fetched once. The git hooks of radical hooks install run it in the background after a checkout, a commit, a pull and a rebase.
Open the model folder itself in Studio, or point the MCP server at it. At the left of the top bar a button counts the other models; opened, it lists each with the version pinned and the commit fetched (those fetched through another indented under it), says when they were fetched, warns about one not fetched or fetched at another version than pinned, and opens a model's folder of views when you click it. The other models' elements appear beside its own: drawn with a dashed outline, their card names the model and version and edits nothing, a table row and a wiki page name the model and offer no edit, and every change to them (a rename, a move, a deletion, a child) is refused with a notice that names the model, in Studio and over MCP. Their place on this model's views is free, and so are this model's relations to them. Nothing of theirs is ever written into the folder: the model holds references to their elements (relations by id), never copies. Their views come too, read-only, each model's in a view folder named after it with the folders it has there (orders › Logical › Containers), so two models' views of one name stay apart; those folders are marked as the model's and read-only, so no view of yours goes into them; each view shows what it shows in its own repository, that model's elements and those of the models it depends on, on a canvas and in a table, wiki, Warnier view or matrix alike. A bar above such a view, over none of its controls, says whose it is and offers Copy to this model. Their groups of views per element stay theirs, with the views they have there: none makes a view in your model. Copy to this model makes a view of yours from one: editable, in the folder it has there, under its name, or with the model's name after it when yours has a view of that name (Containers (orders)). A milestone keeps only this model's elements and the commit of each other model fetched when it was made; fetch fetches those versions too, and the milestone shows the other models as they were then (or says how to fetch them). When a fetch changes them, Studio shows them anew and keeps what you have not saved yet, also in a model opened before it had a deps.json (one radical setup adds) and after its deps.json was removed and added again; a model that has a deps.json and nothing fetched says which command fetches them. Changes on branch shows only this model's changes.
With a deps.json, radical check fetches and checks the model with its pinned dependencies: a relation to an element of another model passes, one to an element no model has is an error, and what is wrong in another model is left to that model's own check. A test of this repository bound to another model's scenario (radical verify "Order taken" --test …, a consumer contract test) is this repository's: radical check judges it, a failed or missing one is an error here, and --trace shows that scenario's path, the other model's requirement above a failed one broken, as the check says. It names the dependencies and commits it checked with; CI needs read access to their repositories. --alone checks the folder without them.
A decision of another model holds here too where it constrains this model's elements. A standards model's ADR APIs are described in OpenAPI constrains Payments API in the payments model; its fitness function measures that API, so it is the payments model's to pass. Where the API's code is, and how to read it, the model does not say: each repository says it. .radical/radical.json names the elements it builds and the folders that build them, and .radical/sensors/sensors.json names a sensor with the command that measures it there, run from the repository's root.
// .radical/radical.json
{ "implements": [{ "element": "<id of Payments API>", "name": "Payments API", "paths": ["services/payments-api"] }] }
// .radical/sensors/sensors.json
{ "sensors": { "openapi": { "command": "node .radical/sensors/openapi.mjs" } } }
Every accepted decision of a model this one depends on binds it. radical check reports, as errors, one that constrains none of this model's elements (inherited-adr-unapplied) and an element such a decision constrains that no fitness function checks (inherited-adr-unchecked): a fitness function that implements the decision, this model's or the standards model's, and names its check in its metrics or by the tests .radical/radical.json binds to it. A standard that does not apply is waived, not ignored: add an ADR to this model that says why (No outside providers: the shop takes no payments) and draw Waives from it to the standard. The waiver is accepted like any decision, needs no fitness function, and shows in the model's changes on the branch. A project that cannot go through every standard at once lowers the two rules to warnings in check.json.
The same trail runs from a requirement to what a person said. A Derives from relation from a requirement to a need has a Quote: the words of the need the requirement rests on, copied verbatim, one fragment per line. radical check and the Inspector measure how many requirements quote their need (the goal requirements-quoting-need in check.json; the rule behind it, derives-quote-missing, is off until you give it a severity), and report a quote the need does not hold (an error: made up, or the need changed after the requirement was written), and an answer of a person in a need, a line that starts with A:, that no requirement quotes (a warning; mark one that needs no requirement (no requirement)). It compares the hard values too, numbers, percentages, null, true and false, identifiers in backticks: a value the quote says that the requirement drops (the client said its stock is worth 0, the requirement says null), and a value the requirement says that no quote says, unless its rationale names it as the model's decision. A value the requirement takes from its quote must then be named by a scenario that verifies it, so that what the person said reaches a test. All three are warnings, and review_requirements lists the first two with each requirement.
None of it needs a language model. Words are compared as words, with Markdown and typography aside: at most 10 is not in at most 100, and a single word quotes nothing in particular. Values are compared in their forms: 20 percent is 20%, 15 minutes is 900 seconds, 12.30 € is 1230 cents, twenty-five is 25, 10 years is 120 months, and a value keeps its sign however the minus is written (-18 °C, –18 °C and minus 18 are not 18). A minus that is no sign is read as none: a discount (-10% on every basket is said by a discount of 10%) and a subtraction (the total minus 5 € by subtract 5 €). Values that agree can still say opposite things, so the check also compares their sense (quote-value-differs): the side of a limit (up to 90 against a requirement that refuses 90 or more; cannot exceed 20, doesn't exceed 20 and must not exceed 20 allow up to and with 20, as at most 20 does, while the negation of another verb before it, a guest who can't pay yet keeps at most 20 items, turns nothing round; between 8 and 64 is a range, as from 8 to 64 is), the unit (30 days against 30 minutes, 10 years against 10 days, 5 € against 5 USD), the order of a list (oldest first against newest first) and the rounding. A worked example the person gave (For example, 4 on hand at 4.00 € and 12 received at 6.00 € gives 5.50 €) must be whole in one scenario of the requirements derived from the need (example-not-in-scenario). In a repository whose .radical/radical.json binds tests to a scenario, radical check reads the tests' files and names a value the scenario gives that they do not use (scenario-value-untested): a test that passes without the value it should check. An agent hears of all this as it writes: the MCP server adds to its answer to each change what the change brings in, and a change that only takes some of a finding's values or parts away (one of two wrong values corrected, one of two parts quoted) brings in nothing.
Each paragraph and list item of an answer must be quoted, not only one sentence of it (need-answer-unquoted names the parts no requirement quotes). And the person's words are only added to: radical check compares each need with the model at its git base (the merge base with the default branch), the Inspector with the branch's base, and an answer the need held there and no longer holds word for word is an error (need-answer-changed). When the person changes their mind, the old answer stays, marked (superseded), and the new one follows; a requirement that still quotes the old one is an error.
radical implement "Payments API" --path services/payments-api writes the first file for you, finding the element by its name. The element's card in Studio says where it is built, and for an element the file maps nowhere it shows that command to copy.
A Measure line that names such a sensor (openapi) runs, in radical sense run, once for each element of this model that the fitness function's ADR constrains directly, an ADR of this model or of one it depends on. The command gets one more argument, --context with a JSON object: the fitness function (its id, name, model and properties), the ADR, the element (id, name, type, technology, parent, properties, and its paths from .radical/radical.json: its own, else those of its nearest parent with an entry) and metricsOut, a file it may write radical-metrics/1 measurements to. Its exit code is measured as openapi.exit_code, labelled with the element, so openapi.exit_code == 0 holds for each element apart: radical check and the Inspector name each element it does not hold for, and the fitness function passes when it holds for all.
The launcher
radical.sh (macOS, Linux) and radical.cmd (Windows) run the CLI where Node.js is missing. Download one into the folder from radical.tools/radical.sh or radical.tools/radical.cmd.
- It uses Node.js 20.11 or newer from the
PATH, else one it downloaded before into~/.radical/node. With neither, it asks, then downloads Node.js 24 from nodejs.org and checks it against its published SHA-256 sum. - It runs any command:
sh radical.sh check.sh radical.sh mcpruns the MCP server, as the agents do; it never asks anything. setuprun through it pins its version, and the agents and the git hooks go through it too. Commit it with the model, and the team and every agent use one version.RADICAL_VERSION=latest sh radical.sh setupmoves the project to the latest release.
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.