SpecBox Engine

Agentic Dev for Claude Code

English · Español

One-click setup for the SpecBox Engine agentic programming system.
Skills, hooks, MCP servers, and Engram memory — cross-platform, zero config.

Why SpecBox Engine?

Claude Code is powerful out of the box. SpecBox Engine makes it systematic:

Features

The extension provides 5 commands available from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Plus a sidebar panel with Status and Skills tree views, and a status bar indicator that shows engine health at a glance.

Quick Start

1. Install the extension

Search "SpecBox Engine" in the VSCode Marketplace, or run:

code --install-extension EmbedBuild.specbox-engine

2. Choose your mode on first activate

On the first activation in a workspace, the extension shows a one-time notification with two choices:

• Sign in with GitHub — opens your browser, completes a GitHub OAuth flow via cloud.specbox.build, and stores the resulting MCP token in your OS keychain via VSCode SecretStorage. Enables Native backend (shared tracking, multi-developer reservations).
• Continue in local mode (FreeForm) — no auth, no cloud. All tracking lives on disk under doc/tracking/. See Local mode (no auth) below.

You can switch modes at any time later: Ctrl+Shift+P → SpecBox: Sign in with GitHub or SpecBox: Sign out.

3. Run the onboarding wizard

Ctrl+Shift+P → SpecBox: Onboard Project

The wizard handles everything:

Step 1  →  Check prerequisites (Node, Claude Code, Engram)
Step 2  →  Locate engine repo (auto-detect or clone)
Step 3  →  Install all skills + 20+ hooks + settings
Step 4  →  Configure MCP servers (SpecBox + Engram)

4. Start building

/prd "User authentication with OAuth2"     → Requirements
/plan PROJECT-42                            → Technical plan + UI designs
/implement auth_plan                        → Autopilot implementation

Local mode (no auth)

FreeForm remains first-class. If you pick "Continue in local mode" you get the full engine — skills, hooks, BDD acceptance, MCP tools that do not require shared state — without ever opening a browser or storing a token.

What works without signing in:

• The full pipeline: /prd, /plan, /implement, /audit, etc.
• Trello and Plane backends (you provide their own API keys).
• All non-Native tools (110+ tools).

What requires signing in:

• The Native backend's UC reservation system (multi-developer locking).
• The four native tools: whoami, reserve_uc, release_uc, register_native_branch.

See doc/runbooks/freeform-only-mode.md for a detailed walkthrough.

How sign-in works under the hood

1. You click Sign in with GitHub. The extension starts a one-shot HTTP server on 127.0.0.1 (random port assigned by the OS), generates a 64-hex CSRF state, and opens https://cloud.specbox.build/vscode/issue-token in your default browser, passing the loopback URL and state as query params.
2. The cloud handles the GitHub OAuth dance (no plaintext credentials ever touch the extension or the engine — only the cloud).
3. The cloud redirects back to the loopback with ?mcp_token=spbx_<base64url>&state=<csrf>. The token shape is the cloud's issueMcpToken() output — spbx_ prefix + base64url body, mirroring the engine's register_mcp_token algorithm.
4. The extension validates the state, regex-checks the token, persists it to VSCode SecretStorage (Keychain on macOS, Credential Manager on Windows, libsecret on Linux), and tells Claude Code to respawn the MCP server so the token is in scope.
5. If the token is revoked on the cloud, the engine reports UNAUTHENTICATED on the next native tool call (≤30s thanks to the server-side auth cache TTL). The sidebar polls every 60s and updates on its own — total revoke-visibility ≤ 90s.

The cloud side is implemented in EmbedBuild/specbox_cloud (US-09). See doc/decisions/native_default_oauth.md for the architectural rationale and the residual security trade-offs.

Activation telemetry (funnel)

To measure how many people who discover SpecBox on the website actually install the extension, the extension emits a single, anonymous activation event the first time it runs after installation. This closes the loop with the website's anonymous funnel (page view → install intent → activation).

How it works:

1. When you click Get the extension on the SpecBox site, the site opens a deep-link vscode://EmbedBuild.specbox-engine/activate?anon_id=<uuid>. The anon_id is the website's opaque, randomly-generated anonymous session id — it is not tied to your identity, GitHub account, email, or repository.
2. The extension validates the anon_id (must be a UUID v4) and stores it in VS Code global state.
3. On the next activation, the extension posts one activation event to the public funnel endpoint (the same Supabase project the website uses). The event carries the anon_id (so the install can be correlated with the anonymous web session) plus a small technical meta block: extension version, OS platform, and VS Code version. Nothing else.
4. The event is emitted at most once per install (an idempotency flag in global state). If the deep-link anon_id never arrived (e.g. you installed from the Marketplace directly), the activation is still emitted, just without a web-session origin.

What is never sent: local file paths, your git email or name, workspace or repo contents, MCP/auth tokens, or any other personally identifiable data. The anon_id is opaque and is never enriched.

Respecting your preferences: if you have disabled VS Code telemetry (telemetry.telemetryLevel: "off", surfaced as vscode.env.isTelemetryEnabled), the extension emits nothing. The emitter is fully best-effort and fire-and-forget — it never blocks activation and never surfaces errors to you.

Implementation: src/activation.ts (US-26, UC-2601/UC-2602).

Requirements

• Claude Code — install or the official Claude VSCode extension.
• Node.js 18+ — download
• Git — download
• VSCode 1.86+ — required for runtime localization (vscode.l10n).

What Gets Installed

15 Agent Skills

20+ Quality Hooks

Automatic enforcement — Claude Code follows the rules without being told:

2 MCP Servers

Settings

Languages

The extension UI and Marketplace listing are available in:

• 🇺🇸 English (default, canonical)
• 🇪🇸 Spanish (España, neutral)

VSCode auto-resolves the language based on vscode.env.language. To force a locale, launch VSCode with code --locale=es or code --locale=en.

Cross-Platform

The extension uses symlinks where possible, with automatic fallback to file copy on Windows.

Troubleshooting

For other issues, open an issue on GitHub.

Terminal Alternative

For CI/CD or headless environments (macOS/Linux only):

git clone https://github.com/EmbedBuild/specbox-engine.git ~/specbox-engine
cd ~/specbox-engine && ./install.sh

Note: install.sh does not configure MCP servers. See Getting Started for manual MCP setup.

SpecBox Engine by JPS
_{Agentic programming system for Claude Code}
GitHub · Docs · Issues · Changelog