# 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

```bash
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

```bash
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.