Guide

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.
Setup wizard at its Special key step: what the key does and the four keys to pick Setup wizard at its Special key step: what the key does and the four keys to pick
The Setup wizard. Settings → Setup… opens it again.
  • 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. 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/model or architecture/ 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 its architecture/ (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.
Welcome screen: New model and Open, with the three most recent models below Welcome screen: New model and Open, with the three most recent models below
The Welcome screen. The sample is the fastest way to see most of this guide.

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

Designer perspective: views on the left, the element palette above the canvas, canvas controls at its bottom, the canvas over the full width, toolbar on top Designer perspective: views on the left, the element palette above the canvas, canvas controls at its bottom, the canvas over the full width, toolbar on top
Designer with the System Context view of the sample. Activity rail and view list on the left, palette on the canvas, controls at the bottom, properties card on the right when something is selected.
  • 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.
Good to know. Every edit in Designer is one undo step (⌘/Ctrl+Z), views, sequences and metamodel edits included. Viewer and Presentations change nothing in the saved model but the slides.

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.
Models dialog: one list of browser, file and folder models with search, a filter by place and a menu per row Models dialog: one list of browser, file and folder models with search, a filter by place and a menu per row
Models → Manage models… lists every model, the last used first, as the Welcome screen does: not the empty one Studio starts a first visit on, until you use it. Its row menu renames a model, moves it between browser, file and folder, or removes it from the list.

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).

Good to know. In the browser, a file or folder needs access granted again after a reload: click it on the Welcome screen, or Reconnect… on its row. The desktop app launched with 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

A container selected on the canvas; the properties card over the canvas shows its type, name, where it sits, technology, external flag, parent, description and the seven views that show it A container selected on the canvas; the properties card over the canvas shows its type, name, where it sits, technology, external flag, parent, description and the seven views that show it
Properties of a Container. Fields come from the metamodel, so custom types get their own forms.
  • 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 — 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.

  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.
Good to know. The metamodel editor's Validation list warns about an entity that belongs to no aggregate or to two, and a root inside another root.

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.
Good to know. The Validation list checks that a statechart can run: one initial state per machine, nothing leaving a final state, no two unguarded transitions on one event, no unreachable state. These are warnings, because a machine is often incomplete while you build it. Radical Forge derives machines from your scenarios.

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.
The sample's Send a payment process on a canvas: its steps in a frame with dashed arrows from each to the next, Validate running two checks at once, Approve a choice of two alternatives, and the two people who perform steps below The sample's Send a payment process on a canvas: its steps in a frame with dashed arrows from each to the next, Validate running two checks at once, Approve a choice of two alternatives, and the two people who perform steps below
The sample's Send a payment on a canvas: dashed arrows follow the order, Validate runs its checks at once, Approve is a choice. Arrange a process in its Warnier view.

Mockups & screen flows

The Screen Map view of the sample: mockups with low-fi wireframes grouped by journey and linked by labelled navigates-to relations; the properties card shows the selected Review & FX Quote mockup with its wireframe The Screen Map view of the sample: mockups with low-fi wireframes grouped by journey and linked by labelled navigates-to relations; the properties card shows the selected Review & FX Quote mockup with its wireframe
A screen flow: each mockup carries a wireframe, and Navigates to relations are labelled with the action that moves the user on.

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.

Views section open in the left panel listing Structure, Flow, Hierarchy, Matrix, Table and Wiki views of the sample model Views section open in the left panel listing Structure, Flow, Hierarchy, Matrix, Table and Wiki views of the sample model
Every card shows how many elements the view shows and its type. All elements, the whole model as a table, is always first.
  • 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.
View typeWhat it showsBest for
StructureNode-and-link diagram with nestingSystem context, container and component maps
ExploreOne element and what it reaches, level by levelHow one element reaches the rest
FlowNumbered steps of a sequence between participantsRuntime scenarios, “what happens when…”
HierarchyDrillable treemap of containmentPortfolio overviews, size and ownership
TableThe view's elements as a tree, one row each with a summaryRequirement and ADR registers
MatrixDependency structure matrixCoupling, cycles, who depends on whom
WikiOne article per elementReading, reviewing, writing prose
WarnierThe hierarchy in braces, left to rightProcesses, 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.
The list of views with the group Components of a container, view per element, open on a view of each of the sample's eight containers; Payments Service is on the canvas with its two components, the database, queue and systems it is related to The list of views with the group Components of a container, view per element, open on a view of each of the sample's eight containers; Payments Service is on the canvas with its two components, the database, queue and systems it is related to
Components of a container in the sample: one group with a view of each container. Payments Service shows its components and what they are related to.

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.

The Requirements Register's properties: its Filter starts with needs, goes on to the requirements refined from each, then to the scenarios that verify them or the mockups that illustrate them; the table beside shows that tree The Requirements Register's properties: its Filter starts with needs, goes on to the requirements refined from each, then to the scenarios that verify them or the mockups that illustrate them; the table beside shows that tree
The sample's Requirements Register: needs, the requirements refined from each, then the scenarios that verify them or the mockups that illustrate them.
  • 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.

Good to know. Every menu offers first what the model has, then, with a count of 0, what the metamodel allows. So you can build the chain before the elements exist and fill it from the table.

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

An exploration of the bookstore's API saved as the Explore view API context: API on top, Web App, Orders DB and Payment Provider a level below, Web App's + menu open An exploration of the bookstore's API saved as the Explore view API context: API on top, Web App, Orders DB and Payment Provider a level below, Web App's + menu open
An API explored by its relations. Web App's + menu is open on what comes in to it.

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

Flow view: participants across the top, numbered arrows for each step of the Payment Processing sequence Flow view: participants across the top, numbered arrows for each step of the Payment Processing sequence
The Payment Flow view plays the Payment Processing sequence: seven relations from the model, in order, with a note per step.

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

Hierarchy view: nested coloured rectangles for systems, domains and containers with a breadcrumb and size and levels controls Hierarchy view: nested coloured rectangles for systems, domains and containers with a breadcrumb and size and levels controls
Containment as a treemap. Double-click a rectangle to drill in; the breadcrumb takes you back.
  • 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

Table view showing the view's elements as a tree, each row with its type, name and summary Table view showing the view's elements as a tree, each row with its type, name and summary
The Requirements Register: needs, their requirements and the scenarios under those, each with a one-line summary.

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

Dependency structure matrix with elements on rows and columns and coloured cells where relations exist Dependency structure matrix with elements on rows and columns and coloured cells where relations exist
The Dependency Matrix: rows depend on columns. Symmetric pairs reveal cycles at a glance.

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

Wiki view: the article of Payments Service with its type and place under the title, a facts box beside the lead, relations as sentences and its components under a heading Wiki view: the article of Payments Service with its type and place under the title, a facts box beside the lead, relations as sentences and its components under a heading
Every element is an article written from the model. In Designer its text is edited in place.

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.

The sample's Processes view as a Warnier–Orr diagram: Send a payment with its steps in braces, the selected step Quote FX with its actions in its type line and its properties card on the right The sample's Processes view as a Warnier–Orr diagram: Send a payment with its steps in braces, the selected step Quote FX with its actions in its type line and its properties card on the right
The sample's Processes view, Quote FX selected: its actions in its type line, + Step under each brace.

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

KeyWhat it does
EnterAdds an element of the same type after the selected one, its name open to type
Tab / Shift+TabIndents it under the element before it / outdents it
Alt+↑ / Alt+↓Moves it among its siblings
F2Renames it in place
DeleteAsks 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

Milestone v2 active: the canvas shows the model as it was, the chip at the top names the milestone with a diff toggle, and the Milestones list shows Current (live), v4, v3, v2, v1 Milestone v2 active: the canvas shows the model as it was, the chip at the top names the milestone with a diff toggle, and the Milestones list shows Current (live), v4, v3, v2, v1
Time travel: the v2 – Payments & Events milestone of the sample. Current (live) brings you back.

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).
Good to know. Positions belong to the view, not to the milestone, so an element stands in the same place in every milestone and only what changed differs. If you edit while a milestone is shown, Studio asks whether to propagate the change to later milestones, save a new one or discard it.

Viewer & Presentations

Viewer perspective: views list on the left, read-only canvas, model tree on the right Viewer perspective: views list on the left, read-only canvas, model tree on the right
Viewer: everything you can do in Designer to look, nothing that changes the saved model.

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 in the left panel: the Architecture Walkthrough slides one under another, with Present and Add slide above them Presentations in the left panel: the Architecture Walkthrough slides one under another, with Present and Add slide above them
Presentations: build a deck from views, then play 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

Browser folder model with the Customer discussion panel, a question and a nested reply with optional email attribution Browser folder model with the Customer discussion panel, a question and a nested reply with optional email attribution
Discuss a node in a folder model, in the web UI or desktop app; replies and attribution stay beside the model.

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.

Table row context menu offering Discuss for the Customer node Table row context menu offering Discuss for the Customer node
The same node discussions are available from a table row or wiki page.

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

Inspector, Overview tab, on the radical.tools architecture model: a score for consistency, completeness, traceability and decisions and for what the tests verify, and below them what needs attention, a group per rule with its count and baseline Inspector, Overview tab, on the radical.tools architecture model: a score for consistency, completeness, traceability and decisions and for what the tests verify, and below them what needs attention, a group per rule with its count and baseline
Overview on the model of radical.tools itself, which CI checks with 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.json and the repository's .radical/radical.json as they are then, so a test an agent bound meanwhile stays bound.
  • Ratchet lowers each baseline to what the check finds now.
Inspector, Implementation tab: requirements and decisions verified, named tests passing, tests the model names, what falls out from requirement to passing test and from ADR to passing check, coverage by element and what needs attention Inspector, Implementation tab: requirements and decisions verified, named tests passing, tests the model names, what falls out from requirement to passing test and from ADR to passing check, coverage by element and what needs attention
Implementation: what the last test reports say about the model.
Inspector, Measurements tab: the metrics the sensors measured, each measurement with its labels, value, source and age, and under it the fitness functions whose conditions read it, with their outcomes and Path Inspector, Measurements tab: the metrics the sensors measured, each measurement with its labels, value, source and age, and under it the fitness functions whose conditions read it, with their outcomes and Path
The Measurements tab: every value the sensors measured, who reads it and how it fared.

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 tool get_trace returns them.
Inspector, verification path of a need: its requirements, their scenarios and the tests bound to them in columns joined by lines, each with its status Inspector, verification path of a need: its requirements, their scenarios and the tests bound to them in columns joined by lines, each with its status
The verification path of a need, from its requirements to the tests and what they say.
Good to know. The model rules run live as you edit. What the tests say comes from the last 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.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).
  • 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.

MetamodelWhat it holdsPick 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.
C4People, software systems, containers (plus databases, web apps and queues), components and groups, joined by Interacts.The diagram is the whole job.
The Diagram tab of the metamodel editor on the Radical metamodel with Requirement selected: its lines to the types it links to, and beside it where a requirement may sit and every relation going out and coming in The Diagram tab of the metamodel editor on the Radical metamodel with Requirement selected: its lines to the types it links to, and beside it where a requirement may sit and every relation going out and coming in
The Diagram tab of the metamodel editor. Click a type, here Requirement, to see where it may sit and every relation that may go out of it or come in.

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.
Good to know. A change that leaves the model against the metamodel (a parent unticked, an enum option removed), or takes a type's last place (its last allowed parent, or At the root when it has none), asks first and lists what it breaks. Validation warns of a type nothing can be placed as, also while the model holds none. An emptied name, of the metamodel, a type, a relation type or a property, goes back to the one it had. Every type, relation, pair and rule is tabled in the Reference.

Concern Hub

hub.radical.tools: the Authentication concern pack open as a wiki page, with its group Secure by Design and its questions in the Answers panel on the left hub.radical.tools: the Authentication concern pack open as a wiki page, with its group Secure by Design and its questions in the Answers panel on the left
The Authentication pack on hub.radical.tools.

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.

The concern wizard in Studio on the Authentication pack: steps Scope, Sign-in, Other systems, Second factor, Details and Review, with the decision, the requirements, the fitness functions the answers bring The concern wizard in Studio on the Authentication pack: steps Scope, Sign-in, Other systems, Second factor, Details and Review, with the decision, the requirements, the fitness functions the answers bring
The concern wizard: where the decision applies, one question a step, and what the answers bring.
  • 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 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.
Good to know. A pack needs a metamodel with decisions and requirements, such as Radical. A decision that the concern does not apply settles it too, and is asked about no more.

AI assistant

AI providers dialog with a master switch and tabs for Ollama, OpenAI, Anthropic and Google Gemini, each with model, base URL and API key fields and a Test connection button AI providers dialog with a master switch and tabs for Ollama, OpenAI, Anthropic and Google Gemini, each with model, base URL and API key fields and a Test connection button
Settings → AI providers… on the activity rail. Keys stay in this browser and calls go straight to the provider.

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….

Radical Forge's Description step: the description, and under Views the Radical structure chosen with its viewpoints in the folders Conceptual, Logical and Governance, and Layer canvases below Radical Forge's Description step: the description, and under Views the Radical structure chosen with its viewpoints in the folders Conceptual, Logical and Governance, and Layer canvases below
Before a run: the description, and the view structure it will file into.
  • 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.
Radical Forge after its Requirements stage: the stages from Description to Finish on top, the stage's result, its open gaps and the Arrange questions, and the need with the four new requirements in a grid on the Conceptual view behind Radical Forge after its Requirements stage: the stages from Description to Finish on top, the stage's result, its open gaps and the Arrange questions, and the need with the four new requirements in a grid on the Conceptual view behind
After the Requirements stage: the result, the open gaps, and the question how to arrange the new elements.
  • 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.
Radical Forge while its Domain model stage runs: the Domain step marked ✎ in amber, and under the stage's progress the card Add this to earlier stages?, with what the stage found, the requirement it would add with its fields, the requirement it would change with the old and new action, a reply field, and Add it and Don't add Radical Forge while its Domain model stage runs: the Domain step marked ✎ in amber, and under the stage's progress the card Add this to earlier stages?, with what the stage found, the requirement it would add with its fields, the requirement it would change with the old and new action, a reply field, and Add it and Don't add
The Domain model stage found a requirement missing and one to sharpen. It waits for your answer before it writes either.

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.json beside it.
  • Code as you have it. Besides repositories, a folder of code with no .git or a .zip file 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, .zip files 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 with RADICAL_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.json saying 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 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.
Good to know. Ask the agent to call 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
CommandWhat 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 --statusChanges 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 confluenceExports 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 --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, 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-ci it 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 sense keeps beside it, and the files --metrics names (from another CI job).
  • 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; in a repository that judges only its part of a model kept elsewhere it leaves the model's baselines alone, and with --alone or --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 github writes 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 mcp runs the MCP server, as the agents do; it never asks anything.
  • setup run 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 setup moves 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.

Good to know. This repository checks its own architecture model this way on every push. The Inspector shows the result of the same check in Studio.