ai-agent-bridge

Agent Bridge

Modular bridge that connects chat platforms to AI agents. Each layer is independent — swap platforms or agents without touching the others.

Currently supports: Slack, Heartbeat, HTTP Webhook + Claude Code, Pi, Codex, Opencode

┌──────────────┐     ┌──────────┐     ┌──────────────┐
│   Platform   │────▶│  Bridge  │────▶│    Agent     │
│   (Slack)    │◀────│ (Router) │◀────│ (Claude Code)│
└──────────────┘     └──────────┘     └──────────────┘
  Session owner       Pure routing      Purely invoked
  Locking & render    Key → ID map      Yields events
  UI logic            Concurrency       No UI knowledge

Quick Start

Prerequisites

• Python 3.12+
• uv
• Claude Code CLI installed and authenticated

Install

git clone https://github.com/htkuan/ai-agent-bridge.git
cd agent-bridge
uv sync

Configure

cp .env.example .env

Edit .env with your tokens:

# Required for Slack
AGENT_BRIDGE_SLACK_BOT_TOKEN=xoxb-your-bot-token
AGENT_BRIDGE_SLACK_APP_TOKEN=xapp-your-app-level-token

# Claude Code working directory
AGENT_BRIDGE_CLAUDE_WORK_DIR=/path/to/your/project

See Environment Variables for the full list. Every variable is read in one place — AppConfig.from_env() walks each layer's {Component}Config.from_env(), and the whole app is then built from that single AppConfig.

Slack App Setup

1. Create a Slack App at api.slack.com/apps
2. Enable Socket Mode → generate an App-Level Token (xapp-...)
3. Add Bot Token Scopes (OAuth & Permissions):
   • app_mentions:read, chat:write, files:write, im:history, im:read
   • channels:read, users:read, team:read — name lookups for the agent's context and the channel allow-list (add groups:read / mpim:read for private channels / group DMs). Missing these logs missing_scope warnings; see docs/platforms/slack.md
4. Subscribe to Events:
   • app_mention, message.im
5. Install to workspace → copy Bot User OAuth Token (xoxb-...)

Run

uv run agent-bridge

Usage

Each Slack thread is one agent session. The agent remembers context within a thread.

Architecture

The system has three independent layers:

Event Model

All agent output flows through generic events — the shared language between agents and platforms:

Session Lifecycle

1. User sends message → Platform constructs session key (e.g. slack:{channel}:{thread_ts})
2. Bridge resolves key → UUID session ID (creates new if first message)
3. Agent runs with session ID (new session or resume existing)
4. Sessions expire after configurable TTL (default 72h)

Environment Variables

Extending

Add a new platform

Create platforms/{name}/ with config.py and adapter.py. Subclass BasePlatformAdapter (platforms/base.py): pre-process your platform's native event into a BridgeRequest, call process(), and override the on_* hooks to render the streamed events. Define your session key format with make_session_key. HTTP-based platforms expose an APIRouter that gets mounted on the shared HTTP server. See the Slack and Webhook docs for reference.

Add a new agent

Create agents/{name}/ with config.py, controller.py, and events.py. Subclass CliAgentController (agents/base.py): describe your CLI with build_command() and parse_line(), and the base engine handles the subprocess lifecycle — the AgentController protocol stays the contract, and run() yields BridgeEvents. See Claude Agent docs for reference.

Neither change requires modifying the bridge, the other agent, or the other platform.

Development

# Run tests
uv run pytest tests/ -v

# Run the live e2e against the real claude CLI (opt-in, spends tokens)
uv run pytest -m live --live --no-cov -v

# Run with debug logging
AGENT_BRIDGE_LOG_LEVEL=DEBUG uv run agent-bridge

Test layout, fakes and markers: docs/testing.md.

Commits follow Conventional Commits (lowercase types: feat:, fix:, ...) and are enforced on PRs. Merging to main cuts a release automatically — see docs/releasing.md.

License

MIT