fedi-wrap - A Spotify-style year wrap for your Fediverse instance (Mastodon-compatible API).
Generate beautiful, year-in-review reports for your Fediverse account with AI-powered personality insights.
Works with any Mastodon-compatible server: Mastodon, GoToSocial, Pleroma, Misskey, Akkoma, etc.
Most "Mastodon Wrapped" tools assume public API access β you give them your handle, and they fetch your data. But this doesn't work for everyone:
- GoToSocial and other servers don't expose public APIs for user data
- Privacy-conscious users don't want to hand their access tokens to third-party services
- Self-hosters want tools that work offline and respect their data sovereignty
Instead of building yet another web service that asks for your credentials, we leverage toot β a command-line tool many Fediverse users already have installed and authenticated. This means:
- β No tokens shared β your credentials never leave your machine
- β
Works with any server β if
tootcan access it, so can we - β Fully offline β everything runs locally (except optional AI)
- β Reuse existing auth β no new logins or OAuth flows
-
π Comprehensive Statistics
- Total posts, original content, boosts, and replies
- Social Impact Score with ranking tier
- Longest posting streak
- Activity heatmap calendar
- Monthly, hourly, and weekly distribution charts
-
π§ AI-Powered Insights (via Ollama, optional)
- Analyzes all posts (not just a sample) using chunked processing
- Emotional journey analysis
- Personality trait detection
- Writing style characterization
- Interest and passion topic identification
- Personalized year narrative
- Gracefully skipped if Ollama is unreachable
-
π¨ Beautiful Reports
- Dark theme with year-specific accent colors
- Responsive design for all devices
- Standalone HTML files (no server required)
- Top posts by engagement
- Local avatar download
-
π Privacy-First & Local
- No tokens or credentials shared β uses your existing
tootCLI session - All data fetching and processing happens on your machine
- No web service, no OAuth, no third-party access to your account
- Optional AI analysis via local Ollama (or skip entirely)
- No tokens or credentials shared β uses your existing
-
toot CLI - Mastodon command-line client
Install from: https://github.com/ihabunek/toot
# Install via Homebrew (macOS) brew install toot # Or via pip pip install toot
-
jq - JSON processor
# macOS brew install jq # Ubuntu/Debian sudo apt install jq
-
curl & bc - Usually pre-installed on macOS/Linux
-
Authenticated toot session
toot login # Login to your instance toot auth # Verify authentication
-
Ollama (optional, for AI insights)
- Any Ollama server with a language model
- Recommended models:
phi4:14b,llama3.1:latest - If unavailable, AI section is simply omitted
This project was developed with the assistance of AI tools, most notably Cursor IDE and Claude Code. These tools helped accelerate development and improve velocity. All AI-generated code has been carefully reviewed and validated through human inspection to ensure it aligns with the project's intended functionality and quality standards.
cp .env.example .env
# Edit .env if neededNote: Account is auto-detected from your active toot session!
# Generate wrapped report for current year
./wrapped.sh
# Generate for a specific year
./wrapped.sh 2024
# For a different account (overrides active toot session)
./wrapped.sh 2024 user@instance.social
# Skip AI analysis (faster)
./wrapped.sh 2024 --skip-ai
# Only fetch data, don't generate report
./wrapped.sh 2024 --fetch-only
# Use existing data, don't re-fetch
./wrapped.sh 2024 --no-fetchopen wrapped_2024_user_instance.social.htmlfedi-wrap/
βββ wrapped.sh # Main script (fetch + generate)
βββ template.html # HTML template with placeholders
βββ .env.example # Example configuration
βββ .env # Your configuration (create from example)
βββ avatars/ # Downloaded profile pictures
βββ index.html # Landing page linking all reports
βββ statuses_YEAR_*.json # Fetched post data (generated)
βββ wrapped_YEAR_*.html # Generated reports
βββ README.md
Copy .env.example to .env and customize:
cp .env.example .envSettings in .env:
# Default year (can be overridden via command line)
DEFAULT_YEAR=2025
# Ollama AI Configuration (optional - skipped if unreachable)
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_MODEL="llama3.1:latest"
# Posts per chunk for AI analysis (all posts are analyzed)
AI_CHUNK_SIZE=50Edit the get_year_colors() function in wrapped.sh:
get_year_colors() {
case "$1" in
2022) echo "#ec4899|#db2777" ;; # Pink
2023) echo "#14b8a6|#0d9488" ;; # Teal
2024) echo "#f59e0b|#d97706" ;; # Amber
2025) echo "#8b5cf6|#6366f1" ;; # Purple
*) echo "#8b5cf6|#6366f1" ;; # Default
esac
}./wrapped.sh [YEAR] [ACCOUNT] [OPTIONS]| Argument | Description |
|---|---|
YEAR |
Year to generate report for (default: from .env) |
ACCOUNT |
Full handle like user@instance (default: active toot session) |
--skip-ai |
Skip AI analysis (faster) |
--fetch-only |
Only fetch statuses, don't generate report |
--no-fetch |
Skip fetching, use existing data file |
Examples:
./wrapped.sh # Current year, active account
./wrapped.sh 2024 # Specific year
./wrapped.sh 2024 me@mastodon.social # Different account
./wrapped.sh 2024 --skip-ai # Without AI (faster)
./wrapped.sh 2024 --fetch-only # Just download data
./wrapped.sh 2024 --no-fetch # Regenerate from cached dataCalculated as: (reblogs Γ 2) + favorites + (posts Γ 0.1) + (streak Γ 5)
| Score | Tier |
|---|---|
| β₯10,000 | π Top 1% |
| β₯5,000 | π₯ Top 5% |
| β₯1,000 | π₯ Top 15% |
| β₯500 | β Top 30% |
| β₯100 | β¨ Top 50% |
| <100 | π± Growing |
- π’ The Broadcaster - >60% original content
- π― The Curator - >60% boosts
- π¬ The Socialite - >50% replies
- βοΈ The Balancer - Mixed posting style
- π¦ Night Owl - >15% posts between 0-5am
- π¦ Early Bird - >30% posts between 5-10am
- π Slacker - >60% posts during work hours
- βοΈ The Regular - Balanced schedule
for year in 2022 2023 2024 2025; do
./wrapped.sh $year
done
open index.htmltoot login # Login to your instance
toot auth # Verify authentication shows ACTIVE- Ensure you have posts for that year
- Verify authentication:
toot auth
- This is normal if Ollama is unreachable
- Check if Ollama server is running:
curl http://localhost:11434/api/tags - Verify
OLLAMA_BASE_URLin.env
brew install jq # macOS
apt install jq # Linuxbrew install bc # macOS
apt install bc # Linux- Inspired by Mastodon Wrapped
- Built for the Fediverse
- AI analysis powered by Ollama
- CLI access via toot
MIT License - Feel free to modify and share!
Made with π for the Fediverse