Motivation

Anthropic paused the announced separate SDK credit pool on June 15, 2026. Its support update, checked September 9, says SDK and claude -p usage still consume subscription limits. OAuth authentication success does not establish how an individual account is billed. Bridge selection remains an explicit operator choice.

@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.

Prior art: Claude Bridge was inspired by Shannon's interactive-CLI bridge concept, but the supported path in agent-swarm is Desplega's @desplega.ai/claude-bridge.

How to opt in

Set one reloadable env on the worker:

SWARM_USE_CLAUDE_BRIDGE=true

Accepted values:

Value	Behavior
`true`, `1`	Route the Claude adapter through the installed `claude-bridge` binary
`false`, `0`, unset	Use the normal `CLAUDE_BINARY` resolution path, defaulting to `claude`

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):

swarm_config SWARM_USE_CLAUDE_BRIDGE (scope: repo > agent > global)
process.env.SWARM_USE_CLAUDE_BRIDGE (container env)
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

Use CLAUDE_TRANSPORT=cli for bridge sessions. The SDK transport rejects an effective bridge, including direct and legacy bridge binaries. The bridge does not implement the SDK control protocol. The adapter preserves the existing fallback when the bridge flag is enabled without OAuth credentials.

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: an OAuth token is required. The bridge authenticates the spawned claude from CLAUDE_CODE_OAUTH_TOKEN only — it deliberately strips ANTHROPIC_* from the launched process. Bridge mode is therefore gated on an OAuth token: if SWARM_USE_CLAUDE_BRIDGE is set but no CLAUDE_CODE_OAUTH_TOKEN is present, the adapter logs a warning and falls back to stock claude (which Claude Code authenticates fine from ANTHROPIC_API_KEY). API-key billing is identical headless vs interactive, so the bridge buys nothing there.
Claude's on-disk transcript must stay enabled. The bridge reconstructs all of its output — cost/token/duration metrics and the streamed assistant/tool-use events — by reshaping Claude Code's session transcript (~/.claude/projects/<slug>/<sessionId>.jsonl). Anything that suppresses that file breaks the bridge: notably CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 makes Claude Code emit only init + a null-metrics result ($0 / 0 tokens / 0ms), with answer text only via the inline last_assistant_message. The swarm's Claude runtime guardrails set that var; claude-bridge >= 0.2.2 strips it from the launched claude so the transcript persists.

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 remains an executable variant inside the existing Claude provider. Operators can select the bridge per worker or repository without creating a separate provider.

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

Claude Bridge