clario-agent 0.1.0 → 0.3.0

package/README.md

@@ -1,70 +1,74 @@
 # clario-agent: show your AI agent's activity in Clario 🧑‍🍳
 
-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.
+A hook for **Claude Code, Codex and Cursor** that shows what your coding 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: which agent, what it's doing,
+and the project, branch and commit (e.g. `graphite · feat/missions · a1b2c3d`). The badge
+clears when the agent 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:
+1. Open your space on [clario.games](https://www.clario.games) and click **Agent** in the
+   left menu. Pick your agent; it shows your setup command, with your key in it:
+   ```bash
+   npx clario-agent setup --key YOUR_KEY                 # Claude Code
+   npx clario-agent setup --key YOUR_KEY --agent codex   # Codex
+   npx clario-agent setup --key YOUR_KEY --agent cursor  # Cursor
+   ```
+2. Copy it and run it in the terminal, inside the project you want to share.
+   `--agent all` sets up all three; `--agent codex,cursor` works too.
+
+That's it: the Agent button disappears once your agent has connected. Setup:
+
+- **Checks the key** with the Clario server and saves it in `~/.clario/agent.json` (readable
+  only by you). It's your own key and it stays the same: the Agent button always shows the
+  same command for you. It can only post agent activity: it can't sign in, open a space or
+  change anything else. No password is ever typed in the terminal.
+- **Installs the hook** at `~/.clario/hook.mjs`.
+- **Registers it with your agent:**
+
+  | Agent | Hook file | Shared from |
+  |---|---|---|
+  | Claude Code | `.claude/settings.local.json` in this project (`~/.claude/settings.json` with `--global`) | this project |
+  | Codex | `~/.codex/hooks.json` (or `$CODEX_HOME/hooks.json`) | the projects you ran setup in |
+  | Cursor | `~/.cursor/hooks.json` | the projects you ran setup in |
+
+  Codex and Cursor read one hook file for every project, so the hook itself only reports
+  from the projects you ran setup in; add `--global` to share from all of them.
+- **Codex** asks before it runs a new hook: open Codex, run `/hooks` and trust the Clario
+  hook. **Cursor**: restart it if it was open.
+
+Then give your agent a task in that project and click your avatar. Teammates who do the same
+and join your space show up on their avatars too.
+
+To add another project later, run `npx clario-agent setup --agent …` there: it reuses your
+saved key. Setup never registers the hook twice, leaves your other settings and hooks as they
+are, and saves the previous file next to it as `*.clario-backup`.
 
 ```bash
-npx clario-agent setup
+npx clario-agent status              # server, key, which agents are set up and where
+npx clario-agent uninstall           # stop sharing from this project, for every agent
+npx clario-agent uninstall --global  # remove every Clario hook and stop sharing everywhere
 ```
 
-It does three things:
+It uses the live server at `https://api.clario.games`. Running Clario yourself? The Agent
+button on your own site adds `--api-url` to the command for you.
 
-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.
+Used the older `viora-agent` package? Run `npx clario-agent setup` once: it reuses the key
+from `~/.viora` and replaces the old hook. You can delete `~/.viora` afterwards.
 
-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`.
+> Keep the setup command private: anyone with your key can post activity as your agent (and
+> nothing else). If it leaks, delete `~/.clario/agent.json`; the server's owner can cancel
+> every key by changing `JWT_SECRET` (this signs everyone out).
 
 ## 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`)
+- While your agent works your badge shows "cooking" with a short description of what it's
+  doing, e.g. `Claude is using Edit page.tsx`, `Codex is using Shell $ bun, git` or
+  `Cursor is editing page.tsx`, and the card says which agent it is
 - 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
+- When the agent 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

package/clario-agent-hook.mjs

@@ -1,28 +1,44 @@
 #!/usr/bin/env node
 /**
- * Clario agent hook for Claude Code
+ * Clario agent hook for Claude Code, Codex and Cursor
  *
  * 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
+ *   node hook.mjs [--agent claude-code|codex|cursor-agent]   (hook JSON on stdin)
+ *
+ * Reads the agent's 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.
+ * failure so it never blocks your agent session. Without --agent it's Claude Code.
  *
  * 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.
+ * command runs, never its arguments), which agent it is, and 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.
+ *
+ * Codex and Cursor read their hooks from one file for every project, so for them this
+ * only reports from the projects setup was run in (`projects` in the config), unless
+ * setup was run with --global (`everyProject`). Cursor reads each hook's stdout as its
+ * reply, so it always gets the neutral one: carry on, change nothing.
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 
 const CONFIG_PATH = join(homedir(), ".clario", "agent.json");
 const THROTTLE_MS = 2000;
 const STATE_PATH = join(homedir(), ".clario", ".agent-hook-state");
 
+/** Agents this hook understands, by the --agent value setup registers, with the name shown in Clario. */
+const AGENTS = { "claude-code": "Claude", codex: "Codex", "cursor-agent": "Cursor" };
+
+function agentFromArgs(argv) {
+  const i = argv.indexOf("--agent");
+  const value = i > -1 ? argv[i + 1] : argv.find((a) => a.startsWith("--agent="))?.slice("--agent=".length);
+  return value in AGENTS ? value : "claude-code";
+}
+
 function readStdin() {
   return new Promise((resolve) => {
     let raw = "";
@@ -36,7 +52,7 @@ function readStdin() {
 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.
+    // agentKey (from setup) wins over a pasted 7-day login token.
     const credential = config?.agentKey || config?.token;
     if (credential && config?.apiUrl) return { ...config, credential };
   } catch {
@@ -52,6 +68,28 @@ function lastSentAt() {
   }
 }
 
+/** Working directory of a hook event. Claude Code and Codex send `cwd`; Cursor sends `workspace_roots`. */
+function eventCwd(event) {
+  const roots = Array.isArray(event.workspace_roots) ? event.workspace_roots.filter((r) => typeof r === "string" && r) : [];
+  return (typeof event.cwd === "string" && event.cwd) || roots[0] || process.env.CURSOR_PROJECT_DIR || process.cwd();
+}
+
+function realPath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** Codex and Cursor: only from the projects setup was run in, or every project after setup --global. */
+function sharedHere(config, agent, cwd) {
+  if (agent === "claude-code" || config.everyProject === true) return true; // Claude Code's hook is per project already
+  const here = realPath(cwd);
+  const projects = Array.isArray(config.projects) ? config.projects : [];
+  return projects.some((p) => typeof p === "string" && (here === p || here.startsWith(p.endsWith(sep) ? p : p + sep)));
+}
+
 // 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). */
@@ -118,10 +156,9 @@ function readRef(gitDir, name) {
 }
 
 /** Project folder, branch and short commit for the agent card; nothing when sharing is off. */
-function gitInfo(event, config) {
+function gitInfo(cwd, 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);
@@ -152,42 +189,89 @@ function programNames(command) {
   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: "" };
+/** A shell tool's command line. Codex often sends it as ["bash", "-lc", "the command"]. */
+function commandText(input) {
+  const command = input?.command ?? input?.cmd;
+  if (typeof command === "string") return command;
+  if (!Array.isArray(command) || !command.every((part) => typeof part === "string")) return "";
+  const flag = command.findIndex((part) => part === "-c" || part === "-lc");
+  return flag > -1 && command[flag + 1] ? command[flag + 1] : command.join(" ");
+}
 
-  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]}`;
-    }
+/** The first file a Codex apply_patch names ("*** Update File: path"), wherever the patch sits in the input. */
+function patchFile(value, depth = 0) {
+  if (depth > 3 || value == null) return undefined;
+  if (typeof value === "string") return /^\*\*\* (?:Update|Add|Delete) File:\s*(.+?)\s*$/m.exec(value)?.[1];
+  const values = Array.isArray(value) ? value : typeof value === "object" ? Object.values(value) : [];
+  for (const v of values) {
+    const found = patchFile(v, depth + 1);
+    if (found) return found;
   }
-  if (tool === "Bash" && typeof event?.tool_input?.command === "string") {
-    const names = programNames(event.tool_input.command);
+  return undefined;
+}
+
+const fileName = (path) => (typeof path === "string" && path.trim() ? basename(path.trim()) : "");
+
+const DONE_EVENTS = new Set(["Stop", "SessionEnd", "stop", "sessionEnd"]);
+const PROMPT_EVENTS = new Set(["UserPromptSubmit", "beforeSubmitPrompt"]);
+const EDIT_TOOLS = new Set(["edit", "write", "multiedit", "notebookedit"]);
+const PATCH_TOOLS = new Set(["apply_patch", "applypatch"]);
+const SHELL_TOOLS = new Set(["bash", "shell", "local_shell", "exec_command"]);
+
+/** What the agent is doing, as the one line others see; no text means there's nothing to send. */
+function describe(event, agent) {
+  const name = AGENTS[agent];
+  const hookEvent = event.hook_event_name;
+  if (DONE_EVENTS.has(hookEvent)) return { state: "done", text: "" };
+  if (PROMPT_EVENTS.has(hookEvent)) return { state: "cooking", text: `${name} is thinking` };
+  // Cursor: one event per file its agent changes, with the file at the top level.
+  if (hookEvent === "afterFileEdit") {
+    const file = fileName(event.file_path);
+    return { state: "cooking", text: file ? `${name} is editing ${file}` : `${name} is editing` };
+  }
+  if (hookEvent !== "PreToolUse" && hookEvent !== "PostToolUse") return { state: "cooking", text: "" };
+
+  const tool = typeof event.tool_name === "string" ? event.tool_name : "";
+  const key = tool.toLowerCase();
+  let label = tool.replace(/^(mcp__|LambdaResponse)/, "").slice(0, 40) || "a tool";
+  let detail = "";
+  if (EDIT_TOOLS.has(key)) {
+    const file = fileName(event?.tool_input?.file_path ?? event?.tool_input?.notebook_path);
+    if (file) detail = ` ${file}`;
+  } else if (PATCH_TOOLS.has(key)) {
+    label = "Edit";
+    const file = fileName(patchFile(event?.tool_input));
+    if (file) detail = ` ${file}`;
+  } else if (SHELL_TOOLS.has(key)) {
+    if (key !== "bash") label = "Shell";
+    const names = programNames(commandText(event?.tool_input));
     if (names.length) detail = ` $ ${names.join(", ")}`;
   }
-  return { state: "cooking", text: `Claude is using ${toolLabel || "a tool"}${detail}` };
+  return { state: "cooking", text: `${name} is using ${label}${detail}` };
 }
 
 async function main() {
-  const config = loadConfig();
-  if (!config) process.exit(0);
-
+  const agent = agentFromArgs(process.argv.slice(2));
   const raw = await readStdin();
-  if (!raw.trim()) process.exit(0);
-
-  let event;
+  let event = {};
   try {
-    event = JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) event = parsed;
   } catch {
-    process.exit(0);
   }
 
-  const { state, text } = describe(event);
+  // Cursor waits for a reply on stdout before it goes on: give it first, whatever happens next.
+  if (agent === "cursor-agent") {
+    await new Promise((done) => process.stdout.write(event.hook_event_name === "beforeSubmitPrompt" ? '{"continue":true}' : "{}", done));
+  }
+
+  const config = loadConfig();
+  if (!config || !raw.trim()) process.exit(0);
+
+  const cwd = eventCwd(event);
+  if (!sharedHere(config, agent, cwd)) process.exit(0);
+
+  const { state, text } = describe(event, agent);
   if (state === "cooking" && !text) process.exit(0);
 
   // Client-side throttle: hook events fire per tool use and can be chatty.
@@ -204,7 +288,7 @@ async function main() {
         "Content-Type": "application/json",
         Authorization: `Bearer ${config.credential}`,
       },
-      body: JSON.stringify(state === "cooking" ? { text, state, ...gitInfo(event, config) } : { text, state }),
+      body: JSON.stringify(state === "cooking" ? { text, state, agent, ...gitInfo(cwd, config) } : { text, state, agent }),
       signal: controller.signal,
     });
     if (state === "cooking") {

package/cli.mjs

@@ -1,21 +1,27 @@
 #!/usr/bin/env node
 /**
- * clario-agent: show what your Claude Code agent is doing on your Clario avatar.
+ * clario-agent: show what your coding agent (Claude Code, Codex or Cursor) 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
+ *   npx clario-agent setup --key KEY [--agent claude|codex|cursor|all] [--api-url URL] [--global]
+ *   npx clario-agent status                       what is set up
+ *   npx clario-agent uninstall [--global]         stop sharing from this project (or everywhere)
  *
- * 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.
+ * The key comes from the website: the Agent button in a Clario space shows the whole
+ * setup command. setup checks the key with the server, saves it in ~/.clario/agent.json
+ * (one key per user that stays the same; it can only post agent activity), copies the hook
+ * to ~/.clario/hook.mjs and registers it with each agent:
+ *   Claude Code  this project's .claude/settings.local.json, or ~/.claude/settings.json with --global
+ *   Codex        ~/.codex/hooks.json (or $CODEX_HOME/hooks.json)
+ *   Cursor       ~/.cursor/hooks.json
+ * Codex and Cursor use one file for every project, so the hook only reports from the
+ * projects setup was run in (`projects` in the config), or from all 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");
@@ -26,14 +32,43 @@ const HOOK_SOURCE = join(dirname(fileURLToPath(import.meta.url)), "clario-agent-
 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
+const WARN_DAYS = 14; // setup reminds you to get a new key when the saved one has less time left than this
+const GET_A_KEY = "Open your Clario space at https://www.clario.games, click Agent in the left menu, and run the setup command it shows.";
 
 class CliError extends Error {}
 const fail = (message) => {
   throw new CliError(message);
 };
 
+/** A path for a hook command line, quoted for the shell. */
+const quote = (path) => `"${path.replace(/(["\\$`])/g, "\\$1")}"`;
+
+/** Where each agent reads its hooks, the events the hook listens to, and the file's layout. */
+const AGENT_TARGETS = {
+  claude: {
+    name: "Claude Code",
+    file: (global) => (global ? join(homedir(), ".claude", "settings.json") : join(process.cwd(), ".claude", "settings.local.json")),
+    events: ["PreToolUse", "PostToolUse", "Stop", "SessionEnd"],
+    command: () => `node ${quote(HOOK_PATH)}`,
+  },
+  codex: {
+    name: "Codex",
+    shared: true, // one file for every project
+    file: () => join(process.env.CODEX_HOME || join(homedir(), ".codex"), "hooks.json"),
+    events: ["UserPromptSubmit", "PostToolUse", "Stop", "SessionEnd"],
+    // The full path to node: Codex and Cursor can start hooks without your shell's PATH.
+    command: () => `${quote(process.execPath)} ${quote(HOOK_PATH)} --agent codex`,
+  },
+  cursor: {
+    name: "Cursor",
+    shared: true,
+    flat: true, // { version: 1, hooks: { event: [{ command }] } }
+    file: () => join(homedir(), ".cursor", "hooks.json"),
+    events: ["beforeSubmitPrompt", "afterFileEdit", "stop"],
+    command: () => `${quote(process.execPath)} ${quote(HOOK_PATH)} --agent cursor-agent`,
+  },
+};
+
 /** { value } for a JSON file, {} when it doesn't exist; fails on invalid JSON instead of overwriting it. */
 function readJson(file) {
   let text;
@@ -57,16 +92,26 @@ function writeJson(file, value, { mode } = {}) {
   if (mode) chmodSync(file, mode);
 }
 
-/** Days until a JWT expires, or null when it can't be read. */
-function daysLeft(token) {
+/** The readable part of a key (a JWT), or null. The server checks the signature. */
+function keyPayload(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;
+    const payload = JSON.parse(Buffer.from(String(token).split(".")[1], "base64url").toString());
+    return payload && typeof payload === "object" ? payload : null;
   } catch {
     return null;
   }
 }
 
+/** Days until a key expires: Infinity for one that doesn't (today's keys), null when it can't be read. */
+function daysLeft(token) {
+  const payload = keyPayload(token);
+  if (!payload) return null;
+  return typeof payload.exp === "number" ? (payload.exp * 1000 - Date.now()) / 86_400_000 : Infinity;
+}
+
+const expiryText = (days) =>
+  Number.isFinite(days) ? `works until ${new Date(Date.now() + days * 86_400_000).toDateString()}` : "it doesn't expire";
+
 async function post(apiUrl, path, body, token) {
   let res;
   try {
@@ -81,50 +126,28 @@ async function post(apiUrl, path, body, token) {
   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 key from the website, checked with the server before it's saved. */
+async function checkKey(key, apiUrl) {
+  const payload = keyPayload(key);
+  if (!payload || typeof payload.userId !== "string") fail(`That isn't a Clario agent key. ${GET_A_KEY}`);
+  if (payload.scope !== "agent") fail(`That's a login token, not an agent key. ${GET_A_KEY}`);
+  const days = daysLeft(key);
+  if (days === null || days <= 0) fail(`That key has expired. ${GET_A_KEY}`);
+  // A "done" update changes nothing anyone sees, and tells the server the hook is set up.
+  const res = await post(apiUrl, "/agent-activity", { text: "", state: "done" }, key);
+  if (res.status === 403) fail(`The server at ${apiUrl} doesn't accept this key. ${GET_A_KEY}`);
+  if (res.status !== 200) fail(`Could not check the key with ${apiUrl} (HTTP ${res.status}).`);
+  return { key, days, reused: false };
 }
 
-/** 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 };
+/** The key from an earlier setup, when it still works for this server (e.g. to add another project). */
+function savedKey(config, apiUrl) {
+  const days = daysLeft(config.agentKey);
+  if (config.agentKey && config.apiUrl === apiUrl && days !== null && days > 0) return { key: config.agentKey, days, reused: true };
+  fail(`No agent key yet. ${GET_A_KEY}`);
 }
 
-// ---- Claude Code settings -------------------------------------------------------
-
-const settingsFile = (global) =>
-  global ? join(homedir(), ".claude", "settings.json") : join(process.cwd(), ".claude", "settings.local.json");
+// ---- Hook files ---------------------------------------------------------------------
 
 /** Our hooks from any version (also from before the rename): this package's copy, or the repo script. */
 const isOurHook = (hook) =>
@@ -140,6 +163,7 @@ function withoutOurHooks(settings) {
       continue;
     }
     const kept = groups
+      .filter((group) => !isOurHook(group)) // Cursor lists commands directly
       .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;
@@ -149,17 +173,41 @@ function withoutOurHooks(settings) {
 }
 
 const countOurHooks = (settings) =>
-  Object.values(settings?.hooks ?? {}).flat().flatMap((group) => group?.hooks ?? []).filter(isOurHook).length;
+  Object.values(settings?.hooks ?? {})
+    .flat()
+    .flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : [group]))
+    .filter(isOurHook).length;
 
 /** Add the hook for every event, replacing older entries of ours so it never fires twice. */
-function registerHooks(file) {
+function registerHooks(target, global) {
+  const file = target.file(global);
   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 });
+  const command = target.command();
+  const entry = target.flat ? { command, timeout: 10 } : { hooks: [{ type: "command", command, timeout: 10 }] };
+  for (const event of target.events) hooks[event] = [...(hooks[event] ?? []), entry];
+  writeJson(file, { ...(target.flat ? { version: 1 } : {}), ...settings, hooks });
+  return file;
+}
+
+/** Remove our hook from a file; true when there was one. */
+function unregisterHooks(file) {
+  const { value } = readJson(file);
+  if (!value || !countOurHooks(value)) return false;
+  copyFileSync(file, `${file}.clario-backup`);
+  writeJson(file, withoutOurHooks(value));
+  return true;
+}
+
+/** The project setup runs in: the git root around the current folder, or the folder itself. */
+function projectRoot() {
+  const here = realpathSync(process.cwd());
+  for (let dir = here; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    if (dirname(dir) === dir) return here;
+  }
 }
 
 function gitIgnored(file) {
@@ -171,29 +219,54 @@ function gitIgnored(file) {
   }
 }
 
+/** --agent claude|codex|cursor|all, repeatable or comma separated; Claude Code when left out. */
+function parseAgents(args) {
+  const values = args
+    .flatMap((arg, i) => (arg === "--agent" ? [args[i + 1] ?? ""] : arg.startsWith("--agent=") ? [arg.slice("--agent=".length)] : []))
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+  const aliases = { "claude-code": "claude", "cursor-agent": "cursor" };
+  const names = values.includes("all") ? Object.keys(AGENT_TARGETS) : values.map((value) => aliases[value] ?? value);
+  const unknown = names.find((name) => !(name in AGENT_TARGETS));
+  if (unknown !== undefined) fail(`Unknown agent "${unknown}". Use claude, codex, cursor or all.`);
+  return names.length ? [...new Set(names)] : ["claude"];
+}
+
 // ---- 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);
+  // A new key comes from the live site unless --api-url says otherwise; re-running setup keeps the saved server.
+  const apiUrl = String(opts.apiUrl || (opts.key ? DEFAULT_API_URL : config.apiUrl) || DEFAULT_API_URL).replace(/\/+$/, "");
+  const { key, days, reused } = opts.key ? await checkKey(opts.key, apiUrl) : savedKey(config, apiUrl);
 
-  // The 7-day login token isn't needed any more; everything else (shareGit…) stays.
+  // An old 7-day login token isn't needed any more; everything else (shareGit, projects…) stays.
   const { token: _loginToken, ...rest } = config;
-  writeJson(CONFIG_PATH, { ...rest, apiUrl, agentKey: key }, { mode: 0o600 });
+  const next = { ...rest, apiUrl, agentKey: key };
+  const root = projectRoot();
+  if (opts.agents.some((agent) => AGENT_TARGETS[agent].shared)) {
+    if (opts.global) next.everyProject = true;
+    else next.projects = [...new Set([...(Array.isArray(rest.projects) ? rest.projects : []), root])];
+  }
+  writeJson(CONFIG_PATH, next, { 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(`${reused ? "Kept your agent key" : "Saved your agent key"} in ${CONFIG_PATH} (${expiryText(days)}).`);
+  if (reused && days < WARN_DAYS) console.log(`It runs out in ${Math.ceil(days)} days. ${GET_A_KEY}`);
+  for (const agent of opts.agents) {
+    const target = AGENT_TARGETS[agent];
+    const file = registerHooks(target, opts.global);
+    const scope = opts.global ? "every project" : target.shared ? `${root} (and any other project you ran setup in)` : "this project only";
+    console.log(`${target.name}: hook registered in ${file}, sharing from ${scope}.`);
+    if (agent === "claude" && !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.");
+    }
+    if (agent === "codex") console.log("  Codex asks before it runs a new hook: open Codex, run /hooks and trust the Clario hook.");
+    if (agent === "cursor") console.log("  If Cursor is open, restart it so it loads the hook.");
   }
-  console.log("Open your Clario space and give Claude a task: your avatar's card shows what it's doing.");
+  console.log("Open your Clario space and give your agent a task: your avatar's card shows what it's doing.");
 }
 
 function status() {
@@ -202,43 +275,66 @@ function status() {
   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:     ${config.agentKey ? "agent key" : "7-day login token"}, ${left === null ? "unreadable" : left === Infinity ? "doesn't expire" : 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"}`);
-  }
+  const registered = (file) => (countOurHooks(readJson(file).value) ? `registered (${file})` : "not registered");
+  console.log(`Claude Code, this project: ${registered(AGENT_TARGETS.claude.file(false))}`);
+  console.log(`Claude Code, all projects: ${registered(AGENT_TARGETS.claude.file(true))}`);
+  console.log(`Codex:   ${registered(AGENT_TARGETS.codex.file())}`);
+  console.log(`Cursor:  ${registered(AGENT_TARGETS.cursor.file())}`);
+  const projects = Array.isArray(config.projects) ? config.projects : [];
+  console.log(`Codex and Cursor share from: ${config.everyProject ? "every project" : projects.length ? projects.join(", ") : "no project yet"}`);
 }
 
 function uninstall(opts) {
-  const file = settingsFile(opts.global);
-  const { value } = readJson(file);
-  if (!value || !countOurHooks(value)) {
-    console.log(`No Clario hook in ${file}.`);
+  const { value: config } = readJson(CONFIG_PATH);
+  if (opts.global) {
+    // Stop everywhere: every agent's hook, and the list of shared projects.
+    for (const target of Object.values(AGENT_TARGETS)) {
+      const file = target.file(true);
+      if (unregisterHooks(file)) console.log(`Removed the ${target.name} hook from ${file}.`);
+    }
+    if (config) {
+      const { projects: _projects, everyProject: _every, ...rest } = config;
+      writeJson(CONFIG_PATH, rest, { mode: 0o600 });
+    }
+    console.log(`Nothing is shared any more. Your key stays in ${CONFIG_PATH}; delete that file to remove it too.`);
     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.`);
+  // Stop in this project: its Claude Code hook, and Codex and Cursor reporting from it.
+  const file = AGENT_TARGETS.claude.file(false);
+  if (unregisterHooks(file)) console.log(`Removed the Claude Code hook from ${file}.`);
+  const root = projectRoot();
+  if (config && Array.isArray(config.projects) && config.projects.includes(root)) {
+    writeJson(CONFIG_PATH, { ...config, projects: config.projects.filter((p) => p !== root) }, { mode: 0o600 });
+    console.log(`Codex and Cursor no longer share from ${root}.`);
+  }
+  if (config?.everyProject) console.log("Codex and Cursor still share from every project (setup --global); run uninstall --global to stop that.");
+  console.log("This project isn't shared any more.");
 }
 
-const HELP = `clario-agent: show what your Claude Code agent is doing on your Clario avatar
+const HELP = `clario-agent: show what your coding 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
+  clario-agent setup --key KEY [--agent claude|codex|cursor|all] [--global]
+                                    save your key and register the hook
+  clario-agent status               show what is set up
+  clario-agent uninstall [--global] stop sharing from this project (or everywhere)
 
-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}.`;
+Get the setup command (with your key) from the Agent button in your Clario space.
+--agent picks which agents to set up (default claude; comma separated or repeated).
+Without --global only the project you run it in is shared. Without --key, setup reuses
+the key you saved before. The server is ${DEFAULT_API_URL} unless you pass --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 };
+  const value = (flag) => {
+    const i = rest.indexOf(flag);
+    return i > -1 ? rest[i + 1] : undefined;
+  };
   try {
+    const opts = { global: rest.includes("--global"), apiUrl: value("--api-url"), key: value("--key"), agents: parseAgents(rest) };
     if (command === "setup") await setup(opts);
     else if (command === "status") status();
     else if (command === "uninstall") uninstall(opts);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clario-agent",
-  "version": "0.1.0",
-  "description": "Show what your Claude Code agent is doing (project, branch, commit) on your Clario avatar.",
+  "version": "0.3.0",
+  "description": "Show what your Claude Code, Codex or Cursor agent is doing (project, branch, commit) on your Clario avatar.",
   "type": "module",
   "bin": {
     "clario-agent": "cli.mjs"
@@ -18,6 +18,8 @@
   "keywords": [
     "clario",
     "claude-code",
+    "codex",
+    "cursor",
     "hooks",
     "agent",
     "metaverse"