playmaker-cli 0.4.0__py3-none-any.whl

playmaker/registry.py

@@ -0,0 +1,41 @@
+"""Map agent name -> handler instance + profile lookup."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from playmaker.agents.agy import AgyHandler
+from playmaker.agents.base import AgentHandler
+from playmaker.agents.claude import ClaudeHandler
+from playmaker.agents.codex import CodexHandler
+from playmaker.agents.gemini import GeminiHandler
+from playmaker.state import AGENTS_DIR
+
+_HANDLERS: dict[str, AgentHandler] = {
+    "claude": ClaudeHandler(),
+    "codex": CodexHandler(),
+    "agy": AgyHandler(),
+    "gemini": GeminiHandler(),
+}
+
+
+def get_handler(name: str) -> AgentHandler:
+    if name not in _HANDLERS:
+        raise KeyError(f"unknown agent {name!r}; available: {', '.join(_HANDLERS)}")
+    return _HANDLERS[name]
+
+
+def all_handlers() -> dict[str, AgentHandler]:
+    return dict(_HANDLERS)
+
+
+def find_profile(agent_name: str, project_cwd: Path | None = None) -> Path | None:
+    """Project-local profile takes precedence over global."""
+    candidates: list[Path] = []
+    if project_cwd is not None:
+        candidates.append(project_cwd / ".playmaker" / "agents" / f"{agent_name}.md")
+    candidates.append(AGENTS_DIR / f"{agent_name}.md")
+    for path in candidates:
+        if path.exists():
+            return path
+    return None

playmaker/state.py

@@ -0,0 +1,173 @@
+"""SQLite-backed run state for `playmaker`."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+PLAYMAKER_HOME = Path("~/.playmaker").expanduser()
+DB_PATH = PLAYMAKER_HOME / "state.db"
+LOGS_DIR = PLAYMAKER_HOME / "logs"
+OUTPUTS_DIR = PLAYMAKER_HOME / "outputs"
+AGENTS_DIR = PLAYMAKER_HOME / "agents"
+CONFIG_PATH = PLAYMAKER_HOME / "config.toml"
+QUOTAS_PATH = PLAYMAKER_HOME / "quotas.json"
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    agent TEXT NOT NULL,
+    agent_session_id TEXT,
+    prompt TEXT NOT NULL,
+    cwd TEXT NOT NULL,
+    files TEXT,
+    status TEXT NOT NULL,
+    started_at TEXT NOT NULL,
+    finished_at TEXT,
+    exit_code INTEGER,
+    cost_usd REAL,
+    duration_seconds REAL,
+    output_path TEXT,
+    session_file_path TEXT,
+    parent_id TEXT,
+    pid INTEGER,
+    model TEXT,
+    batch_id TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_status ON sessions(status);
+CREATE INDEX IF NOT EXISTS idx_agent ON sessions(agent);
+CREATE INDEX IF NOT EXISTS idx_started ON sessions(started_at DESC);
+"""
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def new_session_id() -> str:
+    return str(uuid.uuid4())
+
+
+@contextmanager
+def connect():
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+
+def ensure_dirs() -> None:
+    for d in (PLAYMAKER_HOME, LOGS_DIR, OUTPUTS_DIR, AGENTS_DIR):
+        d.mkdir(parents=True, exist_ok=True)
+
+
+def init_db() -> None:
+    ensure_dirs()
+    with connect() as c:
+        c.executescript(SCHEMA)
+        # Migration: pre-existing databases may lack newer columns.
+        existing_cols = {row["name"] for row in c.execute("PRAGMA table_info(sessions)")}
+        if "model" not in existing_cols:
+            c.execute("ALTER TABLE sessions ADD COLUMN model TEXT")
+        if "batch_id" not in existing_cols:
+            c.execute("ALTER TABLE sessions ADD COLUMN batch_id TEXT")
+        # Created after migration so it works on pre-existing tables too.
+        c.execute("CREATE INDEX IF NOT EXISTS idx_batch ON sessions(batch_id)")
+        c.commit()
+
+
+def insert_session(
+    *,
+    agent: str,
+    prompt: str,
+    cwd: str,
+    files: list[str] | None = None,
+    parent_id: str | None = None,
+    model: str | None = None,
+    batch_id: str | None = None,
+) -> str:
+    """Insert a new pending session, return its id."""
+    sid = new_session_id()
+    with connect() as c:
+        c.execute(
+            """
+            INSERT INTO sessions (
+                id, agent, prompt, cwd, files,
+                status, started_at, parent_id, model, batch_id
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                sid,
+                agent,
+                prompt,
+                cwd,
+                json.dumps(files) if files else None,
+                "pending",
+                now_iso(),
+                parent_id,
+                model,
+                batch_id,
+            ),
+        )
+        c.commit()
+    return sid
+
+
+def list_batch(batch_id: str) -> list[dict[str, Any]]:
+    """All sessions in a dispatch batch, oldest first."""
+    with connect() as c:
+        rows = c.execute(
+            "SELECT * FROM sessions WHERE batch_id = ? ORDER BY started_at ASC",
+            (batch_id,),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def update_session(session_id: str, **fields: Any) -> None:
+    if not fields:
+        return
+    cols = ", ".join(f"{k} = ?" for k in fields)
+    values = list(fields.values()) + [session_id]
+    with connect() as c:
+        c.execute(f"UPDATE sessions SET {cols} WHERE id = ?", values)
+        c.commit()
+
+
+def get_session(session_id: str) -> dict[str, Any] | None:
+    with connect() as c:
+        row = c.execute(
+            "SELECT * FROM sessions WHERE id = ? OR id LIKE ?",
+            (session_id, f"{session_id}%"),
+        ).fetchone()
+    return dict(row) if row else None
+
+
+def list_sessions(
+    *,
+    status: str | None = None,
+    agent: str | None = None,
+    limit: int = 50,
+) -> list[dict[str, Any]]:
+    sql = "SELECT * FROM sessions"
+    where = []
+    params: list[Any] = []
+    if status:
+        where.append("status = ?")
+        params.append(status)
+    if agent:
+        where.append("agent = ?")
+        params.append(agent)
+    if where:
+        sql += " WHERE " + " AND ".join(where)
+    sql += " ORDER BY started_at DESC LIMIT ?"
+    params.append(limit)
+    with connect() as c:
+        rows = c.execute(sql, params).fetchall()
+    return [dict(r) for r in rows]

playmaker/watcher.py

@@ -0,0 +1,145 @@
+"""Rich Live TUI for `playmaker watch`."""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+
+from playmaker import state
+from playmaker.registry import get_handler
+
+_ICONS = {
+    "pending": "⏳",
+    "running": "🔄",
+    "done": "✅",
+    "failed": "❌",
+    "killed": "🛑",
+}
+
+
+def _build_table() -> Table:
+    rows = state.list_sessions(limit=50)
+    # Keep non-terminal + recently terminated (last 5 minutes).
+    now = datetime.now(UTC)
+    keep = []
+    for r in rows:
+        if r["status"] in ("pending", "running"):
+            keep.append(r)
+        elif r["finished_at"]:
+            try:
+                finished = datetime.fromisoformat(r["finished_at"])
+            except ValueError:
+                continue
+            if (now - finished).total_seconds() < 300:
+                keep.append(r)
+
+    table = Table(
+        title=f"playmaker — live sessions ({len(keep)})",
+        show_header=True,
+        header_style="bold",
+    )
+    table.add_column("id", style="cyan", no_wrap=True)
+    table.add_column("agent", no_wrap=True)
+    table.add_column("status", no_wrap=True)
+    table.add_column("age", no_wrap=True)
+    table.add_column("activity")
+    table.add_column("prompt")
+
+    for r in keep:
+        try:
+            started = datetime.fromisoformat(r["started_at"])
+            age_s = (now - started).total_seconds()
+        except (TypeError, ValueError):
+            age_s = 0
+        age_str = _format_age(age_s)
+        icon = _ICONS.get(r["status"], "?")
+        prompt = (r["prompt"] or "").replace("\n", " ")
+        if len(prompt) > 60:
+            prompt = prompt[:57] + "..."
+        activity = _get_activity(r)
+        table.add_row(
+            r["id"][:8],
+            r["agent"],
+            f"{icon} {r['status']}",
+            age_str,
+            activity,
+            prompt,
+        )
+    return table
+
+
+def _get_activity(row: dict[str, Any]) -> str:
+    status = row["status"]
+    if status == "running":
+        path_str = row.get("session_file_path")
+        if not path_str:
+            return "starting..."
+        path = Path(path_str)
+        if not path.exists():
+            return "starting..."
+        try:
+            handler = get_handler(row["agent"])
+            turns = handler.parse_session_file(path)
+            if not turns:
+                return "starting..."
+            last = turns[-1]
+            if last.tool_calls:
+                # show "tool: <name>" of the LAST tool_call's 'name' field
+                name = last.tool_calls[-1].get("name", "")
+                text = f"tool: {name}"
+            elif last.content:
+                text = last.content
+            else:
+                return "starting..."
+
+            text = text.replace("\n", " ")
+            if len(text) > 60:
+                text = text[:57] + "..."
+            return text
+        except Exception:
+            return "-"
+
+    if status == "done":
+        out_path_str = row.get("output_path")
+        if not out_path_str:
+            return "-"
+        path = Path(out_path_str)
+        if not path.exists():
+            return "-"
+        try:
+            text = path.read_text().replace("\n", " ")
+            if len(text) > 60:
+                text = text[:57] + "..."
+            return text
+        except Exception:
+            return "-"
+
+    return "-"
+
+
+def _format_age(seconds: float) -> str:
+    seconds = int(seconds)
+    if seconds < 60:
+        return f"{seconds}s"
+    if seconds < 3600:
+        return f"{seconds // 60}m{seconds % 60:02d}s"
+    h, rem = divmod(seconds, 3600)
+    return f"{h}h{rem // 60:02d}m"
+
+
+def run() -> None:
+    state.init_db()
+    console = Console()
+    try:
+        with Live(_build_table(), console=console, refresh_per_second=1) as live:
+            while True:
+                time.sleep(1)
+                live.update(_build_table())
+    except KeyboardInterrupt:
+        console.print("[dim]watch stopped[/dim]")

playmaker_cli-0.4.0.dist-info/METADATA

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: playmaker-cli
+Version: 0.4.0
+Summary: Playing-coach CLI for orchestrating Claude Code, Codex and Antigravity sub-agents in parallel.
+Project-URL: Homepage, https://github.com/vladsafedev/playmaker
+Project-URL: Repository, https://github.com/vladsafedev/playmaker
+Project-URL: Issues, https://github.com/vladsafedev/playmaker/issues
+Author-email: Vladislav Shulyugin <vladislav.shulyugin@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,antigravity,claude,claude-code,cli,codex,gemini,orchestration,subagents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# playmaker
+
+[![CI](https://github.com/vladsafedev/playmaker/actions/workflows/ci.yml/badge.svg)](https://github.com/vladsafedev/playmaker/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/playmaker-cli.svg)](https://pypi.org/project/playmaker-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/playmaker-cli.svg)](https://pypi.org/project/playmaker-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Run Claude Code, Codex and Antigravity as parallel sub-agents from one terminal — and spend three separate quotas instead of one.**
+
+You stay in your Claude Code session doing the part only you can do. `playmaker`
+fans the rest out to other agent CLIs as detached processes, tracks them,
+parses their native session files, and pings you when they land.
+
+```console
+$ B=dashboard                      # one label for the whole fan-out
+
+$ playmaker dispatch codex  --batch $B --model gpt-5-codex -p "Add PATCH /users/:id …"
+session: 9f2c1a4e-…  pid: 48211  (detached)
+$ playmaker dispatch agy    --batch $B --model "Gemini 3.5 Flash (High)" -p "pytest coverage for …"
+session: 4b1f9c02-…  pid: 48219  (detached)
+$ playmaker dispatch claude --batch $B --model sonnet -p "Update the API docs for …"
+session: c07d5511-…  pid: 48244  (detached)
+
+# …you keep working in your own session while those three run
+
+$ playmaker list
+┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ id       ┃ agent  ┃ status  ┃ started             ┃ prompt                 ┃
+┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ 9f2c1a4e │ codex  │ running │ 2026-07-27T18:02:09 │ Add PATCH /users/:id … │
+│ 4b1f9c02 │ agy    │ done    │ 2026-07-27T18:02:11 │ pytest coverage for …  │
+│ c07d5511 │ claude │ done    │ 2026-07-27T18:02:14 │ Update the API docs …  │
+└──────────┴────────┴─────────┴─────────────────────┴────────────────────────┘
+
+🔔  playmaker — batch done                    # one ping for the whole fan-out…
+    3/3 done · codex ✓ · agy ✓ · claude ✓     # …click it to open every output
+
+$ playmaker summary 9f2c1a4e                  # what codex says it did
+$ playmaker continue 9f2c1a4e -p "the 404 branch is missing a test"
+```
+
+## Why
+
+Three reasons to fan work out across agent CLIs instead of grinding through it
+in one serial session:
+
+1. **Wall-clock speed.** A task that decomposes into 3–5 independent
+   work-streams (schema, backend, frontend, tests, docs) finishes 2–4× faster
+   when each stream runs as its own parallel agent.
+2. **Provider arbitrage.** Codex and Antigravity quotas are entirely separate
+   pools from your Anthropic plan. Every slice you hand them is capacity your
+   main session never spends — and Antigravity's roster includes Claude
+   Sonnet/Opus, so even Claude-quality work can run on Google's pool.
+3. **Bucket arbitrage inside one plan.** Headless `claude -p` draws on the same
+   subscription as your interactive session, but per-model weekly buckets are
+   separate — dispatching `--model sonnet` spends Sonnet's usually-idle bucket
+   instead of the scarce Opus one.
+
+The catch: doing this by hand — terminal tabs, jumping between tools,
+copy-pasting context — is friction. `playmaker` removes the friction; the
+[coach skill](#the-coach-skill) provides the discipline.
+
+## ⚠️ Sub-agents skip permission prompts by default
+
+By default, playmaker launches Claude and Antigravity sub-agents with
+`--dangerously-skip-permissions` (and Gemini with `--yolo`). This is
+deliberate: a headless agent has no human at the keyboard, so without these
+flags a detached run stalls at the first tool-approval prompt and finishes
+having written nothing.
+
+It also means a dispatched agent can run commands and edit files **without
+asking**. Only dispatch prompts you'd be comfortable running unattended, in
+working directories you trust.
+
+To opt out for Claude, set this in `~/.playmaker/config.toml`:
+
+```toml
+[agents.claude]
+skip_permissions = false
+```
+
+— with the caveat above: detached runs will then stall on the first permission
+prompt, so this only really makes sense alongside `--sync` workflows or
+allowlist rules you've configured in Claude Code itself.
+
+## Install
+
+```bash
+uv tool install playmaker-cli        # or: pipx install playmaker-cli
+```
+
+<details>
+<summary>From source</summary>
+
+```bash
+git clone https://github.com/vladsafedev/playmaker
+cd playmaker
+uv tool install --editable .
+```
+
+</details>
+
+Then set up the data directory and install the coach skill:
+
+```bash
+playmaker init            # creates ~/.playmaker/ (state.db, logs/, outputs/, config.toml)
+playmaker skill install   # drops playmaker-coach into ~/.claude/skills/
+playmaker agents          # which agent CLIs are reachable
+```
+
+## Prerequisites
+
+`playmaker` orchestrates external CLIs — install whichever you have access to:
+
+| Agent | Install | Notes |
+|---|---|---|
+| **Claude Code** | `npm i -g @anthropic-ai/claude-code` | `--model sonnet` / `opus` / `haiku` |
+| **Codex CLI** | `npm i -g @openai/codex` | `--model gpt-5-codex` |
+| **Antigravity (`agy`)** | bundled with [Antigravity](https://antigravity.google) | models are display names: `--model "Claude Opus 4.6 (Thinking)"` — see `agy models` |
+| **Gemini CLI** (legacy) | `npm i -g @google/gemini-cli` | still supported, superseded by `agy` |
+
+At least one is required; `playmaker agents` tells you which it can see.
+
+## The coach skill
+
+`playmaker` is the runner. The decision-making — *when* delegation beats doing
+it yourself, *which* agent gets *which* slice, how to size a subtask so
+reviewing it is cheap — lives in
+[**playmaker-coach**](skills/playmaker-coach/SKILL.md), a Claude Code skill
+that ships with the package:
+
+```bash
+playmaker skill install     # ~/.claude/skills/playmaker-coach/SKILL.md
+```
+
+Then give any Claude Code session a multi-component task and it activates:
+proposes a split with per-model quota rationale, waits for your approval, fans
+out, and reviews what comes back.
+
+## Commands
+
+```bash
+playmaker agents                              # who's installed
+playmaker quotas [--refresh]                  # capacity per provider, per model
+
+playmaker dispatch <agent> --prompt "..."     # detached by default
+                  [--model NAME]              # forwarded to the agent's own CLI
+                  [--cwd DIR]
+                  [--files PATH...]
+                  [--sync]                    # block and print the final answer
+                  [--parent ID]               # link lineage to an earlier session
+                  [--batch LABEL]             # group a fan-out; one summary ping
+playmaker continue <id> --prompt "..."        # follow-up inside the live session
+                  [--model NAME] [--files PATH...] [--sync]
+
+playmaker list [--status running|done|failed] [--agent NAME] [--limit N]
+playmaker get <id> [--wait] [--poll SECONDS]
+playmaker summary <id>                        # last 2 assistant messages
+playmaker thread <id> [--last N] [--all] [--role assistant|user|tool]
+                     [--include-tools] [--max-bytes N] [--follow]
+playmaker logs <id> [--follow]                # subprocess stdout for detached runs
+playmaker kill <id>
+playmaker watch                               # live TUI of sessions
+playmaker skill install [--dir PATH] [--force]
+```
+
+`dispatch`, `continue`, `list`, `get`, `thread` and `quotas` all take `--json`
+for scripting.
+
+**`continue` vs a fresh `dispatch`.** `continue` sends a follow-up into the
+agent's existing session, so its reasoning, tool history and file context are
+still live — that's the cheap path for "almost right, fix Y". Start fresh with
+`--parent <id>` only when the old context has become a liability.
+
+## How it works
+
+```mermaid
+flowchart LR
+    C["🧑‍🏫 coach<br/>your Claude Code session"] -->|dispatch| P(("playmaker"))
+    P --> A1["claude -p<br/><i>--model sonnet</i>"]
+    P --> A2["codex exec"]
+    P --> A3["agy -p"]
+    A1 & A2 & A3 --> S[("state.db<br/>outputs/ · logs/")]
+    S -->|list · thread · summary| C
+    S -.->|batch drained| N["🔔 one ping"]
+```
+
+Each dispatch is a detached OS process with its own quota; playmaker owns the
+bookkeeping in between.
+
+```
+~/.playmaker/
+├── state.db          SQLite — sessions, status, pids, models, output paths
+├── config.toml
+├── agents/           optional agent profile markdown (claude.md, codex.md, agy.md…)
+├── outputs/          final output per session — .md, or .json if the agent returned JSON
+├── logs/             subprocess stdout for detached runs
+└── quotas.json       latest capacity snapshot
+```
+
+`dispatch` runs the agent's CLI non-interactively, parses its native output,
+and locates the session file the tool writes locally. Empirically:
+
+| Agent | Session transcript |
+|---|---|
+| Claude | `~/.claude/projects/<cwd-with-slashes-as-dashes>/<id>.jsonl` |
+| Codex | `~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<ts>-<thread_id>.jsonl` |
+| Antigravity | `~/.gemini/antigravity-cli/brain/<conversation-id>/.system_generated/logs/transcript_full.jsonl` |
+| Gemini | `~/.gemini/tmp/<cwd-basename>/chats/session-<ts>-<short_id>.{json,jsonl}` |
+
+`thread` and `summary` normalize all of them into the same turn list, so every
+agent reads back in one shape.
+
+Profiles are optional and discovered, not shipped: drop
+`~/.playmaker/agents/<name>.md` (or `./.playmaker/agents/<name>.md` next to a
+repo, which wins) and it is prepended to every dispatch for that agent.
+
+Two quirks worth knowing: **agy**'s shell cwd is a private scratch dir rather
+than your workspace, so playmaker prepends a workspace preamble to every agy
+dispatch; and a wrong `--model` is a silent failure on both **codex** (reports
+`turn.failed` while exiting 0) and **agy** (runs its default model instead) —
+playmaker turns both into real errors.
+
+## Notifications
+
+Every detached dispatch pings when it finishes. With
+[`terminal-notifier`](https://github.com/julienXX/terminal-notifier) installed
+(`brew install terminal-notifier`), the notification is **clickable** and opens
+the agent's output file in your editor:
+
+```toml
+[notifications]
+editor = "Zed"     # any app name `open -a` accepts
+```
+
+Without terminal-notifier, playmaker falls back to plain `osascript` banners,
+which can't be clicked.
+
+**Batches.** Pass the same `--batch <label>` to every dispatch in a fan-out and
+per-dispatch success pings are suppressed — one "N/N done" summary fires when
+the whole batch drains. Failures are the actionable event, so they still ping
+immediately, with a distinct sound (Basso vs. the usual Blow).
+
+Each session's final output lands in `~/.playmaker/outputs/<id>.md` (or `.json`
+when the agent returned genuine JSON), so the notification click — and
+`playmaker get` — always have a stable file to open.
+
+## Quotas
+
+`playmaker quotas` is token-based: it reads the credentials each CLI already
+stores, no scraping and no browser.
+
+```console
+$ playmaker quotas --refresh
+Claude  Max 20x
+  Session     ████████████████░░░░ 80% left   resets in 3h 12m
+  Weekly      ███████████░░░░░░░░░ 55% left   resets in 4d 6h
+  Sonnet      ███████████████████░ 95% left   resets in 4d 6h
+
+Codex  Plus
+  Session     ██████████████████░░ 90% left   resets in 1h 40m
+  Weekly      █████████████░░░░░░░ 65% left   resets in 2d 9h
+
+Antigravity (agy)
+  Gemini 5h         ████████████████████ 100% left
+  Gemini weekly     ███████████████████░ 95% left
+  Claude/GPT 5h     ██████████████████░░ 90% left  resets in 2h 05m
+  Claude/GPT weekly ██████████████░░░░░░ 70% left  resets in 5d 1h
+```
+
+The `Weekly` and `Sonnet` rows above are the point: they are **separate
+buckets**. So is every agy row. Routing a subtask is choosing which of them to
+spend.
+
+- **Claude** — OAuth usage API; token from the Claude Code Keychain entry.
+- **Codex** — ChatGPT `wham/usage` API; token from `~/.codex/auth.json`.
+- **Antigravity** — prefers agy's **local daemon**
+  (`RetrieveUserQuotaSummary` over its embedded gRPC-web endpoint), which is
+  the only source for the full categorized breakdown above. Works whenever any
+  agy process has the singleton daemon up. Falls back to the OAuth
+  `retrieveUserQuota` on the Antigravity backend, which surfaces only coarse
+  Gemini buckets and is flagged *daemon offline*. Approach ported from
+  [steipete/CodexBar](https://github.com/steipete/CodexBar).
+
+Reading these at *model* granularity is the point: they are the load-balancing
+input the coach skill uses to route each subtask.
+
+## Limitations
+
+- macOS-only for the Claude quota probe (reads the Claude Code Keychain entry)
+  and for notifications. Everything else works on Linux.
+- No remote agents — everything runs as a local subprocess on your machine.
+- Quota probes read undocumented endpoints the vendors can change at any time.
+
+## Contributing
+
+Handlers for other agent CLIs are especially welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for the `AgentHandler` contract and what you
+need to know about a CLI before writing one.
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).