Piece

Name

Python package

bat-agent-connector (Python 3.10+, deps: websockets, mcp)

MCP server (stdio, or localhost-only streamable HTTP)

bat-agent-connector-mcp (also batc mcp)

CLI

batc

Agent skill

skills/bat-agent-connector/SKILL.md

token_ref

Meaning

env:NAME

environment variable

file:/path

file containing only the token (keep it chmod 600)

bat-profile:<id>

BAT's client token store (profiles/remote-tokens.enc.json, unencrypted variant)

Tier

Enabled by

Tools

read (always)

-

hosts_list, host_status, workspaces_list, sessions_list, session_read, session_wait, worktree_status, session_worktree_status, sessions_triage, quota_sessions

write

per host writes = true

session_send, session_continue, session_interrupt, session_answer, session_set_permissions, approve_pending

orchestrate

per host writes = true and orchestrate = true

session_start, worktree_merge, worktree_remove, session_failover, session_cleanup

Tool

What it does

hosts_list(probe=true)

Configured hosts; with probe: reachable, server version, ping.

host_status(host)

Version, protocol, connect/auth/ping latency, counts of workspaces/terminals/agent sessions/loaded/streaming.

workspaces_list(host?)

Workspaces with folder and session counts.

sessions_list(host?, workspace?, agent?, only_loaded?, active_within_hours?, check_pending=auto, limit=50)

Agent sessions, most recently active first: workspace, title, cwd, agent kind, model, loaded, streaming, pending question, last activity (+ source), worktree branch, orchestrated.

session_read(host, session_id, last_n=20, offset=0, include_tools=false, max_chars=12000, after=null)

Latest messages as compact text, paged (next_offset), size capped; pending question and streaming tail. session_id may be a unique prefix. after=<turn_marker> shows only messages newer than that send.

session_wait(host, session_id, until=attention, timeout_s=120, require_new=false, after=null)

Waits for turn end / question / permission request / error. after=<turn_marker> (from session_send / session_relay) waits for the reply to that send; a stale idle state does not count.

worktree_status(host, workspace?)

Worktree sessions: branch, source branch, merged kind, diff stats.

session_worktree_status(host, session_id, include_diff?)

Same for one session plus dirty files and main-checkout state.

session_send(host, session_id, text, confirm, message_id?, queue?)

Sends a message; client-resumes an unloaded session first; idempotent by message_id.

session_continue(host, session_id, confirm, text="continue")

Nudge.

session_interrupt(host, session_id, mode=soft|hard, confirm)

Soft = Claude interrupt-turn, hard = abort (Codex always hard). The session is kept.

session_answer(host, session_id, confirm, answers? | permission?)

Answers a pending ask-user question or permission prompt.

session_start(host, workspace, agent, confirm, prompt?, model?, use_worktree=true)

Starts a session (by default in a new worktree; BAT picks the branch bat/worktree-<id>). Per-host cap.

worktree_merge(host, session_id, confirm)

Merges only when provably conflict-free and clean; otherwise reports why.

worktree_remove(host, session_id, confirm, delete_branch=false, ...)

Removes the worktree folder; keeps the branch by default; refuses on dirty/unmerged work unless told.

sessions_triage(host?, workspace?, agent?, states?, use_jev=auto, include_unloaded=true)

Classifies each session: quota_exhausted, rate_limited_transient, waiting_permission, waiting_question, working, done_idle, error_other, unknown, with source (pattern/jev), confidence, evidence line and reset time.

quota_sessions(host?)

Shortcut: Claude sessions stopped by a usage quota.

session_set_permissions(host, session_id, mode, confirm)

allow_all (host must allow it) or default. Claude sessions are only switched while idle (switching mid-turn would end the turn); Codex applies it from its next turn.

approve_pending(host, confirm, dry_run?)

Approves every pending permission prompt (not questions) with "don't ask again" and raises the session to allow-all. Only on default_permission_mode = "allow_all" hosts.

session_failover(host, session_id? | all_exhausted, confirm, dry_run?, model?, force?, instructions?, archive_only?)

Starts a Codex session that continues a quota-stopped Claude session: same worktree when there is one, handoff prompt with the original task, latest instruction, recent output and git state (credentials redacted). Idempotent. model defaults to the host's codex_model. instructions replaces the default "continue the task" steps (for example "only commit the work in progress"); archive_only makes cleanup keep that branch unmerged.

session_relay(host, message, confirm, workspace? | session_id?, brief?, earlier?, channel?, thread?, request_fanout=0, dry_run?)

Relays a human's message verbatim to the workspace's main session (or a given one), plus an optional brief labeled as the relayer's interpretation and the BAT-STATUS footer. request_fanout=N asks the session for a bat-fanout plan. Returns the rendered text.

fanout_plan_session(host, workspace, message, confirm, max_items=4, brief?)

Starts a read-only Codex planner in the main checkout (for when the main session is busy or quota-stopped) that answers with a bat-fanout plan.

fanout_from_plan(host, session_id, confirm, dry_run?, agent="codex", model?, max_items=4)

Starts one worktree session per task of the last bat-fanout block of that session, prompts unchanged, then cleans up a planner session.

session_cleanup(host, confirm, dry_run=true, session_id?)

Decides MERGE_AND_CLEAN / CLEAN_ONLY / KEEP / ESCALATE per orchestrated session behind hard gates, then acts (needs auto_cleanup = true). See docs/ORCHESTRATE.md.