Build your SysML v2 model together with your AI agent. SysMLv2 Modeler is a Visual Studio Code (VS Code) extension for MBSE that lets you and your AI agent work on the same model, in text and on diagrams.

This guide uses the included sample, a small delivery robot, to walk you through the basics in three steps: exploring the model, connecting your AI agent, and editing with AI and by hand. The sample contains nine diagrams that cover all eight standard SysML v2 view kinds.

Contents

• 1. Installation
• 2. Exploring a model
• 3. Connecting your AI agent
• 4. Editing a model
• 5. Good to know
• Troubleshooting
• Contact, feedback, requests and bug reports

1. Installation

System requirements

Before installing, make sure your computer runs on one of the supported platforms.

Install VS Code

If you don’t have VS Code yet, follow the instructions in Download and install Visual Studio Code.

Install SysMLv2 Modeler

1. Start VS Code and open the Extensions view from the Activity Bar on the left (the four-squares icon, ⌘/Ctrl+Shift+X).
2. Click … at the top right of the Extensions view → Install from VSIX…, and select the .vsix file you received.

3. The first time, you are asked to accept the license agreement. Review it, accept, and reload the window when prompted.
4. When the SysML v2 icon appears in the Activity Bar, you’re done.

Open the sample model

1. Copy the entire sample folder included with this guide to a working folder.
2. In VS Code, choose File → Open Folder… and select the copied sample folder.
3. When VS Code asks “Do you trust the authors of the files in this folder?”, choose Yes, I trust the authors. The extension doesn’t run in Restricted Mode, which VS Code uses for folders you don’t trust.
4. Click the SysML v2 icon in the Activity Bar. The sample appears in the Model Tree. The first time, this may take up to a minute while the standard library loads.

2. Exploring a model

You can explore the same model in three ways: as text, in the Model Tree, and on diagrams.

As text

Open MiniRobot.sysml from the Explorer or the Model Tree to see the model as SysML v2 text.

Use these commands to navigate the text.

In the Model Tree

The Model Tree shows the model in the open folder, organized by ownership. Double-click an element to open it in the text editor, or right-click it and choose Open Diagram to see it on a diagram.

On diagrams

There are two ways to open a diagram.

A. From a view declaration (a saved diagram)

The MiniRobotViews package at the end of the sample contains view declarations such as view structure : InterconnectionView { expose …; }. A view declaration saves what the diagram shows, so it opens with the same contents every time. To save the layout as well, switch to manual layout (see Saving diagrams).

To open one, click Open Diagram above the declaration in the editor.

Or double-click the view in the Model Tree. You can also right-click the view and choose Open Diagram.

B. From a model element (a temporary diagram)

Place the cursor on an element in the text (for example, part def DeliveryRobot) and press ⌘/Ctrl+Shift+V. Or right-click the element in the Model Tree and choose Open Diagram.

A list appears at the top of the window, in two groups:

• Existing diagrams (upper group): saved diagrams that already show the element, such as the ones in A. Choose one to open it.
• Create a new diagram (lower group): diagram kinds, such as InterconnectionView and StateTransitionView. Only the kinds that suit the element are listed. Choose one, and a diagram centered on that element opens right away.

This new diagram isn’t saved yet. If you close it without saving, it’s discarded. To keep it, right-click its background and choose Save This Diagram to .sysml (Add View Declaration).
The diagram is saved as a view declaration. (This menu item doesn’t appear on diagrams that are already saved.)

From a diagram back to the text

Press F12 in a diagram to go back to the text. If an element is selected, you jump to its declaration. If nothing is selected, you jump to the diagram’s view declaration.

Views in the sample

The sample contains nine diagrams that cover all eight standard SysML v2 view kinds. GeneralView is used twice.

Zooming and panning

3. Connecting your AI agent

Connect the AI agent you use through MCP (a standard way to give AI agents access to tools). You’re not tied to any particular AI service. The connected AI can see the open diagram (as an image and as structure), your current selection, and the model structure. It can explain them, and when you ask for a change, it edits the .sysml files directly.

① Turn on MCP

In Settings (⌘/Ctrl+,), search for sysmlv2-modeler.mcp.enabled and select the checkbox (off by default).

② Register it with your AI agent

How you register depends on your AI agent.

• GitHub Copilot (VS Code chat): no registration needed. Step ① is enough.
• Claude Code or Codex (in a terminal or as a VS Code extension):

1. Open the Command Palette (⌘/Ctrl+Shift+P) and run SysML: Show MCP Connection Information.

2. Click Copy Claude Code Command (or Copy Codex Command).

3. Open a terminal in the sample folder, then paste and run the command.
   On Windows with Claude Code, use the terminal inside VS Code (View → Terminal). A terminal outside VS Code may write the drive letter differently (C:\ vs. c:\), and the Claude Code extension then doesn’t see the registration. If it still doesn’t appear, add -s user to the command.

• Other agents: follow your agent’s documentation and register the following as an MCP server.

③ Talk to it

Try asking the AI the following. If the first one opens a diagram, you’re connected.

• “Open the structure diagram.” — the AI opens the diagram in VS Code.
• “Look at this diagram and explain what the controller does.” — the AI reads the open diagram and explains it.
• “What have I selected?” (select an element in a diagram first) — the AI reads your selection.

4. Editing a model

You can create a new model, or edit an existing one in three ways: ask AI, edit the text, or edit the diagram. All three change the same .sysml text.

Create a new model (.sysml)

When there is no model (.sysml) yet

1. Open an empty folder, then click the New Model or Diagram button (the file icon with ⊕, shown when you hover over the tree) at the top of the Model Tree.
2. In “What do you want to start from?”, pick a starting point. GeneralView starts blank; the other four (InterconnectionView, ActionFlowView, StateTransitionView, SequenceView) start with a template.

3. Choose a file name. The .sysml file is created and its diagram opens. From there, open the palette with the button at the top right of the diagram and place elements.

Adding a diagram to an existing .sysml

1. In the Model Tree, select the package that should hold the diagram.
2. Click New Model or Diagram at the top of the tree (or right-click the package → New SysML Diagram…) and choose the kind and a name.
3. A container element (for a SequenceView, an occurrence def) and a view declaration are added to the package, and a diagram with a template opens.

Ask AI

The easiest way to edit is to describe the change to the AI (set up in Connecting your AI agent). The AI edits the .sysml file, and open diagrams update immediately.

• “Add the 0.5-second stopping time in StopForPeople (R2) as a constraint.”
• “Add motor and brake parts to the drive, and show them in the structure diagram.”
• “Add a charging state to DrivingState with transitions to and from idle.”

Edit the text

These features help you as you edit models in text:

• Completion: suggestions appear as you type (press Ctrl+Space if they don’t). For example, type battery. to see its ports.
• Checks as you type: errors show as red squiggles and are listed in the Problems panel (⌘/Ctrl+Shift+M).
• Rename: put the cursor on a name and press F2. The declaration and every reference to it change together.
• Formatting: right-click anywhere in the text editor and choose Format Document.

// Example: add a brake inside DeliveryRobot
part brake : DriveUnit;

Save (⌘/Ctrl+S) and the open diagrams reflect the change.

Edit the diagram

5. Good to know

.sysml files and the model

• The text is the source of truth: the model is the text of the .sysml files (the standard SysML v2 textual notation). Diagrams draw that text, and diagram layout is also stored inside the view declarations.
• One folder, one model: all .sysml files in the opened folder are loaded together and can refer to each other. .project.json marks the folder as a project.
• Standard library: packages such as ISQ::* (quantities) and SI::* (units) come from the bundled standard library.
• It’s plain text: diffs, reviews and history in git work just as they do for source code.

When in doubt, ask AI

If you’re unsure how to write something in SysML v2, asking AI is the shortcut: “What’s the difference between satisfy and verify?”, “Write a test case that verifies this requirement”, “Which parts are not on this diagram?”. The AI reads the model structure and the diagram on screen, and can confirm its edits against the editor’s diagnostics.

Auto and manual layout

Switch the layout mode on the panel at the bottom left of a diagram.

In either mode, Auto Layout on the panel (⌘/Ctrl+Shift+L) rearranges once. Click the Auto layout and display settings button on the panel to choose the layout algorithm, direction, spacing, and edge routing (Orthogonal, Polyline, or Splines) for each diagram.

View declarations and expose

Diagrams are written as view declarations in the .sysml. The expose lines decide which elements appear.

view structure : StandardViewDefinitions::InterconnectionView {
    expose MiniRobot::DeliveryRobot;      // show this element (and its contents)
}
view requirements : StandardViewDefinitions::GeneralView {
    expose MiniRobot::Payload;            // you can list elements one by one
    expose MiniRobot::StopForPeople;
}
view everything : StandardViewDefinitions::GeneralView {
    expose MiniRobot::*;                  // everything directly in the package
}

• The : …View part is the kind of diagram. There are eight kinds: GeneralView, InterconnectionView, ActionFlowView, StateTransitionView, SequenceView, GridView, BrowserView, and GeometryView.
• The label at the top left of a diagram’s frame shows the view’s name and kind. The box at the top right lists its exposes.

• To add a new diagram, see Create a new model (.sysml).
• Put view declarations in a package of their own (like MiniRobotViews in the sample) to keep the model tidy.

Saving diagrams

You can save a diagram at two levels:

Compartments

The sections separated by horizontal lines inside an element are compartments. They group an element’s contents by kind, such as attributes, parts, ports, doc, and require constraints (see Views in the sample).

• To choose which compartments an element shows, select it and use the compartment button in the quick palette, or right-click it and choose Compartments….
• To edit a compartment row directly, select it and press F2 (for example, the battery’s capacity = 880 [W * h] in the structure diagram).

GridView (trace matrix) (beta)

A GridView shows model elements and relationships as a table. The sample’s view traceMatrix is a matrix of parts (rows) and requirements (columns) that shows which part satisfies which requirement.

1. In Settings, search for sysmlv2-modeler.enableBetaFeatures and select the checkbox.
2. Open the traceMatrix view (under MiniRobotViews in the Model Tree). It opens as a matrix.
3. Double-click an empty cell to add a satisfy relationship. It’s added to the text as well.
4. To see the data as a list (a table with attributes as columns), switch views on the panel at the bottom left.
5. Click the table to select it, press ⌘/Ctrl+C, and paste it into Excel or another spreadsheet.

Copying and exporting diagrams

Learning more about SysML v2

This extension follows the official SysML v2 release 2026-09.1 (SysML 2.1 Beta 2).

Open an official sample folder with this extension to view it as diagrams or have your AI explain it.

Troubleshooting

If that doesn’t help, contact us using the links below.

Contact, feedback, requests and bug reports

Impressions, feature requests (“I wish it did…”), questions about how to use it, and bug reports all go to the same place. Good news and pain points are equally welcome.

From inside VS Code, you can also use SysML: Send Feedback / SysML: Report a Problem in the Command Palette (⌘/Ctrl+Shift+P).

Diagram images were drawn from the sample model by the actual extension. You can read the license agreement at any time with SysML: Show License Agreement in the Command Palette.