Skip to main content

RiNG 🎤

台灣華語 · English

PyPI Python License

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 and Codex, plus process-liveness detection for interactive Ollama and llama.cpp CLIs.
  • 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, kitty, 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
  1. ring --watch opens the interactive board. Select a session and press Enter to return to its terminal.
  2. ring install-hooks installs Claude Code and Codex hooks for precise 🔴 waiting states and system notifications.
  3. 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.

Troubleshooting And Uninstall

  • Hooks not taking effect: restart the agent session, then run ring doctor; hooks are writing only if ls ~/.config/ring/sessions/ shows <session_id>.json files.
  • Uninstall: ring remove-hooks, then uv tool uninstall ring-cli. State and config live in ~/.config/ring/; delete that directory by hand to wipe everything (ring gc only removes stale state files of ended sessions).
  • See "Troubleshooting And Uninstall" in the full guide for details.

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

Metadata

Release files for ring-cli 0.17.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ring-cli 0.17.6
File Size Uploaded Provenance Actions
ring_cli-0.17.6.tar.gz 171.8 kB With provenance Details for ring_cli-0.17.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ring-cli 0.17.6
File Interpreter ABI Platform Actions
ring_cli-0.17.6-py3-none-any.whl Python 3 none any Details for ring_cli-0.17.6-py3-none-any.whl

Total release size: 382.4 kB

Release files / ring_cli-0.17.6.tar.gz

Download URL ring_cli-0.17.6.tar.gz
Size 171.8 kB
Tags Source
SHA-256 checksum
How to use checksums
82504459884f02994b162a0c40b05d6eeff36c263c5bed8c4392b5797fd06a8b
BLAKE2b-256 checksum
How to use checksums
a5fbf3f9d5a2f7a8bfe14292e3f7f6cfed8aa83661bc74bbce23a264c635a97e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

Release files / ring_cli-0.17.6-py3-none-any.whl

Download URL ring_cli-0.17.6-py3-none-any.whl
Size 210.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1d10739491c6a22d5826baaefecad6da7587a124962fd81b2ee87dbc52f7baf
BLAKE2b-256 checksum
How to use checksums
1cb047fe5b4bf87b9c6b6deb4ceaf9f76f409405a60ef85b5b425f4400ad2a5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

Security for ring-cli 0.17.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ring_cli-0.17.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.17.6 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page