cdx-manager 0.16.0 → 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.16.0-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.
 
@@ -421,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.

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

@@ -180,6 +180,10 @@
     "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.16.0",
+  "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.16.0"
+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

@@ -60,7 +60,7 @@ def read_hook_payload(args, stdin_text=None):
 
 def compose_notification(payload, env=None, cwd=None):
     """Title and message for this event, or None if we should stay quiet."""
-    env = env or os.environ
+    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.
@@ -84,7 +84,7 @@ def handle_notify(rest, ctx):
         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 = ctx.get("env") or os.environ
+        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)

package/src/commands/launch.py

@@ -147,6 +147,9 @@ def handle_launch(command, ctx, initial_prompt=None, resume=False, force_json=No
             session, "resume" if resume else "launch", spawn=ctx.get("spawn"), cwd=cwd, env_override=ctx.get("env"),
             signal_emitter=ctx.get("signal_emitter"), initial_prompt=initial_prompt,
             lifecycle_callback=runtime_lifecycle,
+            # A JSON run owns stdout: a terminal title sequence would land in
+            # the middle of the document its caller has to parse.
+            title_enabled=not json_flag,
         )
     except CdxError as error:
         run_info = getattr(error, "run_info", {}) or {}

package/src/provider_runtime.py

@@ -7,6 +7,7 @@ import shutil
 import signal
 import subprocess
 import sys
+import threading
 import uuid
 from datetime import datetime, timezone
 
@@ -24,6 +25,18 @@ from .config import (
 from .errors import CdxError
 
 LOG_ROTATE_BYTES = 10 * 1024 * 1024  # 10 MB
+TERMINAL_TITLE_SEPARATOR = " — "
+# Providers redraw their own title while their TUI runs, so a single write at
+# launch does not survive. Re-asserting on this interval takes the title back
+# without being frequent enough to matter to the terminal.
+TERMINAL_TITLE_REFRESH_SECONDS = 5.0
+TERMINAL_TITLE_ACTIONS = ("launch", "resume")
+# Ollama is deliberately absent: it is a local model runner, not a cdx-managed
+# coding session, and its window title is left to it.
+TERMINAL_TITLE_PROVIDERS = (PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_ANTIGRAVITY)
+# ESC plus the C0/C1 control ranges: anything that could close the OSC string
+# early or start a new escape sequence from session or directory names.
+_TERMINAL_TITLE_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f-\x9f]")
 AUTH_PROBE_TIMEOUT_SECONDS = 15
 CODEX_INTERACTIVE_AUTH_LOCK_TIMEOUT_SECONDS = 10
 AUTH_PROBE_AUTHENTICATED = "authenticated"
@@ -1120,12 +1133,112 @@ def _signal_name(sig):
         return str(sig)
 
 
+def _sanitize_terminal_title_component(value):
+    """Strip anything that could escape the OSC title string.
+
+    Session names and directories are user data, so they are the injection
+    vector here: a raw ESC or BEL inside either would end the title string and
+    let the rest be read as terminal commands.
+    """
+    if value is None:
+        return ""
+    return _TERMINAL_TITLE_CONTROL_CHARS.sub("", str(value)).strip()
+
+
+def format_terminal_title(session_name, cwd=None):
+    """Build the `session -- folder` title shared by every interactive provider.
+
+    The folder is the basename of the effective launch cwd, which is what
+    identifies the work; the full path would not fit a title bar. Missing parts
+    are dropped rather than rendered as an empty half.
+    """
+    session_part = _sanitize_terminal_title_component(session_name)
+    directory = os.path.abspath(cwd or os.getcwd())
+    folder_part = _sanitize_terminal_title_component(os.path.basename(directory) or directory)
+    parts = [part for part in (session_part, folder_part) if part]
+    return TERMINAL_TITLE_SEPARATOR.join(parts)
+
+
+def _stream_is_tty(stream):
+    try:
+        return bool(stream is not None and stream.isatty())
+    except (AttributeError, ValueError, OSError):
+        return False
+
+
+class _TerminalTitleKeeper:
+    """Holds the terminal title for as long as the provider process runs.
+
+    A provider TUI sets its own title whenever it repaints, so this rewrites the
+    OSC sequence on an interval instead of once. Every write is best-effort: a
+    closed or unwritable stream ends the loop rather than the session.
+    """
+
+    def __init__(self, title, stream, interval=None):
+        self.title = title
+        self._sequence = f"\033]0;{title}\007"
+        self._stream = stream
+        self._interval = TERMINAL_TITLE_REFRESH_SECONDS if interval is None else interval
+        self._stop_event = threading.Event()
+        self._thread = None
+
+    def _write(self):
+        try:
+            self._stream.write(self._sequence)
+            self._stream.flush()
+        except Exception:
+            return False
+        return True
+
+    def start(self):
+        if not self._write():
+            return self
+        if self._interval and self._interval > 0:
+            self._thread = threading.Thread(target=self._refresh_loop, daemon=True)
+            self._thread.start()
+        return self
+
+    def _refresh_loop(self):
+        while not self._stop_event.wait(self._interval):
+            if not self._write():
+                return
+
+    def stop(self):
+        self._stop_event.set()
+        thread = self._thread
+        self._thread = None
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(timeout=1)
+
+
+def _start_terminal_title(session, action, cwd=None, stream=None, enabled=True):
+    """Start title upkeep for an interactive launch/resume, or return None.
+
+    Returns None for every case that has no terminal to write to - auth
+    actions, non-TTY stdout, JSON output, captured test streams - so callers can
+    stop() unconditionally.
+    """
+    if not enabled or action not in TERMINAL_TITLE_ACTIONS:
+        return None
+    if session.get("provider") not in TERMINAL_TITLE_PROVIDERS:
+        return None
+    stream = sys.stdout if stream is None else stream
+    if not _stream_is_tty(stream):
+        return None
+    title = format_terminal_title(session.get("name"), cwd)
+    if not title:
+        return None
+    return _TerminalTitleKeeper(title, stream).start()
+
+
 def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
                                       env_override=None, signal_emitter=None,
-                                      initial_prompt=None, lifecycle_callback=None):
+                                      initial_prompt=None, lifecycle_callback=None,
+                                      title_stream=None, title_enabled=True):
     kwargs = dict(spawn=spawn, cwd=cwd, env_override=env_override,
                   signal_emitter=signal_emitter, initial_prompt=initial_prompt,
-                  lifecycle_callback=lifecycle_callback)
+                  lifecycle_callback=lifecycle_callback, title_stream=title_stream,
+                  title_enabled=title_enabled)
     if session.get("provider") != PROVIDER_CODEX:
         return _run_interactive_provider_command_impl(session, action, **kwargs)
     # Hold the per-CODEX_HOME lock for the whole session so concurrent Codex
@@ -1142,7 +1255,28 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
 
 def _run_interactive_provider_command_impl(session, action, spawn=None, cwd=None,
                                            env_override=None, signal_emitter=None,
-                                           initial_prompt=None, lifecycle_callback=None):
+                                           initial_prompt=None, lifecycle_callback=None,
+                                           title_stream=None, title_enabled=True):
+    # The title lives exactly as long as the provider process, including the
+    # error and signal paths below, which is why it is held here rather than
+    # inside the run itself.
+    title_keeper = _start_terminal_title(
+        session, action, cwd=cwd, stream=title_stream, enabled=title_enabled
+    )
+    try:
+        return _run_interactive_provider_process(
+            session, action, spawn=spawn, cwd=cwd, env_override=env_override,
+            signal_emitter=signal_emitter, initial_prompt=initial_prompt,
+            lifecycle_callback=lifecycle_callback,
+        )
+    finally:
+        if title_keeper is not None:
+            title_keeper.stop()
+
+
+def _run_interactive_provider_process(session, action, spawn=None, cwd=None,
+                                      env_override=None, signal_emitter=None,
+                                      initial_prompt=None, lifecycle_callback=None):
     spawn = spawn or subprocess.Popen
     if action == "launch":
         spec = _build_launch_spec(session, cwd=cwd, env_override=env_override, initial_prompt=initial_prompt)