Skip to content

Plugin Overview

Jump to bottom
Oleksandr Geronime edited this page Jul 16, 2026 · 4 revisions

SERP VS Code Plugin — Overview

The SERP VS Code plugin is the control surface for spec-bounded AI development. It is where architecture, generation, runtime observation, and role-scoped AI sessions come together.

The Explorer shows the architecture. The Dashboard shows it running. The Inspector lets you call into running services directly. AI Sessions are how you design, implement, and debug within enforced scopes. The current extension uses Claude Code as its first agent backend, but the session model is modular: context, scope, workflow, validation, and runtime tools belong to SERP, while the AI agent is an adapter. Everything is derived from the same specs/ tree.

Installation

  1. Open VS Code.
  2. Go to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).
  3. Search for SERP.
  4. Click Install.

Alternatively, open the VS Code Quick Open (Ctrl+P) and run:

ext install serp

Requirements

Requirement Purpose
A SERP workspace open in VS Code The extension activates when it detects specs/serp.sidl in the workspace root
serp-dev package installed Provides the serpgen CLI used for validation and code generation
grpcurl (macOS) Required for the Runtime Inspector when using the gRPC transport
gdbus (Linux) Required for the Runtime Inspector when using the DBus transport; available by default as part of glib

The extension activates automatically when a SERP workspace is opened (detected by the presence of specs/serp.sidl).

Features

Feature Description
Explorer Project tree: specs, deployments (build/run/stop, processes, hosted services), services (interfaces, sequences, tests, generated + impl files). Validate and regenerate from the panel.
Architecture Dashboard Interactive live view: process cards, live CPU/MEM stats, dependency arrows, one-click detail panels.
Runtime Inspector Call methods, read and watch properties, subscribe to notifications. Works over gRPC or DBus. No client code needed.
SERP AI Sessions Scoped AI sessions — architecture, service, HMI, sequence, debug/fix, freeform exploration — on a pluggable agent backend (Claude Code or Codex). Context guard and scope guard hooks enforce focus and prevent out-of-scope writes at the filesystem level.
Design Contracts Durable, user-approved design blocks (specs/**/*.design.yaml) that gate what an AI session may call "implemented" — with a sync path for projects adopting it after the fact.
SERP AI Runs Batch-plans and spawns implementation sessions for every design block that isn't implemented yet (or needs updating), project-wide, as one resumable job.
SERP AI Configuration Per-project editor for session-kind roles, workflows, and context — without touching the extension's shipped defaults.
SERP AI Settings Per-project agent backend, model/effort/thinking, and test-generation preferences.

Status Bar Items

The extension adds three items to the VS Code status bar:

  • Active Deployment selector (left side, high priority) — shows the currently selected deployment; click to switch.
  • Build Profile selector (left side) — shows the active build profile (Auto, Dev (gRPC), Dev (DBus), Release); click to change.
  • Run State indicator — shows whether the deployment is running, stopped, or in an unknown state.

Keyboard Shortcuts

Action macOS Linux / Windows
Validate specs Ctrl+Option+V Ctrl+Alt+V
Generate Ctrl+Option+G Ctrl+Alt+G
Architecture Dashboard Ctrl+Option+D Ctrl+Alt+D
Build Ctrl+Option+B Ctrl+Alt+B
Run Ctrl+Option+R Ctrl+Alt+R
Stop Ctrl+Option+S Ctrl+Alt+S

All shortcuts are also available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) by searching for SERP:.

Extension Commands

All commands are registered under the serp.explorer.* and serp.ai.* namespaces. You can browse the full list in the Command Palette by typing SERP.

Further Reading

  • Explorer — Project tree, file navigation, toolbar actions
  • Architecture Dashboard — Live process view, dependency arrows, per-process controls
  • Runtime Inspector — Call methods, watch properties, subscribe to notifications
  • Build Profiles — Choosing a build profile for runtime debugging
  • SERP AI Sessions — Session kinds, agent backends, Configuration and Settings panels
  • Design Contracts — Durable, approved design blocks and the sync path for existing projects
  • Implementation Runs — Batch-spawning implementation sessions from design/state drift

SERP Wiki

Getting Started

The Development Model

Architecture Language

Code Generator

Framework Internals

VS Code Plugin

Examples

Clone this wiki locally