SPA — Spawn's Personal Agent

Slack bot that listens in #proj-spawn via Socket Mode. When @mentioned, it collects the full thread, pipes it into a claude -p session, and streams Claude Code's responses back to the Slack thread in real-time.

Subsequent thread replies in tracked threads auto-trigger new Claude Code runs.

Slack App Setup

Option A: Create from manifest (recommended)

1. Go to https://api.slack.com/apps
2. Click Create New App > From a manifest
3. Select your workspace
4. Paste the contents of slack-manifest.yml from this directory
5. Click Create
6. Socket Mode: Settings > Basic Information > scroll to "App-Level Tokens" > Generate Token and Scopes > add connections:write scope > copy the xapp-... token
7. Install to Workspace: Features > OAuth & Permissions > Install > copy the xoxb-... Bot User OAuth Token
8. Invite the bot to the target channel: /invite @spa
9. Get the channel ID: Right-click channel name > View channel details > copy the ID (starts with C)

Option B: Manual setup

1. Go to https://api.slack.com/apps > Create New App > From scratch
2. Name it SPA, select the workspace
3. Socket Mode: Settings > Socket Mode > Enable > generate app-level token with connections:write scope > save xapp-...
4. Event Subscriptions: Features > Event Subscriptions > Enable > subscribe to bot events: app_mention, message.channels, message.groups
5. OAuth Scopes: Features > OAuth & Permissions > Bot Token Scopes: app_mentions:read, channels:history, channels:read, groups:history, groups:read, chat:write, reactions:write
6. Install to Workspace > save xoxb-... token
7. Invite bot to channel, get channel ID

Env Vars

Var	Description
SLACK_BOT_TOKEN	Bot User OAuth Token (xoxb-...)
SLACK_APP_TOKEN	App-Level Token for Socket Mode (xapp-...)
SLACK_CHANNEL_ID	Channel ID to listen in (e.g. C0123456789)
GITHUB_REPO	Target repo context (default: OpenRouterLabs/spawn)
REPO_ROOT	Working directory for Claude Code (default: cwd)

GitHub auth uses the gh CLI — run gh auth login before starting.

start-spa.sh Template

Create .claude/skills/setup-spa/start-spa.sh (gitignored):

#!/bin/bash
set -eo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

export SLACK_BOT_TOKEN="xoxb-YOUR-BOT-TOKEN"
export SLACK_APP_TOKEN="xapp-YOUR-APP-TOKEN"
export SLACK_CHANNEL_ID="C0000000000"
export GITHUB_REPO="OpenRouterLabs/spawn"
export REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"

exec bun run "${SCRIPT_DIR}/main.ts"

Install

bun install    # from repo root — workspace install

Systemd Service

Create /etc/systemd/system/spawn-spa.service:

[Unit]
Description=SPA — Spawn's Personal Agent
After=network.target

[Service]
Type=simple
User=lab
Group=lab
WorkingDirectory=/home/lab/spawn/.claude/skills/setup-spa
ExecStart=/bin/bash /home/lab/spawn/.claude/skills/setup-spa/start-spa.sh
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment="PATH=/home/lab/.local/bin:/home/lab/.bun/bin:/usr/local/bin:/usr/bin:/bin"

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now spawn-spa

Verify

sudo systemctl status spawn-spa
journalctl -u spawn-spa -f

# Test: @mention spa in channel → Claude Code runs, response streams back
# Test: Reply and @mention again → resumes same session

State

Thread-to-session mappings are persisted at ~/.config/spawn/slack-issues.json.

Troubleshooting

Symptom	Fix
ERROR: SLACK_BOT_TOKEN env var is required	Set all required env vars in start-spa.sh
Bot doesn't respond to @mentions	Verify bot is invited to the channel; check SLACK_CHANNEL_ID
Claude errors with permission denied	Ensure --dangerously-skip-permissions is working, or run in a sandbox
Responses truncated	Slack has ~4000 char limit per message; long responses show the tail
Hourglass reaction	A Claude run is already active for that thread; wait for it to finish