Getting started

No Bun or source checkout required for normal use. Download a v0.4.0 release binary, run setup, pair once.

Requirements

• A Telegram bot with Threaded Mode on in @BotFather (Bot Settings; Telegram also calls this topics in private chats)
• Shell access on the host (to approve pairing — you do not need a Telegram user id first)
• At least one agent CLI on PATH and logged in where required:
  • Grok Build — grok (grok agent stdio)
  • Claude — claude + npx (ACP adapter)
  • Codex — codex + npx (ACP adapter)
  • OpenCode — opencode (opencode acp)
  • Cursor Agent — cursor-agent (cursor-agent acp; run cursor-agent login once)
  • Pi — pi + npx (ACP adapter pi-acp; install from pi.dev)

1. Provision the bot

@BotFather is not scriptable. Once per bot:

1. Create a bot → copy the token
2. Open the BotFather mini app (the Open button), pick the bot → Bot Settings → enable Threaded Mode. Chat-style BotFather commands do not always show this toggle. Telegram also calls it topics in private chats. acpbot setup checks getMe.has_topics_enabled and stops if it is false.

Pair as operator after start: DM the bot for a code, then run acpbot pair approve <code> on the host. See Pairing.

2. Download the binary

Current release: v0.4.0. Download one artifact for your platform (or use the landing page install section):

One unified binary — host and worker are subcommands of acpbot.

# Apple Silicon example (swap the asset name for your platform)
curl -fsSL -o acpbot.tar.gz \
  "https://github.com/pmdroid/acpbot/releases/download/v0.4.0/acpbot-v0.4.0-darwin-arm64.tar.gz"
tar -xzf acpbot.tar.gz
chmod +x acpbot-v0.4.0-darwin-arm64
sudo mv acpbot-v0.4.0-darwin-arm64 /usr/local/bin/acpbot   # or ~/.local/bin
acpbot help    # host, worker, setup, services, …

Checksums ship on the release (SHA256SUMS, SHA256SUMS-darwin-v0.4.0).

Config is created automatically on first start under ~/.config/acpbot/ (no manual mkdir / cp).
Full reference: Configuration.

Docker (optional)

docker pull ghcr.io/pmdroid/acpbot:v0.4.0
# or compose from the repo — see docker-compose.yml and Configuration → Docker

Image tags: v0.4.0, 0.4.0, latest. Multi-arch (linux/amd64, linux/arm64).

3. Setup + start host and worker

You need both processes: host (agents) and worker (Telegram). The worker fails at boot if the host socket is missing.

acpbot setup
# Guided TUI: bot token, agent, workspace, speech keys, optional OAuth callback.
# OAuth step can suggest Tailscale DNS / Tailscale IP / LAN IP, or a custom URL.
# macOS: offers Full Disk Access so agents can read real folders.
# Daemon step installs BOTH (same binary, two processes):
#   • acpbot host    (LaunchAgent / systemd)
#   • acpbot worker  (LaunchAgent / systemd)

• macOS: app.acpbot.host + app.acpbot.worker LaunchAgents (KeepAlive)
• Linux: acpbot-host.service + acpbot.service (systemd user)

Same ~/.config/acpbot/config.toml for both (mode 600). Logs: ~/.local/share/acpbot/logs/ on macOS, or journalctl --user -u acpbot-host -u acpbot on Linux.

Day-to-day service control (default = both host + worker):

acpbot install    # write + enable LaunchAgents / systemd units
acpbot start
acpbot stop
acpbot restart
acpbot status
# one side only: acpbot start --host   ·   acpbot stop --worker

If you skip the daemon step in setup:

acpbot host      # terminal 1 — agent stdio, schedules, OAuth
acpbot worker    # terminal 2 — Telegram

You must add a project folder before /new. Setup’s folder browser often starts in a parent like ~/code or ~/Projects. That parent is not the workspace. Browse into the project, then Use this folder. If you skip this in the wizard, /new cannot start a session until you run:

acpbot repo add
# or: acpbot repo add demo ~/code/demo
# host/worker hot-reload [repos]; no restart needed

See Repos.

Optional — install bundled skills (telegram, schedules, multi-agent, eve) into global agent dirs so Grok/Claude/… see them outside Telegram:

acpbot skills install

Background service paths: Configuration.

4. Pair as operator

The bot starts unpaired. Approve on the host CLI:

1. Open a private chat with the bot and send any message (e.g. /ping).
2. The bot replies with a pairing code (e.g. AB3K-9Q2M).
3. On the machine running acpbot:

acpbot pair list
acpbot pair approve AB3K-9Q2M
acpbot pair status

Details: Pairing.

5. Add a workspace repo

/new will not create a session until [repos] has at least one entry. Each entry is one project folder, not the parent that holds many projects.

acpbot repo add
# folder browser: go into the project, then Use this folder
# or: acpbot repo add demo ~/code/demo

macOS Full Disk Access (offered in setup) only lets agents read those paths. It does not add repos. Skip the workspace step and Telegram /new replies that you need acpbot repo add first.

6. Use Telegram

/ping
/new
# pick a repo, name the session, open that topic → type a prompt

/status   /model   /effort   /agent   /mode   /skills   /mcp   /cancel
# while busy: free-text is queued; /steer <text> interrupts

On startup acpbot wipes stale setMyCommands scopes and registers the slash menu from the command registry. Slash commands never go to the agent.

While a turn runs you will see a single ⏳ (or ❓) status bubble in the topic. It updates in place as tools run. The final reply appears after the bubble is removed. Forum topic titles stay fixed (repo/name).

Busy-turn UX: free-text is queued (non-interrupt) with a Remove button on the ack; /steer … interrupts. Telegram does not notify message deletes — use Remove or /unqueue.

Details: Commands, Agents, Architecture.

7. Media & speech (optional)

OpenAI-only example:

[speech]
tts_provider = "openai"
stt_provider = "openai"

[speech.openai]
api_key = "sk-…"
tts_voice = "alloy"

Full provider options: Configuration. Outbound path: Worker API.

Common failures

From source (developers only)

Binary installs do not need Bun. For contributors, build or run via Bun, but all operator commands stay acpbot:

git clone https://github.com/pmdroid/acpbot.git
cd acpbot
bun install
bun run build:compile    # → dist/acpbot
# or during dev: bun run src/main.ts <command>

acpbot skills install    # global agent skills
acpbot host              # terminal 1
acpbot worker            # terminal 2

bun test ./test
bun run typecheck

Next

• Architecture
• MCP — per-repo tools & host acpbot tools
• Skills — bundled skills, global install
• Multi-agent · EVE
• OAuth — remote MCP gateways