cloud-usage-token 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Guilarte
+
+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

@@ -0,0 +1,103 @@
+# cloud-usage-token
+
+Monitor your **Claude Code** and **OpenAI Codex CLI** usage **live** — sessions, limits, costs, and the status of each agent — from the [CloudUsage](https://cloudusage.space) dashboard, across all your machines.
+
+> **Your code stays on your machine.** What the agent sends is session metadata: usage (tokens, costs), quotas, and live status — including a short preview of the last assistant message and a label of the current activity (e.g. the file or command being worked on). Absolute paths, environment variables, tokens/secrets, and emails are **redacted before sending**. Your full file contents and full prompts are never transmitted.
+
+## Requirements
+
+- **Node.js 20 or newer** (`node --version`).
+- A free account at [cloudusage.space](https://cloudusage.space).
+
+## Installation
+
+```bash
+npm install -g cloud-usage-token
+```
+
+## Getting started (3 steps)
+
+**1. Create your account and a device**
+
+Go to [cloudusage.space](https://cloudusage.space), sign up, then open **Settings → API & devices → Create device**. Copy the **API key** (`cut_agent_...`) — it's shown only once.
+
+**2. Connect the agent**
+
+```bash
+cloud-usage-token connect --api-key=cut_agent_YOUR_KEY
+```
+
+> Prefer not to leave the key in your shell history? Pipe it (`echo cut_agent_YOUR_KEY | cloud-usage-token connect`) or set `CLOUD_USAGE_DEVICE_API_KEY`.
+
+**3. Run it in the background**
+
+```bash
+cloud-usage-token start
+```
+
+Done. It starts automatically at login and restarts if it crashes. Within a few seconds your device shows up **online** in the dashboard, with your usage and sessions live.
+
+## Live status (optional but recommended)
+
+For the dashboard to show the **session traffic light** accurately (🟢 working · 🔴 your turn · 🔴 waiting for your approval), install the hooks:
+
+```bash
+cloud-usage-token install-hooks           # for Claude Code
+cloud-usage-token install-hooks --codex   # for OpenAI Codex
+```
+
+Hooks are added **non-destructively** (your existing hooks/config are preserved) and can be removed anytime. With Codex, the first time the CLI will ask you to **trust** the hook — approve it.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `cloud-usage-token connect --api-key=cut_agent_xxx` | Configure the device (saves the key to `~/.cloud-usage/config.json`). |
+| `cloud-usage-token start` | Run the agent in the background + autostart at login. |
+| `cloud-usage-token status` | Show configuration and service status. |
+| `cloud-usage-token stop` | Stop and remove the service. |
+| `cloud-usage-token install-hooks` | Install the live-status hooks for **Claude Code**. |
+| `cloud-usage-token install-hooks --codex` | Install the hooks for **OpenAI Codex**. |
+| `cloud-usage-token uninstall-hooks` | Remove the Claude hooks (`--codex` for Codex). |
+| `cloud-usage-token help` | Show help. |
+
+### `install-hooks` options (Claude)
+
+By default it installs the hooks at the user level (global). You can scope it:
+
+```bash
+cloud-usage-token install-hooks --global              # ~/.claude/settings.json (default)
+cloud-usage-token install-hooks --project             # ./.claude/settings.json (this project)
+cloud-usage-token install-hooks --settings <path>     # a specific settings.json
+```
+
+## What it monitors
+
+- **Usage & costs**: tokens and cost per day, trend, per-model breakdown.
+- **Limits / plan**: quota bars (session, weekly, per model).
+- **Live sessions**: which agents are working, which need your response, activity and context.
+
+All of this is computed **locally** on your machine. What travels to the server is metadata — numbers, statuses, and short redacted previews — not your files or full prompts.
+
+## Uninstall
+
+```bash
+cloud-usage-token stop                 # stop the service
+cloud-usage-token uninstall-hooks      # remove Claude hooks
+cloud-usage-token uninstall-hooks --codex
+npm uninstall -g cloud-usage-token     # remove the CLI
+```
+
+Local config lives in `~/.cloud-usage/config.json` (you can delete it by hand).
+
+## Troubleshooting
+
+- **Not showing online in the dashboard**: make sure you ran `connect` with the right key and then `start`. Check with `cloud-usage-token status`.
+- **Device was revoked**: if you rotated or deleted the API key in the dashboard, create a new device and run `connect` with the new key.
+- **Codex hooks don't fire**: Codex only runs trusted hooks — the first time, in the interactive TUI, approve the hook when prompted.
+- **Connecting to your own server** (self-host): pass your endpoint with `connect --api-key=... --realtime-url=wss://your-domain/agent`.
+
+## Links
+
+- Dashboard: [cloudusage.space](https://cloudusage.space)
+- Development / contributing: see [DEVELOPMENT.md](https://github.com/cguilarte/cloud-usage-agent/blob/main/docs/DEVELOPMENT.md)

package/dist/codex-hook-bridge.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+// src/codex-hook-bridge.ts
+import http from "http";
+
+// src/cli.ts
+import { promises as fs } from "fs";
+import { homedir } from "os";
+import path from "path";
+var CONFIG_DIR_NAME = ".cloud-usage";
+var HOOKS_PORT_FILE_NAME = "hooks-port";
+function hooksPortFilePath(home = homedir()) {
+  return path.join(home, CONFIG_DIR_NAME, HOOKS_PORT_FILE_NAME);
+}
+async function readHooksPort(home = homedir()) {
+  try {
+    const port = Number((await fs.readFile(hooksPortFilePath(home), "utf8")).trim());
+    return Number.isInteger(port) && port > 0 ? port : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/codex-hook-bridge-core.ts
+function asRecord(value) {
+  return value !== null && typeof value === "object" ? value : {};
+}
+function mapCodexHookToHint(payload, at) {
+  const p = asRecord(payload);
+  const sessionId = typeof p.session_id === "string" ? p.session_id : void 0;
+  if (!sessionId) return null;
+  const event = typeof p.hook_event_name === "string" ? p.hook_event_name : "";
+  switch (event) {
+    case "PermissionRequest":
+      return { sessionId, kind: "permission", at };
+    case "Stop":
+    case "SessionStart":
+      return { sessionId, kind: "activity", at };
+    default:
+      return null;
+  }
+}
+
+// src/codex-hook-bridge.ts
+var MAX_STDIN_BYTES = 64 * 1024;
+var POST_TIMEOUT_MS = 200;
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    let size = 0;
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size <= MAX_STDIN_BYTES) data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
+function post(port, body) {
+  return new Promise((resolve) => {
+    const data = JSON.stringify(body);
+    const request = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: "/hooks/codex",
+        method: "POST",
+        headers: { "content-type": "application/json", "content-length": Buffer.byteLength(data) },
+        timeout: POST_TIMEOUT_MS
+      },
+      () => resolve()
+    );
+    request.on("error", () => resolve());
+    request.on("timeout", () => {
+      request.destroy();
+      resolve();
+    });
+    request.end(data);
+  });
+}
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    return;
+  }
+  const body = mapCodexHookToHint(payload, (/* @__PURE__ */ new Date()).toISOString());
+  if (!body) return;
+  const port = await readHooksPort();
+  if (port) await post(port, body);
+}
+void main().finally(() => process.exit(0));

package/dist/hook-bridge.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+// src/hook-bridge.ts
+import http from "http";
+
+// src/cli.ts
+import { promises as fs } from "fs";
+import { homedir } from "os";
+import path from "path";
+var CONFIG_DIR_NAME = ".cloud-usage";
+var HOOKS_PORT_FILE_NAME = "hooks-port";
+function hooksPortFilePath(home = homedir()) {
+  return path.join(home, CONFIG_DIR_NAME, HOOKS_PORT_FILE_NAME);
+}
+async function readHooksPort(home = homedir()) {
+  try {
+    const port = Number((await fs.readFile(hooksPortFilePath(home), "utf8")).trim());
+    return Number.isInteger(port) && port > 0 ? port : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/hook-bridge-core.ts
+var TOOL_CATEGORY = {
+  Read: "read",
+  Glob: "search",
+  Grep: "search",
+  Bash: "run",
+  Edit: "write",
+  Write: "write",
+  MultiEdit: "write",
+  NotebookEdit: "write",
+  WebFetch: "web",
+  WebSearch: "web",
+  Task: "task"
+};
+function toolCategoryOf(toolName) {
+  return typeof toolName === "string" ? TOOL_CATEGORY[toolName] : void 0;
+}
+function classifyRisk(command) {
+  if (typeof command !== "string") return void 0;
+  const c = command.toLowerCase();
+  if (/\bgit\s+push\b/.test(c) && /(--force|-f)\b/.test(c)) return "force-push";
+  if (/\bgit\s+(reset\s+--hard|rebase\b|filter-branch|commit\s+--amend)/.test(c)) return "history-rewrite";
+  if (/\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r|\brm\s+-r\b[^|;&]*-f|\brm\s+-f\b[^|;&]*-r/.test(c)) return "recursive-delete";
+  return void 0;
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" ? value : {};
+}
+function mapHookToHint(event, payload, at) {
+  const p = asRecord(payload);
+  const sessionId = typeof p.session_id === "string" ? p.session_id : void 0;
+  if (!sessionId) return null;
+  switch (event) {
+    case "Notification": {
+      const type = typeof p.notification_type === "string" ? p.notification_type.toLowerCase() : "";
+      const kind = type.includes("permission") ? "permission" : "input_required";
+      return { sessionId, kind, at };
+    }
+    case "PreToolUse": {
+      const command = asRecord(p.tool_input).command;
+      const risk = p.tool_name === "Bash" ? classifyRisk(command) : void 0;
+      if (risk) return { sessionId, kind: "risk", at, riskCategory: risk };
+      const toolCategory = toolCategoryOf(p.tool_name);
+      return { sessionId, kind: "activity", at, ...toolCategory ? { toolCategory } : {} };
+    }
+    case "PostToolUse": {
+      const toolCategory = toolCategoryOf(p.tool_name);
+      const durationMs = typeof p.duration_ms === "number" && Number.isFinite(p.duration_ms) ? p.duration_ms : void 0;
+      return {
+        sessionId,
+        kind: "activity",
+        at,
+        ...toolCategory ? { toolCategory } : {},
+        ...durationMs !== void 0 ? { durationMs } : {}
+      };
+    }
+    case "PreCompact":
+      return { sessionId, kind: "context_saturated", at };
+    default:
+      return null;
+  }
+}
+
+// src/hook-bridge.ts
+var MAX_STDIN_BYTES = 64 * 1024;
+var POST_TIMEOUT_MS = 200;
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    let size = 0;
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size <= MAX_STDIN_BYTES) data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
+function post(port, body) {
+  return new Promise((resolve) => {
+    const data = JSON.stringify(body);
+    const request = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: "/hooks/claude",
+        method: "POST",
+        headers: { "content-type": "application/json", "content-length": Buffer.byteLength(data) },
+        timeout: POST_TIMEOUT_MS
+      },
+      () => resolve()
+    );
+    request.on("error", () => resolve());
+    request.on("timeout", () => {
+      request.destroy();
+      resolve();
+    });
+    request.end(data);
+  });
+}
+async function main() {
+  const event = process.argv[2] ?? "";
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    return;
+  }
+  const body = mapHookToHint(event, payload, (/* @__PURE__ */ new Date()).toISOString());
+  if (!body) return;
+  const port = await readHooksPort();
+  if (port) await post(port, body);
+}
+void main().finally(() => process.exit(0));