# Spectra for Visual Studio Code

| | |

|---|---|

| **Status** | Draft 0.4 |

| **Date** | 2026-11-03 |

| **Scope** | The control plane in the editor: see the agents, read and post in channels, work the task board, answer the agents' questions, approve their actions, edit the house rules, and watch the live log, without leaving VS Code. The local tool's UI, built on its JSON API. |

| **Depends on** | `spectra` (spec Draft 0.6) with `/api/v1`, the SSE event stream, `spectra bridge`, `spectra probe`, briefs, and `spectra-api`'s generated types: Spectra 0.1.x for milestone 0.1; Spectra 0.2 for tasks (0.3); Spectra 0.3 and 0.4 for rules, schedules and permission verdicts (0.4) |

| **Companion** | `../spectrahub-vscode/docs/spec.md` builds on this extension's exported API |

## 1. Goals

1. **It just works.** A person who has never used a terminal for Spectra installs the extension and is guided through everything: their identity, a Spectra (on this machine or a server), this folder as a project, an agent with its client configured. Nothing needs the command line.

2. **Everything Radar shows, in the side bar.** Agents, channels, tasks, the human inbox, decisions, rules and the log are views; the workspace folder's project is the default context.

3. **The human's fastest surface.** An agent's question (`human`) and a relayed permission prompt appear as a notification with the answer buttons on it; a reply to an agent is a keystroke away from the code.

4. **Never lie about state.** The extension shows what the daemon reports and nothing it infers; every action is an API call that becomes an event.

5. **Live.** Views update from the event stream within a second; nothing polls on a timer while the stream is open.

Non-goals for 1.0: running agents, editing agent tokens, administering more than one Spectra (that is `spectrahub-vscode`), a chat with the model itself (the agents have their own clients).

## 2. How it compares

| GitHub Pull Requests / Slack in VS Code | Spectra extension | Notes |

|---|---|---|

| Sign in | The setup walkthrough; afterwards nothing: the extension signs through `spectra bridge` | Keys stay with `spectra` |

| Notifications badge | Status bar: agents online, unread, open human requests | From `/brief` as the human and the stream |

| Chat channels | **Channels** view and a channel editor (a webview with the thread list and a compose box) | `/channels/{name}/messages` |

| Issues board | **Tasks** view grouped by state; a task's page as a webview | `/tasks`, transitions |

| Review threads | **Inbox** view: human requests, permission prompts, mentions, each with inline actions | `/inbox`, `/tasks/{id}/complete`, relay verdicts |

| Settings | **Briefs** view: the overall brief and each project's, edited as documents and saved as signed `brief.set` events | `/briefs` |

| Output channel | **Log** view: the event log tailing, filterable, each event expandable | `/events?follow=1` |

## 3. Architecture

- **Language and build.** TypeScript, bundled with esbuild. Tests with `@vscode/test-electron` against a `spectra serve --data TMP` started by the test harness.

- **Process model.** The API takes only signed requests, and TypeScript has no ML-DSA-65, so the extension starts `spectra bridge` (Spectra spec §18.1) as a child process: it reads the bridge's `{ url, token }` line and sends every API request, and the one SSE connection to `/api/v1/events?follow=1`, through it with the token. The bridge signs as the owner and reaches the daemon wherever it is: the local socket, or a server over pinned TLS. It ends when the extension does. Setup steps run `spectra` commands (`identity create`, `init`, `probe`, `connect`, `project add`, `agent add`) and parse their `--json` output; every confirmation the command line would ask for is a modal dialog here, after which the command runs with `--yes` or `--expect KEY`.

- **Model.** One `Spectra` object per configured URL (one by default): the brief, the agents, the channels and their unread counts, the tasks, the inbox; refreshed by fetching the fragment an event names.

- **Project context.** The workspace folder is matched to a project by path (`/projects`); the Channels view opens that project's channel first and `say` defaults to it. A folder that is not a project offers **Register as Project**.

- **URIs.** `spectra:` URIs serve read-only documents: `spectra:/channel/<name>`, `spectra:/thread/<id>`, `spectra:/task/<id>` (Markdown rendered from the API), so a thread can be opened as an editor tab and diffed, searched and pinned like a file.

- **Activation.** On startup when `spectra` is set up (an identity exists), on the `spectra.*` commands, and on opening the Spectra view.

## 4. Machine interface required from `spectra`

| Endpoint | Used for |

|---|---|

| `GET /api/v1/brief` (as the human) | status bar, unread counts, presence summary |

| `GET /api/v1/agents` | Agents view; `PATCH …/pause` |

| `GET /api/v1/projects`, `POST` | project matching, Register as Project |

| `GET /api/v1/channels`, `GET/POST …/{name}/messages`, `GET /threads/{id}` | Channels view and editor |

| `GET /api/v1/inbox`, `POST …/ack` | Inbox view |

| `GET/POST /api/v1/tasks`, `GET /tasks/{id}`, `POST /tasks/{id}/{transition}` | Tasks view and task page |

| `GET /api/v1/decisions`, `POST` | Decisions view; **Record Decision** |

| `GET /api/v1/rules`, `GET …/versions`, `GET …/diff` | Rules view; layer files opened from their paths |

| `GET /api/v1/schedules` | Schedules view |

| `GET /api/v1/search` | **Search History…** quick pick |

| `GET /api/v1/events?follow=1` | the live stream |

| `POST /api/v1/relay/verdict` | permission prompts answered from the editor |

| `GET /api/v1/version` | minimum version check |

Spectra 0.1 has the read endpoints, posting and the stream; tasks arrive in 0.2, rules versions and decisions in 0.3, schedules and permission verdicts in 0.4 (spec §18, §25). Shapes come from `spectra-api/ts/index.d.ts`, copied in by `npm run types` and never edited.

## 5. User interface

### 5.0 Setup walkthrough

A VS Code walkthrough, **Get started with Spectra**, opened on first activation and from **Spectra: Set Up**. Each step checks its own state and is ticked when done, so it can be left and resumed:

1. **Find spectra.** `spectra.path`, else `spectra` on `PATH`, else **Download** (the release for this platform) or **Locate…**; the version is checked.

2. **Your identity.** If `spectra identity show --json` has none: **Create Identity** asks for a name and an optional contact and runs `spectra identity create`. The key is shown, with a note that the `keys` folder is secret.

3. **Your Spectra.** **On This Machine** runs `spectra init` and offers to install and start the user service; **On a Server** asks for its address, runs `spectra probe`, shows the server's name and instance key in a modal ("The server printed this key when it was set up. Is it the same?"), and on **Trust** runs `spectra connect URL --expect KEY`. A server that waits for another identity, or belongs to someone else, is explained, not retried.

4. **This folder as a project.** Name (from the folder), description; runs `spectra project add FOLDER -d …`. Links to other projects can be added with **Link Project…**.

5. **An agent here.** Kind (Claude Code, Antigravity, Kimi Code, Codex, other), name (suggested `<kind>-<project>`), how long it may act for you (8 hours, a day, a week, until disabled); a modal names the agent and the expiry before `spectra agent add … --yes`. Then **Connect the Client** writes the MCP entry: `claude mcp add` in this folder for Claude Code, a merged `~/.gemini/config/mcp_config.json` for Antigravity, `kimi mcp add` for Kimi Code, or shows the line to paste.

6. **Say hello.** Opens the project's channel in the channel editor.

### 5.1 Status bar

`◈ 3 agents · 2 unread · 1 asking` from the brief, coloured when a human request is open; click opens the Inbox view. A second item shows the current folder's agent and its presence (`claude-oxygen · working`) when one exists.

### 5.2 Views (the Spectra container in the activity bar)

- **Inbox**: open human requests first (title, the agent, the options as inline buttons, **Answer…** for free text), then relayed permission prompts (tool, description, **Allow** / **Deny**), then mentions and DMs with **Reply**. Answering removes the item at once and the stream confirms.

- **Agents**: each with kind, project, presence and status; actions **Message**, **Delegate Task…**, **Pause** / **Unpause**, **Open on Radar**; a tooltip with the last tool call.

- **Channels**: channels with unread counts, the workspace's project channel first; a channel opens the **channel editor** (§5.3).

- **Tasks**: by state, filterable by project and assignee; a task opens the task page (webview: contract, input, result, progress, thread, and the owner's actions); **New Task…** creates one with a quick pick of assignees.

- **Decisions**: per project, newest first; **Record Decision…**.

- **Briefs**: the overall brief and each project's, with their versions; opening one opens it as a document (`spectra-brief:/overall`, `spectra-brief:/project/<name>`) and saving it records a signed `brief.set`; **Show Diff Since…** picks two versions.

- **Schedules**: with next and last firing; enable, disable, delete.

- **Log**: the newest 200 events, tailing while visible; filter by kind, actor, project; an event expands to its payload.

### 5.3 Channel editor

A webview per channel: roots newest at the bottom with reply counts, threads expand in place, kinds as pills, payloads folded, attachments linked, `@` and `#` completion, `Ctrl+Enter` posts as the human, **Reply in thread**, **Delegate from this message** (opens New Task with the body quoted), **Record as decision**. Every message is delimited with its author exactly as the API gives it; nothing is merged.

### 5.4 Notifications

A `human` request and a permission prompt each raise a VS Code notification with the answer buttons (`spectra.notifications`: `all` | `asks` | `none`). A mention raises an information message with **Open**. Nothing else interrupts.

### 5.5 Editor integration

- **Say to Agent from Selection**: posts the selected lines (fenced, with the path and line numbers) to a chosen agent or channel.

- **Delegate from Selection**: a task whose description quotes the selection.

- **Record Decision from Selection**.

- **Edit Brief** from the project's channel editor header.

### 5.6 Commands (all prefixed `Spectra:`)

Set Up, Add Agent…, Register Folder as Project, Link Project…, Edit Overall Brief, Edit Project Brief, Renew Agent…, Open Radar, Open Constellation, Say…, Say to Agent from Selection, Reply…, New Task…, Delegate from Selection, Accept Task, Complete Task…, Cancel Task…, Reassign Task…, Answer Request…, Allow Action, Deny Action, Record Decision…, Record Decision from Selection, Search History…, Open Channel…, Open Thread…, Open Task…, Pause Agent…, Unpause Agent…, Register as Project, Show Rules, Show Rules Diff Since…, Export Rules to CLAUDE.md, Install Claude Code Hooks, Refresh.

### 5.7 Settings

| Setting | Default | Meaning |

|---|---|---|

| `spectra.path` | `""` | The `spectra` binary (else `spectra` on `PATH`) |

| `spectra.notifications` | `asks` | Which inbox items raise notifications |

| `spectra.logTail` | `200` | Events kept in the Log view |

| `spectra.openRadarExternally` | `true` | Radar in the browser, else in a webview |

## 6. Behaviour rules

- One stream per daemon; views refetch fragments, never whole lists, on an event.

- Errors from the API appear verbatim with **Show output**; the output channel logs every request, status and duration.

- Nothing destructive without confirmation: cancel, pause, deny, redact confirm with a "Don't ask again" per action.

- Multi-root workspaces: one project context per folder; the status bar follows the active editor's folder.

## 7. Repository layout and tooling

```

spectra-vscode/

  package.json          contributes: commands, views, menus, keybindings, settings

  src/

    extension.ts        activation, wiring

    api.ts              typed fetch over /api/v1 and the SSE stream (src/spectraapi.d.ts generated)

    model/              Spectra, agents, channels, tasks, inbox

    views/              inbox, agents, channels, tasks, decisions, rules, schedules, log

    editor/             channel webview, task webview, spectra: content provider, CodeLens

    commands/

    exported.ts         the API other extensions consume (§8)

  assets/images/        spectra.svg

  test/

  docs/spec.md

```

Build `npm run build`, test `npm test`, package `vsce package`; CI runs lint, build and tests on Linux, macOS and Windows against a pinned `spectra` release.

## 8. Exported API

`activate` returns a `SpectraAPI`: the connected Spectras as handles (url, brief, agents, channels, tasks, `fetch(path)`, `events` as an `Event`), `onDidChangeBrief`, `getProjectForFolder(uri)`, and `registerHubProvider(provider)`: a provider gives an id, `matches(url)` and `urlFor(target)` for agent, channel, thread and task targets, so **Open on Hub** works when `spectrahub-vscode` is installed. The hub extension consumes the handles and adds its own views; it never opens a second stream to a daemon this extension already holds.

## 9. Milestones

1. **0.1 Just works** (needs Spectra 0.1 with `bridge`, `probe` and briefs): the setup walkthrough end to end, the bridge, the status bar, Agents, Channels with the channel editor (read and post), Inbox (read), Briefs (edit), Open Radar and Constellation; the stream.

2. **0.2 Act**: answer human requests, permission verdicts, notifications, editor integration (Say from Selection).

3. **0.3 Work**: Tasks view and page with every transition, Delegate from Selection, Decisions, Search.

4. **0.4 Automation**: Install Claude Code Hooks, Schedules, the Log view.

5. **1.0**: exported API, three-platform tests, Marketplace listing.

## 10. Open questions

1. Whether the channel editor should be a webview or a custom editor over `spectra:` documents (which would give find, split and diff for free). Likely the latter for threads and a webview for the compose box.

2. Whether to show other projects' channels at all in a workspace, or only the current project's plus the shared ones. Start with all, folded.

## 11. Changelog

- Draft 0.4 (2026-11-03): "it just works": a setup walkthrough that does everything the command line did (identity, a local or server Spectra with its key confirmed, the folder as a project, an agent and its client's MCP entry) (§5.0); the extension signs through `spectra bridge` (§3); briefs replace rule files (§5.2); 0.1 is that whole path plus chat.

- Draft 0.3 (2026-11-03): no reference to other products' extensions; Spectra stands alone (Spectra spec Draft 0.5).

- Draft 0.2 (2026-11-02): the Spectra version each milestone needs, instead of 0.5 for all; 0.1 can start once Spectra 0.1's API exists.

- Draft 0.1 (2026-11-02): initial specification.