signature-agent-bridge

Signature Agent Bridge connects Claude Desktop, Claude Code, and your applications through one OpenAI-compatible API and a durable local queue. Install the native integration, keep your own official Claude Code login, and use the OpenAI SDK, Pydantic AI, conversation tools, or a live management console.

Screenshots show the running application with deterministic test data, not a mockup.

Why this project exists

A conversation is a useful place to start work. It is not always enough to coordinate it.

Local scripts need a stable interface. Long tasks need a durable record. Workflows need checkpoints. When a conversation compacts or a subscription reaches a limit, the surrounding application needs to know what happened and how work can continue.

This project adds that coordination layer around the unmodified official Claude Code executable. Each person operates their own bridge with their own subscription. Authentication remains with Claude Code; the bridge does not collect Claude credentials or turn one account into a shared model service.

The motivation is practical: use the tools and subscription you already work with, while making local work observable, manageable, and recoverable.

Related MCP server: Orchestrator MCP Server

What you get

PNG version · Detailed architecture

Quickstart

Before installing either integration

Install Claude Code, then sign in with your own subscription:

claude --version
claude auth login
claude auth status

Use Claude Code 2.1.260 or later. Authentication must report claude.ai and a subscription. Remove API-key/provider overrides from the bridge environment. Release packages include their runtime; Node.js is not required for installation.

Claude Code — install from GitHub

Run these commands inside Claude Code:

/plugin marketplace add signature-organization/signature-agent-bridge
/plugin install signature-agent-bridge@signature-organization

Restart Claude Code so its MCP integration loads. On first load, the plugin downloads the pinned release for your platform, verifies the release checksum, and starts the shared listener. Windows users need Git Bash available as bash.

Then ask:

Use Signature Agent Bridge to check its status. Submit a job that writes a short hello-world note, wait for the result, and show me the management panel.

The included skill is available as:

/signature-agent-bridge:bridge

Claude Desktop — install the extension

1. Download the matching .mcpb from the latest release: darwin-arm64 for Apple silicon, darwin-x64 for Intel Macs, or win32-x64 for Windows.

2. Open Claude Desktop → Settings → Extensions → Advanced settings → Install Extension… and select the file.

3. Enable the extension and complete any installation consent shown by Desktop.

4. Start a conversation and ask:

Check Signature Agent Bridge status, submit a simple test job, and give me the dashboard URL.

The extension includes the service executable and starts it when Desktop activates its MCP server. Desktop uses the locally installed Claude Code executable for automatic jobs.

Already using both hosts? They discover the same local service and queue. Installing the second integration does not create a second subscription identity.

Open the console and run a first job

Ask Claude to call bridge_panel, then open the returned local URL, normally http://127.0.0.1:8766.

Paste the token from owner.token in your bridge data directory:

Select New job, enter a task, and choose Queue job. Open its conversation to inspect progress or send a follow-up. The owner token remains in the browser tab's memory.

Get your bridge token includes clipboard commands for macOS, Windows, and Linux, scoped application tokens, API authentication, revocation, and troubleshooting.

Full installation guide covers verification, updates, portable CLI usage, and troubleshooting.

Connect an application

Create a scoped application token under Diagnostics → Client access, then set it in your shell:

export BRIDGE_URL="http://127.0.0.1:8766"
export BRIDGE_TOKEN="your-scoped-bridge-token"

curl --fail-with-body "$BRIDGE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-example-job" \
  -d '{"model":"bridge/default","messages":[{"role":"user","content":"Write a concise project checklist"}]}'

For the OpenAI SDK and Pydantic AI, use base_url="$BRIDGE_URL/v1", api_key=BRIDGE_TOKEN, and model bridge/default. Follow the complete SDK quickstart, including Python functions, typed output, streaming, and recovery.

PNG diagram · Runnable Pydantic AI example

Native agent work uses the same /v1/chat/completions endpoint with bridge: {"execution":"agent","background":true}. The console and MCP integration use this path too. Management, workflows, and notifications live under /v1/bridge/* and operate on the same queue.

In another terminal, receive durable orchestration events:

curl -N "$BRIDGE_URL/v1/bridge/events" \
  -H "Authorization: Bearer $BRIDGE_TOKEN"

SSE is one-way: the client sends messages and controls with HTTP requests; the server sends events back over the stream. Together they provide bidirectional application communication.

API reference · OpenAPI specification · Runnable JavaScript client · Tunnel setup

Keep work under control

Compaction is handled by Claude itself. The bridge records its boundary and continues using the same native session. Pausing an active CLI job stops its owned process tree and retains the session ID; resuming uses --resume.

A reported quota rejection pauses dispatch durably. A future reset timestamp enables up to three automatic continuations for a resumable job. If the reset is unknown, the session is unavailable, or recovery cannot be established, the job stays available for operator review. A retry starts a new session and can repeat side effects; it is different from a resume.

Execution and recovery · Workflows and subagents

Launch advanced development workflows

Configure the included code-workflow profile, register the advanced-development template, and launch a repeatable plan → implement → review → repair → verify process from Claude, the console, or the API. The planner and reviewer are native Claude Code subagents; the bridge owns the durable sequence and recovery controls.

Step-by-step workflow guide · Launch and observe subagents · Profile example · Template definition · PNG diagram

Explore the console

The interface is tested at 320, 390, 768, 1024, and 1440 pixels. See the complete console tour, including mobile views and the new-job dialog.

Inspect every observed action

Open a job's Activity tab for tool calls, commands, stdout/stderr, and complete inputs/results. Files brings together reported targets, contents, and available edit diffs. The durable audit survives notification retention and can be exported as JSON.

Audit guide and API · PNG diagram · Streaming export example · Mobile inspection

Boundaries that matter

• One person, one local bridge, one subscription identity. Subscription eligibility and usage rules remain Anthropic's. The bridge neither bypasses quotas nor silently falls back to API billing.

• Bypass is not an OS sandbox. Jobs use separate working directories, but allowed tools run with the operating-system permissions of the user. Only give tokens and execution profiles to trusted callers.

• Host consent remains host-owned. Initial login, extension installation, managed policy, and channel enrollment cannot be suppressed by this plugin.

• Desktop and Code have different notification capabilities. Automatic jobs work through both. Optional push notifications into the current Code conversation require channel enrollment; Desktop can inspect channel jobs through tools.

• No exactly-once promise for external side effects. Durable claims prevent duplicate ownership, but a process failure can leave an external action uncertain. Such work requires reconciliation.

See security, compatibility, and the verification record.

Develop and contribute

Source development requires Node.js 24 or later; native packaging requires an official Node.js 26.3.0 distribution.

git clone https://github.com/signature-organization/signature-agent-bridge.git
cd signature-agent-bridge
npm ci
npx playwright install chromium
python3 -m venv .client-venv
.client-venv/bin/pip install -r tests/clients/requirements.txt
BRIDGE_PYTHON="$PWD/.client-venv/bin/python" npm run check

Contributing explains architecture, meaningful tests, license headers, contributors, and release builds.

License and authorship

Copyright © 2026 Signature Management Consultants SLU. Initial author: @ancongui.

Licensed under the Apache License, Version 2.0. First-party source files include the full Apache notice and per-file author attribution. Strict JSON manifests have adjacent .license files. Bundled dependencies retain their own notices.

Claude is a product of Anthropic. This independently developed project is not endorsed by Anthropic.