A terminal-based privacy control system for auditing, archiving, and unsending Instagram Direct Messages. Built with Python 3.13+ and the Textual TUI framework — runs entirely offline with zero external data transmission.
Core Capabilities
A complete privacy toolkit for your Instagram DM history — scrape, inspect, and unsend at terminal speed.
On startup, Thread Vault silently probes cached credentials against the Instagram inbox API. Valid sessions route directly to the thread explorer. Expired sessions are cleared and the re-auth panel is shown automatically — no manual intervention needed.
A parallel scraper worker and unsend worker run concurrently over
a shared asyncio.Queue. Scraped messages are pushed
into the queue immediately — the unsend worker begins processing
while scraping is still in progress, maximizing throughput.
All scraped messages, cursor indexes, and cache files are swept from disk immediately upon logout or dashboard exit. Zero-persistence policy means your DM data never lingers beyond the active session.
Instagram's 429 rate limits are handled with exponential backoff and jitter — wait times expand dynamically across five cooldown stages (30s → 60s → 120s → 300s → 600s) with ±20% jitter. A live countdown progress bar in the dashboard tracks remaining wait time.
Three configurable scrape modes let you target exactly what you need — media only, text only, or everything. Modes filter at the pipeline level, meaning only the selected content types are queued for processing.
Scraped messages are written to a local SQLite database at
data/vault.db using WAL (Write-Ahead Logging) for
concurrent access, with a 5-second busy timeout. Four tables:
threads, scraped_messages, scrape_progress, and unsend_progress.
Built on the modern Textual framework with custom CSS cyberpunk neon themes, glassmorphism gradients, ASCII art logos, queue node visualizers, rate-limit countdown widgets, and a fully responsive multi-panel layout.
Authenticate via a headed Chromium browser (Playwright captures
cookies automatically) or by pasting a raw
sessionid value directly from browser DevTools. Both
methods write to the same cache/session.json file
atomically.
23 fully offline automated tests covering auth flow boot
sequences, cache file I/O, data isolation and purge lifecycle,
HTTP and unsend worker backoff, and scraping mode filters — all
runnable with a single uv run pytest command.
Content Scoping
Three precision modes give you full control over which message types are scraped and queued for unsending.
Targets exclusively media-type messages. Text content and captions are recursively stripped from all payloads before storage. Ideal for removing photos, videos, voice notes, and disappearing media.
Targets text messages and any unclassified fallback payload types. Also includes media types as secondary targets. Useful for scrubbing written conversations while preserving media.
Complete, unfiltered conversation archival. Every message type is scraped and queued regardless of classification. The most thorough option for full conversation cleanup or audit.
System Design
Four distinct layers coordinate through asyncio tasks — never blocking the Textual event loop.
VaultApp starts → StartupScreen silently validates cached credentials → routes to ThreadExplorerScreen (success) or AuthScreen (fail/no session) → select a thread → ThreadDetailScreen for mode selection → ScrapeReviewScreen for pipeline control.
ScraperWorker paginates the Instagram thread API,
filters by active mode, writes to SQLite (archival), and pushes
items to the asyncio.Queue.
UnsendWorker consumes queue items, calls the
unsend API, marks rows as deleted, and defers to
RateLimitManager on 429 responses.
Get Running Fast
Requires Python 3.13+ and uv package manager. Full
platform guides available for Windows, macOS, and Linux.
data/vault.db on your
local filesystem. No data is uploaded to external servers. All
cached session credentials and database records are automatically
purged upon logout or dashboard exit.
Interface Controls
Thread Vault CLI is fully keyboard-driven. Every action is accessible without a mouse.
| Key / Shortcut | Screen Context | Action |
|---|---|---|
| ctrl + c | Global | Immediately quit the application |
| escape | Screen Stack | Return to the previous screen |
| r | Thread Explorer | Reload thread directory from Instagram API |
| ctrl + f | Explorer / Dashboard | Focus the search bar |
| 1 / 2 / 3 | Scope Selector | Choose Mode A, B, or C |
| p | Scrape Dashboard | Start automatic parallel pipeline (Scrape + Unsend) |
| s | Scrape Dashboard | Manually scrape conversation targets |
| u | Scrape Dashboard | Manually unsend checked messages |
| space | Scrape Dashboard | Toggle selection on highlighted table row |
| ctrl + a | Scrape Dashboard | Select or clear all filtered table items |
| x | Scrape Dashboard | Reset pagination cursors (re-scrape from page 1) |
Platform Support
Dedicated installation and configuration instructions for your operating system.