clario-agent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# clario-agent: show your AI agent's activity in Clario 🧑‍🍳
 
-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.
+A Claude Code hook that shows what your agent is working on to everyone in your current
+Clario space. Others see a pulsing badge above your avatar while the agent works, and
+clicking your avatar shows your agent card: what Claude is doing plus the project, branch
+and commit (e.g. `graphite · feat/missions · a1b2c3d`). The badge clears when Claude finishes.
+
+## Setup (one command)
+
+Make an account at [clario.games](https://www.clario.games) first, then run this inside the
+project you want to share:
+
+```bash
+npx clario-agent setup
+```
+
+It does three things:
+
+1. **Saves an agent key** in `~/.clario/agent.json` (readable only by you). It asks for your
+   Clario email and password once (sent only to the Clario server). The key lasts 180 days and
+   can only post agent activity: it can't sign in, open a space or change anything else.
+2. **Installs the hook** at `~/.clario/hook.mjs`.
+3. **Registers it with Claude Code** for this project only, in `.claude/settings.local.json`.
+   Add `--global` to use it in every project (`~/.claude/settings.json`) instead.
+
+Then open your Clario space, give Claude a task in that project, and click your avatar.
+Teammates who do the same and join your space show up on their avatars too.
+
+It uses the live server at `https://api.clario.games`. Running Clario yourself? Add
+`--api-url http://localhost:3001` (or your own server's address); setup remembers it.
+
+Running `setup` again keeps a key that still has more than 14 days left, updates the hook
+and never registers it twice. Your other Claude Code settings and hooks are left as they
+are, and the previous file is saved next to it as `*.clario-backup`.
+
+```bash
+npx clario-agent status      # server, key expiry, where the hook is registered
+npx clario-agent uninstall   # remove the hook from this project (add --global for all)
+```
+
+Used the older `viora-agent` package? Run `setup` once: it reuses the key from `~/.viora` and
+replaces the old hook, so it never runs twice. You can delete `~/.viora` afterwards.
+
+From a checkout of this repo, `node tools/agent-hook/setup.mjs` does the same as `setup`.
+For scripts, `CLARIO_EMAIL` and `CLARIO_PASSWORD` are read instead of prompting.
+
+<details>
+<summary>Manual alternative: a 7-day login token</summary>
+
+Sign in, open DevTools → Console on your Clario site and run
+`copy(localStorage.getItem("metaverse:token"))`, then save it as `"token"` in
+`~/.clario/agent.json` next to `"apiUrl"`. It expires after 7 days. If you then run
+`setup`, it uses that token to create the agent key without asking for your password.
+</details>
+
+> An agent key can't be cancelled on its own before it expires. If one leaks, delete it
+> from `~/.clario/agent.json` and change the server's `JWT_SECRET` (this signs everyone out).
+> The server needs the `/api/v1/agent-key` endpoint from this repo's `apps/server`.
+
+## How it behaves
+
+- While Claude runs tools (edits, bash commands…) your badge shows "cooking" with a short
+  description of the current tool (e.g. `Claude is using Edit page.tsx` or
+  `Claude is using Bash $ bun, git`)
+- Your agent card also shows the project folder, git branch and short commit the agent is
+  working in
+- When Claude finishes, the badge clears automatically
+- If you're not inside a Clario space, updates are silently dropped
+- Updates are throttled (2s) so fast tool bursts don't spam the room
+- The hook never blocks or fails your agent session: all errors are swallowed
+
+## Privacy notes
+
+Everyone in your space sees what is sent. That is the tool name, the edited file's name,
+the names of the programs a shell command runs (`bun`, `git`; never its arguments, which
+can hold tokens or paths), and the project folder, branch and short commit. Never file
+contents, prompts or code.
+
+To keep project, branch and commit on your machine, add `"shareGit": false` to
+`~/.clario/agent.json` (or set `CLARIO_SHARE_GIT=0`). Run `npx clario-agent uninstall` to stop
+broadcasting from a project.
+
+Requires Node.js 18 or newer. MIT licensed.

package/clario-agent-hook.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * Clario agent hook for Claude Code
+ *
+ * Broadcasts what your AI agent is doing to everyone in your current Clario space.
+ * Setup guide: tools/agent-hook/README.md
+ *
+ * Reads Claude Code hook events from stdin and POSTs activity to
+ * POST /api/v1/agent-activity on your Clario server. Exits 0 silently on any
+ * failure so it never blocks your agent session.
+ *
+ * Sent: a short status line (tool name, edited file name, or the programs a shell
+ * command runs, never its arguments) plus the project folder, git branch and short
+ * commit. `"shareGit": false` in ~/.clario/agent.json (or CLARIO_SHARE_GIT=0) keeps
+ * project, branch and commit on this machine.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+const CONFIG_PATH = join(homedir(), ".clario", "agent.json");
+const THROTTLE_MS = 2000;
+const STATE_PATH = join(homedir(), ".clario", ".agent-hook-state");
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let raw = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (raw += chunk));
+    process.stdin.on("end", () => resolve(raw));
+    setTimeout(() => resolve(raw), 1500);
+  });
+}
+
+function loadConfig() {
+  try {
+    const config = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    // agentKey (setup.mjs, lasts 180 days) wins over a pasted 7-day login token.
+    const credential = config?.agentKey || config?.token;
+    if (credential && config?.apiUrl) return { ...config, credential };
+  } catch {
+  }
+  return null;
+}
+
+function lastSentAt() {
+  try {
+    return Number(readFileSync(STATE_PATH, "utf8")) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+// Git: project, branch and commit, read from .git directly (no git CLI).
+
+/** Walk up from `start` to the first directory containing `.git` (a dir, or a file for worktrees). */
+function findGitRoot(start) {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** The repository's git dir. Throws if `.git` is missing or unreadable. */
+function gitDirOf(gitRoot) {
+  const gitDir = join(gitRoot, ".git");
+  if (!statSync(gitDir).isFile()) return gitDir;
+  // Worktrees and submodules: ".git" is a file containing "gitdir: <path>".
+  const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(gitDir, "utf8"));
+  return m ? resolve(gitRoot, m[1].trim()) : undefined;
+}
+
+/** A full commit id: 40 hex characters, or 64 in SHA-256 repositories. */
+const COMMIT_RE = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
+
+/** Branch and commit from HEAD. A detached HEAD has no branch; a repo with no commits has no commit. */
+function readHead(gitRoot) {
+  let gitDir;
+  let head;
+  try {
+    gitDir = gitDirOf(gitRoot);
+    head = gitDir && readFileSync(join(gitDir, "HEAD"), "utf8").trim();
+  } catch {
+    return {};
+  }
+  if (!head) return {};
+  if (COMMIT_RE.test(head)) return { commit: head };
+  const ref = /^ref:\s*(refs\/heads\/(.+))$/.exec(head);
+  return ref ? { branch: ref[2], commit: readRef(gitDir, ref[1]) } : {};
+}
+
+/** A branch's commit: loose ref first, then packed-refs. Linked worktrees keep both in the main git dir. */
+function readRef(gitDir, name) {
+  let commonDir = gitDir;
+  try {
+    commonDir = resolve(gitDir, readFileSync(join(gitDir, "commondir"), "utf8").trim());
+  } catch {
+    // Not a linked worktree.
+  }
+  let id;
+  try {
+    id = readFileSync(join(commonDir, name), "utf8").trim();
+  } catch {
+    try {
+      for (const line of readFileSync(join(commonDir, "packed-refs"), "utf8").split("\n")) {
+        const [sha, ref] = line.trim().split(" ");
+        if (ref === name) id = sha;
+      }
+    } catch {
+      // No packed-refs either: a repo with no commits yet.
+    }
+  }
+  return id && COMMIT_RE.test(id) ? id : undefined;
+}
+
+/** Project folder, branch and short commit for the agent card; nothing when sharing is off. */
+function gitInfo(event, config) {
+  const env = process.env.CLARIO_SHARE_GIT;
+  if (env !== undefined ? env === "0" : config.shareGit === false) return {};
+  const cwd = typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
+  const root = findGitRoot(cwd);
+  if (!root) return { project: basename(resolve(cwd)) };
+  const { branch, commit } = readHead(root);
+  return { project: basename(root), branch, commit: commit?.slice(0, 7) };
+}
+
+const WRAPPERS = new Set(["sudo", "env", "time", "nohup", "exec", "command"]);
+const NOT_PROGRAMS = new Set(["cd", "export", "source", ".", "set", "unset"]);
+
+/**
+ * The programs a shell command runs ("bun", "git"), never its arguments: those can
+ * hold tokens, passwords or private paths, and the status is shown to the whole space.
+ */
+function programNames(command) {
+  const names = [];
+  // First line only (skips heredoc bodies), and quoted strings removed, so a `;` or `|`
+  // inside quotes can't turn quoted text into a "program".
+  const line = command.split("\n")[0].replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "''");
+  for (const segment of line.split(/&&|\|\||[;|]/)) {
+    const words = segment.trim().split(/\s+/);
+    let i = 0;
+    // Skip leading VAR=value, wrappers like sudo/env and their flags.
+    while (i < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || WRAPPERS.has(words[i]) || words[i].startsWith("-"))) i++;
+    if (!words[i] || NOT_PROGRAMS.has(words[i])) continue;
+    const name = basename(words[i]);
+    if (/^[A-Za-z0-9_.][A-Za-z0-9._+-]{0,23}$/.test(name) && !names.includes(name)) names.push(name);
+  }
+  return names.slice(0, 3);
+}
+
+function describe(event) {
+  const tool = typeof event.tool_name === "string" ? event.tool_name : "";
+  if (event.hook_event_name === "Stop") return { state: "done", text: "" };
+  if (event.hook_event_name === "SessionEnd") return { state: "done", text: "" };
+
+  const toolLabel = tool.replace(/^(mcp__|LambdaResponse)/, "").slice(0, 40);
+  let detail = "";
+  if (tool === "Edit" || tool === "Write" || tool === "MultiEdit") {
+    const filePath = event?.tool_input?.file_path;
+    if (typeof filePath === "string") {
+      const parts = filePath.split("/");
+      detail = ` ${parts[parts.length - 1]}`;
+    }
+  }
+  if (tool === "Bash" && typeof event?.tool_input?.command === "string") {
+    const names = programNames(event.tool_input.command);
+    if (names.length) detail = ` $ ${names.join(", ")}`;
+  }
+  return { state: "cooking", text: `Claude is using ${toolLabel || "a tool"}${detail}` };
+}
+
+async function main() {
+  const config = loadConfig();
+  if (!config) process.exit(0);
+
+  const raw = await readStdin();
+  if (!raw.trim()) process.exit(0);
+
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const { state, text } = describe(event);
+  if (state === "cooking" && !text) process.exit(0);
+
+  // Client-side throttle: hook events fire per tool use and can be chatty.
+  const now = Date.now();
+  if (state === "cooking" && now - lastSentAt() < THROTTLE_MS) process.exit(0);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 2500);
+
+  try {
+    await fetch(`${config.apiUrl.replace(/\/$/, "")}/api/v1/agent-activity`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.credential}`,
+      },
+      body: JSON.stringify(state === "cooking" ? { text, state, ...gitInfo(event, config) } : { text, state }),
+      signal: controller.signal,
+    });
+    if (state === "cooking") {
+      const { writeFileSync, mkdirSync } = await import("node:fs");
+      try {
+        mkdirSync(join(homedir(), ".clario"), { recursive: true });
+        writeFileSync(STATE_PATH, String(now));
+      } catch {
+      }
+    }
+  } catch {
+    // Never let analytics failures disturb the agent session.
+  } finally {
+    clearTimeout(timer);
+  }
+
+  process.exit(0);
+}
+
+main();

package/cli.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * clario-agent: show what your Claude Code agent is doing on your Clario avatar.
+ *
+ *   npx clario-agent setup [--api-url URL] [--global]   agent key + hook, once
+ *   npx clario-agent status                              what is set up
+ *   npx clario-agent uninstall [--global]                remove the hook
+ *
+ * setup saves a 180-day agent key in ~/.clario/agent.json (it can only post agent
+ * activity), copies the hook to ~/.clario/hook.mjs and registers it in this project's
+ * .claude/settings.local.json, or in ~/.claude/settings.json with --global.
+ */
+
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const DIR = join(homedir(), ".clario");
+const CONFIG_PATH = join(DIR, "agent.json");
+const HOOK_PATH = join(DIR, "hook.mjs");
+const HOOK_SOURCE = join(dirname(fileURLToPath(import.meta.url)), "clario-agent-hook.mjs");
+// Where this package kept its key before it was renamed: setup reuses that key instead of asking again.
+const OLD_CONFIG_PATH = join(homedir(), ".viora", "agent.json");
+// The live Clario server; pass --api-url http://localhost:3001 for a local one.
+const DEFAULT_API_URL = "https://api.clario.games";
+const HOOK_EVENTS = ["PreToolUse", "PostToolUse", "Stop", "SessionEnd"];
+const RENEW_DAYS = 14; // setup makes a new key when the saved one has less time left than this
+
+class CliError extends Error {}
+const fail = (message) => {
+  throw new CliError(message);
+};
+
+/** { value } for a JSON file, {} when it doesn't exist; fails on invalid JSON instead of overwriting it. */
+function readJson(file) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return {};
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch {
+    fail(`${file} is not valid JSON. Fix or remove it, then run this again.`);
+  }
+}
+
+function writeJson(file, value, { mode } = {}) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, mode ? { mode } : {});
+  renameSync(tmp, file);
+  if (mode) chmodSync(file, mode);
+}
+
+/** Days until a JWT expires, or null when it can't be read. */
+function daysLeft(token) {
+  try {
+    const { exp } = JSON.parse(Buffer.from(String(token).split(".")[1], "base64url").toString());
+    return typeof exp === "number" ? (exp * 1000 - Date.now()) / 86_400_000 : null;
+  } catch {
+    return null;
+  }
+}
+
+async function post(apiUrl, path, body, token) {
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/api/v1${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify(body),
+    });
+  } catch {
+    fail(`Can't reach the Clario server at ${apiUrl}. Start it, or pass --api-url, then run this again.`);
+  }
+  return { status: res.status, json: await res.json().catch(() => null) };
+}
+
+/** Email and password from the terminal (the password isn't echoed), or CLARIO_EMAIL / CLARIO_PASSWORD. */
+async function askCredentials() {
+  if (process.env.CLARIO_EMAIL && process.env.CLARIO_PASSWORD) {
+    return { email: process.env.CLARIO_EMAIL, password: process.env.CLARIO_PASSWORD };
+  }
+  if (!process.stdin.isTTY) fail("No terminal to ask for your email and password; set CLARIO_EMAIL and CLARIO_PASSWORD.");
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  const ask = (text) => new Promise((resolve) => rl.question(text, resolve));
+  const email = (await ask("Clario email: ")).trim();
+  const answer = ask("Password: ");
+  const write = rl._writeToOutput;
+  rl._writeToOutput = () => {}; // hide the password as it's typed
+  const password = await answer;
+  rl._writeToOutput = write;
+  rl.close();
+  process.stdout.write("\n");
+  return { email, password };
+}
+
+/** A usable agent key: the saved one if it has time left, else a new one from the server. */
+async function ensureAgentKey(config, apiUrl) {
+  const left = daysLeft(config.agentKey);
+  if (config.agentKey && config.apiUrl === apiUrl && left !== null && left > RENEW_DAYS) {
+    return { key: config.agentKey, days: left, reused: true };
+  }
+  // A login token from the manual setup (README) is enough to create the key.
+  let res = config.token ? await post(apiUrl, "/agent-key", {}, config.token) : null;
+  if (!res || res.status !== 200) {
+    if (res?.status !== 404) {
+      const { email, password } = await askCredentials();
+      const signin = await post(apiUrl, "/signin", { email, password });
+      if (!signin.json?.token) fail("Sign-in failed. Check your email and password.");
+      res = await post(apiUrl, "/agent-key", {}, signin.json.token);
+    }
+  }
+  if (res.status === 404) fail(`The server at ${apiUrl} has no /api/v1/agent-key yet. Restart it so it runs the latest code.`);
+  if (res.status !== 200 || !res.json?.key) fail(`Could not create an agent key (HTTP ${res.status}).`);
+  return { key: res.json.key, days: daysLeft(res.json.key), reused: false };
+}
+
+// ---- Claude Code settings -------------------------------------------------------
+
+const settingsFile = (global) =>
+  global ? join(homedir(), ".claude", "settings.json") : join(process.cwd(), ".claude", "settings.local.json");
+
+/** Our hooks from any version (also from before the rename): this package's copy, or the repo script. */
+const isOurHook = (hook) =>
+  typeof hook?.command === "string" && /(clario|viora)-agent-hook\.mjs|[\\/]\.(clario|viora)[\\/]hook\.mjs/.test(hook.command);
+
+/** Settings with every one of our hooks removed; other hooks and settings are left exactly as they were. */
+function withoutOurHooks(settings) {
+  if (!settings.hooks || typeof settings.hooks !== "object") return settings;
+  const hooks = {};
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(groups)) {
+      hooks[event] = groups;
+      continue;
+    }
+    const kept = groups
+      .map((group) => (Array.isArray(group?.hooks) ? { ...group, hooks: group.hooks.filter((h) => !isOurHook(h)) } : group))
+      .filter((group) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+    if (kept.length) hooks[event] = kept;
+  }
+  const { hooks: _old, ...rest } = settings;
+  return Object.keys(hooks).length ? { ...rest, hooks } : rest;
+}
+
+const countOurHooks = (settings) =>
+  Object.values(settings?.hooks ?? {}).flat().flatMap((group) => group?.hooks ?? []).filter(isOurHook).length;
+
+/** Add the hook for every event, replacing older entries of ours so it never fires twice. */
+function registerHooks(file) {
+  const { value = {} } = readJson(file);
+  if (existsSync(file)) copyFileSync(file, `${file}.clario-backup`);
+  const settings = withoutOurHooks(value);
+  const hooks = { ...(settings.hooks ?? {}) };
+  const command = `node "${HOOK_PATH}"`;
+  for (const event of HOOK_EVENTS) hooks[event] = [...(hooks[event] ?? []), { hooks: [{ type: "command", command, timeout: 10 }] }];
+  writeJson(file, { ...settings, hooks });
+}
+
+function gitIgnored(file) {
+  try {
+    execFileSync("git", ["check-ignore", "-q", file], { cwd: dirname(file), stdio: "ignore" });
+    return true;
+  } catch (e) {
+    return e.status === 1 ? false : null; // 1: tracked-able; anything else: not a git repo
+  }
+}
+
+// ---- Commands -----------------------------------------------------------------------
+
+async function setup(opts) {
+  const { value: config = readJson(OLD_CONFIG_PATH).value ?? {} } = readJson(CONFIG_PATH);
+  const apiUrl = String(opts.apiUrl || config.apiUrl || DEFAULT_API_URL).replace(/\/+$/, "");
+  const { key, days, reused } = await ensureAgentKey(config, apiUrl);
+
+  // The 7-day login token isn't needed any more; everything else (shareGit…) stays.
+  const { token: _loginToken, ...rest } = config;
+  writeJson(CONFIG_PATH, { ...rest, apiUrl, agentKey: key }, { mode: 0o600 });
+  mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  copyFileSync(HOOK_SOURCE, HOOK_PATH);
+
+  const file = settingsFile(opts.global);
+  registerHooks(file);
+
+  const until = new Date(Date.now() + days * 86_400_000).toDateString();
+  console.log(`${reused ? "Kept your agent key" : "Saved a new agent key"} in ${CONFIG_PATH} (works until ${until}).`);
+  console.log(`Hook registered in ${file}${opts.global ? " for every project" : " for this project only"}.`);
+  if (!opts.global && gitIgnored(file) === false) {
+    console.log("Note: .claude/settings.local.json isn't git-ignored here. It holds no secrets, but you may want to ignore it.");
+  }
+  console.log("Open your Clario space and give Claude a task: your avatar's card shows what it's doing.");
+}
+
+function status() {
+  const { value: config = {} } = readJson(CONFIG_PATH);
+  const left = daysLeft(config.agentKey ?? config.token);
+  console.log(`Server:  ${config.apiUrl ?? "not set"}`);
+  console.log(
+    config.agentKey || config.token
+      ? `Key:     ${config.agentKey ? "agent key" : "7-day login token"}, ${left === null ? "unreadable" : left > 0 ? `${Math.floor(left)} days left` : "EXPIRED (run setup)"}`
+      : "Key:     none (run setup)",
+  );
+  console.log(`Hook:    ${existsSync(HOOK_PATH) ? HOOK_PATH : "not installed (run setup)"}`);
+  for (const global of [false, true]) {
+    const file = settingsFile(global);
+    const n = countOurHooks(readJson(file).value);
+    console.log(`${global ? "All projects" : "This project"}: ${n ? `registered (${file})` : "not registered"}`);
+  }
+}
+
+function uninstall(opts) {
+  const file = settingsFile(opts.global);
+  const { value } = readJson(file);
+  if (!value || !countOurHooks(value)) {
+    console.log(`No Clario hook in ${file}.`);
+    return;
+  }
+  copyFileSync(file, `${file}.clario-backup`);
+  writeJson(file, withoutOurHooks(value));
+  console.log(`Removed the Clario hook from ${file}. Your key stays in ${CONFIG_PATH}; delete that file to remove it too.`);
+}
+
+const HELP = `clario-agent: show what your Claude Code agent is doing on your Clario avatar
+
+  clario-agent setup [--api-url URL] [--global]   save an agent key and register the hook
+  clario-agent status                              show what is set up
+  clario-agent uninstall [--global]                remove the hook
+
+Without --global the hook is registered only for the project you run it in.
+--api-url defaults to the saved server, then ${DEFAULT_API_URL}.`;
+
+export async function run(argv) {
+  const [command = "help", ...rest] = argv;
+  const i = rest.indexOf("--api-url");
+  const opts = { global: rest.includes("--global"), apiUrl: i > -1 ? rest[i + 1] : undefined };
+  try {
+    if (command === "setup") await setup(opts);
+    else if (command === "status") status();
+    else if (command === "uninstall") uninstall(opts);
+    else console.log(HELP);
+  } catch (e) {
+    if (!(e instanceof CliError)) throw e;
+    console.error(e.message);
+    process.exitCode = 1;
+  }
+}
+
+// Run when called as a command (npm links the bin, so compare real paths).
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  run(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "clario-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Show what your Claude Code agent is doing (project, branch, commit) on your Clario avatar.",
+  "type": "module",
+  "bin": {
+    "clario-agent": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "setup.mjs",
+    "clario-agent-hook.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "clario",
+    "claude-code",
+    "hooks",
+    "agent",
+    "metaverse"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Deepak-negi11/graphite-hacks.git",
+    "directory": "tools/agent-hook"
+  },
+  "license": "MIT"
+}

package/setup.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Same as `clario-agent setup` (see cli.mjs), for running straight from this repo:
+//   node tools/agent-hook/setup.mjs [--api-url http://localhost:3001] [--global]
+import { run } from "./cli.mjs";
+
+run(["setup", ...process.argv.slice(2)]);