playmaker-cli 0.4.0__tar.gz

playmaker_cli-0.4.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.DS_Store
+dist/
+build/
+.claude/
+.smoke/

playmaker_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-07-27
+
+### Added
+
+- `playmaker skill install` — the `playmaker-coach` Claude Code skill now ships
+  with the package (`skills/playmaker-coach/SKILL.md`) and installs itself into
+  `~/.claude/skills/`. It was previously documented as a separate repository
+  that was never published.
+- `playmaker --version`. `__version__` is read from installed package metadata
+  rather than a hand-maintained literal, which had drifted to 0.1.0.
+- `[notifications] editor` in `config.toml` — the app a clicked notification
+  opens the output in was hardcoded to Zed.
+
+### Fixed
+
+- `claude`: a failing `claude -p` run reports the error in its final
+  stream-json event with an empty stderr, so failures surfaced as a blank
+  `claude failed (exit 1):`. The error text is now captured and raised.
+- `codex`: a non-zero exit no longer discards an answer the CLI had already
+  written. The last-message file is consumed before the exit-code check, so
+  testing the file at that point always failed — codex's harmless
+  "failed to record rollout items" shutdown warning would have lost the result.
+- `codex`: invalid-model / auth / upstream failures are now surfaced. Codex
+  reports these via a `turn.failed`/`error` stream event while still exiting 0
+  and writing an empty last-message file, so a bad `--model` used to look "done"
+  with no output. The handler now inspects those events (unwrapping the nested
+  JSON error) and raises, so the coach reroutes instead of silently getting
+  nothing back.
+
+### Added
+
+- `agy`: `--model` is validated against `agy models` before dispatch. agy
+  resolves an unknown model name to its default *silently* (wrong model runs, no
+  error); a typo'd or stale name now raises with the available roster. Skipped
+  when the roster can't be read, so a probe hiccup never blocks a dispatch.
+- Antigravity quota probe now prefers agy's **local daemon** (`RetrieveUser
+  QuotaSummary` over the embedded self-signed-TLS gRPC-web endpoint), giving the
+  full categorized breakdown — Gemini and Claude/GPT, each split 5-hour vs
+  weekly — matching Antigravity's own UI and CodexBar. Works whenever any agy or
+  CodexBar daemon is running. Falls back to the coarse OAuth `retrieveUserQuota`
+  (Gemini daily buckets only) with a "daemon offline" note when none is up.
+  Ported from steipete/CodexBar's `AntigravityStatusProbe`.
+- Quota render: adaptive name column so longer categorized labels keep bar
+  alignment.
+
+### Changed
+
+- Packaging: PEP 639 license metadata, accurate description/keywords, sdist now
+  ships tests and the skill.
+- Lint: ruff `select = E,F,I,UP,B` (minus B008, which flags Typer's own API) and
+  linting covers `tests/` too.
+- Removed `packaging/homebrew/playmaker.rb` — it targeted a tap that was never
+  published, under an org name no longer in use.
+
+## [0.3.0] - 2026-07-12
+
+### Added
+
+- `agy` agent handler — Antigravity CLI (Google AI Pro): Gemini 3.5 Flash / 3.1 Pro,
+  Claude Sonnet/Opus 4.6 (Thinking), GPT-OSS 120B, addressed by display name from
+  `agy models`. Oneshot via `agy -p`, resume via `--conversation <id>`; the
+  conversation id is recovered early from the CLI debug log (`--log-file`), and
+  threads are parsed from the plain-JSONL brain transcript
+  (`~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript_full.jsonl`).
+  Dispatch prepends a workspace preamble because the agy agent's shell cwd is a
+  private scratch dir — without it, relative file writes never reach the workspace.
+- `antigravity_probe` quota probe (daily-cloudcode-pa, ideType ANTIGRAVITY) —
+  replaces the gemini probe in the default set; surfaces Gemini buckets only
+  (Antigravity's Claude/GPT windows are not exposed to plain OAuth tokens).
+
+### Changed
+
+- Default probe set is now codex / claude / agy; gemini-cli's handler and probe
+  remain in the codebase but the CLI is retired locally.
+
+## [0.2.0] - 2026-06-10
+
+### Removed
+
+- ACP/Zed integration layer — project is now a dispatch-only core with no Zed or ACP dependencies.
+
+### Changed
+
+- `claude`: headless dispatch and resume now pass `--dangerously-skip-permissions` so unattended runs are not blocked by permission prompts.
+- `quotas`: CLI renders the Extra usage pool (metered overage) alongside standard quota display.
+- `gemini`: falls back to session-file parse when the stream or JSON response body is empty, preventing silent failures on partial responses.

playmaker_cli-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Shulyugin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

playmaker_cli-0.4.0/PKG-INFO

@@ -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).