61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# 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.
|