Metadata-Version: 2.4
Name: blip-boop
Version: 0.1.0
Summary: Colored presences and floating particles in your terminal.
Author: Loreleï
License-Expression: MIT
Keywords: terminal,github,ambient,collaboration,pixels
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# blip-boop

**A little company in your terminal.**

Leave it open beside your code. You are a small colored pixel at the bottom of
an otherwise quiet screen. When you contribute on GitHub, a white particle rises,
drifts, and fades away. Other connected people share the space as colors.

No scores, leaderboards, or public usernames. Just a quiet sign that someone
else is making something.

## Install and join

Requires Linux or macOS, Python 3.10+, and a terminal with Unicode and 24-bit
color support. Install with [pipx](https://pipx.pypa.io):

```sh
pipx install blip-boop
blip-boop login
blip-boop
```

The hosted beta is **invite-only**. Get a one-time invitation from the operator
before your first login. Login opens GitHub in your browser and displays a device
code, then asks for the invitation in a hidden terminal prompt. The invitation
is linked to your GitHub account; later logins do not need another code.

Authorize the GitHub App, then install it on the repositories you want to
connect. No server setup or GitHub CLI installation is needed to participate.
The client uses `https://blip-boop-relay.onrender.com` by default.

The beta supports 50 simultaneous accounts and one terminal per account.
If the space is full, the client retries periodically without consuming another
invitation. Windows is not currently supported.

## What makes a particle?

- A push, excluding branch or tag deletion: one particle per push.
- A pull request opened.
- An issue opened.
- A review submitted.

Only supported GitHub events from connected participants produce particles.
Local commits that have not been pushed and bot events are not tracked. GitHub
webhook delivery may be delayed. Particles fade over 18–26 seconds.

## Controls

- `c`: change your color and save it for next time.
- `q`, `Esc`, or `Ctrl+C`: quit.
- A small dot marks your own pixel.

```sh
blip-boop status
blip-boop --help
blip-boop --version
pipx upgrade blip-boop
```

For another relay, run `blip-boop login --server https://YOUR-RELAY`.
Settings and your relay session are saved in your user configuration directory.

## Privacy

Peers receive pixel identifiers, colors, and contribution signals, not GitHub
usernames, repository names, code, or commit messages. The relay uses your
GitHub numeric user ID to match events to your pixel. It verifies a GitHub access
token transiently at sign-in; the token is not saved by blip-boop.

Connecting a private repository shares the timing of its supported activity.
Colors and timing can identify someone, so hidden usernames do not guarantee
anonymity. All participants on the hosted relay share the same space.

## License

MIT. The package includes client, relay, and operator command code. Hosted relay
administration requires a separate secret credential; installing the package
does not grant administrator access.
