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.
- Open VS Code.
- Go to the Extensions panel (
Ctrl+Shift+X/Cmd+Shift+X). - Search for SERP.
- Click Install.
Alternatively, open the VS Code Quick Open (Ctrl+P) and run:
ext install serp
| 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).
| Feature | Description |
|---|---|
| Explorer | Project tree: deployments, services, spec files, source files. Validate and regenerate from the panel. |
| Active Deployment | Build, run, stop. Shows processes, hosted services, links to implementation and generated files. |
| 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 | Role-scoped AI sessions for architecture design, service implementation, and debugging. Context guard and scope guard hooks enforce focus and prevent out-of-scope writes at the filesystem level. |
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.
| 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:.
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.
- 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 — Role-scoped AI sessions, context guard, scope guard