agent-tether 0.4.0

Chat platform bridges for AI agent supervision

agent-tether

Connect AI coding agents to human oversight through Telegram, Slack, and Discord.

A Python library that provides chat platform bridges for supervising AI agents. Each bridge handles platform-specific formatting, thread management, approval flows with inline buttons, auto-approve timers, and command handling.

Use Cases:

• Monitor Claude Code or Codex sessions from your phone while agents run locally
• Get approval requests as Telegram notifications with one-tap approve/deny
• Set auto-approve timers (per-session, per-tool, per-directory)
• Send additional input or stop agents remotely

Looking for a ready-made solution for connecting your agents? Check out Tether.

Install

pip install agent-tether[telegram]   # Telegram support
pip install agent-tether[slack]      # Slack support (experimental)
pip install agent-tether[discord]    # Discord support
pip install agent-tether[all]        # All platforms

Architecture

Your Application
    │
    ├── BridgeCallbacks       → You implement these to wire up your backend
    │
    ├── agent-tether bridges
    │     ├── TelegramBridge  → Telegram forum topics
    │     ├── SlackBridge     → Slack threads (experimental)
    │     └── DiscordBridge   → Discord threads
    │
    ├── BridgeManager         → Routes events to the right bridge
    └── BridgeSubscriber      → Consumes store events, forwards to bridges

Core Components

• BridgeCallbacks: Dataclass of async callbacks that you provide, connecting bridges to your session backend
• BridgeInterface: Abstract base class with shared logic for auto-approve, approval parsing, error debouncing, and formatting
• BridgeManager: Routes output, approvals, and status changes to the correct platform bridge
• BridgeSubscriber: Consumes events from a store subscriber queue and forwards them to bridges
• BridgeConfig: Configuration (data directory, default adapter, error debounce)

Quick Start

from agent_tether import (
    BridgeCallbacks,
    BridgeConfig,
    BridgeManager,
    TelegramBridge,
)

# Implement callbacks to wire bridges to your backend
callbacks = BridgeCallbacks(
    create_session=my_create_session,
    send_input=my_send_input,
    stop_session=my_stop_session,
    respond_to_permission=my_respond_to_permission,
    list_sessions=my_list_sessions,
    get_usage=my_get_usage,
    check_directory=my_check_directory,
    list_external_sessions=my_list_external,
    get_external_history=my_get_history,
    attach_external=my_attach_external,
)

# Configure
config = BridgeConfig(data_dir="/tmp/agent-tether")

# Create a Telegram bridge
telegram = TelegramBridge(
    bot_token="BOT_TOKEN",
    forum_group_id=123456,
    config=config,
    callbacks=callbacks,
    get_session_directory=lambda sid: "/home/user/project",
)

# Register with manager
manager = BridgeManager()
manager.register_bridge("telegram", telegram)

# Route events from your backend
await manager.route_output("sess_1", "Starting work...", "telegram")
await manager.route_status("sess_1", "running", "telegram")

BridgeCallbacks

The BridgeCallbacks dataclass defines 10 async functions that connect agent-tether to your session backend:

Callback	Signature	Purpose
create_session	(**kwargs) -> dict	Create a new agent session
send_input	(session_id, text) -> None	Send human input to a session
stop_session	(session_id) -> None	Interrupt/stop a running session
respond_to_permission	(session_id, request_id, allow, message?) -> bool	Approve or deny a permission request
list_sessions	() -> list[dict]	List all active sessions
get_usage	(session_id) -> dict	Get token/cost usage for a session
check_directory	(path) -> dict	Validate a directory path
list_external_sessions	(**kwargs) -> list[dict]	Discover running external sessions
get_external_history	(external_id, runner_type, limit) -> dict?	Fetch history for an external session
attach_external	(**kwargs) -> dict	Attach to an external session

All callbacks default to no-ops, so you only need to implement the ones your application uses.

Approval Parsing

Bridges parse human text into approval responses:

from agent_tether import BridgeInterface

# These are parsed by bridges when users reply in chat
bridge.parse_approval_text("allow")       # → {"allow": True, "timer": None}
bridge.parse_approval_text("deny: risky") # → {"allow": False, "reason": "risky"}
bridge.parse_approval_text("allow all")   # → {"allow": True, "timer": "all"}
bridge.parse_approval_text("allow Bash")  # → {"allow": True, "timer": "Bash"}

Auto-Approve Timers

# Auto-approve all tools for this session (30 min)
bridge.set_allow_all("sess_1")

# Auto-approve only Bash for this session (30 min)
bridge.set_allow_tool("sess_1", "Bash")

# Auto-approve all sessions in a directory (30 min)
bridge.set_allow_directory("/home/user/project")

# Check if a request should be auto-approved
reason = bridge.check_auto_approve("sess_1", "Bash")
# Returns "Allow All", "Allow Bash", "Allow dir project", or None

Features

Chat Platform Bridges

• Telegram: Forum topics, inline keyboard approval buttons, typing indicators, HTML formatting
• Slack (experimental): Socket mode, threaded conversations, text-based approval commands
• Discord: Channel threads, pairing/authorization system, text-based approvals

Shared Bridge Logic

• Auto-approve engine: Per-session, per-tool, and per-directory timers (30 min default)
• Approval parsing: Text commands (allow/deny/proceed/cancel) with tool and directory timers
• Choice parsing: Numeric or label-based selection for multi-option prompts
• Error debouncing: Suppress rapid-fire error notifications
• Notification batching: Collapse rapid auto-approvals into single messages
• External session pagination: Browse and attach to running Claude Code/Codex sessions
• Formatting: Tool input JSON to readable markdown, message chunking

Commands (available in all bridges)

• /help or !help: Show available commands
• /status or !status: List all sessions
• /list or !list: List external sessions (Claude Code, Codex)
• /attach or !attach: Attach to an external session
• /new or !new: Start a new session
• /stop or !stop: Interrupt the current session
• /usage or !usage: Show token usage and cost

Documentation

• CHANGELOG.md: Version history and changes

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

MIT. See LICENSE for details.