cdx-manager 0.15.1 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.15.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.17.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
@@ -70,7 +70,8 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 
 - **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
 - **Pick for me.** `cdx next` selects the best available assistant from your pinned priorities and the live quota picture, shows the reason, and prints the exact command to run.
-- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately. `cdx notify` covers reset times and scheduled wake-ups.
+- **Agent notifications.** When a session finishes a turn or blocks waiting for you, cdx raises a desktop notification naming the session and the repository — so you can run several in parallel without watching any of them. Opt in per session with `cdx set <name> --notify on`.
+- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
 - **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
 - **Banked reset visibility.** Eligible Codex accounts show the number of manually redeemable bonus resets in `cdx status` and expose reset details in JSON output.
 
@@ -342,7 +343,43 @@ cdx disk profiles --candidates
 
 ### Next-Ready Notifications
 
-Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. It is shorthand for `cdx notify --schedule --next-ready`: cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
+### Agent notifications
+
+When a session's agent finishes a turn, or stops to wait for you, cdx raises a
+desktop notification naming the session and the repository:
+
+```text
+✓ work1     logics-manager · waiting for you
+✓ codex-a   cdx-manager · finished
+```
+
+Off until you ask for it, per session:
+
+```bash
+cdx set work1 --notify on      # turn it on for one session
+cdx set --all --notify on      # turn it on everywhere
+cdx set work1 --notify off     # and back off; cdx removes what it installed
+```
+
+Turning it on records the setting. The wiring happens at that session's **next
+launch**: cdx writes the hook into the session's own home and says so once.
+Claude Code honours it straight away. Codex only runs hooks that come from an
+installed plugin, so cdx generates one per session and installs it — and Codex
+asks you to approve it once, which cdx leaves to you rather than writing that
+trust on your behalf.
+
+It is off by default because turning it on writes into the provider's own
+configuration and, on Codex, puts an approval prompt in front of you. That is
+not something to do to sessions you already own without being asked.
+
+Per platform: macOS uses `osascript`, Linux `notify-send`, Windows a toast, and
+WSL reaches the Windows notification centre through interop. On a host with no
+way to deliver one — a headless or SSH Linux session, or WSL with interop
+disabled — cdx installs no hooks at all rather than asking you to approve
+something that could show you nothing. Headless `cdx run` never notifies: its
+caller already learns of completion from the return value.
+
+Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
 
 ```bash
 cdx ready
@@ -384,6 +421,12 @@ cdx model provider:ollama default
 
 `--model` maps to Codex `--model`, Claude `--model`, and Ollama `ollama run <model>`. `--power` maps to Codex `model_reasoning_effort` and Claude `--effort`; supported values are `minimal`, `low`, `medium`, `high`, and `xhigh`. `--permission` maps to provider-native permission flags. Codex Fast mode is separate from reasoning effort: `--fast on` opts a Codex session into the Codex Fast service tier, while new sessions, `--fast off`, and default launches force the non-Fast `flex` tier. Use `--power low` when you want low reasoning effort without enabling Codex Fast credits. Existing legacy sessions that stored `fast=on` before this split continue to behave as low effort unless the user explicitly sets `--fast on` again. `--priority` is a 0..100 selector preference used as a tie-breaker after readiness and availability. `--rtk on` injects a launch instruction that encourages assistants to use RTK (`rtk <command>`) for noisy terminal commands when RTK is available, while keeping raw commands for exact output. Logics guidance is auto-enabled when `logics-manager` is available; use `--logics off` to disable that guidance for a session, or `--logics on` to pin it explicitly.
 
+### Terminal Titles
+
+Interactive launches and resumes set the terminal window title to `session — folder`, where `folder` is the basename of the launch directory - for example `work — cdx-manager`. The convention is identical for Claude, Codex, and Antigravity: it comes from the shared launch runtime, not from provider flags, and cdx keeps re-asserting it so a provider TUI cannot take the title back mid-session.
+
+The title is only written when stdout is a terminal. Nothing is emitted for `--json` launches, redirected or piped output, `cdx run` and other headless runs, login flows, or Ollama sessions. Session names and directories are stripped of escape and control characters before the title is emitted, and cdx does not restore the previous title when the session ends.
+
 ### Launch History
 
 Every interactive `cdx <name>` launch is recorded under `CDX_HOME`, including success/failure, duration, cwd, launch settings, and transcript path.
@@ -446,8 +489,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx update all [--yes] [--json]` | Check installed providers, RTK, and Ponytail across Codex profiles; show the plan and ask once before applying safe native/Homebrew updates and missing RTK/Ponytail setup |
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
-| `cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait for a session reset time or schedule an OS wake-up notification when due |
-| `cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait until the recommended session is usable, or schedule the next known reset notification |
+| `cdx notify` | Hook target: raises the desktop notification when a session's agent finishes a turn or waits for you. Called by the provider, not by you |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
 | `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit, `--prompt-file -` reads the prompt from stdin |
@@ -499,7 +541,6 @@ Commands with machine-readable output:
 - `cdx view --json`
 - `cdx update --json`
 - `cdx ready --json`
-- `cdx notify ... --json`
 - `cdx select ... --json`
 - `cdx run ... --json`
 

package/changelogs/CHANGELOGS_0_16_0.md

@@ -0,0 +1,97 @@
+# CDX Manager 0.16.0
+
+> cdx now tells you when one of its sessions finishes or needs you, which is
+> the one thing it could not do in the situation it was built for: several
+> assistants running in parallel across different repositories. Getting there
+> meant retiring the old `cdx notify` and reserving the name for this.
+
+## Breaking
+
+### `cdx notify` means something else
+
+`cdx notify <name> --at-reset` and `cdx notify --next-ready` are gone. Those
+answered "when does my quota come back", which `cdx status` already answers,
+and in practice the only form anyone typed was `cdx ready`.
+
+`cdx ready` is unchanged — same behaviour, same output, same flags. If you
+scripted the retired flags, `cdx ready --json` is the replacement; there is no
+equivalent for waiting on one named session's reset.
+
+`cdx notify` is now the target a provider hook calls. You do not run it
+yourself.
+
+## Features
+
+### Notifications when a session finishes or waits for you
+
+```text
+✓ work1     logics-manager · waiting for you
+✓ codex-a   cdx-manager · finished
+```
+
+The notification names the session and the repository, because the case this
+exists for is several of them at once — a notification that cannot tell you
+which one is not worth raising. Only cdx knows the session name, which is why
+this lives here rather than in a hook you write by hand.
+
+Off until you ask for it:
+
+```bash
+cdx set work1 --notify on      # one session
+cdx set --all --notify on      # all of them
+```
+
+The setting is recorded straight away; the wiring happens at that session's
+next launch, into the home directory cdx already owns, and cdx says so once.
+Turning it back off removes what cdx installed and leaves any hooks you wrote
+yourself alone.
+
+It is opt-in rather than on by default because enabling it writes into the
+provider's own configuration and, on Codex, puts an approval prompt in front of
+you — not something to do unrequested to sessions you already own.
+
+### Codex goes through a generated plugin
+
+Codex does not read hooks from a file. Not at its home root, not under a
+`hooks/` directory, not from a project `.codex/` — all three were tried and
+none is ever loaded. It runs only hooks that come from an installed plugin, so
+cdx generates one per session and installs it with `codex plugin marketplace
+add`.
+
+The generated plugin lives outside `CODEX_HOME` on purpose. Rooted inside it,
+the marketplace installs without an error and reports `installed, enabled`, and
+then never runs a thing: Codex registers it pointing at the source directory
+rather than the cache copy it executes from. Everything looks right and nothing
+happens.
+
+Codex also refuses to run a hook it has not been told to trust, so it asks you
+once per session. cdx does not answer that for you.
+
+### Delivery on every platform, and silence where there is none
+
+macOS uses `osascript`, Linux `notify-send`, native Windows a toast, and WSL
+reaches the Windows notification centre through interop rather than being
+treated as plain Linux — which is what it was before, and why it delivered
+nothing at all there.
+
+On a host with no way to show a notification — a headless or SSH Linux
+session, or WSL with interop disabled — cdx installs no hooks. Approving a
+hook that could never show you anything is a cost with no return. A host that
+gains a channel later is provisioned on its next launch.
+
+Headless `cdx run` never notifies, so a script issuing fifty runs stays quiet.
+Its caller already learns of completion from the return value.
+
+## Fixes
+
+### The Windows notification no longer blocks
+
+Windows notifications were a `MessageBox` spawned with no timeout. As an
+occasional quota alert that was survivable. As a hook firing on every agent
+turn it would have held the turn open until someone dismissed the dialog, and
+a window stealing focus every turn is worse than no notification at all. It is
+now a toast, which needs no dismissing.
+
+Claude Code honours the hooks it finds immediately. Codex is the one that
+gates them behind trust, so only Codex asks — cdx passes no bypass flag, the
+guard is there on purpose.

package/changelogs/CHANGELOGS_0_17_0.md

@@ -0,0 +1,64 @@
+# CDX Manager 0.17.0
+
+> A terminal running four cdx sessions gave you four windows titled by whatever
+> each provider felt like calling itself. The title now says which session it
+> is and which repository it is in, and it says it the same way for Claude,
+> Codex and Antigravity.
+
+## Features
+
+### Interactive sessions title the terminal `session — folder`
+
+```text
+work — cdx-manager
+perso — logics-manager
+```
+
+Every interactive `cdx <name>` and `cdx resume <name>` sets the window title to
+its session name and the basename of the launch directory. Both halves matter:
+the session is the account you are spending, the folder is the work. Neither
+alone tells you which window you are looking at when several are open.
+
+The convention comes from cdx's own launch runtime rather than from provider
+flags, which is why it is identical across Claude, Codex and Antigravity. No
+provider argument changed, and no undocumented option is relied on — Codex and
+Antigravity do not expose one, and depending on a private flag would make this
+break on their next release.
+
+A title written once at launch does not survive: a provider TUI sets its own
+whenever it repaints. cdx keeps re-asserting it for as long as the session
+runs, and releases it when the session ends — on the error and interrupt paths
+as well as the normal one.
+
+Nothing is emitted where there is no terminal to emit to. `--json` launches,
+redirected or piped output, `cdx run` and other headless runs, and login flows
+all stay byte-for-byte as they were; a title sequence in the middle of a JSON
+document its caller has to parse is a bug, not a feature. Ollama is left alone
+as a local model runner rather than a cdx-managed coding session.
+
+Session names and directories are your data, so both are stripped of escape
+and control characters before the title is written. A directory named with a
+raw `ESC` would otherwise end the title string early and leave the rest of the
+name to be read by the terminal as commands.
+
+cdx does not restore the previous title when a session ends. Terminals do not
+reliably report the title they had, so restoring it means guessing, and
+guessing wrong is worse than leaving the last true statement in place.
+
+## Validation
+
+- `ruff check .`
+- `python3 -m pytest` — 679 tests.
+- Verified against a real pty rather than a mocked stream: the launch emits
+  `\x1b]0;work — cdx-manager\x07`.
+- The non-TTY, `--json`, login and Ollama paths are each pinned by a test that
+  asserts nothing at all is written.
+
+## Known limits
+
+- The em dash is written as UTF-8. A terminal whose stdout encoding cannot
+  represent it — `LC_ALL=C`, for instance — gets no title rather than a
+  mangled one or a crash, since every title write is best-effort.
+- The refresh interval is fixed at five seconds and is not configurable. A
+  provider that repaints its title more aggressively than that would show its
+  own for up to that long before cdx takes it back.

package/checksums/release-archives.json

@@ -176,6 +176,14 @@
     "v0.15.0": {
       "github_tarball_sha256": "93d0a7305a5235f20e89a3e2a404029546926437952ee61d43a1f69c3ae98e4e",
       "github_zip_sha256": "23e4e42fb746f4af5fa407f853e979ffce91e147dbb623c250e276fdcaa9638a"
+    },
+    "v0.15.1": {
+      "github_tarball_sha256": "1dc7ea87600844e4853ab12c9f123dc67548ae904f511fea9a58ddf7b3eacfef",
+      "github_zip_sha256": "7ad41c63adffdd1ef12d02a72c86fb1b6a64cbcddd9970b0741ba5516f241707"
+    },
+    "v0.16.0": {
+      "github_tarball_sha256": "bdcd2808922410b20567ba86589d49166c5c2b9404325195b28457df80ca3dad",
+      "github_zip_sha256": "e89cb8c964304f0805d06da9d355d543f8a590e0febbf07e585a692ccf73ef99"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.15.1"
+version = "0.17.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/agent_notify.py

@@ -0,0 +1,324 @@
+"""Agent-event notifications: the hook target, and the per-session provisioning.
+
+`cdx notify` is what a provider hook calls when an agent turn ends or blocks
+waiting for input. It exists because the notification has to name *which* cdx
+session, in *which* repository — the case the feature is for is several sessions
+running in parallel — and only cdx knows the session name.
+
+Provisioning writes the hook into the session's own home, which cdx already
+owns because it sets HOME/CODEX_HOME per session at launch.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+from .notify import notification_channel, send_desktop_notification
+
+# Set on the provider process at launch; the hook runs as its child and inherits both.
+SESSION_ENV = "CDX_SESSION_NAME"
+ENABLED_ENV = "CDX_NOTIFY"
+
+# Our entries are recognised by the command they run, not by a marker key of our
+# own: both providers validate this file against their own schema, and an extra
+# key they do not know is a rejection risk for no gain.
+HOOK_ARG = "notify"
+
+_WAITING_EVENTS = {"notification", "permissionrequest", "userpromptsubmit"}
+
+
+def resolve_hook_command(env=None):
+    """Absolute path to cdx, not the bare name.
+
+    Codex spawns the hook without a shell, and a Windows npm install ships a
+    `.cmd` shim rather than an executable called `cdx`, so the bare name does
+    not resolve there. pipx and uv installs can likewise leave cdx off the PATH
+    the provider inherits.
+    """
+    env = env or os.environ
+    return env.get("CDX_BIN") or shutil.which("cdx", path=env.get("PATH")) or "cdx"
+
+
+def read_hook_payload(args, stdin_text=None):
+    """Accept the payload however the provider hands it over.
+
+    Claude Code and current Codex hooks write JSON to stdin. Codex's older
+    `notify` key — which it now calls `legacy_notify` — passes it as an argv.
+    Anything unparseable is an empty payload, never an error: a hook that fails
+    loudly turns a missing notification into a broken agent turn.
+    """
+    for candidate in ([stdin_text] if stdin_text else []) + list(args or []):
+        try:
+            payload = json.loads(candidate)
+        except (TypeError, ValueError):
+            continue
+        if isinstance(payload, dict):
+            return payload
+    return {}
+
+
+def compose_notification(payload, env=None, cwd=None):
+    """Title and message for this event, or None if we should stay quiet."""
+    env = os.environ if env is None else env
+    if env.get(ENABLED_ENV) == "0":
+        # Headless runs share the session's home, so they read the same hooks.
+        # Their caller already learns of completion from the return value.
+        return None
+    session = env.get(SESSION_ENV)
+    if not session:
+        return None
+    directory = payload.get("cwd") or payload.get("workspace") or cwd or os.getcwd()
+    event = str(payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or "").lower()
+    state = "waiting for you" if event.replace("_", "") in _WAITING_EVENTS else "finished"
+    where = os.path.basename(str(directory).rstrip("/\\")) or directory
+    return f"✓ {session}", f"{where} · {state}"
+
+
+def handle_notify(rest, ctx):
+    """Hook target. Never fails: a broken notification is not a broken turn."""
+    try:
+        import sys
+        stdin_text = None
+        # "stdin" in ctx is the {"isTTY": ...} descriptor, not a stream.
+        reader = ctx.get("prompt_stdin") or sys.stdin
+        if reader is not None and not ctx.get("stdin_is_tty"):
+            stdin_text = reader.read()
+        env = os.environ if ctx.get("env") is None else ctx["env"]
+        composed = compose_notification(read_hook_payload(rest, stdin_text), env, ctx.get("cwd"))
+        if composed:
+            send_desktop_notification(*composed, spawn_sync=ctx.get("spawn_sync"), env=env)
+    except Exception:  # noqa: BLE001 - deliberate: the caller is an agent turn
+        pass
+    return 0
+
+
+def launch_notify_env(session, enabled, env=None):
+    """Env the provider is launched with, carrying who we are and whether to notify."""
+    values = {SESSION_ENV: session["name"]}
+    if not enabled:
+        values[ENABLED_ENV] = "0"
+    return values
+
+
+def notifications_enabled(session):
+    """Off unless this session explicitly turned it on.
+
+    Opt-in rather than on-by-default: provisioning writes into the provider's
+    own configuration and, on Codex, asks the user to approve a hook. Doing
+    that to every session someone already owns, without being asked, is not a
+    default worth having.
+    """
+    launch = session.get("launch") or {}
+    return launch.get("notify") is True
+
+
+def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=None):
+    """Install or remove cdx's notification hooks in this session's own home.
+
+    Idempotent, so an existing session picks the hooks up on its next launch and
+    repeated launches change nothing. Returns True when they were newly
+    installed, so the caller can say so once.
+
+    The two providers need different mechanisms, which is not a stylistic
+    choice: Claude Code reads hooks straight out of `settings.json`, while Codex
+    reads them only from an installed plugin — a free-standing hooks file
+    anywhere under `CODEX_HOME` is never looked at.
+    """
+    env = env or os.environ
+    if enabled and not notification_channel(env):
+        # Nothing could be delivered on this host, so installing a hook would only
+        # buy the user an approval prompt for a feature that shows nothing.
+        enabled = False
+    command = resolve_hook_command(env)
+    if provider == "claude":
+        return _apply_hooks(hook_config_path(auth_home, provider), enabled, command)
+    if provider == "codex":
+        return _provision_codex_plugin(auth_home, enabled, command, env, spawn_sync, base_dir)
+    return False
+
+
+def hook_config_path(auth_home, provider, base_dir=None):
+    if provider == "claude":
+        return os.path.join(auth_home, ".claude", "settings.json")
+    if provider == "codex":
+        return os.path.join(codex_plugin_root(auth_home, base_dir), "hooks", "cdx-hooks.json")
+    return None
+
+
+def codex_plugin_root(auth_home, base_dir=None):
+    """Where the generated Codex plugin lives — deliberately outside CODEX_HOME.
+
+    A marketplace rooted inside Codex's own home installs without complaint and
+    then never runs: Codex registers it pointing straight at the source
+    directory instead of taking the cache copy it executes from. Moving the same
+    plugin one directory out is the whole difference between working and
+    silently doing nothing.
+    """
+    if base_dir:
+        return os.path.join(base_dir, "state", "codex-plugins", os.path.basename(auth_home))
+    # Without a base directory, sit beside the home rather than guessing at cdx's
+    # layout by walking up from it: two levels above a home is `/` for anything
+    # not laid out as `<base>/profiles/<name>`, and writing there fails.
+    return os.path.join(os.path.dirname(auth_home), ".cdx-codex-plugins", os.path.basename(auth_home))
+
+
+# Codex only runs hooks that come from an installed plugin, identified as
+# `<plugin>@<marketplace>`. Generating one per session keeps the resolved cdx
+# path baked into it.
+CODEX_PLUGIN = "cdx-notify"
+CODEX_MARKETPLACE = "cdx"
+CODEX_PLUGIN_REF = f"{CODEX_PLUGIN}@{CODEX_MARKETPLACE}"
+
+
+def _provision_codex_plugin(auth_home, enabled, command, env, spawn_sync=None, base_dir=None):
+    installed = _codex_plugin_installed(auth_home)
+    if enabled == installed:
+        return False
+    if not enabled:
+        _run_codex(["plugin", "remove", CODEX_PLUGIN_REF], auth_home, env, spawn_sync)
+        _run_codex(["plugin", "marketplace", "remove", CODEX_MARKETPLACE], auth_home, env, spawn_sync)
+        return False
+    root = _write_codex_plugin(auth_home, command, base_dir)
+    if not root:
+        return False
+    if not _run_codex(["plugin", "marketplace", "add", root], auth_home, env, spawn_sync):
+        return False
+    return _run_codex(["plugin", "add", CODEX_PLUGIN_REF], auth_home, env, spawn_sync)
+
+
+def _codex_plugin_installed(auth_home):
+    """Whether Codex's own config already lists our plugin.
+
+    Read rather than remembered, so a plugin the user removed by hand is
+    reinstalled on the next launch instead of being assumed present.
+    """
+    try:
+        with open(os.path.join(auth_home, "config.toml"), encoding="utf-8") as handle:
+            return f'[plugins."{CODEX_PLUGIN_REF}"]' in handle.read()
+    except OSError:
+        return False
+
+
+def _write_codex_plugin(auth_home, command, base_dir=None):
+    root = codex_plugin_root(auth_home, base_dir)
+    files = {
+        os.path.join(root, ".claude-plugin", "marketplace.json"): {
+            "name": CODEX_MARKETPLACE,
+            "description": "cdx agent notifications",
+            "owner": {"name": "cdx"},
+            "plugins": [{
+                "name": CODEX_PLUGIN,
+                "description": "Notify when this cdx session finishes a turn or waits for you",
+                "source": "./",
+            }],
+        },
+        # The "hooks" key is what makes Codex load the file at all; without it
+        # the plugin installs cleanly and never runs anything.
+        os.path.join(root, ".claude-plugin", "plugin.json"): {
+            "name": CODEX_PLUGIN,
+            "version": "1.0.0",
+            "description": "Notify when this cdx session finishes a turn or waits for you",
+            "hooks": "./hooks/cdx-hooks.json",
+        },
+        os.path.join(root, "hooks", "cdx-hooks.json"): {
+            "hooks": {
+                event: [{"hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}]}]
+                for event in ("Stop", "Notification")
+            },
+        },
+    }
+    for path, document in files.items():
+        if not _write_json(path, document):
+            return None
+    return root
+
+
+def _run_codex(args, auth_home, env, spawn_sync):
+    """Run one `codex` command, following the repo's (command, args, options)
+    spawn_sync contract rather than subprocess.run's, so the same injected
+    double serves here as everywhere else."""
+    options = {"env": {**env, "CODEX_HOME": auth_home}, "cwd": auth_home}
+    try:
+        result = (spawn_sync or _subprocess_spawn_sync)("codex", list(args), options)
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        # No codex on PATH, or it hung: a skipped provisioning step, never a
+        # failed launch.
+        return False
+    if isinstance(result, dict):
+        return not result.get("error") and result.get("status", 0) == 0
+    return getattr(result, "returncode", 0) == 0
+
+
+def _subprocess_spawn_sync(command, args, options):
+    return subprocess.run(
+        [command, *args],
+        env=options.get("env"),
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+
+
+def _apply_hooks(path, enabled, command):
+    document = _read_json(path)
+    if document is None:
+        return False
+    hooks = document.get("hooks")
+    hooks = hooks if isinstance(hooks, dict) else {}
+    before = json.dumps(hooks, sort_keys=True)
+    for event in ("Stop", "Notification"):
+        # Rebuilt from whatever is there minus our own entry, so user-authored
+        # hooks on the same event survive both installing and removing.
+        entries = [entry for entry in hooks.get(event, []) if not _is_ours(entry)]
+        if enabled:
+            entries.append({
+                "hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}],
+            })
+        if entries:
+            hooks[event] = entries
+        else:
+            hooks.pop(event, None)
+    if json.dumps(hooks, sort_keys=True) == before:
+        return False
+    document["hooks"] = hooks
+    return _write_json(path, document) and enabled
+
+
+def _is_ours(entry):
+    """Ours if any of its commands is a cdx notify invocation."""
+    if not isinstance(entry, dict):
+        return False
+    for hook in entry.get("hooks") or []:
+        command = str((hook or {}).get("command") or "")
+        if command.endswith(f" {HOOK_ARG}") and "cdx" in command:
+            return True
+    return False
+
+
+def _read_json(path):
+    """Existing content, {} when absent, or None when we must not touch it.
+
+    An unparseable file is someone else's, so we leave it exactly as it is
+    rather than replacing settings the user cares about.
+    """
+    try:
+        with open(path, encoding="utf-8") as handle:
+            document = json.load(handle)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def _write_json(path, document):
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(document, handle, indent=2)
+            handle.write("\n")
+    except OSError:
+        # An unwritable home is a skipped provisioning step, not a failed launch.
+        return False
+    return True

package/src/cli.py

@@ -5,6 +5,7 @@ import os
 import sys
 from datetime import datetime, timezone
 
+from .agent_notify import handle_notify
 from .cli_commands import (
     API_SCHEMA_VERSION,
     STATUS_USAGE,
@@ -34,7 +35,7 @@ from .cli_commands import (
     handle_logout,
     handle_memory,
     handle_next,
-    handle_notify,
+    handle_ready,
     handle_remove,
     handle_rename,
     handle_repair,
@@ -258,8 +259,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx view [--json]', '36', use_color)}",
         f"  {_style('cdx update [all] [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx ready [--refresh] [--json]', '36', use_color)}",
-        f"  {_style('cdx notify <name> --at-reset [--schedule] [--refresh] [--json]', '36', use_color)}",
-        f"  {_style('cdx notify --next-ready [--schedule] [--refresh] [--json]', '36', use_color)}",
+        f"  {_style('cdx notify', '36', use_color)}  # hook target, called by the provider",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
         f"  {_style('cdx --help', '36', use_color)}",
         f"  {_style('cdx --version', '36', use_color)}",
@@ -576,9 +576,7 @@ def main(argv, options=None):
     }
 
     if resolved_command == "ready":
-        if any(arg not in ("--refresh", "--json") for arg in rest):
-            raise CdxError("Usage: cdx ready [--refresh] [--json]")
-        return handle_notify(["--next-ready", "--schedule", *rest], ctx)
+        return handle_ready(rest, ctx)
 
     if resolved_command in ("power", "perm", "fast", "model"):
         return handle_launch_setting_alias(resolved_command, rest, ctx)