SemanticMatter Autonomous Development

A Visual Studio Code extension that provides a read-only observer and visual control plane for the autonomous feature-development workflow implemented by quaat/autonomous-development.

It discovers workflow runs created by the external Python controller, visualizes their progress and artifacts, compares prompt/specification revisions in the native diff editor, surfaces verification and review results, and exposes safe controller actions — without requiring you to navigate the external state directory by hand. It works even when a run was started entirely outside VS Code.

The extension is observer-first. It does not orchestrate Claude or Codex directly; it reads the state the existing workflow already writes and adds a typed, append-only event protocol (events.jsonl) that later live integrations can emit. See ROADMAP.md.

Features

• Activity-bar container with three native tree views: Active, Completed, and Archived runs. Each run exposes its id, feature summary, status/phase, repository/worktree, verification pass/fail counts, review round vs. budget, latest verdict, adversarial-review requirement, and unresolved completion gates.
• Workflow dashboard (webview) for a selected run: a stage timeline, current status, the prompt/artifact evolution chain, verification commands and results, Codex review rounds with findings, adversarial-review state, completion-gate failures, and the recommended next action.
• Artifact viewing & comparison: open the original feature, enhanced/accepted specs, proposed/accepted plans, latest review, and verification logs in normal editors; compare original idea ↔ accepted spec and proposed ↔ accepted plan in the native VS Code diff editor. Clicking a review finding opens the file at the correct source line.
• Safe controller actions: evaluate completion gates, accept repository drift, cancel, and archive — each targeting an explicit run id, invoked through an argument array (never an interpolated shell string), confirmed before mutating, and disabled in untrusted workspaces.
• Live refresh: watches run-state.json, events.jsonl, and artifacts, and refreshes the UI (debounced) without a manual reload. A malformed or half-written file produces a precise diagnostic instead of crashing the view.

Requirements

• VS Code ^1.85.0, Node >=18.
• For controller actions only: a local checkout of quaat/autonomous-development and Python. Observer features need neither.
• No Claude or Codex credentials are required to run or test the extension.

Installation

From a packaged .vsix:

npm install
npm run package          # → packages/vscode-extension/semanticmatter-autonomous-development.vsix
code --install-extension packages/vscode-extension/semanticmatter-autonomous-development.vsix

Usage

1. Open a Git repository in VS Code and select the Autonomous Development activity-bar icon.
2. Runs are discovered from the resolved state home (see Configuration). Runs started outside VS Code appear automatically.
3. Select a run to open its dashboard; expand a run in the tree for quick details.
4. Use the run's context menu (or the dashboard buttons) to open or compare artifacts, inspect reviews, or run controller actions.

If no runs appear, use Set Up Controller (or just point autonomousDev.stateHome at your state directory). Observer features work without a controller.

Configuration

Setting	Default	Purpose
autonomousDev.controllerPath	""	Absolute path to scripts/controller.py. Empty ⇒ observer-only.
autonomousDev.stateHome	""	Override for the state-home directory.
autonomousDev.pythonPath	python3	Python executable used for controller actions.
autonomousDev.autoRefresh	true	Refresh views when state files change.
autonomousDev.notificationLevel	important	all / important / none.
autonomousDev.maxEventLogEntries	5000	Max events.jsonl entries retained per run in memory.
autonomousDev.loadCompletedRuns	true	Load terminal runs into Completed.
autonomousDev.loadArchivedRuns	false	Load archived runs into Archived.

State-home precedence (mirrors the reference project): the autonomousDev.stateHome setting → CLAUDE_AUTONOMOUS_STATE_HOME → platform default (~/.local/state/claude-autonomous on Linux, ~/Library/Application Support/claude-autonomous on macOS, %LOCALAPPDATA%/claude-autonomous on Windows). The legacy in-repo layout <repo>/.ai/autonomous-development/ is detected for read-only inspection.

Development

This is an npm-workspaces TypeScript monorepo:

packages/protocol/        # versioned RunEvent protocol (no vscode, no deps)
packages/core/            # state parsing + shared workflow evaluator (no vscode)
packages/vscode-extension # the VS Code UI
resources/                # prompts, schemas, skills mirrored from the reference
docs/                     # REFERENCE.md compatibility contract

npm install            # install all workspaces
npm run build          # build libs (tsc -b) then bundle the extension (esbuild)
npm run typecheck      # strict type-check of host + webview
npm run lint           # eslint
npm test               # protocol + core unit tests (Mocha + node:assert)
npm run test:integration  # VS Code integration tests (downloads VS Code)
npm run package        # produce the .vsix

The integration tests launch a real VS Code instance, so the first run downloads it and requires a display (use xvfb-run on headless Linux).

Documentation

• ARCHITECTURE.md — package boundaries and data flow.
• PROTOCOL.md — the RunEvent envelope and compatibility rules.
• SECURITY.md — trust boundaries and sensitive-data handling.
• CONTRIBUTING.md — workflow and coding standards.
• ROADMAP.md — planned Claude Agent SDK and Codex app-server adapters.
• docs/REFERENCE.md — the exact quaat/autonomous-development compatibility contract this extension implements.

License

MIT.