Wacht Bench

Wacht Bench is the AI-assisted development surface for Wacht.

It bundles the things AI coding assistants need to build Wacht apps without guessing:

• Skills — task-shaped playbooks installed under ./skills, scoped per framework and per platform surface.
• Docs MCP — the Wacht Docs MCP server at https://wacht.dev/docs/mcp, so assistants always read the current SDK, API, and guide content instead of hallucinating.
• Bench CLI (@wacht/bench) — init, login, projects, deployments, users, orgs, workspaces, config, api, and completion commands for everything else.

The CLI is opinionated about being agent-first: it scaffolds context, never patches your app code. Your editor agent does the wiring.

Install Wacht skills

Install the full skill pack:

wacht skills add

Install one skill:

wacht skills add --skill wacht-nextjs-patterns

Use the Bench CLI

Run without installing:

npx @wacht/bench init

After npm i -g @wacht/bench (or pnpm add -g @wacht/bench), the binary is wacht:

wacht init
wacht login
wacht deployments select
wacht --version

wacht init detects Next.js, React Router, and TanStack Router projects, then writes a short, agent-readable context: .env.wacht.example (the SDK env vars your app actually reads) and a ## Wacht Bench block in your AGENTS.md that tells your assistant which skill to load, where to find the Docs MCP, and which CLI commands to use. It does not wire framework code, patch app files, or edit package dependencies.

Bootstrap a new project

init --starter clones a ready-to-run starter and bootstraps it.

wacht init --starter nextjs           # → ./wacht-nextjs-starter
wacht init --starter react-router
wacht init --starter tanstack

Pass --target <dir> to choose the destination.

Connect Wacht Docs MCP

wacht mcp install detects every supported AI client on the machine and lets you bulk-apply the Wacht Docs MCP server to the ones you pick.

wacht mcp install              # interactive: detect + multi-select + apply
wacht mcp list                 # show known clients + detection + install status
wacht mcp uninstall            # remove from selected clients

Non-interactive form for CI or scripts:

wacht mcp install --client cursor-user,vscode-user,codex --yes
wacht mcp install --all --yes

Supported clients (user and project scope where applicable):

• Claude Desktop
• Claude Code (~/.claude.json or .mcp.json)
• Cursor (~/.cursor/mcp.json or .cursor/mcp.json)
• VS Code (mcp.json)
• Windsurf
• Codex CLI (TOML)

Bench merges the wacht-docs server into the existing config — other servers are preserved. Use wacht mcp config --client <name> to print raw JSON for a client without writing to disk.

See Docs MCP for more setup options.

Drive the platform from the terminal

Once you are signed in (wacht login) and have an active deployment (wacht deployments select), Bench can drive the Wacht Machine API directly:

wacht projects list
wacht deployments current

wacht users list
wacht users get <user_id>
wacht users create --field email_address=person@example.com

wacht orgs list
wacht orgs get <organization_id>
wacht orgs create --field name="Acme"

wacht workspaces list --org <organization_id>
wacht workspaces create --org <organization_id> --field name="Production"

For everything not yet wrapped as a first-class command, Bench exposes the full Wacht Platform OpenAPI surface:

wacht api ls --search users
wacht api describe createUser
wacht api call createUser --field email_address=person@example.com

The schema is cached at ~/.wacht/platform-api.openapi.json; pass --refresh to refetch.

Manage deployment settings as code

wacht config pull --file wacht.config.json
wacht config diff --file wacht.config.json
wacht config apply --file wacht.config.json --dry-run
wacht config apply --file wacht.config.json --yes

Production applies require an explicit deployment confirmation:

wacht config apply --file wacht.config.json --production --confirm <deployment_id> --yes

Secrets and provider credentials are never written to config files.

Shell completion

wacht completion bash > /etc/bash_completion.d/wacht
wacht completion zsh  > "${fpath[1]}/_wacht"
wacht completion fish > ~/.config/fish/completions/wacht.fish

Recommended assistant instruction

Drop this into your AGENTS.md or assistant rules so every Wacht task starts in the right place:

Use Wacht skills for Wacht implementation work.
Before coding, use Wacht Docs MCP at https://wacht.dev/docs/mcp for current Wacht SDK, API, and guide details.
Run the validation commands named by the active skill before finishing.

wacht init writes a project-scoped AGENTS.md block that includes this guidance, plus a routing table that points agents at the right skill, MCP, and CLI commands for each task.

What the skill pack covers

• New Wacht setup and framework detection
• Next.js, React Router, and TanStack Router patterns
• Backend JS integrations
• Organizations and workspaces
• API Auth and OAuth clients
• Webhooks and replay
• Notifications and realtime streams
• Agents, MCP servers, approvals, hooks, and skill bundles
• Testing Wacht auth and integration flows

Read next

• Bench Skills
• Docs MCP
• Next.js Quick Start
• Backend JS SDK