Quickstart

This guide gets you from zero to a running goal in the Control Tower.

1. Install the extension

Install NodalMerge Studio from the VS Code Marketplace: Install from the VS Code Marketplace → Or search for NodalMerge Studio in VS Code’s Extensions panel (Ctrl+Shift+X / Cmd+Shift+X). The extension bundles the Studio host — no separate install of the nodalmerge or nodalmerge-studio repos required; everything the host needs is pulled from NuGet automatically.

Prerequisites: VS Code 1.90+ and the .NET SDK 10.0. The host ships with the extension, but it’s a .NET process — it needs a .NET runtime on the machine to start.

2. Open the Control Tower

Two ways in:

Command palette — Ctrl+Shift+P / Cmd+Shift+P, then run NodalMerge: Open Studio.
Side panel — click the NodalMerge icon in the Activity Bar. This opens a quick-launch panel (“Agent orchestration, task management, and human review — backed by a persistent, branchable artifact graph”) with five buttons: Open Studio, Open Insights, Start Local Runtime, Restart Studio Host, and Show Output.

Either one opens the Control Tower — a tabbed shell with Goal Workspace, Model & Agent Studio, Activity Center, Review, Pathways, Insights, and Projection Snapshots. (The extension’s tab labels have moved on a bit from a couple of names still used elsewhere in these docs — e.g. the merge-review gate is called “Decision Convergence” on this page and in the UI reference; the extension itself labels that tab Review.)

Side panel quick-launch (left) and the Control Tower shell with its full tab bar (right)

You can also reach NodalMerge: Open Studio and the rest of the command set from the command palette directly:

Command palette filtered to "noda", showing the full NodalMerge command set

3. Configure an agent profile

Before you can run a goal, define at least one agent profile in VS Code settings — this maps agent roles to an LLM provider and model:

// settings.json
{
  "nodalmerge.agentProfiles": [
    {
      "id": "orchestrator",
      "label": "Orchestrator (Claude)",
      "domain": "orchestration",
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "apiKeyRef": "anthropic-key",
      "systemPrompt": "You are an orchestrator agent. Plan work, assign tasks, review results."
    }
  ]
}

Choosing a provider

provider takes one of five values, in two shapes:

Provider	Shape	Notes
`anthropic`	HTTP API	Claude models. Needs `apiKeyRef`. `baseUrl` defaults to `https://api.anthropic.com`.
`openai`	HTTP API	GPT models. Needs `apiKeyRef` and `baseUrl`.
`vscode-lm`	HTTP API (proxied)	VS Code’s built-in Language Model API — no API key required. Inline deployment only.
`claude-cli`	Local CLI harness	Spawns your local `claude` binary in the work unit’s branch directory.
`codex-cli`	Local CLI harness	Spawns your local `codex` binary in the work unit’s branch directory.

The first three call an HTTP API. The last two don’t: they route the role to a harness executor that runs the vendor’s own CLI as a subprocess, so prompting, context management, compaction, and retries stay with the harness while Studio keeps the goals, work units, leases, review, and replay. CLI providers take no baseUrl, and apiKeyRef is optional — leave it blank to use the machine’s ambient CLI login, or store a key to have it injected as ANTHROPIC_API_KEY / OPENAI_API_KEY for headless use. A blank model means the CLI’s own default. So the shortest possible profile is:

{
  "id": "cli-worker",
  "label": "Worker (local Claude Code CLI)",
  "domain": "code",
  "provider": "claude-cli"
}

If claude already works in your terminal, that profile already works. Store API keys via VS Code’s SecretStorage (Ctrl+Shift+P → “Preferences: Configure Runtime Arguments”, or through the Model & Agent Studio panel’s Profiles tab).

4. Run your first goal

In the Goal Workspace topbar:

Type a goal, e.g. “Add input validation to the signup form”
Leave Exploration Strategy at its default (single-agent) and Review: Human Required (the default review policy)
Click ▶ Run

Watch the Decision Tree populate as the orchestrator plans and workers execute. Click any node to load its timeline into the Decision Lens.

5. Review and approve the proposal

When a worker finishes, it submits a merge proposal, which routes to Decision Convergence for review (or shows up under Activity Center’s “Pending Decisions”). Inspect the diff, evidence, and rationale, then Accept Decision and Apply Decision.

Review (Decision Convergence) in proposal review mode: rationale, split diff view, evidence, and the Accept/Reject/Apply action row

Next steps

Read Concepts → How Studio works for the mental model behind work units, projections, and branches
Read Concepts → Trust & autonomy to configure review policy, promotion branches, and experiments for less hands-on runs
Browse the Control Tower UI reference for every panel and control
If you’re integrating from CI or an external system rather than the extension, see Guides → Extending goals and Guides → Headless peer
If you want to build the extension and host from source instead of installing the packaged release, see Guides → Build from source

Introduction

How Studio works

Configuration and extension

Control Tower UI

API surface

Quickstart

Quickstart

1. Install the extension

2. Open the Control Tower

3. Configure an agent profile

Choosing a provider

4. Run your first goal

5. Review and approve the proposal

Next steps

​Quickstart

​1. Install the extension

​2. Open the Control Tower

​3. Configure an agent profile

​Choosing a provider

​4. Run your first goal

​5. Review and approve the proposal

​Next steps

Quickstart

1. Install the extension

2. Open the Control Tower

3. Configure an agent profile

Choosing a provider

4. Run your first goal

5. Review and approve the proposal

Next steps