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 + Claude Code
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ 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.
Slack App Setup
- Create a Slack App at api.slack.com/apps
- Enable Socket Mode → generate an App-Level Token (
xapp-...) - Add Bot Token Scopes (OAuth & Permissions):
app_mentions:read,chat:write,files:write,im:history,im:read
- Subscribe to Events:
app_mention,message.im
- Install to workspace → copy Bot User OAuth Token (
xoxb-...)
Run
uv run agent-bridge
Usage
| Action | How |
|---|---|
| Channel | @AgentBridge help me refactor this function |
| DM | Send a direct message to the bot |
| Continue conversation | Reply in the same Slack thread |
| Attach files | Upload files in the message — the agent receives download URLs |
Each Slack thread is one agent session. The agent remembers context within a thread.
Architecture
The system has three independent layers:
| Layer | Role | Docs |
|---|---|---|
| Platform Adapter | Owns session semantics, per-session locking, UI rendering | Slack Adapter |
| Bridge | Routes messages, maps session keys → IDs, enforces concurrency | Core — see below |
| Agent Controller | Executes prompts, yields generic events | Claude Agent |
Event Model
All agent output flows through generic events — the shared language between agents and platforms:
| Event | Description |
|---|---|
Processing |
Slot acquired, agent is starting |
TextDelta |
Incremental text from agent |
StatusUpdate |
Agent performing an action (tool use, etc.) |
UserQuestion |
Agent asking user for input |
Completion |
Agent finished (with cost, duration, error status) |
Session Lifecycle
- User sends message → Platform constructs session key (e.g.
slack:{channel}:{thread_ts}) - Bridge resolves key → UUID session ID (creates new if first message)
- Agent runs with session ID (new session or resume existing)
- Sessions expire after configurable TTL (default 72h)
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
ANTHROPIC_API_KEY |
No | — | API key for the Claude Code CLI (skip if already authenticated via claude login) |
AGENT_BRIDGE_SLACK_BOT_TOKEN |
Yes (if using Slack) | — | Slack Bot User OAuth Token (xoxb-...) |
AGENT_BRIDGE_SLACK_APP_TOKEN |
Yes (if using Slack) | — | Slack App-Level Token for Socket Mode (xapp-...) |
AGENT_BRIDGE_CLAUDE_WORK_DIR |
No | . |
Working directory for Claude Code |
AGENT_BRIDGE_CLAUDE_PERMISSION_MODE |
No | acceptEdits |
Claude permission mode |
AGENT_BRIDGE_CLAUDE_TIMEOUT_SECONDS |
No | 600 |
Per-invocation timeout (seconds) |
AGENT_BRIDGE_CLAUDE_WORKTREE_ENABLED |
No | false |
Run each session in an isolated git worktree (requires origin/HEAD) |
AGENT_BRIDGE_SESSION_STORE_PATH |
No | ./sessions.json |
Session mapping file path |
AGENT_BRIDGE_SESSION_TTL_HOURS |
No | 72 |
Session TTL (hours) |
AGENT_BRIDGE_MAX_CONCURRENT_SESSIONS |
No | 5 |
Max concurrent agent processes |
AGENT_BRIDGE_HEARTBEAT_ENABLED |
No | false |
Enable the heartbeat platform — fires a fixed prompt on a fixed interval |
AGENT_BRIDGE_HEARTBEAT_INTERVAL_MINUTES |
Yes (if heartbeat enabled) | — | Interval between heartbeat ticks (minutes) |
AGENT_BRIDGE_HEARTBEAT_PROMPT |
Yes (if heartbeat enabled) | — | Prompt sent on every heartbeat tick |
AGENT_BRIDGE_HEARTBEAT_STATE_PATH |
No | ./heartbeat.json |
Last-run timestamp path (used for restart catch-up) |
AGENT_BRIDGE_LOG_LEVEL |
No | INFO |
DEBUG / INFO / WARNING / ERROR |
Extending
Add a new platform
Create platforms/{name}/ with config.py and adapter.py. Implement the PlatformAdapter protocol. Define your session key format. See Slack Adapter docs for reference.
Add a new agent
Create agents/{name}/ with config.py, controller.py, and events.py. Implement the AgentController protocol — your 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 with debug logging
AGENT_BRIDGE_LOG_LEVEL=DEBUG uv run agent-bridge
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ai_agent_bridge-0.2.1.tar.gz.
File metadata
- Download URL: ai_agent_bridge-0.2.1.tar.gz
- Upload date:
- Size: 155.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
96e6bba7a52d2c30fef5810932e1f5d624b9edf825f88f2a04b0e7be744186a0
|
|
| MD5 |
04d1786ee0316f5fade9462fd4af98b4
|
|
| BLAKE2b-256 |
a3246c00ce9822b6038c1b108d2b31ad34ba949507a794ded633fca39cac12b0
|
Provenance
The following attestation bundles were made for ai_agent_bridge-0.2.1.tar.gz:
Publisher:
release.yml on htkuan/ai-agent-bridge
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ai_agent_bridge-0.2.1.tar.gz -
Subject digest:
96e6bba7a52d2c30fef5810932e1f5d624b9edf825f88f2a04b0e7be744186a0 - Sigstore transparency entry: 2381290690
- Sigstore integration time:
-
Permalink:
htkuan/ai-agent-bridge@b20a87b350bb30a2aac9fe6a8defe21e7030451a -
Branch / Tag:
refs/heads/main - Owner: https://github.com/htkuan
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b20a87b350bb30a2aac9fe6a8defe21e7030451a -
Trigger Event:
push
-
Statement type:
File details
Details for the file ai_agent_bridge-0.2.1-py3-none-any.whl.
File metadata
- Download URL: ai_agent_bridge-0.2.1-py3-none-any.whl
- Upload date:
- Size: 36.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
aa918ad1d426d137947fa3df3a315ecf4bf828e6a788830c98b77377ac6a9c94
|
|
| MD5 |
fee967fd217872aad3557c61aa9f0af0
|
|
| BLAKE2b-256 |
74f7bf8be5d55132572e7b52252d5ec69ce6f649bd75c29c17e29ce532a08afb
|
Provenance
The following attestation bundles were made for ai_agent_bridge-0.2.1-py3-none-any.whl:
Publisher:
release.yml on htkuan/ai-agent-bridge
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ai_agent_bridge-0.2.1-py3-none-any.whl -
Subject digest:
aa918ad1d426d137947fa3df3a315ecf4bf828e6a788830c98b77377ac6a9c94 - Sigstore transparency entry: 2381290803
- Sigstore integration time:
-
Permalink:
htkuan/ai-agent-bridge@b20a87b350bb30a2aac9fe6a8defe21e7030451a -
Branch / Tag:
refs/heads/main - Owner: https://github.com/htkuan
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@b20a87b350bb30a2aac9fe6a8defe21e7030451a -
Trigger Event:
push
-
Statement type:
