telegram-journal-analytics

JijiBot 🐾 | Telegram Companion & Discord Relay

Offline, privacy-first reflection familiar, real-time Discord webhook stream, and analytical time-capsule engine for personal Telegram channels.

Interactive Demos (Synthetic Benchmark)

Interactive reports generated from a 400-message mock dataset. No server required; fully static HTML/JS.

Module Description Live Demo CLI Command
Master Dossier All-in-one unified dashboard combining all 4 engines dashboard.html python -m scripts.run_all
Channel-Wrapped Annual & all-time Spotify Wrapped-style story deck wrapped.html python -m scripts.run_wrapped
On This Day (OTD) Multi-year personal flashback for matching calendar days on_this_day.html python -m scripts.run_otd
Tag Lifecycles Streamgraph & lifespan categorization of bracket tags [tag] tag_lifecycle_report.html python -m scripts.run_tag_lifecycles
Circadian Habits 24-hour distribution, weekly heatmaps & longitudinal shifts circadian_report.html python -m scripts.run_circadian

Features & Visuals

1. Master Journal Dossier & Unified Dashboard

An all-in-one standalone HTML intelligence dossier that aggregates every analytical engine into a single cohesive report with sticky section navigation:

# Run everything and generate output/dashboard.html
python -m scripts.run_all

# Open directly in default web browser
python -m scripts.run_all --open

# Also output individual reports alongside the master dashboard
python -m scripts.run_all --all-reports

👉 Explore the live demo: demos/dashboard.html

2. Tag & Hobby Lifecycles

Extracts bracket tags (e.g. [reading], [fitness], [f1]) and classifies them into Evergreen passions, Seasonal bursts, and Emerging eras.

Hobby Streamgraph

Tag Lifespans Gantt

Tag Turnover Matrix

3. Circadian & Habit Heatmaps

Analyzes message timestamps to determine natural reflection hours, peak day of the week, and schedule shifts over time.

Weekly Heatmap

Hourly Distribution

Longitudinal Shift

4. On This Day (OTD) Time Capsule

Surfaces what you wrote on today’s calendar date across previous years. Includes active spans, photo indicators, and compact formatting.

$ python -m scripts.run_otd --date 09-15

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📅 1 YEAR AGO (2025) · 4 messages · 1:40 AM -> 11:44 PM
──────────────────────────────────────────────────────────────────────
   1. [1:40 AM] Cooked dinner at home today instead of ordering takeout.
   2. [10:29 PM] 📷 [reading] Picked up a new paperback today during lunch break.
   3. [10:55 PM] Quick reminder to drink more water and get to sleep earlier tonight.
   4. [11:44 PM] [synthv] Exported the final audio mixdown, sounds balanced and clean.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📅 2 YEARS AGO (2024) · 4 messages · 7:47 AM -> 2:35 PM
──────────────────────────────────────────────────────────────────────
   1. [7:47 AM] 📷 [coding] Finally resolved a stubborn caching bug that bugged me for days.
   2. [10:41 AM] [baking] Proofing dough overnight for fresh bread tomorrow morning.
   3. [11:48 AM] [reading] The plot twist in this chapter caught me completely off guard.
   4. [2:35 PM] Had a productive day clearing backlogged tasks and emails.

5. Channel-Wrapped Retrospective

Spotify Wrapped-style retrospective highlighting your annual or all-time writing volume, book page metaphors, longest streaks, circadian personas (e.g. The Midnight Philosopher), top fixations, and standout memories.

═══════════ ✨ CHANNEL-WRAPPED RETROSPECTIVE: 2024 ✨ ════════════
  • Total Entries:       136 messages
  • Words Inscribed:     1,367 words (8,738 characters)
  • Real-World Metaphor: ~5.0 book pages (~7 min read)
  • Consistency:         104/366 active days (28.4%)
  • Archetype:           The Midnight Philosopher 🦉
  • Peak Reflection Hour:11:00 PM (24h: 23:00)
  • Top Fixations:       [reading] (21), [fitness] (19), [coffee] (19)
════════════════════════════════════════════════════════════════

6. JijiBot Companion & Live Discord Webhook Relay

A silent 24/7 background daemon (scripts/setup_daemon.py) that captures live channel reflections, merges them with historical archives, and streams them into Discord:

Quickstart

1. Setup Environment

# Using Conda
conda env create -f environment.yml
conda activate tele-journal

# Or using standard venv
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. Run JijiBot Background Service

# Install and run 24/7 daemon on macOS
python -m scripts.setup_daemon install

# View status & logs
python -m scripts.setup_daemon status

3. Run on Synthetic Benchmark

# Generate 400 mock entries (Dec 2023 - Sep 2026)
python -m scripts.generate_synthetic_export --output-dir "ChatExport_sample"

# Run analytics against mock data (master dossier)
python -m scripts.run_all --export-dir "ChatExport_sample"

# Or run individual modules
python -m scripts.run_wrapped --export-dir "ChatExport_sample" --year 2024
python -m scripts.run_otd --export-dir "ChatExport_sample"
python -m scripts.run_tag_lifecycles --export-dir "ChatExport_sample"
python -m scripts.run_circadian --export-dir "ChatExport_sample"

4. Run on Real Telegram Export

Export chat history in Telegram Desktop as HTML:

# Place export in repo and point to it
python -m scripts.run_all
python -m scripts.run_otd --export-dir "path/to/ChatExport"
python -m scripts.run_otd --date 04-20 --window 2
python -m scripts.run_otd --random

5. Run Automated Tests

# 100% self-contained; all 68 tests pass without private data
python -m unittest discover tests

Potential Future Features