VS Code Features

The extension is the authoring and inspection surface for Norn workflows: agents and their run graphs, domain knowledge, tools, sequences, tests, and environment-aware execution.

CodeLens in .norn Files

Clickable CodeLens actions appear directly above relevant lines in .norn files.

• ▶ Send Request appears above standalone HTTP requests outside sequences.
• ▶ Run Sequence appears above runnable sequence and test sequence declarations.
• ▷ Debug Sequence appears next to runnable sequences for step-through debugging.
• env: ... or + Add env file appears next to request and sequence actions so you can switch or create environments without leaving the editor.
• Open Contract and View Contract appear on matchesSchema assertions.

GET https://api.example.com/health

test sequence ContractCheck
    GET https://api.example.com/users/1
    assert $1.body matchesSchema "./schemas/user.schema.json"
end sequence

▶ Send Request does not appear for requests inside a sequence because those requests run as part of the sequence action instead.

Contract Validation

Schema assertions integrate with the editor workflow, so you can move from a failing response to the exact contract mismatch quickly.

• Open Contract opens the schema file referenced by a matchesSchema assertion. Paths can be relative or use the @/ alias for the workspace contracts/ folder.
• View Contract reruns the enclosing sequence and opens a contract report for that assertion.
• Hovering a validated matchesSchema line shows the current pass or fail status, schema path, last run, and a shortcut to open the contract view.
• Response panel results show contract cards with the schema name, validation counts, validated properties, and the most relevant issues.
• When schema validation fails in the response panel, the assertion output includes View Contract Details so you can inspect the mismatch directly from the run results and return with Back to Results.

test sequence GetUserContract
    GET {{baseUrl}}/users/1
    assert $1.status == 200
    assert $1.body matchesSchema "@/users/get-user-200.schema.json"
end sequence

The contract report separates breaking issues from warnings and lets you switch between the issue list, validated properties, annotated response, and resolved schema.

Response-Body IntelliSense and Diagnostics

After a successful explicit VS Code run, Norn can reuse sampled response-shape metadata to make body-path authoring faster without storing live payload data.

• Send Request and Run Sequence cache bounded response-shape metadata in .norn-cache/api-response-intellisense.json.
• Later completions for $1.body. and captured response variables such as user.body. can suggest cached properties, including nested object paths.
• The cache stores property names, type summaries, request identity, and cachedAt, but not raw response values, request bodies, headers, cookies, tokens, or secrets.
• CLI runs do not write this IntelliSense cache.
• Diagnostics flag undefined base variables in bare expressions such as assert missing.status == 200 while keeping runtime-shaped JSON property paths quiet when the base variable exists.

sequence InspectUser
    var user = GET https://api.example.com/users/1

    # After the first successful VS Code run, both lines benefit from cached body-path completion.
    assert user.body.profile.email exists
    assert $1.body.profile.email exists
end sequence

Environment-Aware Hints and Hovers

Norn resolves template references in the editor using the active environment, then shows the value inline and on hover across .norn, .nornapi, .nornsql, and .nornenv files. Secret values are masked.

• In .norn files, {{name}} resolves through sequence-local var declarations, then file-level var declarations, then the active environment.
• {{$env.name}} always reads directly from the active environment.
• Runtime values such as $1.body.id, request captures, and sequence return values do not show inline values, but hover explains where they come from.
• In .nornapi and .nornsql files, {{name}} resolves from the active environment.
• In .nornsql files, the connection appDb hover explains that the alias comes from an imported .nornai database block.

CodeLens in .nornapi Files

Swagger lines in .nornapi files expose API-definition actions.

• Import Endpoints parses the OpenAPI/Swagger spec and generates endpoint definitions.
• Generate Schemas creates JSON Schema files from response definitions.
• Show Coverage opens API coverage for that .nornapi file and its folder scope.
• Endpoint URLs and header groups highlight {{variables}} the same way as .norn files, and diagnostics flag unresolved environment-backed endpoint variables.

swagger "https://petstore.swagger.io/v2/swagger.json"

CodeLens in .nornenv Files

.nornenv files get editor support for environment authoring and secret-management actions.

• Template references such as {{appDb_server}} get IntelliSense, including single-brace completion while typing.
• Template tokens are highlighted inside variable and connection-string values.
• Diagnostics catch unsupported template references, missing variables, and invalid references between environment-specific values.
• A Refactor ... templates CodeLens appears when Norn detects a flat stage/region matrix such as dev_us, dev_uk, prod_us, and prod_uk.
• Encrypt Secret appears on plaintext secret values.
• View Decrypted, Rotate Secret, and Delete Secret appear on encrypted secret lines.

[env:prelive]
secret apiKey = ENC[NORN_AGE_V1:kid=team-main:abc123xyz]

[env:dev_us]
var baseUrl = https://dev.example.com

[env:dev_uk]
var baseUrl = https://dev.example.com

[env:prod_us]
var baseUrl = https://api.example.com

[env:prod_uk]
var baseUrl = https://api.example.com

SQL Files (.nornsql)

SQL files get dedicated editor support so database setup and verification behave like first-class Norn assets instead of opaque scripts.

• .nornsql files have syntax highlighting for declaration lines and SQL bodies.
• The connection line names a database block in a directly imported .nornai file; credentials are kept out of its hover.
• Import completion in .norn files suggests .nornsql files alongside other Norn imports.
• Diagnostics catch invalid SQL-file structure, bad imports, duplicate SQL operation names, and invalid run sql calls.
• The sidebar starter catalogue includes a runnable SQL demo and a separate real database connection starter.
• Database blocks support syntax highlighting, folding, diagnostics, and completion; the Agent Graph shows them as nodes beside knowledge declarations and the agents that use them.

connection appDb

query ListUsersByStatus(status)
select Id, Email, Status
from Users
where Status = :status
end query

command UpdateUserStatus(id, status)
update Users
set Status = :status
where Id = :id
end command

Agent Files (.nornai)

Agent sidecars get full editing support: completion for model and agent directives, hovers, and diagnostics that resolve contract paths, prompt files, and {{$env.*}} references before a run spends a model call.

A sidecar can be named .nornai or .nornagent. Both map to the same language, so highlighting, completion, diagnostics, the agent graph, and import suggestions behave identically, and existing .nornagent files need no migration. Import completion in .norn files offers both. A file named with a bare .ai extension is not a Norn sidecar: importing one is flagged as an error telling you to rename it to .nornai, and .ai files are kept out of import suggestions so the mistake is harder to make.

Norn: Show Agent Graph, or the CodeLens on any agent block, draws the graph for the file — who calls whom, the accepts / returns contract on each boundary, and how each hop turned out. Click an agent or a boundary for models, timings, usage, prompts, payloads, and contract issues. A second click closes the detail, Escape dismisses it, and its footer button jumps to the declaration or steps replay to that hop.

The graph toolbar lists the project's recorded runs, each labelled with the .norn file it came from. Play run replays a recording's own events hop by hop on the canvas — nothing re-executes and no model is called.

Running a sequence that calls agents fills the response panel with the run's invocation tree: each agent call, its sub-calls, and its MCP steps, with contracts and payloads available on demand. Rows start collapsed and large values stay host-side until you reveal or copy them, so a long run stays responsive.

While that run is still going, the panel shows an Agent activity stack beneath the running header: the agent currently working, any child agents below it, and whether each one is preparing context, waiting for a model, calling an MCP tool, loading knowledge, or invoking another agent. The stack clears on completion, cancellation, or reset, leaving the ordinary result tree as the record of the run.

Norn: Show Agent Run Results reopens a recorded run in that same Results panel, chosen from the workspace's recorded runs. The agent graph toolbar carries a matching button that opens whichever past run is selected in its run list. A recording only captures agent hops, so the reopened view has one row per recorded agent call with its full child, tool, and contract tree; ordinary API, SQL, script, and assertion steps are not stored in a recording and do not reappear there.

A recording can also be stepped in the existing norn debugger by adding it to a launch configuration, where agent calls appear as nested frames with their request, response, and contracts. See AI Agents.

Chat With a Declared Agent

Every agent block carries a Chat CodeLens beside Show Agent Graph. It opens a conversation with that exact declaration, so you can try a system prompt, a knowledge grant, or a tool boundary without writing a sequence first. The same action is available as Norn: Chat With Agent in the Command Palette for the agent under the cursor.

• The declaration and every sub-agent it can reach are validated before the chat opens. An invalid one shows an error naming the offending line instead of opening a tab.
• The chat opens as its own editor tab with a dedicated chat icon, one tab per agent per file. Asking again reveals the tab you already have.
• Each message runs the declared model, prompts, contracts, MCP grants, and knowledge grants against the active environment — the same runtime a sequence uses.
• Conversation history is kept per tab and sent as context on the next message. A failed or stopped turn is not added, and closing the tab discards the conversation.
• Knowledge delivery appears as short transcript notes: what was supplied up front, which topic indexes and domains were offered, what was actually loaded, what was requested again, and what was refused.
• MCP tool calls and child-agent invocations get separate collapsible entries in call order, and a child agent shows its reply with its own nested activity.
• Values declared as secrets in .nornenv are masked before anything reaches the view, and Stop cancels the turn in flight and closes the MCP sessions it opened.

This chat is separate from the :codex and :claude sessions in the Norn Terminal, which keep their own behavior, and it has no CLI equivalent.

Knowledge Markdown (.md)

A Markdown file that a knowledge declaration includes gets its own editing surface: a formatted title, controls on the line below it, and environment-aware rendering of the {{name}} references described in AI Agents. The controls sit under the title rather than on it, because the H1 marker is hidden by the styled rendering.

• An env: control names the environment currently applied to the document and opens the environment picker. The choice is made per environment file and, in the editor, wins over the environment the run selected. An explicit None resolves common variables only.
• When the document has an H1 but no environment file is in scope, the control reads + Import env file and writes an empty import: "" into a norn:meta block under the title, leaving the cursor between the quotes for path completion. The same action is available as Set environment file import…. Without an H1 to anchor the block, it offers + Add env file instead.
• A Knowledge source paths pill counts the declared knowledge source paths that include this file. A count of zero only means no declaration covers it; the file may still be referenced as an agent prompt, which is deliberately not counted.
• View knowledge usage appears once the document has recorded loads, and opens per-topic load counts for the current and earlier versions.

Variable references are underlined and their braces take the theme’s bracket-pair colours, matching how .norn renders them. Hover names the variable, and an inline hint after each reference shows the value it resolves to, while the authored placeholder stays editable. A reference with no environment file in scope is marked as such rather than reported as broken.

Completion starts at the first { and offers both the {{name}} and {{$env.name}} forms from the common section and the selected environment. Secret names are listed and labelled, because including one is an explicit authoring decision, but hovers and inline hints mask the values — both direct secrets and ordinary variables whose templates depend on one. The import value completes folders and .nornenv files relative to the document.

Power with Norn

An ordinary Markdown file that no declaration covers shows a Power with Norn action above the document. Opting in gives that single file the same editor treatment — styled title, environment selector, variable rendering and completion — without adding it to any agent’s knowledge declarations or grants. Remove Norn powers reverts it from the same place.

The opt-in is an editor preference, stored per workspace in .norn-cache/powered-markdown.json. It creates no knowledge occurrence and has no CLI equivalent. Because the action is offered on any Markdown file, the extension now activates when a Markdown file is opened.

Project Setup and MCP Tools

The sidebar leads with Create agentic flow starter. It creates a new folder containing one .norn sequence, one agents.nornai sidecar, and an AGENTS.md for coding assistants. The model and MCP values are placeholders; the sequence does not call a model until you configure and enable it. The guide explains how to structure agents, use the CLI, and turn rough notes into focused prompts and knowledge.

• See what else you can do with Norn opens the existing sample catalogue with a Back button. Each sample is created in its own new folder to avoid collisions.
• The catalogue includes simple requests, scripts with JSON data, a runnable SQL demo, a real SQL connection starter, and an advanced end-to-end flow with contract validation.
• The Explorer folder context menu opens the same starter picker, including the agentic flow starter.
• For new agent flows, declare MCP servers in the .nornai sidecar and grant only the tools an agent needs. Existing norn.config.json MCP aliases remain supported and get JSON schema validation in the editor.
• Postman import remains available through Norn commands, but is no longer part of the sidebar setup path.
• run mcp list and run mcp call get syntax highlighting, diagnostics, server-alias completions, cached tool-name completions, and parameter hints after a successful list call.
• MCP steps show up in the response panel with dedicated styling instead of sharing SQL visuals.

test sequence TimeTools
    var tools = run mcp list localTools
    var result = run mcp call localTools get_current_time("UTC")

    assert tools.count > 0
    assert result.isError == false
end sequence

Test Explorer

Norn integrates with VS Code's built-in Testing sidebar.

• All test sequence blocks are discovered automatically.
• Plain sequence blocks stay as helpers and do not show up as tests.
• Tests are grouped by file, and then by their primary tag when tags exist.
• @data and @theory sequences show one child test per data case.
• Both run and debug profiles are available.
• Execution output streams into the test run so you can inspect requests, assertions, waits, scripts, and print statements.

@smoke
test sequence HealthCheck
    GET {{baseUrl}}/health
    assert $1.status == 200
end sequence

@data(1, 2, 3)
test sequence TodoTest(id)
    GET {{baseUrl}}/todos/{{id}}
    assert $1.status == 200
end sequence

Swagger Coverage

Norn can calculate coverage for Swagger-defined endpoints and response codes.

• Coverage counts response codes separately, not just endpoints.
• Show Coverage on a swagger line scopes coverage to that .nornapi file and its folder plus subfolders.
• When a .nornapi file is active and Swagger data exists, the status bar shows Coverage with a shortcut to the coverage panel.
• Norn: Refresh API Coverage recalculates the panel.
• Coverage updates after sequence execution.

test sequence OrderTests
    var found = GET GetOrderById(1)
    assert found.status == 200

    var missing = GET GetOrderById(999999)
    assert missing.status == 404
end sequence

TLS Verification

HTTPS certificate verification is enabled by default in the extension.

{
  "norn.security.verifyTlsCertificates": true
}

Set norn.security.verifyTlsCertificates to false only for trusted local development environments with self-signed certificates. The setting affects both request execution and Swagger/OpenAPI fetches.

If you need the same behavior in the CLI, use --insecure for that run instead of changing editor settings globally.

HTTP Request Timeouts

VS Code request and sequence runs use the same project timeout config as the CLI. Put team defaults in norn.config.json, then use the VS Code setting only when your local editor needs a different timeout.

{
  "version": 1,
  "http": {
    "timeoutMs": 180000
  }
}

{
  "norn.request.timeoutMs": 240000
}

Open Settings and search for norn request timeout to edit Norn › Request: Timeout Ms. Leave the setting unset to use norn.config.json; if neither is set, Norn uses the built-in 30 second default. Precedence is the VS Code setting, then norn.config.json, then the default.