Metadata-Version: 2.4
Name: meanwhile-rain
Version: 0.6.0
Summary: Horizontal matrix rain of things happening right now
Project-URL: Homepage, https://github.com/tomdavenport/meanwhile
Project-URL: Repository, https://github.com/tomdavenport/meanwhile
Project-URL: Issues, https://github.com/tomdavenport/meanwhile/issues
Author: Tom Davenport
License-Expression: MIT
License-File: LICENSE
Keywords: matrix,news,screensaver,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# meanwhile

**Horizontal matrix rain of things happening right now.**

[![AUR version](https://img.shields.io/aur/version/meanwhile-rain?logo=archlinux&label=AUR)](https://aur.archlinux.org/packages/meanwhile-rain)
[![PyPI version](https://img.shields.io/pypi/v/meanwhile-rain?logo=pypi&label=PyPI)](https://pypi.org/project/meanwhile-rain/)
[![License: MIT](https://img.shields.io/github/license/tomdavenport/meanwhile)](https://github.com/tomdavenport/meanwhile/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://github.com/tomdavenport/meanwhile/blob/main/meanwhile.py)
[![Stars](https://img.shields.io/github/stars/tomdavenport/meanwhile?style=social)](https://github.com/tomdavenport/meanwhile/stargazers)

A wall of code sweeps across your terminal. Embedded in the noise — readable
if you look — are real things: live news headlines, local intel for places
you care about, and true, quietly poetic facts about what is happening
somewhere on Earth at this exact moment.

![meanwhile in motion](https://raw.githubusercontent.com/tomdavenport/meanwhile/main/shots/rain.gif)

In *The Matrix*, the operators stopped seeing code and started seeing the
world through it. That's the idea: an ambient screen you can actually read.
Glance at it and it's rain; look at it and it's the world.

- **News** — live headlines, narrowed by your topics, decoded into the
  stream. **Click a headline and its story decodes into the rain** as a
  short summary; shift-click opens the article in your browser (headlines
  are real OSC 8 hyperlinks).
- **Local intel** — tune to any towns or regions and read what is
  happening there, down to village-notice level.
- **Poetic** — true things happening right now, for scale and gratitude,
  drawn from a growing set of veins: the sky, the sea, deep time, the body,
  creatures, other people. Live counters (people born since you opened the
  window, what Voyager 1 did while you watched), tonight's actual moon phase,
  where the sun is rising at this second, what the season is doing at the
  poles. Every line is true, and more are finding their way in.

Zero runtime dependencies. One Python file. Runs on Linux, macOS, and WSL
with Python 3.11+.

## Install

With [uv](https://docs.astral.sh/uv/) (Linux, macOS, or WSL):

```sh
uv tool install meanwhile-rain
```

Or with pipx:

```sh
pipx install meanwhile-rain
```

On macOS with Homebrew:

```sh
brew install tomdavenport/tap/meanwhile
```

On Arch: `yay -S meanwhile-rain` (the plain name was taken by the old
Lotus Sametime library, of all things).

From source:

```sh
git clone https://github.com/tomdavenport/meanwhile.git
cd meanwhile
ln -sf "$PWD/meanwhile.py" ~/.local/bin/meanwhile
meanwhile
```

## No API key? It just works.

Out of the box, headlines come from **public RSS feeds for your region**
(detected from your locale — BBC, NPR, Guardian, NHK, and friends; set
`"region"` in the config or pass `--region us` to steer it). Click a
headline and the feed's own story summary decodes into the rain.

With an [Exa](https://exa.ai) key (`EXA_API_KEY` in your environment, or
point `env_files` in the config at a `.env` that has it), the news upgrades:
headlines follow **your topics** (`fast` type — Exa's cheapest tier, a few
requests per refresh), **places** unlock true local intel, and clicked
stories decode as fresh, live-crawled summaries.

## Keys

| key | action | key | action |
|-----|--------|-----|--------|
| `click` | **decode a story into the rain** | `q` | quit |
| `enter` | pick a story to decode (↑/↓ + enter) | `space` | pause |
| `t` | edit topics | `g` | edit places (local intel) |
| `f` | focus — surface the text | `n` / `o` | a headline / something true |
| `m` / `p` | toggle news / poetic | `r` | refresh headlines |
| `+` / `-` | speed | `s` / `?` | status / help |

Editors: type + enter adds, `1`–`9` removes, esc closes. Changes persist
and refetch immediately.

## Reading modes

By default text sits **embedded** — a shade above the field, part of the
code. Press `f` for **focus** and headlines surface in full contrast when
you actually want to read the world. The preference sticks.

Click any headline (or press `enter` to pick one) and its story decodes
into the stream as a short summary — you never leave the rain:

![summary](https://raw.githubusercontent.com/tomdavenport/meanwhile/main/shots/summary.png)

## Theming — it adopts *your* colors

Three tiers, automatic, in this order:

1. **[Omarchy](https://omarchy.org)**: meanwhile reads your active theme
   and rains in its palette — and when you switch themes, the rain follows
   within seconds, live. No configuration.
2. **Any modern terminal**: no Omarchy? meanwhile asks the terminal itself
   for its colors (an OSC query — kitty, Alacritty, ghostty, foot, WezTerm,
   xterm all answer) and rains in whatever theme you already run.
3. **Classic matrix green** everywhere else — or force it anytime with
   `--theme matrix`.

![omarchy theming](https://raw.githubusercontent.com/tomdavenport/meanwhile/main/shots/omarchy-theme.png)

## Screensaver

```sh
meanwhile --saver     # any key or click exits, cmatrix-style
```

Pair it with your idle daemon (hypridle, swayidle) to drop into the rain
when you step away. A true **Wallpaper Engine / live wallpaper build is on
the roadmap** — it needs a web port of the renderer; if that's your thing,
the door is open.

## Config

`~/.config/meanwhile/config.json`, created on first run:

| key | meaning |
|-----|---------|
| `topics` | what the news follows (also: `t` in-app; needs an Exa key) |
| `places` | places for local intel (also: `g` in-app; needs an Exa key) |
| `region` | RSS fallback region (`"auto"` reads your locale) |
| `poetic_ratio` | fraction of lines that are poetic |
| `density`, `speed`, `message_every_seconds` | feel of the rain |
| `focus`, `theme`, `show_source`, `ascii_only` | look |
| `refresh_minutes`, `hours_back` | news freshness window |
| `check_updates` | one cached GitHub release check (`false` disables it completely) |
| `env_files` | where to find `EXA_API_KEY` |

Headlines are cached in `~/.cache/meanwhile/` so launch is instant.
The update check contacts GitHub at most once every 24 hours, shows one dim
hint per new release, and never downloads or installs anything.

## Community

- [brendan-jarvis/meanwhile](https://github.com/brendan-jarvis/meanwhile) —
  a full **Rust port** with prebuilt binaries, WezTerm/Starship theme
  inheritance and an S&P ticker mode. Its regional-RSS idea flowed back
  into this repo in v0.5. This is exactly the kind of forking the rain
  approves of.
- Issues and PRs welcome — new poetic veins especially. Every line must be
  *true*.

## Notes

- Plain click decodes a summary in-app; shift-click follows the OSC 8
  hyperlink (kitty, Alacritty, ghostty, foot, WezTerm and most modern
  terminals; inside tmux you need a recent tmux). Set `"mouse": false`
  in the config to leave the mouse alone entirely.
- CPU ~1–2% of one core; it's just characters.
- Every so often — not often — the rain has something to say to you
  directly. If you're impatient, you know whose name to type.

## License

[MIT](https://github.com/tomdavenport/meanwhile/blob/main/LICENSE)
