Skip to main content
Glama

English | 中文

cli-agent-bridge

Run independent Codex, Claude Code, Pi, and Antigravity sessions through MCP or a command line. Send tasks, follow up, inspect results, and stop sessions; the broker keeps task history in SQLite, and workers can continue when the MCP client disconnects.

For one user on their own computer or trusted SSH hosts. Supports Linux and macOS. On Windows, use WSL2. Model calls use your own authenticated CLI account and may cost money. Worktrees keep file edits separate and share your user account's OS permissions.

Install

On Linux with systemd --user or macOS in a logged-in desktop session, this command installs the latest stable release and enables automatic Bridge updates.

curl -fsSL https://github.com/qinjian623/agent-bridge/releases/latest/download/install.sh | sh

The installer verifies the wheel, sets up uv and Python if needed, and starts the broker and update timer under your account. If your shell cannot find agent-bridge, add $HOME/.local/bin to PATH or run ~/.local/bin/agent-bridge directly. For source installation, installing without starting services, or migrating an existing installation, see installation options.

Related MCP server: pi-agent-mcp

Configure and check

Install and log in to a model CLI separately. Run agent-bridge init, choose 1) Profiles, then a to add a profile named local using your logged-in Codex, Claude Code, or Pi CLI and its exact model ID. Return with b and save with s. Profiles start unverified. You can still specify local to dispatch your first task. See Antigravity setup for its access requirements.

After saving a profile, restart the broker so it loads the changes, then check that it responds. See managed service commands for Linux and macOS. With a standalone source installation, start agent-bridge serve in another terminal.

agent-bridge call agent_inspect --json '{}'

CLI help, setup prompts, the terminal monitor, Web pages, and parent task notices support English and Simplified Chinese. Try agent-bridge --lang zh-CN --help; the Web dashboard and login page have their own language selector. See language settings.

To open the dashboard, run agent-bridge monitor --web in another terminal and visit the local login page. Sign in with the token in your Bridge state's admin.token. See Web setup.

Connect MCP

For Codex, run:

codex mcp add cli-agent-bridge -- "$(command -v agent-bridge)" mcp
codex mcp list

Start a new Codex session to load the tools. For other MCP clients, use the absolute agent-bridge executable as the command and ["mcp"] as its arguments. The broker must be running. See MCP setup for custom state directories and managed launchers.

Send a first task

The CLI uses the same tools as MCP. Replace /absolute/path/to/project with a real project directory, and local if you chose a different profile name. This command starts a real model task and may incur charges:

agent-bridge call agent_dispatch --json '{"profile":"local","cwd":"/absolute/path/to/project","access":"read-only","instruction":"Read the project README and summarize how to run it. Do not modify files.","request_id":"quickstart-task-1"}'

Save the returned task_id and session_id. Repeating the exact request with the same request_id returns the same task; give each new task a new ID. Through MCP, ask your assistant to call agent_catalog, then dispatch the same read-only task with profile="local" and your project directory.

For automatic profile selection on new local tasks, see off-peak routing.

Read the result

Replace the angle-bracket placeholders with the returned IDs:

agent-bridge call agent_result --json '{"task_id":"<task_id>"}'
agent-bridge monitor

queued or running means work remains. waiting_input needs a response; recovery_needed needs investigation. completed means the model finished its reply. Check its answer, files, and any reported tests before accepting it with agent_review or starting dependent work. The guide explains review and full result retrieval.

New installations use agent_result or the monitor to see progress. Automatic completion notices require a configured parent notification helper.

Stop a task or session

Cancel just one task:

agent-bridge call agent_cancel --json '{"task_id":"<task_id>","request_id":"quickstart-cancel-1"}'

To close its session and cancel unstarted work, inspect it, then replace 0 below with the returned current revision:

agent-bridge call agent_inspect --json '{"session_id":"<session_id>"}'
agent-bridge call agent_control --json '{"session_id":"<session_id>","action":"close","expected_revision":0,"request_id":"quickstart-close-1"}'

Check the session again until its worker has exited. Pressing Ctrl+C in the broker terminal stops the broker; independent workers require their own cancellation or close. Closing a session preserves its history and working directory.

Configuration and troubleshooting · Uninstall · Design · Contributing · Security · Checks and limits · Privacy · Changes

Licensed under Apache-2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers