dreki-gg-pi-slack

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# @dreki-gg/pi-slack

Slack read tools for [pi](https://github.com/earendil-works/pi-coding-agent) — messages, threads, channels, search, and file/image downloads.

Uses [Effect](https://effect.website) 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 |
| `slack_post_message` | Post a message to a channel or reply in a thread (requires `chat:write`) |
| `slack_edit_message` | Edit a message the bot previously posted (requires `chat:write`) |
| `slack_delete_message` | Delete a message the bot previously posted (requires `chat:write`) |

## Setup

### 1. Create a Slack App

Go to [api.slack.com/apps](https://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`

```bash
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:

```json
{
  "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

```bash
pi install @dreki-gg/pi-slack
```

@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
`slack_post_message`	Post a message to a channel or reply in a thread (requires `chat:write`)
`slack_edit_message`	Edit a message the bot previously posted (requires `chat:write`)
`slack_delete_message`	Delete a message the bot previously posted (requires `chat:write`)

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