bat-agent-connector

An unofficial connector that lets AI agents work with Better Agent Terminal (BAT) sessions.

BAT (by TonyQ / tony1223) is a terminal app that runs Claude Code and Codex agent sessions, grouped into workspaces, on your machines. It has a remote protocol (bat-remote/v2) that its own GUI and phone clients use. This project speaks that protocol so that other agents (Claude Code, Codex, Cursor, Hermes, or any MCP client) and shell scripts can:

• see which agent sessions exist, which are running or blocked on a question, and what they said recently;

• wait for a session to finish its turn;

• (opt-in) nudge a session: send a message, say "continue", interrupt it, answer its question;

• (opt-in, separate tier) fan work out: start sessions in fresh git worktrees, review their diffs, merge the clean ones.

This project is not affiliated with or endorsed by the BAT authors. The protocol was read from BAT's MIT-licensed source (v3.2.12) and can change between BAT releases. Credit for BAT goes to TonyQ and its contributors.

It ships three things:

Why

Running several long-lived coding agents means constantly checking tabs: which one is done, which one is stuck on a question, which one just needs "continue". Reading this through BAT's protocol is reliable (no screen scraping, no GUI automation) and lets a supervising agent do the checking for you, with you in control of anything that writes.

Related MCP server: HT MCP Server

Install

# from a git checkout / URL (until published on PyPI)
uv tool install git+https://github.com/<owner>/bat-agent-connector
# or
pipx install git+https://github.com/<owner>/bat-agent-connector
# or run without installing
uvx --from git+https://github.com/<owner>/bat-agent-connector batc hosts

Configure

The connector needs, per host: the wss:// URL of its bat-server, the server's TLS certificate SHA-256 fingerprint (pinned; BAT uses self-signed certs), and a reference to the remote token. If you already use the BAT desktop client, import everything from it:

batc import-bat                      # writes ~/.config/bat-agent-connector/hosts.toml (writes disabled)
batc import-bat --rename my-profile-id=box1 --output -   # preview with nicer names
batc hosts                           # probe: version + ping per host

Token references (token values are never stored in the config, logged, or returned by any tool):

See examples/hosts.example.toml for all options. The connector keeps a stable deviceId in ~/.config/bat-agent-connector/device-id so hosts don't show a new "remote client connected" notification on every reconnect.

Permission tiers

Write and orchestrate tools are not even registered unless enabled, need confirm=true on every call, are rate limited, and are appended to an audit log (~/.local/state/bat-agent-connector/audit.jsonl, message bodies only as a hash + length unless you opt into a short preview). --read-only on the MCP server or CLI disables both tiers regardless of config. The channel allowlist is enforced in the client core, below the MCP layer: stop/reset/kill, PTY writes, file operations, settings, workspace edits (except the append-only tab helper), installs, updates and account changes are never sent.

MCP setup

The server name is bat. Examples (add --read-only if you want to be sure):

Claude Code

claude mcp add bat -- bat-agent-connector-mcp --read-only

Codex (~/.codex/config.toml)

[mcp_servers.bat]
command = "bat-agent-connector-mcp"
args = ["--read-only"]

Cursor (~/.cursor/mcp.json)

{ "mcpServers": { "bat": { "command": "bat-agent-connector-mcp", "args": ["--read-only"] } } }

Hermes Agent (~/.hermes/config.yaml)

mcp_servers:
  bat:
    command: /home/you/.local/bin/bat-agent-connector-mcp
    args: [--read-only]
    connect_timeout: 60.0
    enabled: true

Any MCP client over HTTP (binds to loopback only):

bat-agent-connector-mcp --http --port 8765     # http://127.0.0.1:8765/mcp

Tools reference

CLI

batc hosts
batc status box1
batc sessions --active-within 24
batc sessions box1 --workspace api --json
batc read box1 1a2b3c4d -n 30
batc wait box1 1a2b3c4d --timeout 600
batc worktrees box1
# write tier (host needs writes = true)
batc send box1 1a2b3c4d "Please run the tests and fix failures" --confirm
batc continue box1 1a2b3c4d --confirm
batc interrupt box1 1a2b3c4d --mode soft --confirm
batc answer box1 1a2b3c4d --answer "Which database?=postgres" --confirm
# orchestrate tier
batc fanout PLAN.md                                   # dry run: split into task prompts
batc fanout PLAN.md --start --host box1 --workspace api --confirm
batc merge box1 1a2b3c4d --confirm
batc remove-worktree box1 1a2b3c4d --confirm

Every command accepts --json.

Safety model (short)

• Read-only by default; writes and orchestration are opt-in per host, need confirm=true, are rate-limited and audited.

• TLS certificate pinning is mandatory; a mismatch aborts before the token is sent. Only bat-remote/v2 is accepted.

• Tokens are resolved at connect time from a reference and redacted from every error string.

• The client always drains the socket (BAT drops clients with 256 queued frames) and uses bounded event queues.

• Session text is untrusted input: agents should not follow instructions found in it.

Details: SECURITY.md, docs/PROTOCOL.md, docs/ORCHESTRATE.md.

Development

uv sync --extra dev
uv run ruff check . && uv run pytest            # unit tests use a mock TLS WebSocket server
BATC_LIVE=1 uv run pytest tests/test_live.py    # optional read-only test against your configured hosts

License

MIT, see LICENSE. BAT itself is MIT-licensed by TonyQ.