Rainbird for VS Code

Author, check, query and ship Rainbird knowledge maps without leaving your editor.

Beta. Commands, file formats and some platform endpoints this extension relies on may change between releases. Please report problems and ideas on GitHub Issues.

Rainbird is a decision-intelligence platform. Its knowledge maps are written in RBLang, an XML dialect that declares concepts, relationships, facts and rules. This extension turns VS Code into a first-class RBLang editor and connects it to your Rainbird environment so you can run real queries, read the evidence behind every answer, and push maps to the platform.

Features

Write RBLang with confidence

• Syntax highlighting for elements, attributes, enum values and the expression language inside expression="…", including %VARIABLES and natural-language operators.
• Diagnostics as you type, matched check by check against Studio's validator: unknown or misspelled elements and attributes, missing required attributes, invalid values, undeclared or duplicate concepts, relationships and instances, type mismatches in facts and conditions, certainty out of range, unbalanced quotes and unclosed elements, expression precedence traps, rules that can never fire, relationships that are never used, recursive rules, and more.
• Quick fixes on most problems: declare a missing instance, accept a did-you-mean rename, pick a valid value, add or remove attributes, delete duplicates, parenthesise an expression.
• Completions and hovers that know your map: child elements by context, attribute names, enum values, the concepts, relationships and instances you have declared, and every expression function with its documentation.
• Navigation and rename: go to definition, find references and rename for concepts, relationships and instances. Edit a name where it is declared and every mention follows as you type (linked editing, on by default for .rbl files); or press F2 on any mention. Rename also updates quoted names inside expressions, evidence text and datasource maps, and an instance rename stays within the instance's concept (France the Country, not France the Team). Hover a name to see what uses it.
• Outline, breadcrumbs and folding for the structure of the map, plus a full snippet catalogue.
• Formatting with Format Document, Format Selection or editor.formatOnSave. Each line is re-indented from the element nesting and trailing whitespace is trimmed; the file's line breaks, blank lines, comments, wrapped attributes and element order are kept as written.

Author without memorising the syntax

• Guided authoring: use Rainbird: Insert… from the editor title bar, the right-click menu or the Map Explorer to add a concept, relationship, instance, fact, rule or condition by answering a few plain-English questions. Choices come from what the map already declares, and the element is inserted in the recommended section of the file.
• CodeLens above every relationship and rule to run it as a query or add a fact, rule or condition in place.
• Map Explorer in the Rainbird sidebar lists the concepts, relationships, rules, facts and instances of the open map. Click any item to jump to its source.
• Graph view shows the open map as a live, force-directed graph. Click a node or edge to jump to its line.

Query the real engine and see the evidence

• Run Query opens an interactive panel: find the goal by typing part of a relationship's name, subject or object (the relationship of the rule, fact or declaration under the cursor is preselected, and the last goal for each map is remembered), give a subject, an object or both, choose draft, live or a specific version, inject facts, and answer the engine's questions. Change… in the panel's header points it at another map. Back undoes the last answer.
• Answers in the form the engine expects. Truth questions show True and False. Number questions have a number field with a format hint. Date questions accept dates typed naturally, such as 1 October 1981 or 1981-10-01, or picked from a calendar, and send them as YYYY-MM-DD. A numeric date that could be read either way, such as 01/10/1981, is never guessed: the card offers both readings, day first by default (rainbird.query.dateOrder). Options from the map appear as buttons or chips, with a filter for long lists. If the engine rejects an answer, the card keeps your answers. For a single question it says what format it expects; on a grouped card, where the engine does not say which answer failed, it asks you to fix the one in question.
• Grouped questions arrive on one card that works like a form: fill in every answer, then send them together with a single Submit answers.
• Known answers. Cards show what the engine already knows for a question. Plural questions with known answers offer No more, single-answer ones Keep known answer. By default the panel answers No more for you when the facts you injected cover every question on the card (rainbird.query.autoSkipPluralQuestions); on a larger card the covered questions start on No more. The transcript shows each automatic skip with Answer instead.
• Results show certainty bars and an inline evidence tree laid out like Studio's: the result as a card, each rule's conditions as rows with the source, certainty and impact of the fact behind each, a nested card where another rule inferred that fact, every fact a list function used, and an Inputs used by this result list. Open in Studio and Copy link open or share the same tree in Rainbird Studio (while the session lasts), and Open in panel gives it its own tab.
• Show on graph projects the inference path of a result onto the graph view.
• Explain (AI) under a result turns it into a plain-English narrative of why the engine decided what it did.
• Ask in Natural Language sends a free-text question to Rainbird's natural-language endpoint.

Work with the platform

• Connect once per environment. Your API key is stored in VS Code's encrypted secret storage, never in settings files.
• Open Map by Knowledge Map ID downloads a map's draft and saves it as an editable .rbl that remembers which map it came from, so queries, diffs and the assistant need no ID. The Knowledge Map ID is on the map's Publish page in Studio.
• Push Map to Platform uploads the open file as a new map and binds the file to the new map. The extension lints the map first, then shows any validation message the platform returns in the Problems panel on the element it refers to.
• Pull Map RBLang from Platform opens the draft or any saved version of a map as read-only RBLang, for reading and diffing. Save as .rbl… turns it into a file bound to that map. Reload Map from Studio, or the cloud button on a map in the Maps view, brings a bound file up to date after the map was edited in Studio.
• Bind Open File to a Knowledge Map ID tells the extension which map an exported or pasted file is a copy of.
• Maps view keeps a per-environment list of the maps you have opened, pushed, queried or added by ID. Open a map's current draft or run a query straight from the list. It is not a listing of your Studio account (see Known limitations).
• Extract RBLang from .rbird export unpacks a Studio export into an editable .rbl file.
• Add Served Graph as MCP Server registers a served-graph endpoint in .vscode/mcp.json for use in Copilot agent mode.

Compare and test

• Side-by-side diffs against git HEAD, the platform draft, a saved version, a Studio export, or the snapshot of the draft you last downloaded into a file or last pushed. Each comes with a semantic report that lists the concepts, relationships, facts and rules that were added, removed or changed, rather than line noise.
• Promotion diff replays a saved test or your last query session against two versions of the same map and reports every result and certainty that moved.
• Regression tests: save any finished query as a .rbtest.json. The Test Explorer replays it against the recorded target and flags certainty drift.

AI assistant

The Rainbird sidebar includes a Co-author-style assistant powered by Claude, using your own Anthropic API key. It knows RBLang and the Rainbird reasoning model in depth (a bundled reference covering concepts, relationships, rules, expressions, datasources, the certainty model and Match → Infer → Ask), and it works on the map you have open:

• Ask about the map — "which rules infer has risk level?", "why would this never ask about postcode?", "explain this rule" — and it answers from the map's actual content, naming rules and lines.
• Ask for changes — "add a rule that applicants over 65 skip the income check", "add question wording to every askable relationship", "fix every error" — and it edits the file through validated element-level operations (insert, replace, delete, set attribute), re-lints, fixes what it broke and summarises the change. By default edits land directly in the editor, each one undoable, with a per-turn Changes card offering Show diff and Undo this turn; set rainbird.ai.applyEdits to preview to review a side-by-side diff and Accept or Reject instead.
• Start a map from a description when no file is open.
• Test it live — with a connection it can push the map (always asking first), run queries against the draft, fetch evidence trees, replay saved regression tests and compare the map with git HEAD or the last pulled or pushed snapshot.

Requirements

• VS Code 1.90 or later.
• A Rainbird account and API key for opening maps from the platform, querying and pushing. The key and the Knowledge Map ID are on the map's Publish page in Rainbird Studio; the ID is also under View Knowledge Map ID in the map details menu. Editing, linting and the graph view work offline.
• An Anthropic API key if you want to use the AI assistant.
• To see evidence trees, enable the map's Evidence Tree Link in Studio under Publish, API Management, Access Control. Open in Studio works out the Studio address from rainbird.apiUrl for Rainbird-hosted environments; for other hosts, set rainbird.studioUrl.

Getting started

1. Install Rainbird from the Visual Studio Marketplace, or from the Extensions view in VS Code, or from a terminal:

   code --install-extension RainbirdTechnologies.rainbird
   

2. Run Rainbird: Connect, pick Community, Enterprise or a custom URL, and paste the API key from your map's Publish page in Rainbird Studio.

3. Run Rainbird: Open Map by Knowledge Map ID…, paste the map's Knowledge Map ID, which is on the same page, and choose where to save the .rbl (your open folder by default): it opens bound to that map. Two other routes work too: export a .rbird from Studio and right-click it to Extract RBLang, or paste the RBLang from Studio's </> code panel into a new file. To look around without an account, run Help: Get Started, choose Get started with Rainbird and click Open example; you can explore the example map offline, but it must be pushed to your account before it can be queried.

4. Click the play button in the editor title bar, or run Rainbird: Run Query…. Type part of the goal relationship's name and pick it, give a subject or an object, and click Start query. Answer the questions, then click Show evidence under the result. For an exported or pasted file, run Rainbird: Bind Open File to a Knowledge Map ID… first, or enter the ID when prompted (it becomes the folder's default map).

5. Optional: open the Rainbird icon in the activity bar, choose AI Assistant and paste an Anthropic API key when prompted.

Commands

All commands are available from the Command Palette. The most used ones:

Settings

API keys are never stored in settings. Use Rainbird: Connect and Rainbird: Set Anthropic API Key to change them.

RBLang files default to a two-space indent (editor.tabSize 2, editor.insertSpaces true under [rblang]), which is the style Rainbird's documentation uses. VS Code's indentation detection still wins for a file that already uses tabs. To format every time you save, add to your settings:

"[rblang]": {
  "editor.formatOnSave": true
}

File types

Known limitations

• Push creates a new map every time. The platform API has no update-in-place or delete, so promote changes through Studio.
• Linked maps are not resolved. References to symbols declared in an imported map are reported as unknown.
• Single-file scope. Navigation, rename and diagnostics work within the open file. There is no workspace-wide index yet.
• The graph view is read-only. Edit the RBLang, and the graph follows.
• No map browser. The Rainbird API has no endpoint that lists an account's maps, so there is no "pick a map" dialog: start from the Knowledge Map ID on the map's Publish page with Open Map by Knowledge Map ID…. The Maps view lists the maps you have opened, pushed or queried from VS Code; if the platform adds a list endpoint, the Maps view will use it.
• Packaging to .rbird is not supported. Studio's importer needs its structured model, not just the RBLang text. Use Push instead.

Privacy

• Rainbird API keys, the evidence key and the Anthropic API key are stored in VS Code's secret storage.
• The AI assistant sends your prompts to Anthropic using your own key, together with a short context header (file name, size, cursor, diagnostic counts, connection state), the selection if any, small maps in full, and whatever the assistant reads or writes through its tools (map overview, line ranges, diagnostics, edits, query results). Nothing is sent unless you use the assistant or an AI command.
• MCP endpoint URLs are self-authenticating secrets. They are written only to your workspace's .vscode/mcp.json and masked on input.
• The extension reads the clipboard only when the Knowledge Map ID prompt opens, to offer an ID it finds there. Nothing is sent anywhere.

Release notes

See the changelog.

Contributing and background

Development setup, test instructions and the product research behind this extension are in docs/.

Licence

MIT. Copyright (c) 2026 Rainbird Technologies Ltd.