Claude Bridge

Motivation

Starting 2026-06-15, claude -p and the Claude Agent SDK / GitHub Actions surfaces draw from a dedicated programmatic-credit pool rather than the Max/Pro subscription quota (@ClaudeDevs announcement, 2026-05-13). Interactive claude sessions stay on the subscription pool.

@desplega.ai/claude-bridge is a Desplega-owned drop-in replacement for common claude -p automation. It starts interactive Claude Code inside tmux, sends the prompt through the pane, tails Claude's JSONL transcript, and emits Claude-compatible text, json, or stream-json output. From the swarm's perspective, the usual Claude adapter flags still apply.

How to opt in

Set one reloadable env on the worker:

SWARM_USE_CLAUDE_BRIDGE=true

Accepted values:

When enabled, the swarm spawns:

claude-bridge -p "..." --model ... --output-format stream-json ...

You do not need to set CLAUDE_BINARY for claude-bridge. SWARM_USE_CLAUDE_BRIDGE=true wins over CLAUDE_BINARY.

Reloadable via swarm_config

SWARM_USE_CLAUDE_BRIDGE participates in the same overlay-then-fallback pattern as CLAUDE_BINARY and HARNESS_PROVIDER. The runner fetches swarm_config on the poll loop and applies safe reloadable keys to process.env; each new Claude session also receives the resolved env overlay in config.env.

Precedence (highest first):

1. swarm_config SWARM_USE_CLAUDE_BRIDGE (scope: repo > agent > global)
2. process.env.SWARM_USE_CLAUDE_BRIDGE (container env)
3. disabled

Set it from your dashboard, the MCP set-config tool, or PUT /api/config:

curl -X PUT "$MCP_BASE_URL/api/config" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"scope":"global","key":"SWARM_USE_CLAUDE_BRIDGE","value":"true"}'

In-flight task sessions stay on the binary they spawned with; new spawns pick up the change.

Requirements

• Bun >= 1.1. The npm package is @desplega.ai/claude-bridge; the published bin uses #!/usr/bin/env bun.
• tmux on PATH. The bridge starts interactive Claude Code in a detached tmux pane. The swarm fail-fasts at session-create when tmux is missing.
• claude on PATH, version >= 2.1.80. The bridge launches the local Claude CLI.
• Auth: unchanged. The normal Claude harness credential check still applies: CLAUDE_CODE_OAUTH_TOKEN is preferred, with ANTHROPIC_API_KEY as the alternate accepted by the swarm. The bridge itself relies on the spawned claude process auth.

Prompt pre-clear

The swarm adapter pre-seeds Claude's global project trust/onboarding entries before it spawns Claude Bridge. Bridge mode launches interactive Claude Code inside tmux, so this prevents the first-run trust prompt from blocking or exiting before the bridge becomes ready.

Claude Bridge then writes per-workdir .claude/settings.local.json for dangerous-mode bypass, launches Claude with --dangerously-skip-permissions, and auto-accepts supported startup prompts from the tmux pane.

Legacy compatibility

Existing legacy bridge deployments that set CLAUDE_BINARY directly continue to work:

CLAUDE_BINARY="<legacy-bridge-command>"

CLAUDE_BINARY is still whitespace-split into argv tokens and is still reloadable through swarm_config. When the resolved value matches the legacy bridge binary, the adapter:

• emits a deprecation warning pointing to SWARM_USE_CLAUDE_BRIDGE=true
• checks that tmux is on PATH
• runs the same $HOME/.claude.json trust pre-seed before spawning

Use this only as a compatibility path while migrating.

Why not a new HARNESS_PROVIDER?

Claude Bridge is a drop-in replacement for the claude binary inside the existing claude harness: same provider adapter, same MCP plumbing, same Stop-hook behavior, and the same spawned Claude flags. Keeping it as a reloadable env variant avoids a duplicate provider while still letting operators flip the subscription-pool bridge per worker or per repo.

See also: runbooks/harness-providers.md — engineering reference for the bridge and compatibility wiring.