cdx-manager 0.3.2 → 0.3.4

package/README.md

@@ -6,7 +6,7 @@ If you use AI coding tools at scale ; multiple accounts, multiple providers : yo
 
 One command to launch any session. Zero auth juggling.
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.3.2-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.3.4-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 ---
 
@@ -16,7 +16,9 @@ One command to launch any session. Zero auth juggling.
 - [Technical Overview](#technical-overview)
 - [Getting Started](#getting-started)
 - [All Commands](#all-commands)
+- [JSON Output](#json-output)
 - [Available Scripts](#available-scripts)
+- [Windows Support](#windows-support)
 - [Project Structure](#project-structure)
 - [Data Layout](#data-layout)
 - [Troubleshooting](#troubleshooting)
@@ -53,6 +55,7 @@ One command to launch any session. Zero auth juggling.
   - Fallback: `status-source` scans provider JSONL history files and terminal log transcripts, strips ANSI/OSC sequences, and extracts `usage%`, `5h remaining%`, and `week remaining%` via pattern matching.
 - Claude status refreshes are cached briefly by default; pass `--refresh` to force a live rate-limit probe.
 - If `script` is unavailable, Codex launch falls back to running without transcript capture.
+- On Windows, transcript capture is optional. If no compatible `script` wrapper is installed, Codex still launches normally without transcript capture.
 - Auth probe: synchronous subprocess call to `codex login status` or `claude auth status` before any interactive launch.
 - Signal forwarding: `SIGINT`, `SIGTERM`, and `SIGHUP` are forwarded to the child process and produce clean exit codes.
 - Test stack: Python built-in `unittest` runner with no test framework dependency.
@@ -87,6 +90,18 @@ With uv:
 uv tool install cdx-manager
 ```
 
+On Windows with PowerShell:
+
+```powershell
+npm install -g cdx-manager
+```
+
+With the standalone PowerShell installer:
+
+```powershell
+irm https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.ps1 | iex
+```
+
 With the standalone GitHub installer:
 
 ```bash
@@ -96,7 +111,7 @@ curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.
 For a specific version:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh | CDX_VERSION=v0.3.2 sh
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh | CDX_VERSION=v0.3.4 sh
 ```
 
 From source:
@@ -107,6 +122,14 @@ cd cdx-manager
 make install
 ```
 
+From source on Windows:
+
+```powershell
+git clone <repo>
+cd cdx-manager
+npm install -g .
+```
+
 `cdx` is now available globally. Changes to the source take effect immediately — no reinstall needed.
 
 To uninstall:
@@ -115,6 +138,12 @@ To uninstall:
 make uninstall
 ```
 
+To uninstall on Windows after `npm install -g`:
+
+```powershell
+npm uninstall -g cdx-manager
+```
+
 Alternatively, for a non-symlinked global source install:
 
 ```bash
@@ -137,6 +166,24 @@ export CDX_SCRIPT_BIN=script
 export CDX_SCRIPT_ARGS='-q -F {transcript}'
 ```
 
+PowerShell equivalents:
+
+```powershell
+$env:CDX_HOME = "C:\cdx-data"
+$env:CDX_CLAUDE_STATUS_MODEL = "claude-haiku-4-5-20251001"
+$env:CDX_SCRIPT_BIN = "script"
+$env:CDX_SCRIPT_ARGS = "-q -F {transcript}"
+```
+
+Command Prompt equivalents:
+
+```cmd
+set CDX_HOME=C:\cdx-data
+set CDX_CLAUDE_STATUS_MODEL=claude-haiku-4-5-20251001
+set CDX_SCRIPT_BIN=script
+set CDX_SCRIPT_ARGS=-q -F {transcript}
+```
+
 ### Quick Start
 
 ```bash
@@ -163,14 +210,16 @@ cdx status
 | Command | Description |
 |---|---|
 | `cdx` | List all sessions with last-updated timestamps |
+| `cdx --json` | List all sessions as a machine-readable JSON payload |
 | `cdx <name>` | Launch a session (checks auth first) |
-| `cdx add [provider] <name>` | Register a new session (`provider`: `codex` or `claude`, default: `codex`) |
-| `cdx cp <source> <dest>` | Copy a session into another session name, overwriting the destination if it exists |
-| `cdx ren <source> <dest>` | Rename a session and move its auth data |
-| `cdx login <name>` | Re-authenticate a session (logout + login) |
-| `cdx logout <name>` | Log out of a session |
-| `cdx rmv <name> [--force]` | Remove a session and its auth data (prompts for confirmation unless `--force`) |
-| `cdx clean [name]` | Clear launch transcript logs for one session or all sessions |
+| `cdx <name> [--json]` | Launch a session; `--json` returns a structured success payload after the interactive run ends |
+| `cdx add [provider] <name> [--json]` | Register a new session (`provider`: `codex` or `claude`, default: `codex`) |
+| `cdx cp <source> <dest> [--json]` | Copy a session into another session name, overwriting the destination if it exists |
+| `cdx ren <source> <dest> [--json]` | Rename a session and move its auth data |
+| `cdx login <name> [--json]` | Re-authenticate a session (logout + login) |
+| `cdx logout <name> [--json]` | Log out of a session |
+| `cdx rmv <name> [--force] [--json]` | Remove a session and its auth data (prompts for confirmation unless `--force`) |
+| `cdx clean [name] [--json]` | Clear launch transcript logs for one session or all sessions |
 | `cdx doctor [--json]` | Inspect CLI dependencies, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines |
 | `cdx repair [--dry-run] [--force] [--json]` | Plan or apply safe repairs for missing state files, quarantines, and orphan profiles |
 | `cdx notify <name> --at-reset [--poll seconds] [--once]` | Wait for a session reset time and send a desktop notification when due |
@@ -183,6 +232,57 @@ cdx status
 
 ---
 
+## JSON Output
+
+`cdx-manager` can be consumed by other apps through its CLI JSON contract.
+
+Commands with machine-readable output:
+
+- `cdx --json`
+- `cdx status --json`
+- `cdx status <name> --json`
+- `cdx add ... --json`
+- `cdx cp ... --json`
+- `cdx ren ... --json`
+- `cdx rmv ... --json`
+- `cdx clean ... --json`
+- `cdx login ... --json`
+- `cdx logout ... --json`
+- `cdx doctor --json`
+- `cdx repair --json`
+- `cdx notify ... --json`
+
+Success payloads follow a shared envelope:
+
+```json
+{
+  "ok": true,
+  "action": "add",
+  "message": "Created session work (codex)",
+  "warnings": [],
+  "session": {
+    "name": "work"
+  }
+}
+```
+
+Errors use a shared stderr JSON envelope whenever `--json` is present:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "invalid_usage",
+    "message": "Usage: cdx status [--json] [--refresh] | ...",
+    "exit_code": 1
+  }
+}
+```
+
+This makes `cdx-manager` usable from editor plugins, scripts, and desktop apps without scraping human-readable terminal output.
+
+---
+
 ## Available Scripts
 
 - `npm test`: run the Python test suite
@@ -193,6 +293,24 @@ cdx status
 
 ---
 
+## Windows Support
+
+- Supported install paths on Windows:
+  - `npm install -g cdx-manager`
+  - `pipx install cdx-manager`
+  - `uv tool install cdx-manager`
+  - `install.ps1`
+- `install.sh` is Unix-only.
+- `make install` and `make uninstall` are Unix-oriented convenience commands, not the default Windows path.
+- `cdx` isolates Claude sessions on Windows by setting `HOME`, `USERPROFILE`, `HOMEDRIVE`, and `HOMEPATH`.
+- Desktop notifications use PowerShell on Windows.
+- Codex transcript capture is optional on Windows:
+  - if a compatible `script` command is available and exposed via `CDX_SCRIPT_BIN`, `cdx` uses it
+  - otherwise Codex launches without transcript capture and the session still works normally
+- `cdx doctor` reports the transcript-capture fallback explicitly so missing `script` on Windows is visible without being treated as a hard failure.
+
+---
+
 ## Project Structure
 
 ```text
@@ -255,6 +373,7 @@ Session names are URL-encoded when used as directory or file names. CLI command
 - **`cdx rmv` says "Removal requires confirmation in an interactive terminal"** — pass `--force` to bypass the prompt in non-interactive environments (scripts, CI).
 - **`cdx login` hangs** — the provider's login flow requires a browser or device code. Follow the on-screen instructions in the terminal that opened.
 - **`make install` says `npm link` is not found** — ensure Node.js and npm are installed and in your PATH.
+- **On Windows, `doctor` warns that `script` is missing** — this is expected on many setups. Codex still launches, but transcript capture stays disabled unless you point `CDX_SCRIPT_BIN` to a compatible wrapper.
 
 ---
 

package/bin/cdx

@@ -8,7 +8,7 @@ ROOT = Path(__file__).resolve().parent.parent
 if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
 
-from src.cli import format_error, main  # noqa: E402
+from src.cli import format_error, format_json_error, main, wants_json  # noqa: E402
 from src.errors import CdxError  # noqa: E402
 
 
@@ -16,5 +16,8 @@ if __name__ == "__main__":
     try:
         raise SystemExit(main(sys.argv[1:]))
     except CdxError as error:
-        sys.stderr.write(f"{format_error(error)}\n")
+        if wants_json(sys.argv[1:]):
+            sys.stderr.write(f"{format_json_error(error)}\n")
+        else:
+            sys.stderr.write(f"{format_error(error)}\n")
         raise SystemExit(error.exit_code)

package/changelogs/CHANGELOGS_0_3_3.md

@@ -0,0 +1,27 @@
+# CHANGELOGS_0_3_3
+
+Release date: 2026-04-16
+
+## CDX Manager 0.3.3
+
+CDX Manager 0.3.3 adds Windows compatibility across the full codebase.
+
+### Windows support
+
+- **Session store locking**: replaced `fcntl.flock` (Unix-only) with `msvcrt.locking` on Windows, with `seek(0)` to ensure consistent byte-range locking.
+- **Signal handling**: guarded `signal.SIGHUP` references behind `hasattr` checks — `SIGHUP` does not exist on Windows.
+- **Profile isolation**: added `_home_env_overrides()` helper that sets `USERPROFILE`, `HOMEDRIVE`, and `HOMEPATH` in addition to `HOME` when launching the `claude` CLI on Windows, so Node.js `os.homedir()` resolves to the correct session profile.
+- **Desktop notifications**: `cdx notify` now sends a notification via PowerShell `System.Windows.Forms.MessageBox` on Windows (falls back silently if PowerShell is unavailable).
+- **ANSI colors**: `cli_entry` enables VT processing via `ctypes.windll.kernel32.SetConsoleMode` on Windows so color output works in terminals that support it.
+- **Console encoding**: `cli_entry` reconfigures `stdout`/`stderr` to UTF-8 on Windows to prevent `UnicodeEncodeError` on non-ASCII session names.
+
+### Maintenance
+
+- Expanded `.gitignore` with standard Python build artifacts (`__pycache__/`, `*.egg-info/`, `dist/`, `build/`), virtual environments, coverage output, and OS-specific files (`.DS_Store`, `Thumbs.db`, `desktop.ini`).
+
+### Validation
+
+```bash
+npm run lint
+npm test
+```

package/changelogs/CHANGELOGS_0_3_4.md

@@ -0,0 +1,31 @@
+# CHANGELOGS_0_3_4
+
+Release date: 2026-04-16
+
+## CDX Manager 0.3.4
+
+CDX Manager 0.3.4 makes the CLI consumable by other applications through a structured JSON contract and rounds out the Windows release surface.
+
+### JSON CLI API
+
+- Added `cdx --json` to list known sessions as a machine-readable payload.
+- Added `--json` support for session-management commands: `add`, `cp`, `ren`, `rmv`, `clean`, `login`, and `logout`.
+- Added a shared success envelope for JSON responses with `ok`, `action`, `message`, and `warnings`.
+- Added a shared stderr error envelope for JSON mode with machine-readable `code`, `message`, and `exit_code`.
+- Documented the JSON contract in the README so editor plugins and desktop apps can integrate without scraping human-readable terminal output.
+
+### Windows release hardening
+
+- Added a native `install.ps1` installer for Windows.
+- Documented supported Windows install paths and the optional transcript-capture fallback.
+- Added targeted `win32` unit coverage for CLI startup, provider environment isolation, notifications, and session-store locking.
+- Added a Windows CI smoke flow that installs the package and exercises core CLI commands with shimmed providers.
+
+### Validation
+
+```bash
+npm run lint
+npm test
+npm_config_cache=/tmp/cdx-npm-cache npm pack --dry-run
+python3 logics/skills/logics.py lint --require-status
+```

package/install.ps1

@@ -0,0 +1,82 @@
+param(
+    [string]$Version = $env:CDX_VERSION,
+    [string]$Prefix = $env:CDX_PREFIX
+)
+
+$ErrorActionPreference = "Stop"
+
+$repo = "AlexAgo83/cdx-manager"
+
+function Require-Command {
+    param([string]$Name)
+    if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+        throw "cdx install: missing required command: $Name"
+    }
+}
+
+Require-Command python
+
+if (-not $Prefix) {
+    $Prefix = Join-Path $env:LOCALAPPDATA "cdx-manager"
+}
+
+$binDir = Join-Path $Prefix "bin"
+$installRoot = Join-Path $Prefix "versions"
+
+if (-not $Version) {
+    $release = Invoke-RestMethod -Uri "https://api.github.com/repos/$repo/releases/latest"
+    $Version = $release.tag_name
+}
+
+if ($Version.StartsWith("v")) {
+    $tag = $Version
+} else {
+    $tag = "v$Version"
+}
+
+$tmpRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("cdx-install-" + [guid]::NewGuid().ToString("N"))
+$archivePath = Join-Path $tmpRoot "cdx-manager.zip"
+$extractRoot = Join-Path $tmpRoot "extract"
+$targetDir = Join-Path $installRoot $tag.TrimStart("v")
+$archiveUrl = "https://github.com/$repo/archive/refs/tags/$tag.zip"
+
+New-Item -ItemType Directory -Force -Path $tmpRoot, $extractRoot, $binDir, $installRoot | Out-Null
+
+try {
+    Invoke-WebRequest -Uri $archiveUrl -OutFile $archivePath
+    Expand-Archive -Path $archivePath -DestinationPath $extractRoot -Force
+
+    $sourceDir = Get-ChildItem -Path $extractRoot -Directory | Select-Object -First 1
+    if (-not $sourceDir) {
+        throw "cdx install: failed to extract release archive"
+    }
+
+    if (Test-Path $targetDir) {
+        Remove-Item -Recurse -Force $targetDir
+    }
+    New-Item -ItemType Directory -Force -Path $targetDir | Out-Null
+    Copy-Item -Path (Join-Path $sourceDir.FullName "*") -Destination $targetDir -Recurse -Force
+
+    $launcherPath = Join-Path $binDir "cdx.cmd"
+    $launcher = @"
+@echo off
+set SCRIPT=%~dp0..\versions\${($tag.TrimStart("v"))}\bin\cdx
+where py >nul 2>nul
+if %ERRORLEVEL%==0 (
+  py -3 "%SCRIPT%" %*
+  exit /b %ERRORLEVEL%
+)
+python "%SCRIPT%" %*
+"@
+    Set-Content -Path $launcherPath -Value $launcher -Encoding ascii
+
+    Write-Host "Installed cdx $tag to $targetDir"
+    Write-Host "Created launcher $launcherPath"
+    if (-not (($env:PATH -split ";") -contains $binDir)) {
+        Write-Warning "Add $binDir to PATH to run cdx from anywhere."
+    }
+} finally {
+    if (Test-Path $tmpRoot) {
+        Remove-Item -Recurse -Force $tmpRoot
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -28,6 +28,7 @@
     "changelogs",
     "src",
     "install.sh",
+    "install.ps1",
     "pyproject.toml",
     "README.md",
     "LICENSE"

package/pyproject.toml

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

package/src/cli.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import json
 import os
 import sys
 
@@ -39,7 +40,7 @@ from .status_view import (
     _format_status_rows,
 )
 
-VERSION = "0.3.2"
+VERSION = "0.3.4"
 
 
 # ---------------------------------------------------------------------------
@@ -52,21 +53,22 @@ def _print_help(use_color=False):
         "",
         _style("Usage:", "1", use_color),
         f"  {_style('cdx', '36', use_color)}",
+        f"  {_style('cdx --json', '36', use_color)}",
         f"  {_style('cdx status [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx status --small|-s [--refresh]', '36', use_color)}",
         f"  {_style('cdx status <name> [--json] [--refresh]', '36', use_color)}",
-        f"  {_style('cdx add [provider] <name>', '36', use_color)}",
-        f"  {_style('cdx cp <source> <dest>', '36', use_color)}",
-        f"  {_style('cdx ren <source> <dest>', '36', use_color)}",
-        f"  {_style('cdx login <name>', '36', use_color)}",
-        f"  {_style('cdx logout <name>', '36', use_color)}",
-        f"  {_style('cdx rmv <name> [--force]', '36', use_color)}",
-        f"  {_style('cdx clean [name]', '36', use_color)}",
+        f"  {_style('cdx add [provider] <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx cp <source> <dest> [--json]', '36', use_color)}",
+        f"  {_style('cdx ren <source> <dest> [--json]', '36', use_color)}",
+        f"  {_style('cdx login <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx logout <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx rmv <name> [--force] [--json]', '36', use_color)}",
+        f"  {_style('cdx clean [name] [--json]', '36', use_color)}",
         f"  {_style('cdx doctor [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
-        f"  {_style('cdx notify <name> --at-reset', '36', use_color)}",
-        f"  {_style('cdx notify --next-ready', '36', use_color)}",
-        f"  {_style('cdx <name>', '36', use_color)}",
+        f"  {_style('cdx notify <name> --at-reset [--json]', '36', use_color)}",
+        f"  {_style('cdx notify --next-ready [--json]', '36', use_color)}",
+        f"  {_style('cdx <name> [--json]', '36', use_color)}",
         f"  {_style('cdx --help', '36', use_color)}",
         f"  {_style('cdx --version', '36', use_color)}",
     ])
@@ -76,6 +78,33 @@ def _print_version():
     return VERSION
 
 
+def wants_json(argv):
+    return "--json" in argv
+
+
+def format_json_error(error):
+    message = str(error)
+    code = "cdx_error"
+    if message.startswith("Usage:"):
+        code = "invalid_usage"
+    elif message.startswith("Unknown session:"):
+        code = "unknown_session"
+    elif message.startswith("Unknown command:"):
+        code = "unknown_command"
+    elif message.startswith("Session already exists:"):
+        code = "session_exists"
+    elif "requires an interactive terminal" in message or "requires confirmation" in message:
+        code = "interactive_terminal_required"
+    return json.dumps({
+        "ok": False,
+        "error": {
+            "code": code,
+            "message": message,
+            "exit_code": error.exit_code,
+        },
+    }, indent=2)
+
+
 # ---------------------------------------------------------------------------
 # main()
 # ---------------------------------------------------------------------------
@@ -114,6 +143,11 @@ def main(argv, options=None):
         out(f"{_print_version()}\n")
         return 0
 
+    if argv == ["--json"]:
+        rows = service["format_list_rows"]()
+        out(f"{json.dumps(_list_json_payload(rows), indent=2)}\n")
+        return 0
+
     if not argv:
         out(f"{_format_sessions(service, use_color=use_color)}\n")
         return 0
@@ -122,6 +156,7 @@ def main(argv, options=None):
     ctx = {
         "env": env,
         "options": options,
+        "raw_args": argv,
         "err": err,
         "out": out,
         "refresh_fn": refresh_fn,
@@ -174,17 +209,58 @@ def main(argv, options=None):
         out(f"{_print_version()}\n")
         return 0
 
-    if not rest:
+    if not rest or rest == ["--json"]:
         return handle_launch(command, ctx)
 
     raise CdxError(f"Unknown command: {command}. Use cdx --help.")
 
 
+def _list_json_payload(rows):
+    return {
+        "ok": True,
+        "action": "list",
+        "message": "Listed known sessions",
+        "warnings": [],
+        "sessions": rows,
+    }
+
+
+def _enable_windows_ansi():
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        for handle_id in (-10, -11, -12):  # stdin, stdout, stderr
+            handle = kernel32.GetStdHandle(handle_id)
+            mode = ctypes.c_ulong()
+            if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+                kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    except Exception:
+        pass
+
+
+def _configure_windows_encoding():
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if hasattr(stream, "reconfigure"):
+                stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
 def cli_entry():
+    _enable_windows_ansi()
+    _configure_windows_encoding()
     try:
         raise SystemExit(main(sys.argv[1:]))
     except CdxError as error:
-        sys.stderr.write(f"{format_error(error)}\n")
+        if wants_json(sys.argv[1:]):
+            sys.stderr.write(f"{format_json_error(error)}\n")
+        else:
+            sys.stderr.write(f"{format_error(error)}\n")
         raise SystemExit(error.exit_code)
 
 

package/src/cli_commands.py

@@ -32,23 +32,44 @@ def _local_now_iso():
     return datetime.now().astimezone().isoformat()
 
 
+def _json_success(action, message, **extra):
+    payload = {
+        "ok": True,
+        "action": action,
+        "message": message,
+        "warnings": [],
+    }
+    payload.update(extra)
+    return payload
+
+
+def _write_json(ctx, payload):
+    ctx["out"](f"{json.dumps(payload, indent=2)}\n")
+
+
+def _parse_json_flag(args):
+    json_flag = "--json" in args
+    cleaned = [arg for arg in args if arg != "--json"]
+    return json_flag, cleaned
+
+
 def _parse_add_args(args):
     if len(args) == 1:
         return {"provider": "codex", "name": args[0]}
     if len(args) == 2:
         return {"provider": args[0], "name": args[1]}
-    raise CdxError("Usage: cdx add [provider] <name>")
+    raise CdxError("Usage: cdx add [provider] <name> [--json]")
 
 
 def _parse_copy_args(args):
     if len(args) != 2:
-        raise CdxError("Usage: cdx cp <source> <dest>")
+        raise CdxError("Usage: cdx cp <source> <dest> [--json]")
     return {"source": args[0], "dest": args[1]}
 
 
 def _parse_rename_args(args):
     if len(args) != 2:
-        raise CdxError("Usage: cdx ren <source> <dest>")
+        raise CdxError("Usage: cdx ren <source> <dest> [--json]")
     return {"source": args[0], "dest": args[1]}
 
 
@@ -57,7 +78,7 @@ def _parse_remove_args(args):
     names = [a for a in args if a != "--force"]
     unknown = [a for a in args if a.startswith("-") and a != "--force"]
     if unknown or len(names) != 1 or len(args) > 2:
-        raise CdxError("Usage: cdx rmv <name> [--force]")
+        raise CdxError("Usage: cdx rmv <name> [--force] [--json]")
     return {"name": names[0], "force": force}
 
 
@@ -78,10 +99,10 @@ def _resolve_confirmation(confirm_fn, name):
 
 
 def handle_add(rest, ctx):
-    parsed = _parse_add_args(rest)
+    json_flag, args = _parse_json_flag(rest)
+    parsed = _parse_add_args(args)
     session = ctx["service"]["create_session"](parsed["name"], parsed["provider"])
     message = f"Created session {parsed['name']} ({parsed['provider']})"
-    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     _ensure_session_authentication(
         session,
         ctx["service"],
@@ -100,28 +121,50 @@ def handle_add(rest, ctx):
         "lastAuthenticatedAt": now,
         "lastLoggedOutAt": auth.get("lastLoggedOutAt"),
     })
+    if json_flag:
+        _write_json(ctx, _json_success(
+            "add",
+            message,
+            session=ctx["service"]["get_session"](parsed["name"]),
+        ))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     return 0
 
 
 def handle_copy(rest, ctx):
-    parsed = _parse_copy_args(rest)
+    json_flag, args = _parse_json_flag(rest)
+    parsed = _parse_copy_args(args)
     result = ctx["service"]["copy_session"](parsed["source"], parsed["dest"])
     overwritten = " (overwritten)" if result["overwritten"] else ""
     message = f"Copied session {parsed['source']} to {parsed['dest']}{overwritten}"
+    if json_flag:
+        _write_json(ctx, _json_success(
+            "copy",
+            message,
+            session=result["session"],
+            overwritten=result["overwritten"],
+        ))
+        return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     return 0
 
 
 def handle_rename(rest, ctx):
-    parsed = _parse_rename_args(rest)
-    ctx["service"]["rename_session"](parsed["source"], parsed["dest"])
+    json_flag, args = _parse_json_flag(rest)
+    parsed = _parse_rename_args(args)
+    session = ctx["service"]["rename_session"](parsed["source"], parsed["dest"])
     message = f"Renamed session {parsed['source']} to {parsed['dest']}"
+    if json_flag:
+        _write_json(ctx, _json_success("rename", message, session=session))
+        return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     return 0
 
 
 def handle_remove(rest, ctx):
-    parsed = _parse_remove_args(rest)
+    json_flag, args = _parse_json_flag(rest)
+    parsed = _parse_remove_args(args)
     if not parsed["force"]:
         confirm_fn = ctx["options"].get("confirmRemove")
         if confirm_fn:
@@ -131,30 +174,47 @@ def handle_remove(rest, ctx):
         else:
             confirmed = _confirm_removal(parsed["name"])
         if not confirmed:
+            if json_flag:
+                _write_json(ctx, _json_success("remove", "Cancelled.", cancelled=True, session=None))
+                return 0
             ctx["out"](f"{_warn('Cancelled.', ctx['use_color'])}\n")
             return 0
-    ctx["service"]["remove_session"](parsed["name"])
+    removed = ctx["service"]["remove_session"](parsed["name"])
     message = f"Removed session {parsed['name']}"
+    if json_flag:
+        _write_json(ctx, _json_success("remove", message, session=removed, cancelled=False))
+        return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     return 0
 
 
 def handle_clean(rest, ctx):
+    json_flag, args = _parse_json_flag(rest)
     service = ctx["service"]
-    if len(rest) == 0:
+    if len(args) == 0:
         targets = service["list_sessions"]()
-    elif len(rest) == 1:
-        session = service["get_session"](rest[0])
+    elif len(args) == 1:
+        session = service["get_session"](args[0])
         if not session:
-            raise CdxError(f"Unknown session: {rest[0]}")
+            raise CdxError(f"Unknown session: {args[0]}")
         targets = [session]
     else:
-        raise CdxError("Usage: cdx clean [name]")
+        raise CdxError("Usage: cdx clean [name] [--json]")
 
+    cleaned_sessions = []
     for session in targets:
         log_paths = _list_launch_transcript_paths(session)
         if not log_paths:
             message = f"{session['name']}: no log found"
+            cleaned_sessions.append({
+                "session_name": session["name"],
+                "cleared": False,
+                "files_cleared": 0,
+                "freed_kb": 0,
+                "message": message,
+            })
+            if json_flag:
+                continue
             ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
             continue
         total_size = 0
@@ -171,10 +231,30 @@ def handle_clean(rest, ctx):
                 f"Cleared {session['name']} logs ({cleared} file"
                 f"{'' if cleared == 1 else 's'}, {round(total_size / 1024)} KB freed)"
             )
+            cleaned_sessions.append({
+                "session_name": session["name"],
+                "cleared": True,
+                "files_cleared": cleared,
+                "freed_kb": round(total_size / 1024),
+                "message": message,
+            })
+            if json_flag:
+                continue
             ctx["out"](f"{_success(message, ctx['use_color'])}\n")
         else:
             message = f"{session['name']}: no log found"
+            cleaned_sessions.append({
+                "session_name": session["name"],
+                "cleared": False,
+                "files_cleared": 0,
+                "freed_kb": 0,
+                "message": message,
+            })
+            if json_flag:
+                continue
             ctx["out"](f"{_dim(message, ctx['use_color'])}\n")
+    if json_flag:
+        _write_json(ctx, _json_success("clean", "Cleaned session logs", sessions=cleaned_sessions))
     return 0
 
 
@@ -301,13 +381,14 @@ def _write_refresh_warnings(refresh_errors, ctx, stream="out"):
 
 
 def handle_login(rest, ctx):
-    if len(rest) != 1:
-        raise CdxError("Usage: cdx login <name>")
+    json_flag, args = _parse_json_flag(rest)
+    if len(args) != 1:
+        raise CdxError("Usage: cdx login <name> [--json]")
     if not ctx["stdin_is_tty"]:
         raise CdxError("Login requires an interactive terminal.")
-    session = ctx["service"]["get_session"](rest[0])
+    session = ctx["service"]["get_session"](args[0])
     if not session:
-        raise CdxError(f"Unknown session: {rest[0]}")
+        raise CdxError(f"Unknown session: {args[0]}")
     _run_interactive_provider_command(
         session, "logout", spawn=ctx.get("spawn"), env_override=ctx.get("env"),
         signal_emitter=ctx.get("signal_emitter")
@@ -317,36 +398,44 @@ def handle_login(rest, ctx):
         signal_emitter=ctx.get("signal_emitter")
     )
     now = _local_now_iso()
-    ctx["service"]["update_auth_state"](rest[0], lambda auth: {
+    ctx["service"]["update_auth_state"](args[0], lambda auth: {
         **auth, "status": "authenticated",
         "lastCheckedAt": now, "lastAuthenticatedAt": now,
     })
     message = f"Reauthenticated session {session['name']} ({session['provider']})"
+    if json_flag:
+        _write_json(ctx, _json_success("login", message, session=ctx["service"]["get_session"](session["name"])))
+        return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     return 0
 
 
 def handle_logout(rest, ctx):
-    if len(rest) != 1:
-        raise CdxError("Usage: cdx logout <name>")
-    session = ctx["service"]["get_session"](rest[0])
+    json_flag, args = _parse_json_flag(rest)
+    if len(args) != 1:
+        raise CdxError("Usage: cdx logout <name> [--json]")
+    session = ctx["service"]["get_session"](args[0])
     if not session:
-        raise CdxError(f"Unknown session: {rest[0]}")
+        raise CdxError(f"Unknown session: {args[0]}")
     _run_interactive_provider_command(
         session, "logout", spawn=ctx.get("spawn"), env_override=ctx.get("env"),
         signal_emitter=ctx.get("signal_emitter")
     )
     now = _local_now_iso()
-    ctx["service"]["update_auth_state"](rest[0], lambda auth: {
+    ctx["service"]["update_auth_state"](args[0], lambda auth: {
         **auth, "status": "logged_out",
         "lastCheckedAt": now, "lastLoggedOutAt": now,
     })
     message = f"Logged out session {session['name']} ({session['provider']})"
+    if json_flag:
+        _write_json(ctx, _json_success("logout", message, session=ctx["service"]["get_session"](session["name"])))
+        return 0
     ctx["out"](f"{_success(message, ctx['use_color'])}\n")
     return 0
 
 
 def handle_launch(command, ctx):
+    json_flag = "--json" in ctx["options"].get("raw_args", [])
     session = ctx["service"]["launch_session"](command)
     _ensure_session_authentication(
         session,
@@ -359,11 +448,15 @@ def handle_launch(command, ctx):
         signal_emitter=ctx.get("signal_emitter"),
     )
     message = f"Launching {session['provider']} session {session['name']}"
-    ctx["out"](f"{_info(message, ctx['use_color'])}\n")
+    if not json_flag:
+        ctx["out"](f"{_info(message, ctx['use_color'])}\n")
     if session["provider"] == "codex":
-        ctx["out"](f"{_dim('Tip: run /status once the Codex session opens.', ctx['use_color'])}\n")
+        if not json_flag:
+            ctx["out"](f"{_dim('Tip: run /status once the Codex session opens.', ctx['use_color'])}\n")
     _run_interactive_provider_command(
         session, "launch", spawn=ctx.get("spawn"), env_override=ctx.get("env"),
         signal_emitter=ctx.get("signal_emitter")
     )
+    if json_flag:
+        _write_json(ctx, _json_success("launch", message, session=ctx["service"]["get_session"](session["name"])))
     return 0

package/src/health.py

@@ -1,6 +1,7 @@
 import json
 import os
 import shutil
+import sys
 import tempfile
 from urllib.parse import quote, unquote
 
@@ -43,7 +44,7 @@ def collect_health_report(service, base_dir, env=None):
     issues.append(_issue(
         "OK" if script_path else "WARN",
         "script_cli",
-        f"{script_bin} CLI {'found' if script_path else 'not found; Codex will launch without transcript fallback'}",
+        _script_cli_message(script_bin, bool(script_path)),
         script_path,
     ))
 
@@ -74,6 +75,17 @@ def _check_cdx_home(base_dir):
         return _issue("FAIL", "cdx_home_writable", "CDX_HOME is not writable", f"{base_dir}: {error}")
 
 
+def _script_cli_message(script_bin, is_available):
+    if is_available:
+        return f"{script_bin} CLI found"
+    if sys.platform == "win32":
+        return (
+            f"{script_bin} CLI not found; Codex will launch without transcript capture "
+            f"(expected on many Windows setups)"
+        )
+    return f"{script_bin} CLI not found; Codex will launch without transcript fallback"
+
+
 def _collect_profile_issues(base_dir, session_names):
     profile_dir = _profiles_dir(base_dir)
     if not os.path.isdir(profile_dir):

package/src/notify.py

@@ -114,13 +114,38 @@ def _event(ready, title, message, session_name, target_timestamp=None):
 
 
 def send_desktop_notification(title, message, spawn_sync=None, env=None):
+    import sys
     spawn_sync = spawn_sync or subprocess.run
     env = env or os.environ
-    if shutil_which("osascript", env):
+    if sys.platform == "win32":
+        _send_windows_notification(title, message, spawn_sync, env)
+    elif shutil_which("osascript", env):
         script = f'display notification "{_escape_applescript(message)}" with title "{_escape_applescript(title)}"'
         spawn_sync(["osascript", "-e", script], env=env, capture_output=True, text=True)
 
 
+def _send_windows_notification(title, message, spawn_sync, env):
+    title_escaped = _escape_powershell(title)
+    message_escaped = _escape_powershell(message)
+    script = (
+        "Add-Type -AssemblyName System.Windows.Forms; "
+        f"[System.Windows.Forms.MessageBox]::Show('{message_escaped}', '{title_escaped}')"
+    )
+    try:
+        spawn_sync(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+            env=env,
+            capture_output=True,
+            text=True,
+        )
+    except (FileNotFoundError, OSError):
+        pass
+
+
+def _escape_powershell(value):
+    return str(value).replace("'", "''")
+
+
 def shutil_which(command, env):
     import shutil
     return shutil.which(command, path=env.get("PATH"))

package/src/provider_runtime.py

@@ -3,6 +3,7 @@ import os
 import signal
 import shlex
 import subprocess
+import sys
 from datetime import datetime, timezone
 
 from .errors import CdxError
@@ -11,6 +12,21 @@ from .errors import CdxError
 LOG_ROTATE_BYTES = 10 * 1024 * 1024  # 10 MB
 
 
+def _home_env_overrides(auth_home):
+    """Return env vars that point the claude CLI to the given home directory.
+
+    On Unix, only HOME is needed.  On Windows, Node.js resolves the home
+    directory via USERPROFILE (and falls back to HOMEDRIVE+HOMEPATH), so we
+    set all three to ensure profile isolation works regardless of the platform.
+    """
+    overrides = {"HOME": auth_home}
+    if sys.platform == "win32":
+        overrides["USERPROFILE"] = auth_home
+        overrides["HOMEDRIVE"] = os.path.splitdrive(auth_home)[0] or "C:"
+        overrides["HOMEPATH"] = os.path.splitdrive(auth_home)[1] or auth_home
+    return overrides
+
+
 def _get_auth_home(session):
     return session.get("authHome") or session.get("sessionRoot") or session.get("codexHome", "")
 
@@ -91,7 +107,7 @@ def _build_launch_spec(session, cwd=None, env_override=None):
             "args": ["--name", session["name"]],
             "options": {
                 "cwd": cwd,
-                "env": {**env, "HOME": _get_auth_home(session)},
+                "env": {**env, **_home_env_overrides(_get_auth_home(session))},
             },
             "label": "claude",
         }
@@ -108,7 +124,7 @@ def _build_launch_spec(session, cwd=None, env_override=None):
 def _build_login_status_spec(session, env_override=None):
     env = {**os.environ, **(env_override or {})}
     if session["provider"] == "claude":
-        env["HOME"] = _get_auth_home(session)
+        env.update(_home_env_overrides(_get_auth_home(session)))
 
         def parser(output):
             try:
@@ -133,7 +149,7 @@ def _build_auth_action_spec(session, action, cwd=None, env_override=None):
     cwd = cwd or os.getcwd()
     env = {**os.environ, **(env_override or {})}
     if session["provider"] == "claude":
-        env["HOME"] = _get_auth_home(session)
+        env.update(_home_env_overrides(_get_auth_home(session)))
         return {"command": "claude", "args": ["auth", action],
                 "options": {"cwd": cwd, "env": env}, "label": f"claude auth {action}"}
     env["CODEX_HOME"] = _get_auth_home(session)
@@ -165,7 +181,19 @@ def _probe_provider_auth(session, spawn_sync=None, env_override=None):
 
 
 def _signal_exit_code(sig):
-    return {signal.SIGHUP: 129, signal.SIGINT: 130, signal.SIGTERM: 143}.get(sig, 1)
+    mapping = {signal.SIGINT: 130, signal.SIGTERM: 143}
+    if hasattr(signal, "SIGHUP"):
+        mapping[signal.SIGHUP] = 129
+    return mapping.get(sig, 1)
+
+
+def _signal_name(sig):
+    if hasattr(sig, "name"):
+        return sig.name
+    try:
+        return signal.Signals(sig).name
+    except (TypeError, ValueError):
+        return str(sig)
 
 
 def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
@@ -210,7 +238,10 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
             handlers.append((sig, handler))
             signal_emitter.on(sig, handler)
     else:
-        for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        _forward_sigs = [signal.SIGINT, signal.SIGTERM]
+        if hasattr(signal, "SIGHUP"):
+            _forward_sigs.append(signal.SIGHUP)
+        for sig in _forward_sigs:
             try:
                 original_handlers[sig] = signal.signal(sig, forward)
             except (OSError, ValueError):
@@ -238,7 +269,7 @@ def _run_interactive_provider_command(session, action, spawn=None, cwd=None,
 
     if forwarded_signal[0] is not None:
         raise CdxError(
-            f"{spec['label']} interrupted by {forwarded_signal[0].name} for session {session['name']}",
+            f"{spec['label']} interrupted by {_signal_name(forwarded_signal[0])} for session {session['name']}",
             _signal_exit_code(forwarded_signal[0]),
         )
     if child.returncode != 0:

package/src/session_store.py

@@ -54,23 +54,40 @@ def _fsync_directory(directory):
 
 @contextmanager
 def _file_lock(lock_path):
+    import sys
     _ensure_dir(os.path.dirname(lock_path))
     with open(lock_path, "a", encoding="utf-8") as lock:
-        try:
-            import fcntl
-        except ImportError as error:
-            raise CdxError("Session store locking requires fcntl on this platform") from error
-        try:
-            fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
-        except OSError as error:
-            raise CdxError(f"Failed to lock session store: {error}") from error
-        try:
-            yield
-        finally:
+        if sys.platform == "win32":
+            import msvcrt
+            try:
+                lock.seek(0)
+                msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)
+            except OSError as error:
+                raise CdxError(f"Failed to lock session store: {error}") from error
+            try:
+                yield
+            finally:
+                try:
+                    lock.seek(0)
+                    msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1)
+                except OSError as error:
+                    raise CdxError(f"Failed to unlock session store: {error}") from error
+        else:
             try:
-                fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+                import fcntl
+            except ImportError as error:
+                raise CdxError("Session store locking requires fcntl on this platform") from error
+            try:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
             except OSError as error:
-                raise CdxError(f"Failed to unlock session store: {error}") from error
+                raise CdxError(f"Failed to lock session store: {error}") from error
+            try:
+                yield
+            finally:
+                try:
+                    fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
+                except OSError as error:
+                    raise CdxError(f"Failed to unlock session store: {error}") from error
 
 
 def create_session_store(base_dir):