Slack Bot v0.46.0

What it looks like

One mention starts a run. The thread becomes the run’s home: the ack, any human gates (rendered as buttons or a reply), progress notifications, and the final deliverable all land there. Here is a full conversation, start to finish.

The live status card is one message that updates in place as the run happens, so the thread stays a single dashboard instead of a wall of per-step posts. A freeform gate instead asks you to reply in the thread (✍️ <question>); an interview asks one question at a time.

Prerequisites

Create the Slack app

trackerbot connects over Socket Mode — an outbound WebSocket — so you need no public URL, ingress, or request-URL verification. Two tokens do it: an app-level token for the socket and a bot token for posting.

1. Create the app

   Go to api.slack.com/apps → Create New App → From scratch. Name it and pick your workspace.

2. Enable Socket Mode

   Settings → Socket Mode → toggle on. When prompted, generate an App-Level Token with the connections:write scope — this is your xapp-… token. Copy it.

3. Add bot token scopes

   Features → OAuth & Permissions → Bot Token Scopes. Add all four:

   Scope	Why
   app_mentions:read	see @trackerbot mentions
   chat:write	post acks, gates, notifications, results
   channels:history	read thread replies (freeform gates) in public channels
   groups:history	same, for private channels

4. Subscribe to events

   Features → Event Subscriptions → toggle on (Socket Mode needs no request URL). Under Subscribe to bot events, add: app_mention, message.channels, message.groups.

5. Turn on interactivity

   Features → Interactivity & Shortcuts → toggle on. This lets gate buttons send their clicks back over the socket. No request URL needed.

6. Install & grab the bot token

   Install App → install to the workspace. Copy the Bot User OAuth Token (xoxb-…).

7. Invite the bot to a channel

   In Slack: /invite @yourbot. It only sees channels it’s a member of.

You now have two secrets: SLACK_APP_TOKEN (xapp-) and SLACK_BOT_TOKEN (xoxb-).

Install & run

Build the binary, export the two tokens (plus a provider key), and start it. The bot logs a line when the socket connects.

# build from the repo root
go build -o trackerbot ./cmd/trackerbot

# the two Slack secrets from the app setup
export SLACK_APP_TOKEN=xapp-1-...
export SLACK_BOT_TOKEN=xoxb-...

# a provider key powers agent runs + natural-language intent
export ANTHROPIC_API_KEY=sk-ant-...

# recommended from day one — see Security & cost below
export TRACKERBOT_ALLOWED_USERS=U012ABC,U034DEF

# where run workdirs live (isolated per thread)
export TRACKERBOT_RUNS=/var/tmp/trackerbot-runs

./trackerbot
# trackerbot: connecting via Socket Mode (max 8 concurrent runs; runs under /var/tmp/trackerbot-runs)…

Workflows. The bot resolves a request to a workflow by name (built-ins like ask_and_execute and build_product, or a local <name>.dip under TRACKERBOT_WORKDIR). See the workflows catalog. No API key? Set TRACKERBOT_BACKEND=claude-code to run via the claude CLI’s subscription auth; intent then falls back to the run <workflow> grammar.

Talk to it

Mention the bot with a request, or use a control command. Every mention roots (or continues) a thread; the thread is the run’s identity.

Implement the requested change.
Extra guidance from the operator (may be empty): ${ctx.steer.guidance}

How it works

One process holds one outbound WebSocket and runs N concurrent pipelines, one per thread. The bot is a pure consumer of Tracker’s transport boundary — no engine changes — so it inherits panic containment, the one-terminal-event guarantee, per-run isolation, and durable resume from the core.

Two-level demux. Inbound events route by thread_ts (which run) and a gate_id (which question — encoded in a button’s action_id or the thread’s pending freeform gate). Outbound is automatic: each run owns a thread-bound UI, so its posts go to its own thread with no shared state.

Configuration

Everything is an environment variable. Only the two Slack tokens are required.

Security & cost

The bot triggers paid, host-side execution from chat. Three controls make that safe; set the first two before you point it at a shared channel.

Durability & resume

Each thread gets a deterministic workdir + checkpoint. If the bot process restarts — a deploy, an OOM, a crash — it resumes every interrupted run from its checkpoint on startup, no run-id bookkeeping.

• Node-granular resume. A run resumes from its last completed node; a crash while a gate is waiting resumes at the gate without re-running the completed upstream work.
• Atomic writes. Checkpoints and the resume-state file are written temp-then-rename, so a crash mid-write can’t corrupt the one file whose job is recovery. A corrupt state file is preserved aside and logged — never silently dropped.
• Bounded disk. Finished-run workdirs are reaped by default (TRACKERBOT_KEEP_WORKDIRS=1 retains them for inspection), plus a startup sweep of orphans.

Troubleshooting

Further reading