Metadata-Version: 2.4
Name: meditation
Version: 3.0.0
Summary: A colorful, animated, cross-platform terminal meditation companion.
Home-page: https://github.com/ishanoshada/Meditation-CLI
Author: Ishan Oshada
Author-email: Ishan Oshada <ic31908@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ishanoshada/Meditation-CLI
Project-URL: Source, https://github.com/ishanoshada/Meditation-CLI
Project-URL: Bug Tracker, https://github.com/ishanoshada/Meditation-CLI/issues
Keywords: meditation,cli,terminal,mindfulness,breathing,ascii-art
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python


# 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 session timer with progress tracking,
**comprehensive session history and statistics**, and quick links out to
further teachings.

**Repo:** https://github.com/ishanoshada/Meditation-CLI

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

## Install

```bash
pip install meditation
```

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

```bash
pkg install python
pip install meditation
```

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

## Usage

```bash
meditation
```

or

```bash
python -m meditation
```

## What each menu option does

| Option | What it is |
|---|---|
| **1. Guided breathing exercise** | An animated circle walks you through **inhale → hold (4s) → exhale**, repeated for as many cycles as you choose. Sessions are automatically recorded. |
| **2. Meditation timer** | Pick a number of minutes and sit quietly while a progress bar and timer count the session down. **Option to view stats before starting.** Sessions are automatically recorded. |
| **3. View session history & stats** | **📊 NEW!** See your complete meditation journey with: <br> • Total sessions and total time <br> • Average session duration <br> • Current streak tracking (🔥 for 7+ days) <br> • Last 7 days breakdown with visual bars <br> • Last 30 days weekly breakdown <br> • Recent sessions list <br> • Option to clear history |
| **4. A quiet reflection** | Shows one short, original line to sit with — a small prompt for reflection, not a lecture. Recorded as a 1-minute reflection session. |
| **5. About this tool** | A quick summary of what the app is and how it works, including total sessions recorded. |
| **6. Open Abhidhamma Teachings** | Opens https://abhidhamma.ishanoshada.com/ — Buddha's deep teaching on the nature of mind. |
| **7. Open Lahari Mantras** | Opens https://lahari-mantras.ishanoshada.com/ — traditional chants for focus and devotion. |
| **0. Exit** | Closes the session. |

## 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, 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:
| Session Type | What gets recorded |
|---|---|
| **Guided breathing** | Duration based on number of cycles (inhale+hold+exhale) |
| **Meditation timer** | Full session duration (if completed or stopped early) |
| **Quiet reflection** | 1 minute reflection session |

### 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/reflection)
- Last updated timestamp

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

## 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.

## Development

```bash
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:

```bash
python -m build
twine upload dist/*
```

## Roadmap

More companion web apps are on the way — keep an eye on the
[GitHub profile](https://github.com/ishanoshada) for what's coming next.

Planned features:
- [x] Session history tracking
- [x] Statistics dashboard
- [x] Streak tracking
- [ ] Export data to CSV
- [ ] Daily goals and reminders
- [ ] Sound integration (where supported)

## Uninstall

```bash
pip uninstall meditation
```

## License

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

