m0squared-indicator 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 morius (M-zero-Squared)
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of morius. The Software is provided for personal,
+non-commercial use only.
+
+You are permitted to:
+  - Install and use the Software on your own devices for personal use
+  - Share the installation command so others may install the Software
+
+You are NOT permitted to:
+  - Copy, modify, or distribute the source code
+  - Use the Software for commercial purposes without written permission
+  - Publish derivative works based on this Software
+  - Remove or alter this copyright notice
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM THE USE OF THIS SOFTWARE.
+
+Contact: github.com/m0squared/m0squared

package/README.md

@@ -0,0 +1,186 @@
+<div align="center">
+
+<pre>
+  ███╗   ███╗ ██████╗<sup>2</sup>
+  ████╗ ████║██╔═══██╗
+  ██╔████╔██║██║   ██║
+  ██║╚██╔╝██║╚██████╔╝
+  ╚═╝  ╚═╝  ╚═════╝
+</pre>
+
+### **M0²** 
+
+*Real-time token usage indicator for AI coding agents*
+
+---
+
+[![npm](https://img.shields.io/npm/v/m0squared-indicator?color=cyan&label=npm)](https://www.npmjs.com/package/m0squared-indicator)
+[![npm downloads](https://img.shields.io/npm/dm/m0squared-indicator?color=cyan)](https://www.npmjs.com/package/m0squared-indicator)
+[![license](https://img.shields.io/badge/license-Personal%20Use-yellow)](#license)
+[![made with love](https://img.shields.io/badge/made%20with-%E2%9D%A4-red)](https://github.com/m0squared/m0s-indicator)
+[![built by a Claude Code lover](https://img.shields.io/badge/built%20by-Claude%20Code%20lover-blueviolet)](https://claude.ai/code)
+
+</div>
+
+---
+
+## What is M0²?
+
+**M0²** is a live HUD (Heads-Up Display) that sits inside your AI coding agent and shows you exactly how much of your token quota you've consumed — in real time, right where you work.
+
+No more getting cut off mid-task. No more opening dashboards. No more guessing.
+
+> *Start full. Watch it drain. Know when to stop.*
+
+```
+[Pro]  🔋 [████████░░░░░░░░░░░░] 42%  ↺ 3h 20m   📝 [████░░░░░░░░░░░] 18%
+[Max]  🔋 [████████░░░░░░░░░░░░] 42%  ↺ 3h 20m   📝 [████░░░░░░░░░░░] 18%
+[PAYG] 💸 $0.0241                                 📝 [███████░░░░░░░░] 33%
+[Free] 📝 [█░░░░░░░░░░░░░░░░░░░]  5%
+```
+
+---
+
+## Supported Agents
+
+| Agent | Status | Integration |
+|---|---|---|
+| **Claude Code** | ✅ Full support | Native `statusLine` hook — live in the status bar |
+| **Codex CLI** | ✅ Supported | `PostToolUse` hook — tracks every response |
+| **Gemini CLI** | ✅ Supported | `AfterTool` hook — tracks every response |
+
+> More agents coming. PRs welcome.
+
+---
+
+## Install
+
+Pick your method — they all do the same thing.
+
+### npx *(recommended — no install needed)*
+```bash
+npx m0squared-indicator install
+```
+
+### npm
+```bash
+npm install -g m0squared-indicator
+m0squared-indicator install
+```
+
+### pip
+```bash
+pip install m0squared-indicator
+m0squared-indicator install
+```
+
+### curl *(Linux / macOS)*
+```bash
+curl -sSL https://raw.githubusercontent.com/m0squared/m0s-indicator/main/scripts/install.sh | bash
+```
+
+### PowerShell *(Windows)*
+```powershell
+irm https://raw.githubusercontent.com/m0squared/m0s-indicator/main/scripts/install.ps1 | iex
+```
+
+---
+
+## How it works
+
+M0² auto-detects which AI agents are installed on your machine and patches their config files silently. After a restart, the HUD appears automatically.
+
+```
+  M0²  v1.0.0  Universal AI Agent HUD
+  by morius
+
+  Scanning for AI agents…
+
+  ✓  Claude Code     detected
+  ✓  Codex CLI       detected
+  ✗  Gemini CLI      not found
+
+  Installing for: Claude Code, Codex CLI
+
+  ✓ M0² installed successfully!
+  Restart your agent to see the HUD.
+```
+
+---
+
+## Usage
+
+```bash
+m0squared-indicator install          # install for all detected agents
+m0squared-indicator install --agent claude-code   # target one agent
+m0squared-indicator uninstall        # remove from all agents
+m0squared-indicator update           # update to latest version
+m0squared-indicator agents           # list detected agents and status
+```
+
+---
+
+## Configuration
+
+After install, a config file is created at `~/.m0squared/config.json`:
+
+```json
+{
+  "plan": "auto",
+  "bar_width": 20,
+  "codex": {
+    "session_token_limit": 100000
+  },
+  "gemini": {
+    "session_token_limit": 100000
+  }
+}
+```
+
+| Key | Values | Description |
+|---|---|---|
+| `plan` | `auto` `pro` `max` `payg` `free` | Override plan auto-detection |
+| `bar_width` | number | Width of the progress bar (default: 20) |
+| `*.session_token_limit` | number | Token limit for Codex / Gemini sessions |
+
+> **Auto-detection:** Claude Code Pro/Max is detected automatically via the `rate_limits` field. Set `"plan": "max"` manually if you're on Max.
+
+---
+
+## Uninstall
+
+```bash
+npx m0squared-indicator uninstall
+```
+
+This removes all hooks from your agent configs and deletes `~/.m0squared/`.
+
+---
+
+## Why M0²?
+
+Built out of pure love for [Claude Code](https://claude.ai/code) — and frustration with hitting token limits mid-session without any warning.
+
+M0² was born from a simple idea: *your tools should tell you when you're running out of fuel.*
+
+> **Built by a Claude Code lover, with Claude Code.**  
+> *— haddad med / morius*
+
+---
+
+## License
+
+© 2026 morius (M-zero-Squared / haddad med). All rights reserved.
+
+Free for personal use. No redistribution or commercial use without written permission.  
+See [LICENSE](./LICENSE) for full terms.
+
+---
+
+<div align="center">
+
+Made with ❤️ by **haddad med** · [github.com/m0squared](https://github.com/m0squared)
+
+*If M0² saved your session — give it a ⭐*
+
+</div>

package/bin/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+
+// © 2026 morius (M-zero-Squared). All rights reserved.
+// Free for personal use. No redistribution without permission.
+// https://github.com/m0squared/m0squared
+
+const args = process.argv.slice(2);
+const ui = require('../src/ui');
+
+// Parse --agent flag
+let agentFlag = null;
+const agentIdx = args.indexOf('--agent');
+if (agentIdx !== -1 && args[agentIdx + 1]) {
+  agentFlag = args[agentIdx + 1];
+}
+
+const command = args.find(a => !a.startsWith('-') && a !== agentFlag);
+
+const opts = { agent: agentFlag };
+
+switch (command) {
+  case 'install':
+  case 'i':
+    require('../src/commands/install')(opts).catch(e => {
+      ui.error(e.message);
+      process.exit(1);
+    });
+    break;
+
+  case 'uninstall':
+  case 'remove':
+  case 'u':
+    require('../src/commands/uninstall')(opts).catch(e => {
+      ui.error(e.message);
+      process.exit(1);
+    });
+    break;
+
+  case 'update':
+    require('../src/commands/update')(opts).catch(e => {
+      ui.error(e.message);
+      process.exit(1);
+    });
+    break;
+
+  case 'agents': {
+    const { detectAll } = require('../src/detect');
+    const AGENTS = {
+      'claude-code': require('../src/agents/claude-code'),
+      'codex': require('../src/agents/codex'),
+      'gemini': require('../src/agents/gemini'),
+    };
+    ui.banner();
+    ui.section('Agent status:\n');
+    const detected = detectAll();
+    for (const [name, agent] of Object.entries(AGENTS)) {
+      if (!detected[name]) {
+        ui.agentLine(name, 'missing');
+      } else if (agent.isInstalled()) {
+        ui.agentLine(name, 'found', 'M0² installed');
+      } else {
+        ui.agentLine(name, 'found', 'M0² not installed');
+      }
+    }
+    console.log();
+    break;
+  }
+
+  case '--version':
+  case '-v':
+  case 'version': {
+    const pkg = require('../package.json');
+    console.log(`m0squared v${pkg.version}`);
+    break;
+  }
+
+  case '--help':
+  case '-h':
+  case 'help':
+  default:
+    ui.showHelp();
+    break;
+}

package/config.default.json

@@ -0,0 +1,10 @@
+{
+  "plan": "auto",
+  "bar_width": 20,
+  "codex": {
+    "session_token_limit": 100000
+  },
+  "gemini": {
+    "session_token_limit": 100000
+  }
+}

package/core/hooks/codex-hook.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# © 2026 morius (M-zero-Squared). All rights reserved.
+# https://github.com/m0squared/m0squared
+"""
+M0² Codex CLI Hook — PostToolUse
+Reads the session transcript, calculates token usage,
+and writes state to ~/.m0squared/codex-state.json
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+M0SQ_DIR   = Path.home() / ".m0squared"
+STATE_FILE  = M0SQ_DIR / "codex-state.json"
+CONFIG_FILE = M0SQ_DIR / "config.json"
+
+def load_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except Exception:
+            pass
+    return {}
+
+def sum_tokens_from_transcript(transcript_path: str) -> dict:
+    """Sum all token usage from a JSONL transcript."""
+    total = {"input_tokens": 0, "output_tokens": 0,
+             "cache_read": 0, "cache_create": 0}
+    try:
+        with open(transcript_path) as f:
+            for line in f:
+                try:
+                    entry = json.loads(line.strip())
+                    usage = (entry.get("message") or {}).get("usage") or \
+                            entry.get("usage") or {}
+                    total["input_tokens"]  += usage.get("input_tokens", 0)
+                    total["output_tokens"] += usage.get("output_tokens", 0)
+                    total["cache_read"]    += usage.get("cache_read_input_tokens", 0)
+                    total["cache_create"]  += usage.get("cache_creation_input_tokens", 0)
+                except Exception:
+                    pass
+    except Exception:
+        pass
+    return total
+
+def main() -> None:
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except Exception:
+        sys.exit(0)
+
+    transcript_path = hook_input.get("transcript_path", "")
+    config = load_config()
+
+    token_limit = (config.get("codex") or {}).get("session_token_limit", 100000)
+
+    tokens = sum_tokens_from_transcript(transcript_path)
+    total_used = tokens["input_tokens"] + tokens["output_tokens"]
+    pct = min(100.0, (total_used / token_limit) * 100) if token_limit > 0 else 0
+
+    M0SQ_DIR.mkdir(parents=True, exist_ok=True)
+
+    state = {
+        "_agent": "codex",
+        "_updated": datetime.now(timezone.utc).isoformat(),
+        "context_window": {
+            "used_percentage": round(pct, 1),
+            "total_input_tokens": tokens["input_tokens"],
+            "total_output_tokens": tokens["output_tokens"],
+        },
+        "cost": {
+            "total_cost_usd": 0
+        },
+    }
+
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    # Allow hook to continue (don't block)
+    print(json.dumps({"continue": True}))
+
+if __name__ == "__main__":
+    main()

package/core/hooks/gemini-hook.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# © 2026 morius (M-zero-Squared). All rights reserved.
+# https://github.com/m0squared/m0squared
+"""
+M0² Gemini CLI Hook — AfterTool
+Reads the session transcript, calculates token usage,
+and writes state to ~/.m0squared/gemini-state.json
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+M0SQ_DIR   = Path.home() / ".m0squared"
+STATE_FILE  = M0SQ_DIR / "gemini-state.json"
+CONFIG_FILE = M0SQ_DIR / "config.json"
+
+def load_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except Exception:
+            pass
+    return {}
+
+def sum_tokens_from_transcript(transcript_path: str) -> dict:
+    """Sum all token usage from a JSONL transcript."""
+    total = {"input_tokens": 0, "output_tokens": 0}
+    try:
+        with open(transcript_path) as f:
+            for line in f:
+                try:
+                    entry = json.loads(line.strip())
+                    # Gemini CLI transcript format
+                    usage = entry.get("usageMetadata") or \
+                            (entry.get("message") or {}).get("usage") or \
+                            entry.get("usage") or {}
+                    total["input_tokens"]  += (
+                        usage.get("promptTokenCount") or
+                        usage.get("input_tokens", 0)
+                    )
+                    total["output_tokens"] += (
+                        usage.get("candidatesTokenCount") or
+                        usage.get("output_tokens", 0)
+                    )
+                except Exception:
+                    pass
+    except Exception:
+        pass
+    return total
+
+def main() -> None:
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except Exception:
+        sys.exit(0)
+
+    transcript_path = hook_input.get("transcript_path", "")
+    config = load_config()
+
+    token_limit = (config.get("gemini") or {}).get("session_token_limit", 100000)
+
+    tokens = sum_tokens_from_transcript(transcript_path)
+    total_used = tokens["input_tokens"] + tokens["output_tokens"]
+    pct = min(100.0, (total_used / token_limit) * 100) if token_limit > 0 else 0
+
+    M0SQ_DIR.mkdir(parents=True, exist_ok=True)
+
+    state = {
+        "_agent": "gemini",
+        "_updated": datetime.now(timezone.utc).isoformat(),
+        "context_window": {
+            "used_percentage": round(pct, 1),
+            "total_input_tokens": tokens["input_tokens"],
+            "total_output_tokens": tokens["output_tokens"],
+        },
+        "cost": {
+            "total_cost_usd": 0
+        },
+    }
+
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    # Gemini hooks expect exit 0 for success
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/core/indicator.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+# © 2026 morius (M-zero-Squared). All rights reserved.
+# https://github.com/m0squared/m0squared
+"""
+M0² — Universal AI Agent HUD
+Status line script: receives JSON from stdin (Claude Code statusLine mode)
+or reads state file (Codex / Gemini mode).
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+M0SQ_DIR   = Path.home() / ".m0squared"
+CONFIG_FILE = M0SQ_DIR / "config.json"
+
+# ── ANSI ──────────────────────────────────────────────────────────────────────
+GREEN  = "\033[92m"
+YELLOW = "\033[93m"
+RED    = "\033[91m"
+CYAN   = "\033[96m"
+BOLD   = "\033[1m"
+DIM    = "\033[2m"
+RESET  = "\033[0m"
+
+# ── Config ────────────────────────────────────────────────────────────────────
+
+def load_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except Exception:
+            pass
+    return {}
+
+# ── Rendering helpers ─────────────────────────────────────────────────────────
+
+def bar(pct: float | None, width: int) -> str:
+    if pct is None:
+        return "[" + "?" * width + "]"
+    filled = min(width, max(0, round(width * pct / 100)))
+    return "[" + "█" * filled + "░" * (width - filled) + "]"
+
+def color(pct: float | None) -> str:
+    if pct is None: return DIM
+    if pct >= 80:   return RED
+    if pct >= 50:   return YELLOW
+    return GREEN
+
+def fmt_pct(pct: float | None) -> str:
+    return f"{pct:.0f}%" if pct is not None else "?%"
+
+def time_until(ts: float) -> str:
+    remaining = ts - datetime.now(timezone.utc).timestamp()
+    if remaining <= 0: return "resetting…"
+    h = int(remaining // 3600)
+    m = int((remaining % 3600) // 60)
+    return f"{h}h {m}m" if h else f"{m}m"
+
+BADGES = {
+    "pro":  (CYAN,   "Pro"),
+    "max":  (BOLD,   "Max"),
+    "payg": (YELLOW, "PAYG"),
+    "free": (DIM,    "Free"),
+}
+
+def badge(plan: str) -> str:
+    c, label = BADGES.get(plan, (DIM, plan.upper()))
+    return f"{BOLD}{c}[{label}]{RESET}"
+
+AGENT_BADGES = {
+    "claude-code": f"{CYAN}Claude{RESET}",
+    "codex":       f"\033[35mCodex{RESET}",
+    "gemini":      f"\033[34mGemini{RESET}",
+}
+
+def detect_plan(data: dict, config: dict) -> str:
+    user_plan = config.get("plan", "auto").lower()
+    if user_plan != "auto":
+        return user_plan
+    if data.get("rate_limits"):
+        return "pro"
+    cost = (data.get("cost") or {}).get("total_cost_usd", 0)
+    if cost and float(cost) > 0:
+        return "payg"
+    return "free"
+
+# ── Render ────────────────────────────────────────────────────────────────────
+
+def render(data: dict, config: dict) -> None:
+    plan   = detect_plan(data, config)
+    width  = int(config.get("bar_width", 20))
+    ctx    = data.get("context_window") or {}
+    rate   = data.get("rate_limits")
+    cost   = data.get("cost") or {}
+    agent  = data.get("_agent", "claude-code")
+
+    parts: list[str] = []
+
+    # Agent badge (for multi-agent state files)
+    if agent != "claude-code":
+        parts.append(AGENT_BADGES.get(agent, agent))
+
+    parts.append(badge(plan))
+
+    # Subscription rate limit bar (Pro / Max)
+    if plan in ("pro", "max") and rate:
+        five   = rate.get("five_hour", {})
+        pct    = five.get("used_percentage")
+        resets = five.get("resets_at")
+        c  = color(pct)
+        b  = bar(pct, width)
+        p  = fmt_pct(pct)
+        rt = f" {DIM}↺ {time_until(resets)}{RESET}" if resets else ""
+        parts.append(f"🔋 {c}{b} {p}{RESET}{rt}")
+
+    # PAYG cost
+    elif plan == "payg":
+        usd = float(cost.get("total_cost_usd", 0) or 0)
+        parts.append(f"💸 {YELLOW}${usd:.4f}{RESET}")
+
+    # Context window bar
+    ctx_pct = ctx.get("used_percentage")
+    if ctx_pct is not None:
+        c = color(ctx_pct)
+        b = bar(ctx_pct, max(10, int(width * 0.75)))
+        p = fmt_pct(ctx_pct)
+        parts.append(f"📝 {c}{b} {p}{RESET}")
+
+    if parts:
+        print("  ".join(parts))
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    config = load_config()
+
+    # Try stdin first (Claude Code statusLine mode)
+    if not sys.stdin.isatty():
+        raw = sys.stdin.read()
+        if raw.strip():
+            try:
+                data = json.loads(raw)
+                render(data, config)
+                return
+            except Exception:
+                pass
+
+    # Fall back to state files (Codex / Gemini mode)
+    for agent in ("codex", "gemini"):
+        state_file = M0SQ_DIR / f"{agent}-state.json"
+        if state_file.exists():
+            try:
+                data = json.loads(state_file.read_text())
+                data.setdefault("_agent", agent)
+                render(data, config)
+                return
+            except Exception:
+                pass
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "m0squared-indicator",
+  "version": "1.0.0",
+  "description": "M0² — Universal AI Agent Token Usage HUD for Claude Code, Codex CLI & Gemini CLI",
+  "keywords": ["claude-code", "codex", "gemini", "ai", "token", "usage", "hud", "indicator", "m0squared"],
+  "author": {
+    "name": "haddad med",
+    "url": "https://github.com/m0squared"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/m0squared/m0s-indicator.git"
+  },
+  "homepage": "https://github.com/m0squared/m0s-indicator",
+  "bugs": {
+    "url": "https://github.com/m0squared/m0s-indicator/issues"
+  },
+  "bin": {
+    "m0squared-indicator": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "core",
+    "config.default.json",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  }
+}

package/src/agents/claude-code.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+const CLAUDE_DIR = path.join(HOME, '.claude');
+const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
+
+function isInstalled() {
+  try {
+    if (!fs.existsSync(SETTINGS_PATH)) return false;
+    const s = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    return !!(s.statusLine && s.statusLine.command && s.statusLine.command.includes('m0squared'));
+  } catch {
+    return false;
+  }
+}
+
+function install(installDir) {
+  const scriptPath = path.join(installDir, 'indicator.py');
+
+  // Ensure ~/.claude exists
+  fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+
+  // Read or init settings.json
+  let settings = {};
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  settings.statusLine = {
+    type: 'command',
+    command: `python3 ${scriptPath}`,
+  };
+
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true };
+}
+
+function uninstall() {
+  if (!fs.existsSync(SETTINGS_PATH)) return { ok: true };
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    if (settings.statusLine && settings.statusLine.command &&
+        settings.statusLine.command.includes('m0squared')) {
+      delete settings.statusLine;
+      fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+module.exports = { isInstalled, install, uninstall };

package/src/agents/codex.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+const CODEX_DIR = path.join(HOME, '.codex');
+const CONFIG_PATH = path.join(CODEX_DIR, 'config.toml');
+const HOOKS_PATH = path.join(CODEX_DIR, 'hooks.json');
+
+function isInstalled() {
+  try {
+    if (!fs.existsSync(HOOKS_PATH)) return false;
+    const h = JSON.parse(fs.readFileSync(HOOKS_PATH, 'utf8'));
+    const postHooks = h.PostToolUse || [];
+    return postHooks.some(h => JSON.stringify(h).includes('m0squared'));
+  } catch {
+    return false;
+  }
+}
+
+function install(installDir) {
+  const hookScript = path.join(installDir, 'hooks', 'codex-hook.py');
+
+  fs.mkdirSync(CODEX_DIR, { recursive: true });
+
+  // Enable hooks in config.toml
+  let toml = '';
+  if (fs.existsSync(CONFIG_PATH)) {
+    toml = fs.readFileSync(CONFIG_PATH, 'utf8');
+  }
+
+  if (!toml.includes('[features]')) {
+    toml += '\n[features]\ncodex_hooks = true\n';
+  } else if (!toml.includes('codex_hooks')) {
+    toml = toml.replace('[features]', '[features]\ncodex_hooks = true');
+  }
+
+  fs.writeFileSync(CONFIG_PATH, toml);
+
+  // Add PostToolUse hook to hooks.json
+  let hooks = {};
+  if (fs.existsSync(HOOKS_PATH)) {
+    try {
+      hooks = JSON.parse(fs.readFileSync(HOOKS_PATH, 'utf8'));
+    } catch {
+      hooks = {};
+    }
+  }
+
+  if (!hooks.PostToolUse) hooks.PostToolUse = {};
+  if (!hooks.PostToolUse['*']) hooks.PostToolUse['*'] = [];
+
+  // Remove any existing m0squared hook
+  hooks.PostToolUse['*'] = hooks.PostToolUse['*'].filter(
+    h => !JSON.stringify(h).includes('m0squared')
+  );
+
+  hooks.PostToolUse['*'].push({
+    command: `python3 ${hookScript}`,
+    timeout: 5,
+    statusMessage: 'M0² tracking tokens…',
+  });
+
+  fs.writeFileSync(HOOKS_PATH, JSON.stringify(hooks, null, 2) + '\n');
+  return { ok: true };
+}
+
+function uninstall() {
+  if (!fs.existsSync(HOOKS_PATH)) return { ok: true };
+
+  try {
+    const hooks = JSON.parse(fs.readFileSync(HOOKS_PATH, 'utf8'));
+    if (hooks.PostToolUse && hooks.PostToolUse['*']) {
+      hooks.PostToolUse['*'] = hooks.PostToolUse['*'].filter(
+        h => !JSON.stringify(h).includes('m0squared')
+      );
+    }
+    fs.writeFileSync(HOOKS_PATH, JSON.stringify(hooks, null, 2) + '\n');
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+module.exports = { isInstalled, install, uninstall };

package/src/agents/gemini.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+const GEMINI_DIR = path.join(HOME, '.gemini');
+const SETTINGS_PATH = path.join(GEMINI_DIR, 'settings.json');
+
+function isInstalled() {
+  try {
+    if (!fs.existsSync(SETTINGS_PATH)) return false;
+    const s = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    const afterTool = s.hooks && s.hooks.AfterTool;
+    return !!(afterTool && JSON.stringify(afterTool).includes('m0squared'));
+  } catch {
+    return false;
+  }
+}
+
+function install(installDir) {
+  const hookScript = path.join(installDir, 'hooks', 'gemini-hook.py');
+
+  fs.mkdirSync(GEMINI_DIR, { recursive: true });
+
+  // Read or init settings.json
+  let settings = {};
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  if (!settings.hooks.AfterTool) settings.hooks.AfterTool = [];
+
+  // Remove any existing m0squared hook
+  settings.hooks.AfterTool = settings.hooks.AfterTool.filter(
+    entry => !JSON.stringify(entry).includes('m0squared')
+  );
+
+  settings.hooks.AfterTool.push({
+    matcher: '.*',
+    hooks: [
+      {
+        name: 'm0squared-tracker',
+        type: 'command',
+        command: `python3 ${hookScript}`,
+        timeout: 5000,
+      },
+    ],
+  });
+
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true };
+}
+
+function uninstall() {
+  if (!fs.existsSync(SETTINGS_PATH)) return { ok: true };
+
+  try {
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    if (settings.hooks && settings.hooks.AfterTool) {
+      settings.hooks.AfterTool = settings.hooks.AfterTool.filter(
+        entry => !JSON.stringify(entry).includes('m0squared')
+      );
+    }
+    fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+module.exports = { isInstalled, install, uninstall };

package/src/commands/install.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ui = require('../ui');
+const { detectAll, getInstallDir } = require('../detect');
+
+const AGENTS = {
+  'claude-code': require('../agents/claude-code'),
+  'codex': require('../agents/codex'),
+  'gemini': require('../agents/gemini'),
+};
+
+const AGENT_LABELS = {
+  'claude-code': 'Claude Code',
+  'codex': 'Codex CLI',
+  'gemini': 'Gemini CLI',
+};
+
+module.exports = async function install(opts = {}) {
+  ui.banner();
+
+  const installDir = getInstallDir();
+  const targetAgent = opts.agent || null;
+
+  // Detect agents
+  ui.section('Scanning for AI agents…\n');
+  const detected = detectAll();
+
+  const toInstall = [];
+
+  for (const [name, agent] of Object.entries(AGENTS)) {
+    if (targetAgent && name !== targetAgent) continue;
+
+    if (!detected[name]) {
+      ui.agentLine(name, 'missing');
+    } else if (agent.isInstalled()) {
+      ui.agentLine(name, 'skip');
+    } else {
+      ui.agentLine(name, 'found');
+      toInstall.push(name);
+    }
+  }
+
+  if (toInstall.length === 0) {
+    console.log();
+    ui.info('Nothing to install — all detected agents already have M0².');
+    ui.tip('Run "npx m0squared update" to update to the latest version.');
+    console.log();
+    return;
+  }
+
+  // Copy core files
+  console.log();
+  ui.section('Installing core files…');
+
+  fs.mkdirSync(path.join(installDir, 'hooks'), { recursive: true });
+
+  // Copy indicator.py
+  const indicatorSrc = path.join(__dirname, '../../core/indicator.py');
+  const indicatorDst = path.join(installDir, 'indicator.py');
+  fs.copyFileSync(indicatorSrc, indicatorDst);
+  fs.chmodSync(indicatorDst, '755');
+
+  // Copy hook scripts
+  for (const hookFile of ['codex-hook.py', 'gemini-hook.py']) {
+    const src = path.join(__dirname, '../../core/hooks', hookFile);
+    const dst = path.join(installDir, 'hooks', hookFile);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dst);
+      fs.chmodSync(dst, '755');
+    }
+  }
+
+  // Write default config if not exists
+  const configDst = path.join(installDir, 'config.json');
+  if (!fs.existsSync(configDst)) {
+    const configSrc = path.join(__dirname, '../../config.default.json');
+    fs.copyFileSync(configSrc, configDst);
+  }
+
+  // Install per agent
+  console.log();
+  ui.section(`Installing for: ${toInstall.map(n => AGENT_LABELS[n]).join(', ')}\n`);
+
+  let anyFailed = false;
+
+  for (const name of toInstall) {
+    ui.agentLine(name, 'installing');
+    try {
+      const result = AGENTS[name].install(installDir);
+      if (result.ok) {
+        ui.agentLine(name, 'done');
+      } else {
+        ui.agentLine(name, 'error', result.error || 'unknown error');
+        anyFailed = true;
+      }
+    } catch (e) {
+      ui.agentLine(name, 'error', e.message);
+      anyFailed = true;
+    }
+  }
+
+  console.log();
+
+  if (!anyFailed) {
+    ui.success('M0² installed successfully!');
+    ui.tip('Restart your AI agent to see the HUD.');
+    ui.tip(`Config file: ${path.join(installDir, 'config.json')}`);
+    console.log();
+  } else {
+    ui.error('Some agents failed to install. Check the errors above.');
+  }
+};

package/src/commands/uninstall.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ui = require('../ui');
+const { getInstallDir } = require('../detect');
+
+const AGENTS = {
+  'claude-code': require('../agents/claude-code'),
+  'codex': require('../agents/codex'),
+  'gemini': require('../agents/gemini'),
+};
+
+module.exports = async function uninstall(opts = {}) {
+  ui.banner();
+
+  const targetAgent = opts.agent || null;
+
+  ui.section('Removing M0² from agents…\n');
+
+  for (const [name, agent] of Object.entries(AGENTS)) {
+    if (targetAgent && name !== targetAgent) continue;
+
+    ui.agentLine(name, 'installing');
+    try {
+      const result = agent.uninstall();
+      if (result.ok) {
+        ui.agentLine(name, 'done');
+      } else {
+        ui.agentLine(name, 'error', result.error || 'unknown');
+      }
+    } catch (e) {
+      ui.agentLine(name, 'error', e.message);
+    }
+  }
+
+  // Remove install directory only if uninstalling all
+  if (!targetAgent) {
+    const installDir = getInstallDir();
+    if (fs.existsSync(installDir)) {
+      fs.rmSync(installDir, { recursive: true, force: true });
+    }
+  }
+
+  console.log();
+  ui.success('M0² uninstalled.');
+  console.log();
+};

package/src/commands/update.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ui = require('../ui');
+const { getInstallDir } = require('../detect');
+
+module.exports = async function update() {
+  ui.banner();
+  ui.section('Updating M0²…\n');
+
+  const installDir = getInstallDir();
+
+  if (!fs.existsSync(installDir)) {
+    ui.error('M0² is not installed. Run "npx m0squared install" first.');
+    return;
+  }
+
+  // Copy fresh indicator.py
+  try {
+    const src = path.join(__dirname, '../../core/indicator.py');
+    const dst = path.join(installDir, 'indicator.py');
+    fs.copyFileSync(src, dst);
+    fs.chmodSync(dst, '755');
+
+    // Copy hook scripts
+    for (const hookFile of ['codex-hook.py', 'gemini-hook.py']) {
+      const hookSrc = path.join(__dirname, '../../core/hooks', hookFile);
+      const hookDst = path.join(installDir, 'hooks', hookFile);
+      if (fs.existsSync(hookSrc)) {
+        fs.mkdirSync(path.dirname(hookDst), { recursive: true });
+        fs.copyFileSync(hookSrc, hookDst);
+        fs.chmodSync(hookDst, '755');
+      }
+    }
+
+    ui.success('M0² updated to the latest version.');
+    ui.tip('Restart your AI agents to apply the update.');
+    console.log();
+  } catch (e) {
+    ui.error(`Update failed: ${e.message}`);
+  }
+};

package/src/detect.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const HOME = os.homedir();
+
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectClaudeCode() {
+  const hasDir = fs.existsSync(path.join(HOME, '.claude'));
+  const hasCmd = commandExists('claude');
+  return hasDir || hasCmd;
+}
+
+function detectCodex() {
+  const hasDir = fs.existsSync(path.join(HOME, '.codex'));
+  const hasCmd = commandExists('codex');
+  return hasDir || hasCmd;
+}
+
+function detectGemini() {
+  const hasDir = fs.existsSync(path.join(HOME, '.gemini'));
+  const hasCmd = commandExists('gemini');
+  return hasDir || hasCmd;
+}
+
+function detectAll() {
+  return {
+    'claude-code': detectClaudeCode(),
+    'codex': detectCodex(),
+    'gemini': detectGemini(),
+  };
+}
+
+function getInstallDir() {
+  return path.join(HOME, '.m0squared');
+}
+
+module.exports = { detectAll, detectClaudeCode, detectCodex, detectGemini, getInstallDir };

package/src/ui.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const R = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const WHITE = '\x1b[37m';
+
+const AGENT_COLORS = {
+  'claude-code': CYAN,
+  'codex': '\x1b[35m',   // magenta
+  'gemini': '\x1b[34m',  // blue
+};
+
+function banner() {
+  console.log(`
+${BOLD}${WHITE}  ███╗   ███╗ ██████╗²${R}
+${BOLD}${WHITE}  ████╗ ████║██╔═══██╗${R}
+${BOLD}${WHITE}  ██╔████╔██║██║   ██║${R}  ${DIM}Universal AI Agent HUD${R}
+${BOLD}${WHITE}  ██║╚██╔╝██║╚██████╔╝${R}  ${DIM}v1.0.0  by morius${R}
+${BOLD}${WHITE}  ╚═╝  ╚═╝  ╚═════╝${R}
+`);
+}
+
+function section(text) {
+  console.log(`  ${DIM}${text}${R}`);
+}
+
+function agentLine(name, status, detail = '') {
+  const c = AGENT_COLORS[name] || WHITE;
+  const label = name.padEnd(14);
+  if (status === 'found') {
+    console.log(`  ${GREEN}✓${R}  ${BOLD}${c}${label}${R}  ${DIM}detected${R}  ${detail}`);
+  } else if (status === 'missing') {
+    console.log(`  ${DIM}✗  ${label}  not found${R}`);
+  } else if (status === 'installing') {
+    process.stdout.write(`  ${YELLOW}→${R}  ${BOLD}${c}${label}${R}  `);
+  } else if (status === 'done') {
+    console.log(`${GREEN}done${R}`);
+  } else if (status === 'error') {
+    console.log(`${RED}failed — ${detail}${R}`);
+  } else if (status === 'skip') {
+    console.log(`  ${DIM}⊘  ${label}  already installed${R}`);
+  }
+}
+
+function success(text) {
+  console.log(`\n  ${GREEN}${BOLD}✓${R}  ${text}\n`);
+}
+
+function error(text) {
+  console.log(`\n  ${RED}${BOLD}✗${R}  ${text}\n`);
+}
+
+function info(text) {
+  console.log(`  ${CYAN}i${R}  ${text}`);
+}
+
+function tip(text) {
+  console.log(`  ${DIM}${text}${R}`);
+}
+
+function showHelp() {
+  banner();
+  console.log(`  ${BOLD}Usage:${R}  npx m0squared <command>\n`);
+  console.log(`  ${BOLD}Commands:${R}`);
+  console.log(`    ${CYAN}install${R}     Install M0² for all detected AI agents`);
+  console.log(`    ${CYAN}uninstall${R}   Remove M0² from all agents`);
+  console.log(`    ${CYAN}update${R}      Update to the latest version`);
+  console.log(`    ${CYAN}status${R}      Show current token usage in terminal`);
+  console.log(`    ${CYAN}agents${R}      List supported agents and their status`);
+  console.log(`\n  ${BOLD}Options:${R}`);
+  console.log(`    ${CYAN}--agent${R}     Target a specific agent (claude-code, codex, gemini)`);
+  console.log(`\n  ${DIM}Examples:${R}`);
+  console.log(`    npx m0squared install`);
+  console.log(`    npx m0squared install --agent claude-code`);
+  console.log(`    npx m0squared status\n`);
+}
+
+module.exports = { banner, section, agentLine, success, error, info, tip, showHelp, BOLD, DIM, GREEN, CYAN, YELLOW, RED, R };