slack-agent-starter
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 7 GitHub stars
Code Fail
- process.env — Environment variable access in apps/gateway/scripts/bootstrap-worker.mjs
- process.env — Environment variable access in apps/gateway/scripts/check-worker.mjs
- Hardcoded secret — Potential hardcoded credential in apps/gateway/scripts/check-worker.mjs
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Infrastructure-first Slack agent starter: separate Chat SDK gateway and Pi worker
Slack agent starter
A template for running your own AI agent in Slack. Team members mention the bot
in a channel, the open-source Pi coding agent works on the
request in a Vercel Sandbox, and the answer arrives in the same thread. A reply
in that thread continues the same conversation, even after the worker has shut
down. You deploy it on your own Vercel, Upstash, OpenRouter, and Slack accounts,
and you change its instructions, model, and tools in this repository.
It is for developers who want a team assistant they run and control: one Slack
workspace, one public channel, one model, and a small codebase with a TypeScript
gateway and a plain JavaScript worker. A team gets files and links in, a file
out, Status and Stop buttons, thumbs feedback, and shared channel notes
(features). The worker holds no Slack, Redis, or model
keys and runs no shell commands
(why).
How it works
flowchart LR
subgraph Sandbox[Vercel Sandbox]
Worker[Worker] --> Pi[Pi agent]
end
Slack[Slack channel] -->|events and clicks| Gateway[Gateway on Vercel Functions]
Gateway -->|status, answer, file| Slack
Gateway <-->|run state, session references, locks| Redis[Upstash Redis]
Gateway -.->|fetch one link| Web[Public URL]
Gateway -->|stage inputs, start run, read file| Worker
Worker -->|progress and answer| Gateway
Worker <--> Drive[Vercel Drive]
Pi <--> Drive
Pi -->|model calls| OpenRouter[OpenRouter]
- The gateway checks the Slack signature, the workspace and channel, and that
the sender is a person in the same workspace, records the run in Redis, and
answers Slack at once. The rest runs in the background. - It downloads any Slack files and the link, posts an eyes reaction and a
status message, starts the worker Sandbox if it has stopped, writes the
inputs to the Drive, and starts the run. - The worker opens the thread's saved Pi session on the Drive and runs one Pi
turn. Pi calls the OpenRouter model; the Sandbox firewall adds the API key. - The worker saves the session and any result file on the Drive and sends the
answer to the gateway with a token valid for that run only. - The gateway reads the result file from the Sandbox, posts the answer and
file, updates the status, and stops the Sandbox once no run is active. If it
has stopped, the next mention or reply starts a fresh Sandbox session from
the same startup snapshot and Drive.
The gateway never runs the model; the worker never calls Slack. See the
architecture for details.
Quickstart
The supported installation is the quickstart. You need
Bash on x86_64 Linux or WSL (or macOS with the
macOS toolchain steps), Docker for the local test
Redis, a Vercel account, a dedicated Upstash Redis database, an OpenRouter key
with a spending limit and a model that supports tool calls, and a Slack
workspace where you can create an app, with one public channel. The guide also
covers rollback and teardown.
- Prepare a clean checkout.
- Create the service resources.
- Bootstrap the worker.
- Configure and deploy the gateway.
- Apply the Slack manifest.
- Run the paid installation smoke.
Make it your agent
Editapps/worker/sandbox/instructions.md to
change what the agent is for, set OPENROUTER_MODEL to change the model, and
copy the write_artifact extension to add a tool.
Make it your agent explains each change. On a
running installation, new instructions or tools need a new worker with a new,
empty Drive, so earlier threads cannot continue and channel notes start empty; a
model change needs only a gateway redeploy.
Supported features
Items link to the specification. Switches are
gateway environment variables, off unless 1; the quickstart setsSLACK_FILE_EXCHANGE and SLACK_PUBLIC_URL_INPUT.
Works today
- Mentions (F01): mention the
bot in the configured channel, at the top level or in an existing thread. In
an existing thread it first reads the earlier messages
(F03). - Thread replies (F02):
replies continue the same Pi session without another mention, also after the
agent asked a question (F08).
A reply sent while a run is active is not submitted, and the bot says so
(F10). - Files in (F04):
UTF-8 text, Markdown, source code, diff, JSON, CSV, and text-based PDF, withSLACK_FILE_EXCHANGE=1. PNG needs onlySLACK_PNG_INPUT=1and JPEG onlySLACK_JPEG_INPUT=1; check that your model reads images first. Later turns in
the thread can use the files again. - Files out (F06): one
generated text file per answer, uploaded to the thread, withSLACK_FILE_EXCHANGE=1. If the upload fails, the text answer still posts. - Public URLs (F05):
withSLACK_PUBLIC_URL_INPUT=1, any http or https link outside code
formatting in a message to the bot is fetched by the gateway as input. A
message with more than one link, anhttp://link, a private-network address,
or a link that does not return UTF-8 plain text is refused and not submitted. - Status and Stop (F07,
F09): one status message
per accepted request. Status refreshes it; Stop ends only that run and is open
to the requester and the users inSLACK_STOP_OPERATOR_IDS. - Thumbs (F11):
thumbs-up and thumbs-down on an answer are only recorded in Redis; nothing
shows them. - Shared channel notes
(F13):@bot remember for this channel: <one line>saves a note, and@bot use shared notes: <question>asks with the notes, in any thread. Notes
cannot be edited or removed from Slack, so a channel with 16 stays full.
Not supported
- Shell commands or open file access for the agent, because every thread shares
one Drive (F12). - Private channels, DMs, group DMs, Slack Connect channels, and external users
(access). - Providers other than OpenRouter, a model picker in Slack, and automatic
fallback (decisions). - Account connectors such as GitHub or email, browser automation,
search-provider integration, scheduled jobs, image output, OCR, automatic note
extraction, and automatic storage cleanup
(F05,
deferred).
Current limits
These are the default limits, not load-tested
(specification);
Change the limits says where
they live, and
quickstart section 7
adds retention details.
| Area | Limit |
|---|---|
| Run time | 60 s from when the gateway accepts the Slack event, covering downloads, thread history, a Sandbox resume, and the model turn, with the last 12 s (18 s with SLACK_FILE_EXCHANGE=1) kept for saving and the callback; at the limit the turn stops and the bot posts a failure reply |
| Runs per thread | one at a time |
| Runs across threads | no cap; all share one Sandbox with 1 vCPU and one 1 GiB Drive |
| Message | 12,000 characters; a longer message gets no reply |
| Inputs per message | up to 5 Slack files and 1 public link, 16 KiB each |
| Images | PNG or JPEG, up to 1,024 pixels on either edge |
| text-based, up to 16 KiB of extracted text | |
| Inputs per thread | 12 files and links in total |
| Thread context | up to 20 messages from the thread, 2 KiB each, 16 KiB in total |
| Answer | 4,000 characters; a longer answer is cut |
| Generated file | one per answer, UTF-8, up to 256 KiB: CSV, Markdown, text, diff, JSON, YAML, HTML, CSS, SQL, shell, or code |
| Shared notes | 16 per channel, 512 UTF-8 bytes each; a full channel is reported and nothing is evicted |
| Worker Sandbox | stops after the last active run, otherwise at its 25-minute session timeout |
| Retention | Drive data, the startup snapshot, and Redis run, session, message, feedback, and managed-runtime records stay until teardown; only short-lived coordination keys expire |
Costs
This lists what bills and what drives it, without prices, which depend on your
plans. The specification
targets free infrastructure tiers plus capped model spending; whether a
deployment stays within them depends on its use and each provider's terms.
- OpenRouter: tokens for every Pi turn, which can make several model calls
when the agent uses tools. They depend on the model and on what each turn
sends: the message, its files, and the thread's saved history, including file
contents read earlier. The installation smoke and the--paid
worker check spend credit. - Vercel Sandbox: the worker Sandbox runs while there is work. After setup
it stays up until the first completed run or its 25-minute timeout, and it can
run until the timeout when an idle stop is not confirmed. Setup also runs a
seed Sandbox, and the worker check uses a real Sandbox and Drive even without--paid. - Vercel storage: the Drive, up to 1 GiB, and the startup snapshot, kept
until cleanup. - Vercel Functions: every message and reaction in channels the bot is in
reaches the gateway, not only those addressed to it, because the manifest
subscribes to channel messages and reactions. Clicks and worker callbacks are
requests too, and each run keeps a background gateway task open until the
worker exits or the 60-second deadline passes. - Upstash Redis: commands for events, callbacks, and clicks, and storage
that grows with use, since most records do not expire.
Development
Install the pinned toolchain as described in
docs/toolchain.md, start its disposable loopback Redis,
then run:
TEST_REDIS_URL=redis://127.0.0.1:16379 pnpm check
pnpm scan:secrets
Keep credentials, worker records, sessions, memory, real attachments, and
runtime outputs out of Git; committed fixtures are synthetic.
Traceability records what has been checked for each
feature and how: automated tests, real providers, or live Slack.
Documentation
- Quickstart and
Make it your agent - Specification,
traceability, and the
architecture decision - Worker, gateway, and
Slack app manifest - Toolchain, developer instructions, and
contributing
Licensed under the MIT License.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found