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. Supports three output formats via -f/--format:
- pretty (default) — ANSI/tree layout with URLs, for humans.
- llm — token-efficient text (no ANSI/URLs, grouped by channel+date, threads indented).
- jsonl — one JSON object per message; includes raw ts, channel_id, user_id. Renderers are render_pretty / render_llm / render_jsonl; cmd_messages builds the display list once and dispatches.
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.

2.9 KiB Raw Blame History