Skip to main content
Every channel and DM the bot can see becomes a folder of days, each with a chat.jsonl of that day’s messages and the files shared in it. Users become one JSON profile each.

Setup

Create a Slack app with a bot token. A user token is optional and only lets grep -w and slack search use Slack’s search.
  1. Open api.slack.com/apps, click Create New App, From scratch, name it (for example Mirage) and pick the workspace.
  2. Under OAuth & Permissions, Bot Token Scopes, add:
    • channels:read, channels:history: public channels
    • groups:read, groups:history: private channels (optional)
    • im:read, im:history: direct messages (optional)
    • mpim:read, mpim:history: group DMs (optional)
    • users:read: the users/ folder
    • files:read: attachments under files/
  3. Install App, Install to Workspace, then copy the Bot User OAuth Token (xoxb-...).
  4. Invite the bot to each channel it should read with /invite @Mirage. A channel it is not in answers Permission denied.
The mount never posts. The slack CLI needs chat:write for send-message and files:write for upload-file.
Slack’s search.messages refuses bot tokens.
  1. Under User Token Scopes, add search:read. For grep and rg, also add channels:read, groups:read, im:read and mpim:read, so Mirage can tell which channels and DMs that user’s search covers.
  2. Reinstall the app and copy the User OAuth Token (xoxp-...).
The bot token still does every read; the user token is used only for Slack’s search methods.

Connect

workspace.yaml

Layout

  • A name ends with its Slack ID after __. Each channel and DM lists one folder per day for the 90 days up to its newest message; start_time and end_time set another range.
  • A chat.jsonl line is one message as Slack’s API returns it; .user is a user ID, resolved through users/.
  • grep -w with a search_token asks Slack’s search which days match and reads only those. Without them, grep reads the files.

Sample runs

The mount is read-only. Post messages and upload files with the slack CLI.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.