A VS Code extension and MCP server for block-level artifact review with agent feedback loops.
Orbit lets you review generated artifacts (implementation plans, specs, etc.) directly in VS Code with semantic, block-anchored comments — not fragile line-based annotations. Agents can participate in the review cycle via MCP tools.
- Source (
plan.md) — a markdown document (written by you or generated by an agent) - Resolved artifact (
plan.md.resolved) — auto-generated review artifact with stable block IDs and frontmatter - Comments (
plan.md.comments.json) — block-anchored comment threads - Review state (
plan.md.review.json) — tracks approval status and staleness
draft → in_review → changes_requested → in_review → approved
→ approved → stale (if source changes) → in_review
open → resolved | agent_applied | outdated (if block disappears on regeneration)
VS Code editor:
- Custom editor for
*.md.resolvedfiles with React-based UI - Hover-to-comment on any block
- Inline threads with open/resolved/agent_applied/outdated states
- Approve, Request Changes, and Regenerate from the toolbar
- Keyboard navigation (
j/kfor blocks,[/]for threads) - Staleness detection and regeneration
MCP server (for agents):
orbit_generate_resolved— generate a resolved artifact and open it in VS Codeorbit_load_artifact— load an artifact's contentorbit_list_blocks/orbit_list_threads— inspect structure and feedbackorbit_get_review_state— check approval statusorbit_add_comment/orbit_reply/orbit_resolve_thread— participate in revieworbit_approve/orbit_request_changes— update review stateorbit_await_review— block until the user approves or requests changes
- Node.js 18+
- VS Code 1.85+
npm install
npm run buildThis produces three bundles in out/:
extension.js— VS Code extensionwebview.js— React webview UImcp-server.js— MCP server (stdio)
npm run package # creates orbit-artifact-review-0.1.0.vsixThen install the .vsix in VS Code (Extensions > ... > Install from VSIX).
node out/mcp-server.js
# or via the bin entrypoint:
orbit-mcpnpm run watch # rebuild on changes
npm run lint # type-check
npm test # run tests (vitest)src/
├── extension.ts # VS Code activation and command registration
├── editor-provider.ts # Custom editor provider for .md.resolved files
├── webview/app.tsx # React webview app
├── mcp/server.ts # MCP server with tool definitions
├── browser/components/ # React UI components
├── node/ # Core services
│ ├── artifact-file-service.ts # Bundle I/O, hashing, path conventions
│ ├── artifact-comment-service.ts # Thread CRUD and reattachment
│ ├── artifact-review-service.ts # Review state machine
│ ├── artifact-resolution-service.ts # Resolved artifact generation
│ ├── artifact-agent-bridge.ts # Agent integration interface
│ └── __tests__/ # Tests
└── common/ # Shared types, parsers, schemas
MIT