RiNG 🎤
台灣華語 · English
Realtime Instance Notification Grid — one local board for all active agent-CLI sessions.
When several Claude Code, Codex, or local-model sessions are running, RiNG shows which ones are working, idle, or waiting for you. Sessions that need a response are sorted first.
🎤 RiNG — 3 sessions on stage · 2 agent processes running
🔴 maigo 12s → waiting for permission
🟢 pelican-osm 3s → Edit
🟡 commitizen 8m turn finished, idle
What It Does
- One board for session state: built-in sources for Claude Code, Codex, Ollama, and llama.cpp.
- Puts waiting sessions first: shows what 🔴 sessions need and sends desktop or phone notifications.
- Returns you to the right terminal: focuses tmux, iTerm2, Terminal.app, Neovim terminals, or Linux X11 windows from the TUI.
- Avoids an extra context switch: reply to permission requests in supported terminals and assign session names from the board.
- Fits existing workflows: status-bar output, JSON, a provider-neutral hook, and plugin extension points.
Get Started in Three Steps
Requires Python 3.13+:
uv tool install 'ring-cli[tui]'
ring --watch
ring install-hooks
ring --watchopens the interactive board. Select a session and pressEnterto return to its terminal.ring install-hooksinstalls Claude Code and Codex hooks for precise 🔴 waiting states and system notifications.- Restart agent sessions after installing hooks. RiNG can then notify you even while its board is closed.
Use pipx install 'ring-cli[tui]' if you prefer pipx. Run ring for a one-shot snapshot.
Common Operations
| Operation | Purpose |
|---|---|
ring |
Print a snapshot of every current session |
ring --watch |
Open the continuously updating interactive TUI |
Enter / Space |
Return to the selected session's terminal |
p |
Reply to the selected session's permission request in place |
n |
Name the selected session |
ring doctor |
Check hooks, notifications, and terminal focus support |
ring --format oneline |
Produce a summary for tmux, SwiftBar, or waybar |
Zero-config mode works without hooks. Precise 🔴 waiting states, pending details, and immediate notifications require hooks. Restart Claude Code or Codex sessions after installing or updating them.
Learn More
- Full guide: commands, TUI controls, hooks, notifications, configuration, extensions, and privacy
- Session states: how RiNG derives 🔴/🟢/🟡/⚫
- Contributing guide: development setup, tests, and PR checklist
RiNG supports macOS and Linux; Windows is not yet supported. By default it only reads local agent data and writes ~/.config/ring/. Network access occurs only for ntfy or webhook notifiers you configure.
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ring_cli-0.14.0.tar.gz.
File metadata
- Download URL: ring_cli-0.14.0.tar.gz
- Upload date:
- Size: 132.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d6d4211741b980175a8e255437131207328084d0d27bab424857b226b2f154d4
|
|
| MD5 |
0f51d4b2b781f136a58a8f6a6a16afff
|
|
| BLAKE2b-256 |
9aeed778bb8bc405e77bf205683b7e185779f474daa89effd162c2eff59b321c
|
Provenance
The following attestation bundles were made for ring_cli-0.14.0.tar.gz:
Publisher:
release.yml on Lee-W/ring
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ring_cli-0.14.0.tar.gz -
Subject digest:
d6d4211741b980175a8e255437131207328084d0d27bab424857b226b2f154d4 - Sigstore transparency entry: 2209155747
- Sigstore integration time:
-
Permalink:
Lee-W/ring@e6adeee281afb138c34ae508fef13cb006f30780 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/Lee-W
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@e6adeee281afb138c34ae508fef13cb006f30780 -
Trigger Event:
push
-
Statement type:
File details
Details for the file ring_cli-0.14.0-py3-none-any.whl.
File metadata
- Download URL: ring_cli-0.14.0-py3-none-any.whl
- Upload date:
- Size: 171.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1109dce4be041f5002b4c6f4894d06947fbc11b97847c4a040535b3df869c944
|
|
| MD5 |
95b670e512fb538423730ec3c374d0ee
|
|
| BLAKE2b-256 |
721411b7f428ef949f200e754ed4d1975b3279b8c6904aa837e2d37f8cb6ca83
|
Provenance
The following attestation bundles were made for ring_cli-0.14.0-py3-none-any.whl:
Publisher:
release.yml on Lee-W/ring
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ring_cli-0.14.0-py3-none-any.whl -
Subject digest:
1109dce4be041f5002b4c6f4894d06947fbc11b97847c4a040535b3df869c944 - Sigstore transparency entry: 2209155873
- Sigstore integration time:
-
Permalink:
Lee-W/ring@e6adeee281afb138c34ae508fef13cb006f30780 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/Lee-W
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@e6adeee281afb138c34ae508fef13cb006f30780 -
Trigger Event:
push
-
Statement type:
