clighost 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Issam El Bani (VELTEIN)
+
+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.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# CliGhost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One terminal. Multiple identities.**
+
+Created by **Issam El Bani** at **[VELTEIN](https://veltein.com)**
+
+[![npm](https://img.shields.io/npm/v/clighost?color=39ff88&label=clighost)](https://www.npmjs.com/package/clighost)
+[![License: MIT](https://img.shields.io/badge/license-MIT-39ff88)](https://github.com/ssassam/clighost/blob/main/LICENSE)
+
+One command-line interface for **Codex** and **Antigravity CLI (`agy`)** accounts.
+List accounts and remaining quota, add OAuth logins, switch accounts, and launch
+sessions through the existing account-rotation tools.
+
+This is an independent orchestration CLI, not a new OAuth implementation or
+request proxy. It delegates to [codex-multi-auth](https://github.com/ndycode/codex-multi-auth)
+and [antigravity-swap](https://github.com/hrmasss/antigravity-swap). It does not
+read, copy, export, or upload OAuth credential files.
+
+## Install
+
+### From npm
+
+Requires Node.js 18+ and Python 3.10+. The two account backends have their own
+requirements listed below. CliGhost bundles its Python core; no separate pip
+installation of CliGhost is needed.
+
+```sh
+npm install -g clighost
+clighost --help
+```
+
+Or run without a global installation:
+
+```sh
+npx clighost status
+```
+
+If Python is not on PATH, set `CLIGHOST_PYTHON` to the Python 3.10+ executable.
+
+### Provider backends
+
+Install the official Codex and Antigravity CLIs, then their account backends:
+
+```sh
+# Node.js >=22.19 is required by codex-multi-auth.
+npm install -g codex-multi-auth
+
+# Python >=3.12 is required by antigravity-swap.
+pipx install antigravity-swap
+
+clighost doctor
+```
+
+### From source with pipx
+
+```sh
+git clone https://github.com/ssassam/clighost.git
+pipx install ./clighost
+clighost doctor
+```
+
+The earlier `aam` command remains a compatibility alias in Python installations.
+The npm package installs the `clighost` command.
+
+The upstream projects also offer other installation methods. Existing installations
+work: `clighost` resolves commands from PATH, including privately installed runtimes.
+
+## Everyday commands
+
+```sh
+clighost status                         # Both providers, cached quota
+clighost status codex
+clighost status agy --live               # Refresh Antigravity quota
+clighost status --json                   # Normalized JSON; no credential fields
+clighost check codex                     # Live authentication + inference/quota check
+clighost check agy                       # Refresh quota; renew login when needed
+clighost switch codex 2                  # Pin Codex account 2
+clighost switch agy 2                    # Change Antigravity's default account
+clighost run codex                       # mcodex with automatic rotation
+clighost run agy                         # aswap run with quota failover
+clighost run codex -- resume --last
+clighost run codex -- exec "Explain this project"
+clighost run agy -- --continue
+clighost run agy -- -p "Explain this project"
+```
+
+Numbers in `clighost status` are one-based and match the `switch` commands.
+Quota percentages mean **remaining**, including Antigravity reports whose
+upstream percentages mean used. Missing quota stays unknown.
+`status --live --json` writes live-check progress to stderr and JSON to stdout.
+Codex live checks consume some subscription quota.
+
+## Add accounts
+
+```sh
+clighost login codex                     # Device OAuth; repeat for each account
+clighost login agy                       # Opens agy; sign in, then exit to save
+clighost add agy                         # Save the account already signed in to agy
+```
+
+For Antigravity, select the intended Google account in agy's own sign-in UI.
+If it is already signed in, use its account/sign-in controls to change accounts
+before saving. Adding the same account refreshes its stored credentials rather
+than creating another account. Google and ChatGPT accounts are separate pools;
+logging into Codex does not log into Antigravity.
+
+## Switching and continuity
+
+Codex rotation works inside sessions launched with `clighost run codex`. Calling plain
+`codex` does not enable that wrapper. `clighost switch codex N` pins the selected account;
+use `codex-ma unpin` to return to automatic selection.
+
+Antigravity keeps its credentials in memory. `clighost switch agy N` affects new sessions.
+`clighost run agy` uses aswap's quota-failover behavior: stop the session, copy its
+conversation to the next account, and restart with a continuation prompt.
+Saved project files remain in the same working directory. An unfinished tool
+action may be interrupted; this is not a guarantee of exact execution continuity.
+At least two healthy saved accounts are required to test failover.
+
+Automatic health-check schedules remain the backend's settings. For Codex:
+
+```sh
+codex-ma account auto-prime 1 on
+codex-ma account auto-prime 2 on
+```
+
+Those checks run every 15 minutes while the rotation router is running.
+The manager does not install background daemons, shell aliases, Telegram bots,
+or scheduled jobs. Use upstream commands for advanced provider-specific settings.
+
+## Another device
+
+Clone this repository, install both backends, then sign in on that device. Accounts
+and backend settings do not sync through Git. OAuth snapshots are sensitive and
+must never be committed. This repository contains source code only.
+
+## Development
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+For the npm launcher and package contents:
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+Tests mock backend processes and do not make billable requests or change logins.
+Runtime code has no third-party Python dependencies. Backend JSON schema changes
+may require adapter updates. Verified locally with codex-multi-auth 2.24.0 and
+antigravity-swap 0.3.1; automatic two-account Antigravity failover has not been
+verified locally.
+
+## Support the creator
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy_Me_a_Coffee-Support_VELTEIN-FFDD00?logo=buymeacoffee&logoColor=000000)](https://buymeacoffee.com/veltein)
+
+If CliGhost helps your workflow, you can support its development on
+[Buy Me a Coffee](https://buymeacoffee.com/veltein).
+
+## Creator and credits
+
+CliGhost is created and maintained by **Issam El Bani / [VELTEIN](https://veltein.com)**.
+Follow [@ssassam on GitHub](https://github.com/ssassam).
+
+Account authentication and rotation are provided by the independent upstream
+projects [codex-multi-auth by ndycode](https://github.com/ndycode/codex-multi-auth)
+and [antigravity-swap by hrmasss](https://github.com/hrmasss/antigravity-swap).
+Credit for those backends belongs to their authors.
+
+MIT licensed. Not affiliated with OpenAI or Google.

package/bin/clighost.cjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict';
+
+// npm distributes the same Python core as the pipx install. No install hooks,
+// credential copying, or runtime downloads are needed.
+const { spawn, spawnSync } = require('node:child_process');
+const path = require('node:path');
+const os = require('node:os');
+
+function findPython(env = process.env, probe = spawnSync, platform = process.platform) {
+  const candidates = env.CLIGHOST_PYTHON
+    ? [[env.CLIGHOST_PYTHON]]
+    : platform === 'win32'
+      ? [['py', '-3'], ['python3'], ['python']]
+      : [['python3'], ['python']];
+  for (const [command, ...prefix] of candidates) {
+    const result = probe(command, [
+      ...prefix, '-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)',
+    ], { stdio: 'ignore', timeout: 5000, env });
+    if (!result.error && result.status === 0) return { command, prefix };
+  }
+  throw new Error(env.CLIGHOST_PYTHON
+    ? 'CLIGHOST_PYTHON must point to a working Python 3.10+ executable.'
+    : 'Python 3.10+ is required. Install Python, or set CLIGHOST_PYTHON to its executable.');
+}
+
+function launchOptions(interpreter, args, env = process.env) {
+  const source = path.resolve(__dirname, '..', 'src');
+  return {
+    command: interpreter.command,
+    args: [...interpreter.prefix, '-m', 'agent_accounts.cli', ...args],
+    options: {
+      stdio: 'inherit',
+      env: { ...env, PYTHONPATH: source + (env.PYTHONPATH ? path.delimiter + env.PYTHONPATH : '') },
+    },
+  };
+}
+
+function main() {
+  let launch;
+  try {
+    launch = launchOptions(findPython(), process.argv.slice(2));
+  } catch (error) {
+    console.error(`clighost: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const child = spawn(launch.command, launch.args, launch.options);
+  // Interactive terminals deliver Ctrl+C to the foreground process group.
+  // Forward external termination so a killed npm launcher does not leave an agent.
+  const terminate = () => child.kill('SIGTERM');
+  const interrupt = () => {}; // The child receives the terminal's SIGINT directly.
+  process.on('SIGTERM', terminate);
+  process.on('SIGINT', interrupt);
+  child.on('error', (error) => {
+    console.error(`clighost: could not start Python (${error.code || 'unknown error'}).`);
+    process.exitCode = 1;
+  });
+  child.on('close', (code, signal) => {
+    process.removeListener('SIGTERM', terminate);
+    process.removeListener('SIGINT', interrupt);
+    process.exitCode = code === null ? 128 + (os.constants.signals[signal] || 1) : code;
+  });
+}
+
+module.exports = { findPython, launchOptions };
+if (require.main === module) main();

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "clighost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CliGhost by VELTEIN: one CLI for Codex and Antigravity OAuth accounts, quotas, switching, and failover launchers.",
+  "license": "MIT",
+  "author": {
+    "name": "Issam El Bani (VELTEIN)",
+    "url": "https://veltein.com"
+  },
+  "homepage": "https://github.com/ssassam/clighost#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ssassam/clighost.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ssassam/clighost/issues"
+  },
+  "bin": {
+    "clighost": "bin/clighost.cjs"
+  },
+  "files": [
+    "bin/clighost.cjs",
+    "src/agent_accounts/*.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "clighost",
+    "codex",
+    "antigravity",
+    "agy",
+    "oauth",
+    "multi-account",
+    "account-switcher",
+    "quota",
+    "cli"
+  ],
+  "scripts": {
+    "test": "node --test tests/npm-launcher.test.cjs",
+    "prepack": "npm test"
+  },
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://buymeacoffee.com/veltein"
+  }
+}

package/src/agent_accounts/__init__.py

@@ -0,0 +1,3 @@
+"""Unified account management without storing OAuth credentials."""
+
+__version__ = "0.1.0"

package/src/agent_accounts/backends.py

@@ -0,0 +1,152 @@
+"""Invoke the existing account managers and normalize their public reports."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import shutil
+import subprocess
+from typing import Any
+
+
+class BackendError(Exception):
+    """An actionable failure from an installed account manager."""
+
+
+COMMANDS = {"codex": "codex-ma", "agy": "aswap"}
+INSTALL = {
+    "codex": "npm install -g codex-multi-auth (requires Node.js >=22.19 and Codex CLI)",
+    "agy": "pipx install antigravity-swap (requires Python >=3.12 and agy)",
+}
+
+
+def executable(provider: str) -> str:
+    command = COMMANDS[provider]
+    path = shutil.which(command)
+    if not path:
+        raise BackendError(f"Missing {command}. Install it with: {INSTALL[provider]}")
+    return path
+
+
+def json_report(provider: str, *, live: bool = False) -> dict[str, Any]:
+    command = [executable(provider)]
+    command += ["status", "--json"] if provider == "codex" else [
+        "list", "--json", "--refresh" if live else "--cached"
+    ]
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, timeout=180)
+    except subprocess.TimeoutExpired as exc:
+        raise BackendError(f"{provider} status timed out after 180 seconds") from exc
+    except OSError as exc:
+        raise BackendError(f"Could not start {COMMANDS[provider]}: {exc.strerror}") from exc
+    if result.returncode:
+        # Do not forward arbitrary backend diagnostics to a JSON report: some
+        # errors contain local paths or OAuth callback parameters.
+        raise BackendError(f"{COMMANDS[provider]} status failed (exit {result.returncode}); run it directly for details")
+    try:
+        data = json.loads(result.stdout)
+    except ValueError as exc:
+        raise BackendError(f"{COMMANDS[provider]} returned invalid JSON") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("accounts"), list):
+        raise BackendError(f"{COMMANDS[provider]} returned an unsupported status schema")
+    return data
+
+
+def remaining(value: Any) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if not math.isfinite(value) or not 0 <= value <= 100:
+        return None
+    return round(100 - value, 2)
+
+
+def normalize(provider: str, data: dict[str, Any]) -> list[dict[str, Any]]:
+    """Copy only public, known fields; never return backend credential blobs.
+
+    The Codex JSON API uses zero-based indexes, while switch uses one-based
+    numbers. Antigravity's public number is already one-based.
+    """
+    output = []
+    for account in data["accounts"]:
+        if not isinstance(account, dict):
+            raise BackendError(f"{provider} returned an invalid account record")
+        quotas = []
+        if provider == "codex":
+            index = account.get("index")
+            if isinstance(index, bool) or not isinstance(index, int) or index < 0:
+                raise BackendError("Codex account has an invalid index")
+            number = index + 1
+            label = account.get("label")
+            label = label if isinstance(label, str) else f"Account {number}"
+            match = re.search(r"[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}", label)
+            email = match.group(0) if match else None
+            active = account.get("current") is True
+            subscription = account.get("subscription") or {}
+            subscription = subscription if isinstance(subscription, dict) else {}
+            plan = subscription.get("planLabel")
+            auto_check = account.get("autoPrime") is True
+            quota = account.get("quota") or {}
+            quota = quota if isinstance(quota, dict) else {}
+            for key in ("primary", "secondary"):
+                window = quota.get(key)
+                if isinstance(window, dict):
+                    quotas.append({
+                        "name": key,
+                        "window_minutes": window.get("windowMinutes"),
+                        "remaining_percent": remaining(window.get("usedPercent")),
+                        "reset_at_ms": window.get("resetAtMs"),
+                    })
+        else:
+            number = account.get("number")
+            if isinstance(number, bool) or not isinstance(number, int) or number < 1:
+                raise BackendError("Antigravity account has an invalid number")
+            email = account.get("email")
+            active = account.get("active") is True
+            plan, auto_check = None, None
+            usage = account.get("usage") or {}
+            usage = usage if isinstance(usage, dict) else {}
+            for name, window in usage.items():
+                if not isinstance(window, dict):
+                    continue
+                quotas.append({
+                    "name": name,
+                    "remaining_percent": remaining(window.get("usedPct")),
+                    "reset_at": window.get("resetsAt"),
+                })
+        output.append({
+            "provider": provider, "number": number, "email": email,
+            "active": active, "plan": plan, "automatic_checks": auto_check,
+            "quota": quotas,
+        })
+    return output
+
+
+def action(provider: str, operation: str, target: str | None = None) -> list[str]:
+    if operation == "login":
+        return [executable("codex"), "login", "--device-auth"] if provider == "codex" else require_agy()
+    if operation == "check":
+        return [executable(provider)] + (["check", "accounts"] if provider == "codex" else ["list", "--refresh"])
+    if operation == "add":
+        if provider != "agy":
+            raise BackendError("Use 'clighost login codex' to add a Codex account")
+        return [executable(provider), "add"]
+    if operation == "switch":
+        if not target or not target.isdecimal() or int(target) < 1:
+            raise BackendError("Account number must be a positive integer from 'clighost status'")
+        return [executable(provider), "switch", str(int(target))]
+    if operation == "run":
+        if provider == "codex":
+            path = shutil.which("mcodex")
+            if not path:
+                raise BackendError(f"Missing mcodex. Install: {INSTALL['codex']}")
+            return [path]
+        return [executable(provider), "run", "--"]
+    raise BackendError(f"Unsupported operation: {operation}")
+
+
+def require_agy() -> list[str]:
+    path = shutil.which("agy")
+    if not path:
+        raise BackendError("Missing agy. Install the official Antigravity CLI first")
+    return [path]

package/src/agent_accounts/cli.py

@@ -0,0 +1,129 @@
+"""Command-line entry point. OAuth stays in the upstream managers."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+from . import __version__
+from .backends import BackendError, action, json_report, normalize
+
+PROVIDERS = ("codex", "agy")
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="clighost", description="CliGhost by VELTEIN — manage Codex and Antigravity accounts")
+    root.add_argument("--version", action="version", version=f"CliGhost {__version__} by VELTEIN")
+    commands = root.add_subparsers(dest="command", required=True)
+    status = commands.add_parser("status", help="Show accounts and cached quota; never shows tokens")
+    status.add_argument("provider", choices=(*PROVIDERS, "all"), nargs="?", default="all")
+    status.add_argument("--json", action="store_true", help="Emit normalized schema_version=1 JSON")
+    status.add_argument("--live", action="store_true", help="Refresh quota; Codex performs live inference checks")
+    doctor = commands.add_parser("doctor", help="Check the four required commands on PATH")
+    doctor.add_argument("--json", action="store_true")
+    for name, help_text in (
+        ("login", "Add an account through the provider's OAuth login"),
+        ("check", "Check live authentication and quota"),
+        ("add", "Save the currently signed-in Antigravity account"),
+        ("switch", "Switch or pin an account by its displayed number"),
+        ("run", "Launch a provider with its existing failover wrapper"),
+    ):
+        command = commands.add_parser(name, help=help_text)
+        command.add_argument("provider", choices=PROVIDERS)
+        if name == "switch":
+            command.add_argument("number", help="One-based number shown in status")
+        if name == "run":
+            command.add_argument("args", nargs=argparse.REMAINDER, help="Provider arguments after --")
+    return root
+
+
+def run_command(command: list[str]) -> int:
+    try:
+        return subprocess.call(command)
+    except OSError as exc:
+        raise BackendError(f"Could not start command: {exc.strerror}") from exc
+
+
+def status(args: argparse.Namespace) -> int:
+    reports, errors = [], {}
+    providers = PROVIDERS if args.provider == "all" else (args.provider,)
+    for provider in providers:
+        try:
+            if args.live and provider == "codex":
+                # Keep stdout valid JSON while allowing progress on stderr.
+                result = subprocess.run(action(provider, "check"), stdout=sys.stderr, stderr=sys.stderr)
+                if result.returncode:
+                    raise BackendError(f"Codex live check failed (exit {result.returncode})")
+            reports.extend(normalize(provider, json_report(provider, live=args.live)))
+        except BackendError as exc:
+            errors[provider] = str(exc)
+    if args.json:
+        print(json.dumps({"schema_version": 1, "accounts": reports, "errors": errors}, indent=2))
+    else:
+        for provider in providers:
+            print(f"{provider.upper()} accounts")
+            accounts = [a for a in reports if a["provider"] == provider]
+            if provider in errors:
+                print(f"  Error: {errors[provider]}")
+            elif not accounts:
+                print(f"  No accounts. Run: clighost login {provider}")
+            for account in accounts:
+                current = " [active]" if account["active"] else ""
+                print(f"  {account['number']}. {account['email'] or 'Email unavailable'}{current}")
+                for quota in account["quota"]:
+                    name = quota["name"]
+                    minutes = quota.get("window_minutes")
+                    if minutes == 300:
+                        name = "5h"
+                    elif minutes == 10080:
+                        name = "weekly"
+                    percent = quota["remaining_percent"]
+                    print(f"     {name}: " + ("unknown" if percent is None else f"{percent:g}% left"))
+                if not account["quota"]:
+                    print("     Quota unknown; run clighost check " + provider)
+        print("\nQuota is cached unless --live is used; unknown quota does not mean zero.")
+    return 1 if errors else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "doctor":
+            commands = {name: shutil.which(name) for name in ("codex-ma", "mcodex", "aswap", "agy")}
+            if args.json:
+                print(json.dumps({"commands": commands}, indent=2))
+            else:
+                for name, path in commands.items():
+                    print(f"{name}: {path or 'MISSING'}")
+            return 0 if all(commands.values()) else 1
+        if args.command == "status":
+            return status(args)
+        command = action(args.provider, args.command, getattr(args, "number", None))
+        if args.command == "run":
+            forwarded = args.args[1:] if args.args[:1] == ["--"] else args.args
+            # Replace this process, preserving stdin, terminal, signal delivery,
+            # cwd and all backend flags rather than capturing a live session.
+            os.execv(command[0], command + forwarded)
+        if args.command == "login" and args.provider == "agy":
+            # Validate both tools before asking the user to sign in.
+            add = action("agy", "add")
+            print("In agy, sign in to the account you want to save, then exit. clighost will save that login.", file=sys.stderr)
+            code = run_command(command)
+            return code if code else run_command(add)
+        return run_command(command)
+    except BackendError as exc:
+        print(f"clighost: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"clighost: could not launch provider: {exc.strerror}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())