ring-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{ring_cli-0.5.0 → ring_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -59,7 +59,10 @@ RiNG puts them on one board, with sessions waiting for you sorted first.
 - **Waiting first**: sessions that need your response are highlighted and sorted above the rest.
 - **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, Terminal.app (macOS), or a Linux X11 window (`wmctrl`).
 - **Notifies you without the board open**: with hooks installed, the moment a session turns 🔴 waiting it beeps and fires a system notification — even with no RiNG board running. With `terminal-notifier`, clicking the notification jumps back.
-- **Name your sessions**: press `n` in the TUI to add a local label such as `maigo · auth refactor`.
+- **Name your sessions**: press `n` in the TUI to name a session, e.g. "auth refactor"; once named, the board and notifications show the name instead of the workspace directory.
+- **See what it is waiting for**: in hook mode, a 🔴 waiting session carries the concrete pending item (the command to run, the question asked) — shown in the TUI and in the notification body.
+- **Fits your status bar**: `ring --format oneline` prints a `🔴2 🟢1 🟡3` one-liner for tmux / SwiftBar / waybar; `--format json` feeds scripts.
+- **Rings your phone too**: built-in ntfy / webhook notifiers push 🔴 waiting to your phone when you are away from the desk.
 - **Local and extensible**: RiNG only reads local Claude Code / Codex data and writes `~/.config/ring/`; session sources, focusers, and notifiers are pluggable.
 
 ## Run
@@ -119,12 +122,39 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring doctor` | Read-only environment diagnosis |
 | `ring gc --dry-run` | Preview RiNG-owned stale state cleanup |
 | `ring gc` | Clean RiNG-owned stale state files |
+| `ring --format json` | Machine-readable board snapshot (for jq / scripts) |
+| `ring --format oneline` | `🔴2 🟢1 🟡3` one-liner (for status bars) |
+| `ring stats` | Waiting stats: how long agents kept 🔴 waiting in the last 7 days |
+| `ring completion zsh` | Print a shell completion script (zsh / bash) |
+
+### Status Bar Integration (`--format`)
+
+```sh
+ring --format oneline        # 🔴2 🟢1 🟡3 (empty output when no sessions, so the segment collapses)
+ring --format json | jq '.counts.waiting'
+```
+
+- **tmux**: `set -g status-right '#(ring --format oneline) …'` (with `status-interval 5`).
+- **SwiftBar / xbar / waybar**: wrap `ring --format oneline` or consume the JSON.
+- JSON keys are a stable interface (additive only), safe to script against.
+
+### Shell Completion (`ring completion`)
+
+```sh
+# ~/.zshrc
+eval "$(ring completion zsh)"
+# ~/.bashrc
+eval "$(ring completion bash)"
+```
+
+Completes subcommands, flags, and `config set` keys.
 
 ## Watch Mode
 
 - With **Textual** (`[tui]` extra) in a real terminal: interactive TUI.
   Use `↑/↓` to select, `Enter` / `Space` to jump, `n` to name a session, `a` to toggle ended sessions, `r` to refresh, and `q` to quit.
   If you have vim muscle memory like I do, `j/k` move up/down and `g/G` jump to the first/last row.
+  When the selected row is 🔴 waiting, a line under the table shows **what it is concretely waiting for** (the command to run, the question asked; hook mode only).
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -155,6 +185,20 @@ Without it, RiNG falls back to macOS text notifications without click-to-focus.
 Notification sound, repeat timing, and backend selection are configurable; notification backends
 are also pluggable via the `Notifier` extension point.
 
+#### Push To Your Phone (ntfy / webhook)
+
+Desktop notifications do not help when you are away from the desk. Point RiNG at an
+[ntfy](https://ntfy.sh) topic to push to your phone:
+
+```toml
+# ~/.config/ring/config.toml
+notify_ntfy_url = "https://ntfy.sh/my-ring-topic"  # subscribe to the same topic in the ntfy app
+notify_also = ["ntfy"]                             # desktop notification as usual, plus a copy to the phone
+```
+
+`notify_backend = "ntfy"` pushes to the phone only. For Slack / your own bot / IFTTT, set
+`notify_webhook_url` to use the generic webhook backend (JSON POST with a stable, additive-only payload).
+
 ### Cleaning RiNG State Files (`ring gc`)
 
 When RiNG receives `SessionEnd`, it removes its own hook registry entry. If an agent crashes or the
@@ -171,6 +215,19 @@ ring gc --all-ended      # delete every registry file currently classified as en
 `ring gc` only cleans state files RiNG owns under `~/.config/ring/`. It does not touch Claude Code /
 Codex transcripts or state. `ring doctor` remains read-only and never deletes files.
 
+### Waiting Stats (`ring stats`)
+
+In hook mode, RiNG logs session **state transitions** to `~/.config/ring/events.jsonl`
+(transitions only, tiny, self-trimming past a size cap). `ring stats` then tells you, per project,
+how many times an agent 🔴 waited on you and for how long (avg / max / total).
+
+```sh
+ring stats               # last 7 days
+ring stats --since 12h   # custom window
+```
+
+Like precise notifications, 🔴 waiting is invisible to zero-config, so stats also needs hook mode.
+
 ## Session Sources
 
 RiNG collects sessions from registered sources. Built-ins:
@@ -311,7 +368,11 @@ notify_ignore_dnd = false
 notify_backend = "auto"          # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
 notify_repeat_seconds = [30, 120, 300]
 notify_repeat_max = 3
+notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
+notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
+notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]
 focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
+plugins = []                     # external plugin modules imported at startup (see Extending)
 
 [colors]
 waiting = "bold red"
@@ -331,15 +392,35 @@ RiNG is not tied to a specific tool or terminal.
 |-----------------|---------|-----------|
 | `SessionSource` | find sessions | Claude Code, Codex, hook registry |
 | `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
-| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send |
+| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send, ntfy, webhook |
 
 Each backend is a small module under `ring/sources/`, `ring/focus/`, or `ring/notify/`, registered via `register_*()`.
 
+### Loading Your Plugin Into An Installed `ring`
+
+`register_*()` only counts if something runs it. The installed `ring` command loads plugins from
+two places at startup:
+
+1. **Entry point** (for published packages) — declare it in your package's `pyproject.toml`,
+   pointing at a module or callable (a module registers on import; a callable is invoked once
+   with no arguments):
+
+   ```toml
+   [project.entry-points."ring.plugins"]
+   mytool = "ring_mytool.plugin"
+   ```
+
+2. **Config** (for local scripts) — add `plugins = ["my_module"]` to `~/.config/ring/config.toml`;
+   the module must be importable (site-packages or `PYTHONPATH`).
+
+A broken plugin prints one warning line to stderr and never blocks the board.
+
 ## Platform & Privacy
 
 - **Platform**: macOS / Linux. Windows is not supported.
-- **Privacy**: entirely local. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
-  `~/.config/ring/`. No network, uploads, or telemetry.
+- **Privacy**: local by default. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
+  `~/.config/ring/`. No telemetry. The only network calls are the optional ntfy / webhook notifiers,
+  and only to URLs you configure yourself.
 
 ## Name
 

{ring_cli-0.5.0 → ring_cli-0.6.0}/README.en.md

@@ -34,7 +34,10 @@ RiNG puts them on one board, with sessions waiting for you sorted first.
 - **Waiting first**: sessions that need your response are highlighted and sorted above the rest.
 - **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, Terminal.app (macOS), or a Linux X11 window (`wmctrl`).
 - **Notifies you without the board open**: with hooks installed, the moment a session turns 🔴 waiting it beeps and fires a system notification — even with no RiNG board running. With `terminal-notifier`, clicking the notification jumps back.
-- **Name your sessions**: press `n` in the TUI to add a local label such as `maigo · auth refactor`.
+- **Name your sessions**: press `n` in the TUI to name a session, e.g. "auth refactor"; once named, the board and notifications show the name instead of the workspace directory.
+- **See what it is waiting for**: in hook mode, a 🔴 waiting session carries the concrete pending item (the command to run, the question asked) — shown in the TUI and in the notification body.
+- **Fits your status bar**: `ring --format oneline` prints a `🔴2 🟢1 🟡3` one-liner for tmux / SwiftBar / waybar; `--format json` feeds scripts.
+- **Rings your phone too**: built-in ntfy / webhook notifiers push 🔴 waiting to your phone when you are away from the desk.
 - **Local and extensible**: RiNG only reads local Claude Code / Codex data and writes `~/.config/ring/`; session sources, focusers, and notifiers are pluggable.
 
 ## Run
@@ -94,12 +97,39 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring doctor` | Read-only environment diagnosis |
 | `ring gc --dry-run` | Preview RiNG-owned stale state cleanup |
 | `ring gc` | Clean RiNG-owned stale state files |
+| `ring --format json` | Machine-readable board snapshot (for jq / scripts) |
+| `ring --format oneline` | `🔴2 🟢1 🟡3` one-liner (for status bars) |
+| `ring stats` | Waiting stats: how long agents kept 🔴 waiting in the last 7 days |
+| `ring completion zsh` | Print a shell completion script (zsh / bash) |
+
+### Status Bar Integration (`--format`)
+
+```sh
+ring --format oneline        # 🔴2 🟢1 🟡3 (empty output when no sessions, so the segment collapses)
+ring --format json | jq '.counts.waiting'
+```
+
+- **tmux**: `set -g status-right '#(ring --format oneline) …'` (with `status-interval 5`).
+- **SwiftBar / xbar / waybar**: wrap `ring --format oneline` or consume the JSON.
+- JSON keys are a stable interface (additive only), safe to script against.
+
+### Shell Completion (`ring completion`)
+
+```sh
+# ~/.zshrc
+eval "$(ring completion zsh)"
+# ~/.bashrc
+eval "$(ring completion bash)"
+```
+
+Completes subcommands, flags, and `config set` keys.
 
 ## Watch Mode
 
 - With **Textual** (`[tui]` extra) in a real terminal: interactive TUI.
   Use `↑/↓` to select, `Enter` / `Space` to jump, `n` to name a session, `a` to toggle ended sessions, `r` to refresh, and `q` to quit.
   If you have vim muscle memory like I do, `j/k` move up/down and `g/G` jump to the first/last row.
+  When the selected row is 🔴 waiting, a line under the table shows **what it is concretely waiting for** (the command to run, the question asked; hook mode only).
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -130,6 +160,20 @@ Without it, RiNG falls back to macOS text notifications without click-to-focus.
 Notification sound, repeat timing, and backend selection are configurable; notification backends
 are also pluggable via the `Notifier` extension point.
 
+#### Push To Your Phone (ntfy / webhook)
+
+Desktop notifications do not help when you are away from the desk. Point RiNG at an
+[ntfy](https://ntfy.sh) topic to push to your phone:
+
+```toml
+# ~/.config/ring/config.toml
+notify_ntfy_url = "https://ntfy.sh/my-ring-topic"  # subscribe to the same topic in the ntfy app
+notify_also = ["ntfy"]                             # desktop notification as usual, plus a copy to the phone
+```
+
+`notify_backend = "ntfy"` pushes to the phone only. For Slack / your own bot / IFTTT, set
+`notify_webhook_url` to use the generic webhook backend (JSON POST with a stable, additive-only payload).
+
 ### Cleaning RiNG State Files (`ring gc`)
 
 When RiNG receives `SessionEnd`, it removes its own hook registry entry. If an agent crashes or the
@@ -146,6 +190,19 @@ ring gc --all-ended      # delete every registry file currently classified as en
 `ring gc` only cleans state files RiNG owns under `~/.config/ring/`. It does not touch Claude Code /
 Codex transcripts or state. `ring doctor` remains read-only and never deletes files.
 
+### Waiting Stats (`ring stats`)
+
+In hook mode, RiNG logs session **state transitions** to `~/.config/ring/events.jsonl`
+(transitions only, tiny, self-trimming past a size cap). `ring stats` then tells you, per project,
+how many times an agent 🔴 waited on you and for how long (avg / max / total).
+
+```sh
+ring stats               # last 7 days
+ring stats --since 12h   # custom window
+```
+
+Like precise notifications, 🔴 waiting is invisible to zero-config, so stats also needs hook mode.
+
 ## Session Sources
 
 RiNG collects sessions from registered sources. Built-ins:
@@ -286,7 +343,11 @@ notify_ignore_dnd = false
 notify_backend = "auto"          # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
 notify_repeat_seconds = [30, 120, 300]
 notify_repeat_max = 3
+notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
+notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
+notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]
 focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
+plugins = []                     # external plugin modules imported at startup (see Extending)
 
 [colors]
 waiting = "bold red"
@@ -306,15 +367,35 @@ RiNG is not tied to a specific tool or terminal.
 |-----------------|---------|-----------|
 | `SessionSource` | find sessions | Claude Code, Codex, hook registry |
 | `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
-| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send |
+| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send, ntfy, webhook |
 
 Each backend is a small module under `ring/sources/`, `ring/focus/`, or `ring/notify/`, registered via `register_*()`.
 
+### Loading Your Plugin Into An Installed `ring`
+
+`register_*()` only counts if something runs it. The installed `ring` command loads plugins from
+two places at startup:
+
+1. **Entry point** (for published packages) — declare it in your package's `pyproject.toml`,
+   pointing at a module or callable (a module registers on import; a callable is invoked once
+   with no arguments):
+
+   ```toml
+   [project.entry-points."ring.plugins"]
+   mytool = "ring_mytool.plugin"
+   ```
+
+2. **Config** (for local scripts) — add `plugins = ["my_module"]` to `~/.config/ring/config.toml`;
+   the module must be importable (site-packages or `PYTHONPATH`).
+
+A broken plugin prints one warning line to stderr and never blocks the board.
+
 ## Platform & Privacy
 
 - **Platform**: macOS / Linux. Windows is not supported.
-- **Privacy**: entirely local. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
-  `~/.config/ring/`. No network, uploads, or telemetry.
+- **Privacy**: local by default. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
+  `~/.config/ring/`. No telemetry. The only network calls are the optional ntfy / webhook notifiers,
+  and only to URLs you configure yourself.
 
 ## Name
 

{ring_cli-0.5.0 → ring_cli-0.6.0}/pyproject.toml

@@ -2,14 +2,22 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Wei Lee", email = "weilee.rx@gmail.com" }]
-keywords = ["claude-code", "codex", "tui", "dashboard", "session", "monitor", "rich"]
+keywords = [
+  "claude-code",
+  "codex",
+  "tui",
+  "dashboard",
+  "session",
+  "monitor",
+  "rich",
+]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Environment :: Console",
@@ -40,7 +48,13 @@ dev = [
   { include-group = "linters" },
 ]
 base = ["poethepoet>=0.41.0", "babel>=2.14"]
-test = ["pytest>=9", "pytest-cov>=4", "pytest-xdist>=3.1.0", "pytest-asyncio>=0.24", "textual>=0.80"]
+test = [
+  "pytest>=9",
+  "pytest-cov>=4",
+  "pytest-xdist>=3.1.0",
+  "pytest-asyncio>=0.24",
+  "textual>=0.80",
+]
 linters = ["ruff>=0.15.1", "mypy>=1.19.1", "prek>=0.3.3", "commitizen>=4.13.9"]
 
 [build-system]

{ring_cli-0.5.0 → ring_cli-0.6.0}/src/ring/cli.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 import time
 from dataclasses import fields
@@ -18,10 +19,12 @@ from typing import Any
 
 from ring import __version__
 from ring.commands._args import strip_lang as _strip_lang
+from ring.commands.completion import run_completion
 from ring.commands.doctor import run_doctor
 from ring.commands.focus import run_focus
 from ring.commands.gc import run_gc
 from ring.commands.hook import run_hook_command, run_install_hooks, run_remove_hooks
+from ring.commands.stats import run_stats
 from ring.config import CONFIG_PATH as CONFIG_PATH
 from ring.config import Config as Config
 from ring.config import ConfigError as ConfigError
@@ -30,6 +33,7 @@ from ring.config import set_value as set_value
 from ring.i18n import gettext as _
 from ring.i18n import ngettext, set_lang
 from ring.labels import load_labels
+from ring.plugins import load_plugins
 from ring.registry import Session, Status, running_agent_pids
 from ring.sources import discover_sessions
 
@@ -134,8 +138,12 @@ def provider_label(provider: str) -> str:
 
 
 def labeled_project(project: str, label: str) -> str:
-    """專案名後接使用者自訂標籤（有的話）：``maigo · 重構登入``。"""
-    return f"{project} · {label}" if label else project
+    """看板顯示名：使用者取過名（TUI 按 ``n``）就用名字，否則用專案（目錄）名。
+
+    名字本來就是「這個 session 在做什麼」的更精準描述，取了就直接取代 workspace 名，
+    不再併排（``maigo · 重構登入`` 太佔欄寬）。
+    """
+    return label or project
 
 
 def show_tool_column(sessions: list[Session]) -> bool:
@@ -234,6 +242,55 @@ def _render_plain(sessions: list[Session], show_legend: bool, show_tool: bool =
     return "\n".join(lines)
 
 
+# ----------------------------------------------------------------------------- machine-readable
+def render_json(sessions: list[Session]) -> str:
+    """整個看板的機器可讀快照（給 jq / 腳本 / 自訂 status bar widget 用）。
+
+    鍵名視為穩定介面：只加不改。``label`` 是使用者在 TUI 按 ``n`` 取的名字，沒取過為空字串。
+    """
+    labels = load_labels()
+    data = {
+        "generated_at": time.time(),
+        "agent_processes": len(running_agent_pids()),
+        "counts": {st.value: sum(1 for s in sessions if s.status is st) for st in Status},
+        "sessions": [
+            {
+                "session_id": s.session_id,
+                "provider": s.provider,
+                "project": s.project,
+                "label": labels.get(s.session_id, ""),
+                "status": s.status.value,
+                "marker": s.status.marker,
+                "cwd": s.cwd,
+                "location": s.location,
+                "tmux_target": s.tmux_target,
+                "tty": s.tty,
+                "idle_seconds": round(s.idle_for, 1),
+                "last_active": s.last_active,
+                "last_action": s.last_action,
+                "waiting_detail": s.waiting_detail,
+                "todo": {"done": s.todo[0], "total": s.todo[1]} if s.todo else None,
+                "source": s.source,
+            }
+            for s in sessions
+        ],
+    }
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def render_oneline(sessions: list[Session]) -> str:
+    """超精簡單行摘要（給 tmux status bar / SwiftBar / waybar 用）：``🔴2 🟢1 🟡3``。
+
+    只列非零狀態；完全沒 session 時回空字串，讓 status bar 段落自然收起來。
+    """
+    parts = [
+        f"{st.marker}{n}"
+        for st in (Status.WAITING, Status.WORKING, Status.IDLE, Status.ENDED)
+        if (n := sum(1 for s in sessions if s.status is st))
+    ]
+    return " ".join(parts)
+
+
 # ----------------------------------------------------------------------------- entry
 def print_snapshot(sessions: list[Session], show_legend: bool) -> None:
     show_tool = show_tool_column(sessions)
@@ -389,6 +446,8 @@ commands:
   focus SESSION_ID             聚焦指定 session；TUI 在跑時會回到 RiNG 並選中該列
   gc [--dry-run]               清理 RiNG 自己的 stale 狀態檔
   doctor                       顯示環境診斷（唯讀）——hook、通知、focuser、維護提示
+  stats [--since 7d]           等待統計：你讓 agent 🔴 等了多久（hook 模式）
+  completion SHELL             印出 shell 補全腳本（zsh / bash）
 """
     )
 
@@ -443,6 +502,22 @@ options:
 
 唯讀環境診斷：逐節報告 hook 安裝狀態、通知後端可用性、focuser 可用性、維護提示與設定檔位置。
 不寫任何檔案、不安裝、不發通知；固定回傳 0。
+"""
+        ),
+        "stats": _(
+            """usage: ring stats [--since DURATION]
+
+等待統計：最近一段時間各專案讓你回應的次數與 🔴 等待時長（平均 / 最長 / 總計）。
+資料來自 hook 寫的狀態轉換 log（~/.config/ring/events.jsonl），zero-config 測不到等待。
+
+options:
+  --since DURATION  統計時間窗（例如 12h、7d、30d；預設 7d）
+"""
+        ),
+        "completion": _(
+            """usage: ring completion zsh|bash
+
+印出 shell 補全腳本。zsh 放 ~/.zshrc：eval "$(ring completion zsh)"；bash 同理。
 """
         ),
     }
@@ -453,10 +528,12 @@ def main(argv: list[str] | None = None) -> int:
     raw = list(sys.argv[1:] if argv is None else argv)
     cfg = get_config()
     set_lang(_peek_lang(raw) or cfg.lang)  # 在 import ring.tui 前設好，Footer 按鍵說明也跟著語言
+    load_plugins()  # 在任何 dispatch 之前：hook（notifier plugin）與看板（source plugin）都吃得到
 
     if (
         raw
-        and raw[0] in {"hook", "install-hooks", "remove-hooks", "config", "focus", "gc", "doctor"}
+        and raw[0]
+        in {"hook", "install-hooks", "remove-hooks", "config", "focus", "gc", "doctor", "stats", "completion"}
         and any(arg in {"-h", "--help"} for arg in raw[1:])
     ):
         print(_subcommand_help(raw[0]), end="")
@@ -474,6 +551,10 @@ def main(argv: list[str] | None = None) -> int:
         return run_gc(raw[1:])
     if raw and raw[0] == "doctor":
         return run_doctor(raw[1:])
+    if raw and raw[0] == "stats":
+        return run_stats(raw[1:])
+    if raw and raw[0] == "completion":
+        return run_completion(raw[1:])
     if raw and raw[0] == "focus" and len(raw) >= 2:
         return run_focus(raw[1:])
 
@@ -495,8 +576,22 @@ def main(argv: list[str] | None = None) -> int:
         help=_("顯示顏色圖例（--no-legend 關閉）"),
     )
     parser.add_argument("--lang", help=_("語言（如 en / zh-Hant；也吃 config / RING_LANG / LANG）"))
+    parser.add_argument(
+        "--format",
+        choices=["table", "json", "oneline"],
+        default="table",
+        help=_("輸出格式：table（預設）/ json（機器可讀）/ oneline（status bar 單行摘要）"),
+    )
     args = parser.parse_args(raw)
 
+    if args.format != "table":
+        if args.watch:
+            print(_("--format {fmt} 只能用在快照模式，不能配 --watch。", fmt=args.format), file=sys.stderr)
+            return 2
+        sessions = board(args.all)
+        print(render_json(sessions) if args.format == "json" else render_oneline(sessions))
+        return 0
+
     if args.watch:
         if HAVE_TEXTUAL and sys.stdout.isatty():
             from ring.tui import run_tui

ring_cli-0.6.0/src/ring/commands/completion.py

@@ -0,0 +1,167 @@
+"""``ring completion SHELL``——印出 zsh / bash 補全腳本。
+
+CLI 是手寫 dispatch（不是純 argparse subparsers），所以補全腳本也自己生：
+子命令 / 旗標寫死在模板，config 鍵在生成時從 ``settable_keys()`` 動態帶入，
+新增設定鍵不必回來改這裡。用法::
+
+    # zsh（放 ~/.zshrc）
+    eval "$(ring completion zsh)"
+
+    # bash（放 ~/.bashrc）
+    eval "$(ring completion bash)"
+"""
+
+from __future__ import annotations
+
+import sys
+
+from ring.commands._args import strip_lang as _strip_lang
+from ring.config import settable_keys
+from ring.i18n import gettext as _
+
+# 子命令與頂層旗標——跟 cli.main 的 dispatch / argparse 保持同步。
+_COMMANDS = (
+    "hook",
+    "install-hooks",
+    "remove-hooks",
+    "config",
+    "focus",
+    "gc",
+    "doctor",
+    "stats",
+    "completion",
+)
+_TOP_FLAGS = (
+    "--watch",
+    "--interval",
+    "--count",
+    "--all",
+    "--legend",
+    "--no-legend",
+    "--lang",
+    "--format",
+    "--version",
+    "--help",
+)
+
+_ZSH_TEMPLATE = """\
+# ring zsh completion — eval "$(ring completion zsh)"
+_ring() {{
+  local -a commands
+  commands=(
+    'hook:read a provider hook payload from stdin'
+    'install-hooks:install Claude Code / Codex hooks'
+    'remove-hooks:remove Claude Code / Codex hooks'
+    'config:show / get / set configuration'
+    'focus:focus a session by id'
+    'gc:clean stale RiNG state files'
+    'doctor:read-only environment diagnosis'
+    'stats:waiting-time statistics'
+    'completion:print shell completion script'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'ring command' commands
+    _arguments \\
+      '--watch[keep refreshing]' \\
+      '--interval[refresh seconds]:seconds:' \\
+      '--count[frames before exit]:count:' \\
+      '--all[include ended sessions]' \\
+      '--legend[show legend]' \\
+      '--no-legend[hide legend]' \\
+      '--lang[UI language]:lang:(en zh-Hant)' \\
+      '--format[output format]:format:(table json oneline)' \\
+      '--version[show version]'
+    return
+  fi
+
+  case $words[2] in
+    hook)
+      _arguments '--provider[provider name]:provider:(claude-code codex)'
+      ;;
+    install-hooks|remove-hooks)
+      _arguments '--dry-run[preview only, no writes]'
+      ;;
+    gc)
+      _arguments \\
+        '--dry-run[preview only, no deletes]' \\
+        '--older-than[age threshold, e.g. 30m / 2h / 7d]:duration:' \\
+        '--all-ended[remove every ended registry]'
+      ;;
+    completion)
+      (( CURRENT == 3 )) && _values 'shell' zsh bash
+      ;;
+    config)
+      if (( CURRENT == 3 )); then
+        _values 'config action' get set
+      elif (( CURRENT == 4 )); then
+        _values 'config key' {keys}
+      fi
+      ;;
+  esac
+}}
+if ! command -v compdef >/dev/null 2>&1; then
+  autoload -Uz compinit
+  compinit
+fi
+compdef _ring ring
+"""
+
+_BASH_TEMPLATE = """\
+# ring bash completion — eval "$(ring completion bash)"
+_ring_completion() {{
+  local cur prev
+  cur="${{COMP_WORDS[COMP_CWORD]}}"
+  prev="${{COMP_WORDS[COMP_CWORD - 1]}}"
+
+  if [[ $COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "{commands} {flags}" -- "$cur") )
+    return
+  fi
+
+  case "$prev" in
+    --format) COMPREPLY=( $(compgen -W "table json oneline" -- "$cur") ); return ;;
+    --lang) COMPREPLY=( $(compgen -W "en zh-Hant" -- "$cur") ); return ;;
+    --provider) COMPREPLY=( $(compgen -W "claude-code codex" -- "$cur") ); return ;;
+  esac
+
+  case "${{COMP_WORDS[1]}}" in
+    hook) COMPREPLY=( $(compgen -W "--provider" -- "$cur") ) ;;
+    install-hooks|remove-hooks) COMPREPLY=( $(compgen -W "--dry-run" -- "$cur") ) ;;
+    gc) COMPREPLY=( $(compgen -W "--dry-run --older-than --all-ended" -- "$cur") ) ;;
+    completion) [[ $COMP_CWORD -eq 2 ]] && COMPREPLY=( $(compgen -W "zsh bash" -- "$cur") ) ;;
+    config)
+      if [[ $COMP_CWORD -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "get set" -- "$cur") )
+      elif [[ $COMP_CWORD -eq 3 ]]; then
+        COMPREPLY=( $(compgen -W "{keys}" -- "$cur") )
+      fi
+      ;;
+  esac
+}}
+complete -F _ring_completion ring
+"""
+
+
+def completion_script(shell: str) -> str | None:
+    """生成指定 shell 的補全腳本；不支援的 shell 回 ``None``。"""
+    keys = settable_keys()
+    if shell == "zsh":
+        return _ZSH_TEMPLATE.format(keys=" ".join(keys))
+    if shell == "bash":
+        return _BASH_TEMPLATE.format(commands=" ".join(_COMMANDS), flags=" ".join(_TOP_FLAGS), keys=" ".join(keys))
+    return None
+
+
+def run_completion(args: list[str]) -> int:
+    """``ring completion`` 進入點：印腳本到 stdout；shell 缺漏 / 不支援 → 用法到 stderr、rc 2。"""
+    args = _strip_lang(args)
+    if len(args) != 1:
+        print(_("用法：ring completion zsh|bash"), file=sys.stderr)
+        return 2
+    script = completion_script(args[0])
+    if script is None:
+        print(_("不支援的 shell：{shell}（目前支援 zsh / bash）", shell=args[0]), file=sys.stderr)
+        return 2
+    print(script)
+    return 0