@dreki-gg/pi-slack

Slack read tools for pi — messages, threads, channels, search, and file/image downloads.

Uses Effect for the Slack client layer (typed errors, retries, rate limit handling).

Tools

Tool	Description
slack_list_channels	List channels the bot has access to
slack_read_messages	Read message history from a channel
slack_read_thread	Read replies in a thread
slack_search	Full-text search across workspace (requires user token)
slack_download_file	Download a shared file/image to temp directory

Setup

1. Create a Slack App

Go to api.slack.com/apps → Create New App → From scratch. Give it a name (e.g. pi-context) and select your workspace.

2. Add OAuth scopes

In the left sidebar → OAuth & Permissions → scroll to Scopes.

Bot Token Scopes (for SLACK_BOT_TOKEN):

Scope	Enables
channels:read	list public channels
channels:history	read public channel messages
groups:read	list private channels
groups:history	read private channel messages
im:history	read DMs
files:read	file info + image/file downloads

User Token Scopes (for SLACK_USER_TOKEN — only needed for slack_search):

Scope	Enables
search:read	slack_search tool

search.messages is only available with a user token — bots cannot search. Skip the user token entirely if you don't need search.

3. Install to workspace

Still on OAuth & Permissions → click Install to Workspace at the top → authorize. (If your workspace requires admin approval, an admin must approve it.)

4. Copy the tokens

After installing, the same page shows:

• Bot User OAuth Token — starts with xoxb- → your SLACK_BOT_TOKEN
• User OAuth Token — starts with xoxp- → your SLACK_USER_TOKEN

export SLACK_BOT_TOKEN=xoxb-...
export SLACK_USER_TOKEN=xoxp-...  # Optional, needed for slack_search

5. Invite the bot to channels

A bot token can only read channels the bot is a member of. In each Slack channel you want the agent to read, type:

/invite @your-app-name

Otherwise slack_read_messages returns not_in_channel.

6. Optional project config

Create .pi/slack.json in your project to set a default channel and message limit:

{
  "defaultChannel": "C0123ABC456",
  "messageLimit": 50
}

Finding channel IDs

Open a channel in Slack → click the channel name → scroll to the bottom of the popup; the ID (C0123ABC456) is shown there. Or run slack_list_channels once the bot is installed to list channels with their IDs.

Checking status

Run /slack in pi to see token detection and project config status.

Install

pi install @dreki-gg/pi-slack