meditation

A colorful, animated, cross-platform terminal meditation companion — with a genuine (math-driven, not canned) rotating 3D wireframe animation, a guided inhale-hold-exhale breathing exercise, a Tharataka (candle-gazing) meditation, a session timer with progress tracking, comprehensive session history and statistics, and quick links out to further teachings.

Works anywhere Python 3 runs: Windows, Linux, macOS, Termux (Android), and iOS terminal apps (Pythonista, a-Shell).

Install

pip install meditation

On Termux, install Python first, then pip install as usual:

pkg install python
pip install meditation

On iOS (a-Shell or Pythonista), open a shell and run the same pip install meditation.

Usage

meditation

or

python -m meditation

What each menu option does

Session Tracking & Statistics

The app automatically tracks your meditation practice with:

• Persistent storage: All sessions saved to ~/.meditation_history.json
• Session types: Timer sessions, breathing exercises, Tharataka sessions, and reflections are all tracked
• Streak tracking: Counts consecutive days of meditation
• Weekly breakdown: Visual chart showing your practice for the last 7 days
• Monthly breakdown: Weekly totals for the last 30 days
• Progress bars: Visual representation of your consistency

How sessions are recorded:

Statistics you can view:

• Total sessions and total minutes
• Average session length
• Current streak in days (with emoji indicators)
• Last 7 days with daily totals (visual bars)
• Last 30 days with weekly breakdown
• Recent sessions with timestamps

Data Storage

Your meditation history is stored locally at:

~/.meditation_history.json

This file contains:

• All session records with timestamps and durations
• Session types (timer/breathing/tharataka/reflection)
• Last updated timestamp

You can clear your history from the statistics menu (option 4).

Color theme

All colors come from one deliberate 4-color palette (not random per character): saffron #f4a259, deep maroon #a13d63, teal #2ec4b6, and soft lavender #9d8df1 — inspired by monastic robes and calm water/sky.

Recent Updates

v2.2.0 — Tharataka Meditation

• Added Tharataka (candle-gazing) meditation mode
• Display: Full-screen white background with centered black circle
• Timer: Live countdown in MM:SS format at bottom of screen
• Fully integrates with session history and statistics
• Supports Ctrl+C to stop early

Development

git clone https://github.com/ishanoshada/Meditation-CLI.git
cd Meditation-CLI
pip install -e .
meditation

Build and publish with either toolchain — both pyproject.toml and setup.py are included:

python -m build
twine upload dist/*

Roadmap

More companion web apps are on the way — keep an eye on the GitHub profile for what's coming next.

Planned features:

• Session history tracking
• Statistics dashboard
• Streak tracking
• Tharataka meditation
• Export data to CSV
• Daily goals and reminders
• Sound integration (where supported)

Uninstall

pip uninstall meditation

License

MIT License — Ishan Oshada (ic31908@gmail.com)