This Claude skill provides a comprehensive, standalone interface for Telegram, enabling advanced message export, DM management, and group synchronization. It is designed to bridge the gap between Telegram communications and AI workflows, allowing users to seamlessly ingest chat histories for context, manage contact priorities through scoring, and track conversation states directly within an AI-driven environment.

When should I use tg-ingest?

tg-ingest is useful in the following scenarios: • Case 1: Exporting recent Telegram DMs or group messages into Markdown format to provide immediate, high-fidelity context for Claude analysis. • Case 2: Synchronizing and archiving specific Telegram group chats to monitor market trends, community sentiment, or project updates over time. • Case 3: Managing high-volume communications by scoring contacts and tracking thread states (e.g., pending, done, archived) to ensure no critical message is missed. • Case 4: Performing deep-history backfills of Telegram conversations for long-term data analysis and knowledge base construction.

name	tg-ingest
description	>
"tg", "@username", or telegram-specific terms. Triggers	"telegram messages",

Telegram Export (tg-ingest)

Primary interface for all Telegram operations. Standalone and full-featured.

Location: /Users/satoshi/data/tg-ingest

Quick Start

cd /Users/satoshi/data/tg-ingest

# Check status
poetry run tg_export status

# Sync all DMs + whitelisted groups
poetry run tg_export sync-all

# Export specific DM
poetry run tg_export dump-dm --user vibhu --out exports/vibhu.jsonl

# List DMs
poetry run tg_export list-dms

Core Workflows

Quick Export for AI Context (Recommended)

Get recent messages as markdown, ready to paste into Claude:

# Syncs first, outputs to stdout (last 24h)
python scripts/quick_export.py klutch

# Custom time range
python scripts/quick_export.py klutch --hours 48

# Copy to clipboard
python scripts/quick_export.py klutch | pbcopy

# Visual copy in browser
python scripts/quick_export.py klutch | quick-view

# Intentional save
python scripts/quick_export.py klutch --save
# → exports/klutch_2026-01-02.md

See references/files.md for file management philosophy.

Export via CLI (Alternative)

# By username (pulls from API, may have caching issues)
poetry run tg_export dump-dm --user vibhu --out vibhu.jsonl

# Last 7 days only
poetry run tg_export dump-dm --user vibhu --last 7d --out vibhu.jsonl

Note: Prefer quick_export.py for reading synced data. Use dump-dm only for initial exports.

Sync Operations

# One-shot sync (DMs + whitelisted groups)
poetry run tg_export sync-all

# Backfill older messages
poetry run tg_export sync-all --backfill

# Live continuous sync
poetry run tg_export live --interval 5m

# Sync DMs only
poetry run tg_export sync-dms --dir data/dms

Manage Thread State

Thread states are stored in data/decisions.jsonl.

# Via CLI (if implemented) or direct file edit
# States: pending, done, archived
# Also supports: draft, snooze, note

See references/state.md for state management details.

Manage Groups

# List registered groups
poetry run tg_export groups list

# Add a group to sync
poetry run tg_export groups add "crypto trenches" --type trading

# Sync groups
poetry run tg_export groups sync

# Backfill group history
poetry run tg_export groups backfill crypto_trenches --limit 1000

See references/groups.md for registry management.

Contact Lookup & Scoring

# Initialize contacts from DMs
poetry run tg_export contacts-init --dm-dir data/dms

# List contacts by priority
poetry run tg_export contacts-list --tier high

# Score all contacts
poetry run tg_export contacts-score

# Show contact details
poetry run tg_export contacts-show vibhu

See references/contacts.md for scoring algorithm.

Data Locations

Path	Purpose
`data/dms/`	DM exports (.jsonl + .jsonl.idx)
`data/groups/`	Group exports
`data/registry.json`	Group registry
`data/decisions.jsonl`	Thread states
`data/session.session`	Telethon auth
`contacts/`	Contact database

Authentication

First-time setup:

# Set env vars (in .env or shell)
export TG_API_ID=your_id
export TG_API_HASH=your_hash

# Login (interactive)
poetry run tg_export login

Session persists in data/session.session.

Thread ID Format

Telegram threads use format: tg:dm:username or tg:group:slug

Examples:

tg:dm:vibhu - DM with @vibhu
tg:group:crypto_trenches - Group chat

tg-ingest

When & Why to Use This Skill

Use Cases