Skip to main content
Glama
trollbot2012

worker-bridge

by trollbot2012
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

worker-bridge

Delegate coding tasks to external AI coding agents — in isolated git worktrees, with independent verification — from any agent, over MCP.

worker-bridge lets one AI agent hand a scoped coding job (implement a feature, fix a cross-file bug, run a migration) to an external coding CLI — Codex, Claude Code, OpenCode, or any command-line agent — inside an isolated git worktree, then independently verifies the diff itself before handing it back. It exposes this as an MCP server, so any MCP-capable client (Claude Code, Cursor, Windsurf, Cline, Continue, …) can use it with zero code.

Dispatching agents is commodity. worker-bridge is about dispatching with a provable chain of custody: isolated execution, host-wide concurrency limits, an independent verification gate, and secret-safe event logs.

Why

  • Isolation by default — each task runs in its own git worktree on a fresh branch. Workers never touch your working tree.

  • Independent verification — the orchestrator runs your verification commands (pytest -q, npm test, …) itself, separately from the worker, and records the result. A worker can't mark its own homework.

  • Cross-process safety — task ownership is an atomic SQLite claim and concurrency is enforced by DB-backed leases, so many independently-launched runners can share one host without double-executing a task or overrunning limits.

  • Windows-aware — cancellation kills the whole worker process tree (validated by command line, so a recycled PID is never killed).

  • Secret-safe — connection strings, PEM keys, and cloud key IDs are redacted before anything is persisted.

  • Multi-worker — run the same task on several workers and compare, or run an implementer + a reviewer.

These guarantees come from an independent production audit of the engine; see docs/audit.md for the findings.

Related MCP server: agent-locks

Install

pip install worker-bridge-mcp

You also need at least one worker CLI on your PATH — e.g. Codex, Claude Code, or OpenCode. Run worker-bridge workers list to see what's detected.

Use it as an MCP server

The server runs over stdio. Add it to your MCP client:

Claude Code

claude mcp add worker-bridge -- worker-bridge-mcp

Cursor / Windsurf / Cline / Continue — add to the client's MCP config (mcp.json / settings):

{
  "mcpServers": {
    "worker-bridge": {
      "command": "worker-bridge-mcp"
    }
  }
}

Optional environment:

{
  "mcpServers": {
    "worker-bridge": {
      "command": "worker-bridge-mcp",
      "env": { "WORKER_BRIDGE_HOME": "/path/to/state", "WORKER_BRIDGE_MAX_CONCURRENCY": "4" }
    }
  }
}

Tools

Tool

What it does

worker_delegate

Start a scoped coding task on a worker in an isolated worktree; returns a task_id.

worker_status

Poll a task: status, summary, changed files, verification result, artifact paths.

list_workers

Which coding workers are installed and healthy on this machine.

worker_cancel

Cancel a task and terminate its worker process tree.

worker_logs

Normalized event stream for a task (progress, completion, verification).

Typical flow, from the host agent's side: call worker_delegate(objective=…, repository=…, verify=["pytest -q"]), then poll worker_status(task_id) until it's succeeded/failed. The changed files land in an isolated worktree plus a diff artifact; nothing is merged into your branch automatically.

Use it as a CLI

worker-bridge workers list
worker-bridge tasks create --objective "Add a --json flag" --repo /abs/path/repo --worker codex --verify "pytest -q"
worker-bridge tasks start <task_id> --wait
worker-bridge tasks show <task_id>

Workflow-typed dispatch

tasks create --type {chore,feature,hotfix,refactor} shapes the task at creation time. The profile fills only fields you left unset — explicit --worker/--priority/--timeout (or keys in a --spec contract) always win. chore → priority 30, 900s budget, cheapest adequate worker; hotfix → priority 90 with a tight 1800s budget. The type lands in spec.metadata.type for downstream tooling. Profiles live in worker_bridge/workflows.py.

Verification auto-repair

When independent verification fails, the failing commands' exit codes and output tails are piped back into the worker's native session as a follow-up, and the follow-up run re-verifies — bounded by verification_auto_repair in config (default 1 attempt), per-task metadata.auto_repair (0 disables), and limits.maximum_follow_up_turns. Repair attempts emit verification.auto_repair events; only an unrepairable failure counts toward the worker's circuit breaker. Deterministic checks stay outside the agent loop — tokens are spent only when a check fails and its output carries information the worker needs.

Use it as a Python library

import asyncio
from worker_bridge import WorkerBridge

bridge = WorkerBridge()
task = bridge.create_task({
    "objective": "Add a --json flag to the CLI",
    "worker": "codex",
    "workspace": {"repository": "/abs/path/to/repo", "isolation": "git_worktree"},
    "verification": {"commands": ["pytest -q"]},
})
result = asyncio.run(bridge.start_task(task["task_id"]))
print(result["status"], result["result"]["metadata"]["verification"]["ok"])

Workers

Built-in adapters:

  • codex, claude-code, opencode — the mainstream coding CLIs.

  • zcode-glm — Claude Code pointed at an Anthropic-compatible endpoint (default Z.ai GLM). A template for any alternate endpoint: subclass or construct with a different base_url/model; the auth token is read from an env var by name (ZCODE_AUTH_TOKEN) so it never lands in a task spec or result.

  • vscode (experimental) — delegates into a running VS Code window via the companion vscode-extension/ (a loopback HTTP bridge on 127.0.0.1:9394). Install/run the extension first; without it the worker fails closed cleanly. See vscode-extension/README.md.

  • mock — deterministic, for tests.

Any other non-interactive coding CLI can be linked without code:

worker-bridge workers link my-agent --command-json '["my-agent","run","{prompt}"]'

Accepting work

A task's changes live in an isolated worktree and are never merged automatically. When you're satisfied, worker-bridge tasks accept <task_id> copies the verified changes back into the source repository (under a repository lock, refusing symlink escapes). Only independently-verified successful tasks can be accepted.

Configuration

State lives under WORKER_BRIDGE_HOME (default ~/.worker-bridge/): the SQLite store, worktrees, and artifacts. Tunables via env or ~/.worker-bridge/config.yaml:

Env

Default

Meaning

WORKER_BRIDGE_HOME

~/.worker-bridge

State root

WORKER_BRIDGE_MAX_CONCURRENCY

4

Global concurrent workers (host-wide)

WORKER_BRIDGE_REPO_CONCURRENCY

3

Concurrent workers per repository

WORKER_BRIDGE_STORE

—

Override the SQLite path

Storage safety

Workspace allocation is designed so a delegation can never quietly eat the disk:

  • Containment — the worker root and the target repository must never contain each other (checked by path math, not names), so a task can never recursively copy earlier tasks' workspaces into itself. Copying a repo at or above the bridge home requires an explicit allow_profile_copy opt-in, and copy sources containing symlinks/junctions are refused outright.

  • Copy budgets + disk reserve — copy isolation measures the source first (honoring cache/VCS exclusions like .git, node_modules, __pycache__) and refuses anything over 2 GiB / 50k files; the copy must also leave at least max(10 GiB, 5% of capacity) free on disk.

  • Two-phase allocation — the destination is planned and persisted (allocation_state: "allocating") before any filesystem mutation, and the mutation runs under a timeout. A crash, kill, or hang always leaves a task record naming the directory it was building, a clean failed/timed_out state, and a swept partial tree — never an unfindable half-copied giant.

  • Prune — worker-bridge workspaces prune (dry-run by default; --apply to delete, --include-paused to widen) and the worker_prune MCP tool reclaim worktrees of terminal tasks plus orphan directories no task record references. Accepted tasks reclaim their worktree automatically.

Security

Custom/read-only permission profiles are checked after execution and are not an OS sandbox — the real filesystem boundary is the worker client's own sandbox (Codex workspace-write, etc.), which the bridge selects per profile. Symlink escapes are detected and fail the task; a raw path-traversal write by a sandbox-less worker cannot be seen post-hoc. Do not point a full_access worker at hostile input without a container. Secrets are redacted from the event log and store.

License

MIT — see LICENSE.

Available Tools

5 tools
list_workersA

List available coding workers on this machine (installed and healthy), with their capabilities. Call this to see which worker values worker_delegate can use before delegating.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of behavioral disclosure. It states that workers listed are 'installed and healthy' and includes capabilities, which gives insight into the tool's behavior. It does not mention side effects or performance characteristics, but for a read-only list tool, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, no wasted words. It front-loads the main action and adds a usage hint in the second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains that the tool returns workers 'with their capabilities', but does not detail the structure of the output. For a simple list tool, this is mostly adequate, but a more complete description could specify the output format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters. According to guidelines, 0 parameters yields a baseline score of 4. The description does not need to add parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists available coding workers with their capabilities, using a specific verb 'list' and resource 'coding workers'. It distinguishes itself from sibling tools like worker_delegate by specifying it is meant for checking which workers are available.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool: 'Call this to see which worker values worker_delegate can use before delegating.' This provides clear context and implies a workflow. However, it does not mention when not to use it or any alternatives beyond the implied sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

worker_cancelA

Cancel a running or queued delegated task and terminate its worker process tree. Returns the task's terminal state.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the destructive action of terminating the worker process tree and indicates the return value (terminal state). This provides meaningful behavioral context beyond a simple 'cancel' command.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct with two sentences, front-loading the core action and return value. Every word contributes information, with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one param, no output schema), the description covers the essential purpose and behavior. It could mention error conditions or prerequisites, but it is sufficiently complete for a cancel operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only implicitly references the task_id parameter without describing its format or adding meaning. The parameter 'task_id' is left without any elaboration in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: cancel a running or queued delegated task and terminate its worker process tree, and it returns the task's terminal state. The verb 'cancel' is specific and directly distinguishes this from sibling tools like worker_delegate and worker_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for tasks that are running or queued, but does not provide explicit guidance on when not to use this tool or mention alternatives. It lacks clear context for selecting this tool over siblings beyond the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

worker_delegateA

Delegate a scoped coding task to an external AI coding worker in an isolated git worktree, then independently verify the result.

USE for: implementing a feature, fixing a bug across files, a refactor or migration — work you'd otherwise do inline. Delegating keeps your context clean and gets an independent verification pass on the diff. The worker runs in the background; poll with worker_status(task_id). DO NOT USE for a trivial one-line edit, or non-coding work.

Args: objective: What the worker must accomplish. Be specific and scoped. repository: Absolute path to the target git repository. worker: codex | claude-code | opencode | zcode-glm | vscode | mock (or a configured worker). permission: read_only | workspace_write | full_access | custom. verify: Shell commands worker-bridge runs itself to verify, e.g. ["pytest -q"]. base_ref: Git ref to branch the worktree from (default HEAD). wait: Block until finished and return the full result (default false).

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNo
verifyNo
workerNocodex
base_refNoHEAD
objectiveYes
permissionNoworkspace_write
repositoryYes

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses background execution, independent verification, and optionally blocking. However, it lacks details on failure modes or timeouts, but is sufficient for a delegation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a clear first sentence, usage guidelines, and parameter list. Every sentence serves a purpose. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no output schema, and no annotations, the description covers all necessary aspects: purpose, when to use, parameter details, and background behavior. It feels complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the Args section explains all 7 parameters (objective, repository, worker, permission, verify, base_ref, wait) with clear descriptions, adding substantial value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Delegate a scoped coding task to an external AI coding worker in an isolated git worktree, then independently verify the result.' This distinguishes it from sibling tools like list_workers, worker_cancel, worker_logs, and worker_status, which are for management/status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly when to use: 'USE for: implementing a feature, fixing a bug across files, a refactor or migration.' And when not: 'DO NOT USE for a trivial one-line edit, or non-coding work.' Also mentions polling with worker_status for background tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

worker_logsA

Return the normalized event log for a delegated task (worker.started, progress, worker.completed, verification, ...), for streaming-style progress. Pass after (an event_id) to page.

ParametersJSON Schema
NameRequiredDescriptionDefault
afterNo
task_idYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses paging behavior and event types, but does not mention any potential side effects, authorization needs, or output format details beyond being a 'normalized event log'. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. Purpose is front-loaded in the first sentence, and paging guidance is in the second. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters and no output schema or annotations, description covers the main return type (normalized event log) and paging mechanism. Does not detail event structure or how to interpret the log, but sufficient for an agent to understand basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so description adds significant meaning: 'after' is explained as an event_id for paging. 'task_id' is implied by context but not explicitly described. Provides enough semantic value for agent to understand parameter roles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it returns the normalized event log for a delegated task, listing specific event types (worker.started, progress, etc.) and mentions streaming-style progress, which distinguishes it from siblings like worker_status or worker_cancel.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains how to page through results using the 'after' parameter with an event_id, providing clear usage context. Lacks explicit when-not-to-use or alternative suggestions, but appropriate for this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

worker_statusA

Check delegated worker tasks.

With task_id: returns status, summary, changed files, the independent verification result, and artifact paths (diff + manifest). Without task_id: lists recent tasks. Use to poll a task started by worker_delegate.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idNo

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes return fields (status, summary, changed files, verification result, artifact paths) and behavior difference with/without task_id. It implies read-only nature for polling, which is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded purpose. No superfluous words. Each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simplicity (1 optional param, no output schema, no annotations), description covers key behaviors, use case, and mentions sibling (worker_delegate). Could add that it's read-only, but otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has no description for task_id (0% coverage). Description adds meaning: with task_id returns detailed info, without lists recent tasks. This compensates for schema gap, though lacks format/constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks delegated worker tasks, with specific behaviors for with/without task_id. It distinguishes from siblings like worker_delegate (starts tasks) and worker_logs (gets logs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use to poll a task started by worker_delegate.' This provides clear context for usage. Could mention when not to use (e.g., for logs use worker_logs), but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observedlist_workers
    • First observedworker_cancel
    • First observedworker_delegate
    • First observedworker_logs
    • First observedworker_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: listing workers, delegating tasks, canceling tasks, checking status, and retrieving logs. There is no ambiguity or overlap.

Naming Consistency3/5

Most tools use a 'worker_' prefix followed by a noun (cancel, delegate, logs, status), but 'list_workers' reverses the pattern to verb_noun. This inconsistency could cause confusion.

Tool Count5/5

With 5 tools covering discovery, delegation, cancellation, status polling, and logs, the set is appropriately scoped for a worker bridge server.

Completeness4/5

The lifecycle of delegated tasks is well-covered: list available workers, delegate, cancel, check status, and get logs. Minor gap: no explicit tool to get detailed worker health beyond 'list_workers', but that is sufficient.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • cc-delegate

    EtienneLescot
    A
    license
    A
    quality
    A
    maintenance
    Delegates heavy development tasks from a supervisor to an autonomous worker on a cheaper model via MCP, with isolated git worktrees and provider-agnostic support.
    3
    1
    MIT

  • agent-locks

    luohoa97
    A
    license
    A
    quality
    D
    maintenance
    A filesystem-based MCP server for AI coding agents to coordinate work across git worktrees by claiming files, checking for conflicts, and logging progress without affecting the repository's git history.
    5
    MIT

  • wtx

    willkhinz
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI coding agents to manage Git worktrees by creating, listing, removing, and cleaning isolated workspaces through MCP tools.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/trollbot2012/worker-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server