Spectra for Visual Studio Code

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 Spectra knows, 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

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

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; 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…, 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

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); 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.5 (2026-11-03): Spectra has no web interface any more (Spectra spec Draft 0.7): the extension is its local view and SpectraHub its website; Open Radar and Open Constellation are gone.
• 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.