Agent Bridge Connect

中文 | English

AgentBC is a local-first task control system for running background work through agents on your machine. The current release supports Codex/ChatGPT, Claude Code, and Hermes. It gives different agent CLIs one task identity, one Runner gateway, one report contract, and one recovery model.

Public Alpha. Use AgentBC on development projects with version control and review agent output before accepting changes.

Current release: 1.0.1A (Python package version 1.0.1a1).

• Repository and releases: GitHub
• Python package: agentbc
• CLI: agentbc

Why AgentBC

• Dispatch work to local agents through one CLI.
• Keep continuation work in a visible chain such as 4XMC-001 -> 4XMC-002.
• Write deliverables directly to a user project or an isolated managed workspace.
• Observe concurrent work through a compact, automatically managed task list.
• Separate readable task reports from bounded runtime records.
• Close, recover, reassign, or hand off work without relying on chat context.
• Receive concise macOS completion and recovery notifications.
• Send and receive tasks in natural language from any supported agent. See the examples for complete workflows.

Create A Task

In any supported agent conversation, invoke /agentbc, describe the task in natural language, and name the executor:

/agentbc Ask Codex (or any supported agent) to write a document summarizing AgentBC's features and use cases.

Requirements

• macOS for the current desktop notification and task-list workflow;
• Python 3.10 or newer;
• at least one installed and authenticated executor: Codex, Claude Code, or Hermes.

Install And Verify

One command downloads, verifies, installs, and configures AgentBC:

curl -fsSL \
  https://github.com/roway49/agent-bridge-connect/releases/download/v1.0.1A/install-agentbc-alpha.sh \
  | sh -s -- \
  https://github.com/roway49/agent-bridge-connect/releases/download/v1.0.1A

For a package-managed installation from PyPI:

python3 -m pip install agentbc==1.0.1a1
agentbc setup

Start with Quick Start, then use the User Guide for task and Runner commands.

Architecture

AgentBC is a local control plane. Agent integrations submit structured tasks to one local Runner; Core owns task identity, state, reports, records, and notifications.

flowchart TD
    A[Human or controller agent] --> CLI[CLI and installed skill]
    CLI --> S[TaskService]
    S --> TS[TaskStore]
    CLI --> R[Runner gateway]
    R --> X[Executor adapter]
    X --> E[Codex, Claude Code, or Hermes CLI]
    E --> P[Project or managed artifact root]
    R --> L[RunLease and progress record]
    S --> RP[Task brief and report]
    S --> I[Global task index]
    S --> N[Task List and desktop notification]

Component Boundaries

CLI and skills. The CLI exposes task, Runner, setup, record, worker, and uninstall operations. Installed skills teach each controller how to select a customer path, preserve dispatcher identity, and choose create versus handoff. Skills cannot bypass Core validation and do not own task truth.

TaskService and TaskStore. TaskService owns state transitions, task-code allocation, handoff lineage, close and recovery behavior, report finalization, and index refresh. TaskStore owns compact runtime records. Each task iteration has a bounded record budget so long-running agents do not create unbounded metadata.

Runner. Runner is the normal dispatch gateway. It validates the task and path plan, acquires a run lease, launches the executor, records low-frequency progress evidence, and classifies executor termination. Runner does not decide whether a deliverable is good; that remains a user or reviewer decision.

Executor adapters. Adapters translate one task packet into executor-specific arguments and prompts. The executor CLI remains an independent process. Codex and Claude receive scoped writable roots where supported; Hermes runs from the selected project or artifact root and remains subject to its own CLI capabilities.

Reports and records. Readable task briefs and reports are separate from compact machine state. Reports describe requirements, lineage, results, and artifact locations; runtime records preserve exact status and recovery evidence.

Task And Completion Model

A four-character TASKCODE identifies a task chain. The numeric suffix is its iteration: 4XMC-001 and 4XMC-002 belong to the same chain. Commands may use the task code to resolve the current head or the full ID for an exact iteration.

Agent callbacks are optional metadata. Normal executor-process exit is the completion authority:

1. Runner confirms that execution started.
2. The executor CLI exits.
3. Runner classifies the exit contract.
4. Core writes the terminal status and synchronizes the report.
5. Task List and desktop notifications display the same status.

• completed: execution started and ended normally; quality is not asserted.
• needs_recovery: execution could not start or continue normally.
• failed: execution started, but normal executor termination was not confirmed.

A dispatch response such as accepted is not task completion. Task status, reports, artifacts, and notifications are the source of truth.

Path And Data Model

The controller supplies either an explicit user path or the literal "default path". Runner derives the path plan. Explicit paths receive deliverables directly; default-path tasks receive an isolated managed artifact root. Reports and runtime records always remain Core-owned.

~/Documents/AgentBC/workspace/
|-- tasks/
|   |-- artifacts/YYYY-MM-DD/<TASKCODE>/
|   `-- report/YYYY-MM-DD/<TASKCODE>/
|       |-- <TASKCODE>-<NNN>-task.md
|       `-- <TASKCODE>-<NNN>-report.md
`-- record/
    |-- README.md
    |-- TASK_INDEX.md
    |-- task_index.jsonl
    `-- <TASKCODE>/<NNN>/
        |-- task.json
        |-- events.jsonl
        |-- interventions.jsonl
        |-- run_lease.json
        `-- bounded progress and run-log files

Each iteration record is capped at 10KB. agentbc record clean removes eligible terminal diagnostics while preserving core indexes and state. Empty managed artifact directories are removed after terminal execution; customer projects are never automatic-cleanup or uninstall targets.

Local Security Model

• Runner accepts authenticated local spool requests.
• One installation owns one Runner identity and stable PID; duplicate or orphaned startup is rejected even when spool state has been replaced.
• Customer paths are explicit task inputs and are never copied into the managed workspace as a permission workaround.
• Managed tasks receive a task-scoped artifact root rather than the workspace root.
• Report Markdown is Core-owned.
• Uninstall and task close never traverse customer project paths.

AgentBC is not a container sandbox. Use source control, normal OS permissions, and executor-native approval controls for defense in depth.

Documentation

• Quick Start / 快速开始
• User Guide / 用户指南
• Feature Show / 功能展示
• Examples / 演示示例
• Feature Preview / 后续功能预告

License

AgentBC is released under the MIT License.