Slack

The Slack VFS exposes a Slack workspace as a virtual filesystem mounted at some prefix such as /slack/. For token setup, see Slack Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.slack import SlackConfig, SlackVFS

config = SlackConfig(
    token=os.environ["SLACK_BOT_TOKEN"],
    search_token=os.environ.get("SLACK_USER_TOKEN"),
)
vfs = SlackVFS(config=config)
ws = Workspace({"/slack": vfs}, mode=MountMode.READ)

Field	Description
`start_time`	Start of the mount’s time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.
`end_time`	End of the mount’s time scope, exclusive, in the same format as `start_time`, which it must follow. Unset leaves the end open.
`timeout` default `30`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`token` required, secret	Slack token every API call sends: a bot token (`xoxb-`) or a user token (`xoxp-`).
`search_token` secret	User token (`xoxp-`) with `search:read`, used only for Slack’s `search.*` methods, which refuse a bot token. Unset searches with `token`.
`base_url` default `'https://slack.com/api'`	Slack Web API root; override to point at a fake or proxy.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Slack mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`slack`, read

`/<path>` layout

/<path>
  channels/
    <channel-name>__<channel-id>/
      <yyyy-mm-dd>/
        chat.jsonl                # messages for that date
        files/                    # attachments shared that day (may be empty)
          <name>__<F-id>.<ext>    # cat to download bytes
  dms/
    <user-name>__<dm-id>/
      <yyyy-mm-dd>/
        chat.jsonl
        files/
          <name>__<F-id>.<ext>
  users/
    <username>__<user-id>.json    # user profile
  Naming: channel/DM/user directory names are `<display-name>__<id>`.
  The display name keeps the original spelling from Slack; only `/` is
  replaced with `∕` (U+2215) so paths don't break. Quote names
  containing spaces in shell commands. Always ls the parent dir first
  to discover exact entry names (they include IDs).
  Without time bounds, bare channel listings show the latest 90 days
  ending at the newest message. Date globs can discover earlier days.
  With start_time/end_time, listings cover that scope; messages and their
  attachments outside it are absent, including through direct paths.
  Users and channel metadata remain available as context.
  On a time-scoped mount grep and rg see only the in-scope files.
  Messages are JSONL; use jq to extract fields like .text, .user, .ts, .files.
  .user is a user ID (U…), not a username; resolve it through
  users/<username>__<user-id>.json and filter messages by the ID.
  Unless walk_limit is -1, grep -rw and rg -w read only the channel
  and DM days Slack search names; attachments under files/ are always read.
  Time scope: start_time=unbounded (inclusive), end_time=unbounded (exclusive). Explicit paths and globs cannot escape this scope.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `slack` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `slack` answers only for `channels///chat.jsonl` and `dms///chat.jsonl`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `slack`, read |

## `/<path>` layout

```text
/<path>
  channels/
    <channel-name>__<channel-id>/
      <yyyy-mm-dd>/
        chat.jsonl                # messages for that date
        files/                    # attachments shared that day (may be empty)
          <name>__<F-id>.<ext>    # cat to download bytes
  dms/
    <user-name>__<dm-id>/
      <yyyy-mm-dd>/
        chat.jsonl
        files/
          <name>__<F-id>.<ext>
  users/
    <username>__<user-id>.json    # user profile
  Naming: channel/DM/user directory names are `<display-name>__<id>`.
  The display name keeps the original spelling from Slack; only `/` is
  replaced with `∕` (U+2215) so paths don't break. Quote names
  containing spaces in shell commands. Always ls the parent dir first
  to discover exact entry names (they include IDs).
  Without time bounds, bare channel listings show the latest 90 days
  ending at the newest message. Date globs can discover earlier days.
  With start_time/end_time, listings cover that scope; messages and their
  attachments outside it are absent, including through direct paths.
  Users and channel metadata remain available as context.
  On a time-scoped mount grep and rg see only the in-scope files.
  Messages are JSONL; use jq to extract fields like .text, .user, .ts, .files.
  .user is a user ID (U…), not a username; resolve it through
  users/<username>__<user-id>.json and filter messages by the ID.
  Unless walk_limit is -1, grep -rw and rg -w read only the channel
  and DM days Slack search names; attachments under files/ are always read.
  Time scope: start_time=unbounded (inclusive), end_time=unbounded (exclusive). Explicit paths and globs cannot escape this scope.
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` with `-w` ask `slack` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. Without `-w`, `grep -r` and `rg` read every file. `slack` answers only for `channels/*/*/chat.jsonl` and `dms/*/*/chat.jsonl`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

/slack/
  channels/
    <channel-name>__<channel-id>/
      <yyyy-mm-dd>/
        chat.jsonl
        files/
          <name>__<F-id>.<ext>
  dms/
    <user-name>__<dm-id>/
      <yyyy-mm-dd>/
        chat.jsonl
        files/
          <name>__<F-id>.<ext>
  users/
    <username>__<user-id>.json
    ...

Example:

/slack/
  channels/
    general__C04KEPWF6V7/
      2026-04-04/
        chat.jsonl
        files/
      2026-04-05/
        chat.jsonl
        files/
    random__C04JVGZM7UN/
      2026-04-11/
        chat.jsonl
        files/
  dms/
    alice__D0AQDJ5FP9V/
      2026-04-04/
        chat.jsonl
        files/
    slackbot__D0ARPA1QSPJ/
      2026-04-04/
        chat.jsonl
        files/
  users/
    alice__U12345678.json
    bob__U87654321.json

Directory names embed the Slack ID so that write commands (slack send-message --channel, etc.) can reference the correct VFS without extra lookups.

Channels

/slack/channels/ lists public and private channels the bot has access to. The channel ID is appended after __. Each channel directory contains day-partitioned directories for the last 90 days (or since channel creation, whichever is shorter). Each date directory contains chat.jsonl plus a files/ directory for attachments shared that day. The date range is derived from the channel’s created timestamp.

DMs

/slack/dms/ lists direct message conversations. The DM ID is appended after __. Like channels, DM directories contain daily directories with chat.jsonl and files/.

Users

/slack/users/ lists one .json file per non-deleted, non-bot user. Reading a user file calls get_user_profile() and returns the full profile JSON from the Slack API.

Cache

The Slack VFS uses IndexCacheStore (same as Discord and other mounts). Index entries store channel IDs, DM IDs, user IDs, and channel creation timestamps for date range computation. File bytes go through the workspace file cache.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.slack import SlackConfig, SlackVFS

load_dotenv(".env.development")

config = SlackConfig(
    token=os.environ["SLACK_BOT_TOKEN"],
    search_token=os.environ.get("SLACK_USER_TOKEN"),
)
vfs = SlackVFS(config=config)


async def main():
    ws = Workspace({"/slack": vfs}, mode=MountMode.READ)

    # List structure
    r = await ws.shell("ls /slack/")
    print(await r.stdout_str())

    # List channels
    r = await ws.shell("ls /slack/channels/")
    print(await r.stdout_str())

    ch = (await r.stdout_str()).strip().splitlines()[0]
    base = f"/slack/channels/{ch}"

    # Discover an available day, then read a few messages
    r = await ws.shell(f'ls "{base}/" | tail -n 1')
    day = (await r.stdout_str()).strip()
    r = await ws.shell(f'head -n 3 "{base}/{day}/chat.jsonl"')
    print(await r.stdout_str())

    # Extract message text with jq
    r = await ws.shell(
        f'cat "{base}/{day}/chat.jsonl"'
        ' | jq -r ".text" | head -n 5')
    print(await r.stdout_str())

    # Search across channel (scans all date files)
    r = await ws.shell(f'rg message "{base}/"')
    print(await r.stdout_str())

    # Tree view
    r = await ws.shell("tree -L 1 /slack/")
    print(await r.stdout_str())

    # Navigate with cd/pwd
    await ws.shell(f'cd "{base}"')
    r = await ws.shell("pwd")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

See examples/python/vfs/slack/slack.py for the full working example.

Finding IDs

VFS-specific commands require Slack IDs (channel_id, user_id, ts). These can be extracted from the filesystem:

# Channel ID - embedded in directory name after "__"
ls /slack/channels/
# → general__C04KEPWF6V7   ← channel_id = C04KEPWF6V7

# User ID - embedded in filename after "__"
ls /slack/users/
# → alice__U04K21SEVR9.json   ← user_id = U04K21SEVR9

# Message timestamp (ts) - inside JSONL messages
jq -r '"\(.ts) [\(.user)] \(.text)"' \
  "/slack/channels/general__C04KEPWF6V7/2026-04-04/chat.jsonl"
# → 1712345678.123456 [U04K21SEVR9] hello world

# Find a specific message then reply
jq -r 'select(.text | test("hello")) | .ts' \
  "/slack/channels/general__C04KEPWF6V7/2026-04-04/chat.jsonl"
# → 1712345678.123456
slack send-message --channel C04KEPWF6V7 \
  --thread-ts 1712345678.123456 --text "Reply to hello"

Working with Large Channels

Channels with many messages produce large chat.jsonl files per day. Tips for efficient access:

# Check message count per day
wc -l "/slack/channels/general__C04KEPWF6V7/2026-04-04/chat.jsonl"

# Read only recent messages
tail -n 10 "/slack/channels/general__C04KEPWF6V7/2026-04-04/chat.jsonl"

# Search across all dates (scans each file)
rg "keyword" "/slack/channels/general__C04KEPWF6V7/"

# Extract specific fields to reduce output
jq -r '"\(.ts) [\(.user)] \(.text)"' \
  "/slack/channels/general__C04KEPWF6V7/2026-04-04/chat.jsonl" | head -n 20

# Count messages per user
cat "/slack/channels/general__C04KEPWF6V7/2026-04-04/chat.jsonl" \
  | jq -r '.user' | sort | uniq -c

Shell Commands

Standard commands available on the mounted Slack tree:

Command	Notes
`ls`	List channels, DMs, users, dates
`cat`	Read `chat.jsonl`, user `.json`, or files
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON, once per JSONL line (`-s` all)
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view

Acting on Slack (sending, reacting, pins, member info, search) goes through the slack CLI when installed; the mounted tree stays read-oriented. The <name>__<id> path segments supply the channel and user IDs the CLI flags take.

Integration

What Slack answers through its own API, so fewer files are read. Integration explains each command.

Command	On Slack
`grep -r`, `rg`	Slack search, for whole words, with a user token. It can miss recent messages, words only in other fields (bot names and link previews).
`tail -f`	Each new message as it is posted

With a user token, grep -rw and rg -w read only the channel and DM days Slack search names, and print what reading every day would. Search covers message text, file names and titles (search.files) and reactions (has::name:); listing a day already fetches its history, so this saves the second fetch of each day it rules out. A file hit names each day the file was shared. Users, file blobs and a day searched on its own are always read. Every day is read when the word is a key or fixed value of the message JSON, a file-type or URL word, a join or leave message word, or part of a user’s name or of the workspace’s domain, and when a search fails, returns more than 1,000 messages or finds nothing. With a separate search_token, every day is also read when the scope holds a private channel or a DM that token’s user is not in (a bot’s own DMs), since their search never sees it; that token needs channels:read, groups:read, im:read and mpim:read to list the conversations it sees. walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Slack indexes a message some time after it is posted, and a word held only in another field of a message (a bot’s username, an unfurled link) is not searched.

Time scope

Set start_time and/or end_time in the mount’s YAML config (or pass start_time/end_time to Python; startTime/endTime to the TypeScript constructor). Bounds are RFC3339 timestamps with an explicit timezone and at most millisecond precision. Start is inclusive; end is exclusive. An omitted or null bound is open. Start must precede end.

mounts:
  /history:
    vfs: slack
    mode: read
    config:
      token: "<bot-token>"
      start_time: "2026-06-01T10:00:00Z"
      end_time: "2026-06-02T00:00:00Z"

With a bound configured, channel listings cover the selected period rather than the default recent window. Day directories use UTC. Messages are selected by creation time, and attachments follow their parent messages. Direct paths, stat, date globs, and grep/rg cannot escape the scope: a search only rules out files, so scoped searches scan the filtered files. User/member and channel/server metadata remain visible as context. These settings apply to the VFS, not to separately installed account CLIs. mode: read prevents mount writes; it does not freeze upstream edits or deletions. Rebuild/remount the VFS to change its scope so cached listings and bytes are cleared.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Channels

DMs

Users

Cache

Example

Finding IDs

Working with Large Channels

Shell Commands

Integration

Time scope

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Channels

​DMs

​Users

​Cache

​Example

​Finding IDs

​Working with Large Channels

​Shell Commands

​Integration

​Time scope

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Channels

DMs

Users

Cache

Example

Finding IDs

Working with Large Channels

Shell Commands

Integration

Time scope