Slack

Bishop connects to Slack over Socket Mode, so it needs outbound access only.

Setup

From the agent's directory:

bishop slack setup

It asks for an app name, a display name, and a description, defaulting the name to the directory name. Pass them as flags to skip the questions:

bishop slack setup --name salesforce-guy \
    --display-name "Salesforce Guy" \
    --description "Answers Salesforce admin questions"

--no-prompt takes the defaults instead of asking. Bishop assumes it when there's no terminal, so this works in a script.

Setup creates the Slack app, installs it, writes the bot and app tokens to .env, and records the app in .bishop/config.json. Then start Bishop:

bishop

Invite the bot to a channel, or DM it directly.

Set slack.allow before inviting anyone. Without it, anyone who can reach the bot can use the agent. See Access.

Without the Slack CLI

If you can't install the CLI, or somebody else owns app creation in your workspace, Bishop can adopt an app you set up by hand.

First get the manifest, so the scopes and events are right by construction:

bishop slack manifest > manifest.json

Create the app in Slack from that file (Create New App, then From a manifest), install it to the workspace, then collect two tokens from App Settings: the bot token (xoxb-) under OAuth & Permissions, and an app-level token (xapp-) with connections:write under Basic Information.

bishop slack setup --manual

It asks for both tokens, checks them against Slack, and builds the config from what Slack reports. You don't have to type the app ID or name: auth.test returns them.

One thing it can't check is which events the app subscribes to. If the agent never answers anything, that's the first place to look.

How setup gets the tokens

Socket Mode needs an app-level (xapp-) token, and no Slack API will mint one. The slack CLI does, and hands it to a project it runs. So setup writes a throwaway Slack project, runs it once to collect both tokens, and stops it. The CLI creates that app as a dev app and appends (local) to its name, so setup pushes the intended manifest over it afterward. That changes no permissions and needs no reinstall.

The CLI's login expires after 12 hours. If setup says the app kept its (local) suffix, run slack auth login again, or rename the app in Slack.

Using it

DM the bot and every message reaches the agent.

@-mention it in a channel to start a thread. Bishop replies in that thread and follows the conversation there. It ignores everything else in the channel, including messages in threads it isn't part of.

Each thread is its own agent session with its own history, and picks up where it left off, including after Bishop restarts.

A turn shows its work. Slack marks the thread as working for as long as the agent is, which is also the stop button. Everything the agent writes lands as its own message as it writes it, and the tools it calls in between share a card that says what it is doing now. When the run of tool calls ends, the card becomes a line saying how many it used. The turn closes with the answer and a line saying how long it took, or how long it ran before you stopped it. ! verbosity turns this down.

It doesn't answer every message in a busy thread. In a thread where more than one other person is talking, the agent can leave a message alone when it wasn't for the agent. Slack still shows it thinking for a moment, the way somebody starts typing and then doesn't send. It always answers a message that @-mentions it, and always answers in a thread where you're the only other person talking.

Write while it's working. A message sent mid-turn gets an ⏳ and waits, rather than starting a second turn in the same conversation. When the turn ends, everything waiting goes to the agent as one prompt, with who wrote each one attached. Edit or delete a waiting message and the agent sees the change.

Share files with it. Attach a file to a message and the agent gets the path, screenshots included. Tag the agent into a thread that already has files in it and it's told what was shared, then downloads the ones it needs. See Files.

Mentions work both ways. The agent reads mentions of other people as names, and when it writes @name Bishop turns it into a real mention. A name that matches nobody, or more than one account, stays plain text. @here, @channel, and @everyone are never converted, so an agent can't wake a workspace.

Stop a turn. In a DM, Slack shows a stop button for as long as the turn runs. ! stop does the same in any thread, and anything sent while the turn was running is answered next.

Long answers are split. Slack caps messages near 4000 characters. Slack also doesn't render tables and handles nested lists badly, so agent output written for a terminal will sometimes look wrong in a thread.

Other agents

Pull two agents into the same thread and they can address each other, and the one you're talking to is told which messages came from another agent rather than a person.

• Neither can start the exchange. A bot's message is answered only in a thread that already has a session, so a bot can't DM the agent or open a thread with it.
• Apps that post under a name rather than an account, like an incoming webhook, are never answered.
• An exchange is capped at three turns in a row by default, after which Bishop says it's holding off and waits for a person. slack.maxBotTurns changes the cap, and 0 means the agent never answers another bot.
• A turn another agent drew can't use Bishop's own tools, so it can't leave a schedule behind.

Another app is an allow list entry like any other.

Scopes

An app installed by an older Bishop can be missing scopes a newer one uses. To grant them, update the app from the manifest bishop slack manifest prints and reinstall it from App Settings.

• files:read and files:write are what files need. Bishop warns at startup about each one missing, and until they're granted the agent sees a note in place of each file and a file it sends fails to upload.
• channels:read, groups:read and im:write are what adding a schedule with a Slack destination needs. bishop schedules add names the missing one.