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, Python, Claude Code, Engram)
Step 2  →  Locate engine repo (auto-detect or clone)
Step 3  →  Install 15 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.

Requirements

• Claude Code — install or the official Claude VSCode extension.
• Node.js 18+ — download
• Python 3.12+ — 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