slack-cli/AGENTS.md

AI Agent Guidelines

Project Overview

Reads Slack messages from the local Chromium IndexedDB cache on disk. Slack's desktop app (Mac App Store) persists its entire Redux state as a single Blink-serialized blob. We decode it with dfindexeddb and extract messages, channels, members, etc.

Project Structure

.
├── slack_cli/                     # Python package (canonical source)
│   ├── __init__.py
│   └── __main__.py                # CLI entry point
├── pyproject.toml                 # Python packaging metadata
├── flake.nix                      # Nix dev shell + package build
├── docs/
│   └── indexeddb-format.md        # Full IndexedDB data format documentation
└── scripts/
    └── analyze_structure.py       # Generates schema data for docs

Key Files

• slack_cli/__main__.py — Canonical CLI source. Entry point is main(), exposed as the slack-cli console script.
• pyproject.toml — Python packaging metadata. Declares slack-cli console script entry point and dfindexeddb dependency.
• docs/indexeddb-format.md — Documents the on-disk format: LevelDB layer, IndexedDB databases, Blink value encoding, and the full Redux state schema with field-level detail.
• scripts/analyze_structure.py — Introspects the live IndexedDB and dumps database/object-store/record-type info plus Redux state key schemas. Re-run this when the data format changes and update the docs accordingly.
• flake.nix — Nix dev shell (python3.12, uv, snappy) + standalone package build. Packages pinned PyPI deps (python-snappy==0.6.1, zstd==1.5.5.1, dfindexeddb) inline.

Dev Environment

nix develop          # Enter shell with python3.12, uv, snappy
./slack-cli.py      # uv resolves deps automatically via inline metadata

Or without nix, ensure python3.12, uv, and libsnappy are available.

Building

nix build            # Build standalone CLI to ./result/bin/slack-cli
nix run              # Build and run directly
nix run . -- --help  # Pass args

Dependencies

All Python deps are declared inline in each script's # /// script metadata block. uv resolves and caches them automatically. The only dependency is:

• dfindexeddb — Forensic parser for Chromium IndexedDB/LevelDB and Blink V8 serialized values.

The nix flake provides snappy (the C library) because python-snappy needs it to compile its native extension.

Important Rules

1. Timeout for bash tool: The bash tool MUST have a timeout specified.
2. File writing: Use the write / edit tools, not cat with heredocs.
3. No PII in docs: Documentation must contain zero identifying information — no real Slack IDs (user, channel, team, file, bot, group), names, emails, message content, or workspace names. Use anonymized placeholders like U0XXXXXXXXX, C0XXXXXXXXX, T0XXXXXXXXX, "MyBot", etc. The analysis scripts read live data, but anything written to docs/ must be scrubbed.

Style

Comment Style

A logical block of code should have a Title Case comment above it:

# Build Channel Name Lookup
channel_names = {}
for cid, cdata in channels_store.items():
    ...