Inwardis for VS Code

Inwardis is a self-hosted, model-based knowledge base for people and AI agents: one hierarchical model of your systems, with a canvas, an MCP server and a git history. This extension needs an Inwardis server (1.0 or newer) — start a 30-day trial at inwardis.com. Every server also hands out the copy of this extension it was tested with (Help → Integrations); the Marketplace copy tracks the latest release.

Browse an Inwardis model inside VS Code as if it were a directory tree — every element is a folder, its metadata an element.yaml, each of its prose properties a <property>.md (notes.md, description.md — whichever its type declares richtext), and every view a live server-rendered .svg. Element prose is editable (saving notes.md / description.md updates that property); everything else is read-only, and nothing is ever written to your disk.

inwardis://{connection}/{project}/
  _project.yaml            project meta
  _relations.yaml          all relations (from/to as folder paths)
  _views/
    er-overview--ab12cd34.svg   live server-rendered diagram
  _subprojects/            child projects, same structure
  customer-orders--550e8400/
    element.yaml           id, type, name, tags, properties
    notes.md               one file per richtext property, verbatim Markdown (description.md on c4-model)
    id--c01c01c0/          child elements = subfolders

Setup

1. In the Inwardis app, create an API key (Admin → API Keys) with the read:projects scope; add write:elements if you want to edit notes from VS Code. A dedicated key for editor use is recommended — read-only if you don't need editing.
2. In VS Code: Inwardis: Connect to Server — enter the server URL and the ink_… key. The key is stored in VS Code SecretStorage (your OS keychain), never in settings files.
3. Inwardis: Open Project as Workspace Folder — pick a project; it mounts as a workspace folder. The list is ordered like the app's explorer (0.12.0): root projects by name, subprojects indented beneath their parent, the parent path as the row's description — so typing a parent's name filters to its subtree. An element with files shows them under _attachments/ (0.13.0): open one and the bytes come over REST with your key — never through the model's base64 path. Drop or paste a file into _attachments/ (or onto the element folder) to attach it, delete one to remove it (0.14.0); a drop onto an existing name is refused — delete first. Renames are not supported. Ctrl+P fuzzy-finds any element by name; open an SVG in _views/ to see the live diagram.

Changes made elsewhere (the Inwardis app, AI agents) appear live — each mounted project subscribes to the server's change feed (SSE) and refreshes within ~1 s of a change. On servers without the feed, or if the connection drops, the fallbacks kick in: window-focus refresh (inwardis.refreshOnFocus), cache expiry (inwardis.cacheTtlSeconds, default 15 s), and manual Inwardis: Refresh.

Editing notes

Open any prose file (notes.md, or description.md where the type declares that), edit, save — the save updates that property on the server (Markdown, verbatim). Creating one inside an element folder that has none works too. If someone changed the notes on the server after you loaded them, the extension asks before overwriting. Clearing: save an empty notes.md (the file disappears on the next refresh). Structure (element.yaml, relations, views) remains read-only — edit in the app.

Code references

A comment anywhere in your code can point at a model element: @inwardis <uuid> (insert one with Inwardis: Insert code reference, or copy it from an element in the inwardis:// tree). A CodeLens above the mark shows the element's name, type and project, and opens it in the tree.

• Inwardis: Scan code references walks the workspace and reports every mark: resolved, deleted (the element was removed — repair with Re-point / Remove / Keep, also offered on the lens itself), unresolved.
• Freshness (0.11.0): when the folder is a git repository, each marked file's last commit date travels with the scan and the server judges every mark stale (the code changed after the element was last verified), fresh or unverified. The lens shows the verdict; on stale and unverified marks a second lens, ✓ Mark as verified, stamps the element's verifiedOn with today — an explicit act, never a side effect of scanning. Without git there is simply no verdict.
• Linked at once (0.19.0): Insert code reference also tells the server where the mark is (repository, file, line), so the element's Code section shows the link immediately, labelled pending until your push lands and the server's scan finds the mark. When a push lands the extension asks the server to scan straight away; Inwardis: Scan code references on the server now does the same by hand. The repository must be declared on the project (Code Repositories… in the app). A pending link is dropped if your own later push of that file arrives without the mark. Needs server 1.0.6 or newer and a key with write:elements.

Requirements

• An Inwardis server, 1.0 or newer, with the mcp feature flag on (its default). The extension talks to the MCP tools and the render endpoint with an API key.
• VS Code 1.90+.

Security notes

• The API key acts as its creator; grant only the scopes you need (read:projects, plus write:elements only if you edit notes from the editor).
• A plain http:// server URL triggers a warning — the key rides every request.
• The virtual filesystem keeps model content out of your disk entirely (beyond VS Code's own transient caches).