@minhpnq1807/contextos 0.1.9 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.3.0
+
+- Adds `ctx sync --rules` for Ruler-backed project rule/MCP sync across Codex, Claude Code, and Antigravity.
+- Supports `--agents`, `--dry-run`, `--force`, and `--yes` flags for targeted, previewable, idempotent Ruler sync.
+- Injects `ctx-mcp` into `.ruler/ruler.toml` without deleting user-defined MCP servers or agent sections.
+- Imports existing Codex MCP servers from `~/.codex/config.toml` into Ruler so servers like `code-review-graph` and `agentmemory` can propagate to Antigravity and Claude Code.
+- Mirrors Ruler MCP servers into Antigravity app/CLI MCP config files after `ruler apply` so Antigravity receives all imported MCP servers.
+- Imports project `.mcp.json` servers such as `mcp-rtk` so MCPs generated by Ruler or other agents are also propagated.
+- Skips embedding model download during `ctx install` when the required MiniLM files are already present in `~/.ctx/contextos/models`.
+- Writes Antigravity MCP config to the legacy editor path `~/.gemini/config/mcp_config.json` so older editor builds can show ContextOS under `@mcp`.
+
+## 0.2.4
+
+- Hardens workspace isolation for Claude Code, Codex, and Antigravity hooks by normalizing project cwd from hook payloads, `workspacePath(s)`, and `CLAUDE_PROJECT_DIR` before writing prompt/report telemetry.
+
+## 0.2.3
+
+- Registers `ctx-mcp` for Claude Code by writing a user-scoped MCP server into `~/.claude.json`.
+
+## 0.2.2
+
+- Registers `ctx-mcp` for Antigravity app and `agy` CLI by writing `~/.gemini/antigravity/mcp_config.json` and `~/.gemini/antigravity-cli/mcp_config.json`.
+
+## 0.2.1
+
+- Adds `ctx install claude` for Claude Code hooks in `~/.claude/settings.json`.
+- Adds `ctx install agy` for Antigravity hooks in `~/.gemini/config/hooks.json`.
+- Adds Antigravity `PreInvocation` and `Stop` adapters so prompt context can be injected through `ephemeralMessage` and reports remain available through `ctx report` / `ctx evidence`.
+
+## 0.2.0
+
+- Adds `ctx benchmark -- "task"` to compare baseline AGENTS.md ordering with ContextOS scheduling and estimate lost-in-the-middle risk.
+- Improves AGENTS.md rule filtering for generic headings and non-actionable sections.
+- Splits Stop reports into `followed`, `ignored`, `unknown`, and `unmeasurable` so efficiency only reflects rules with evidence.
+
 ## 0.1.9
 
 - Proxies all configured MCP servers except ContextOS' own `ctx-mcp` server.

package/README.md

@@ -1,6 +1,6 @@
 # ContextOS
 
-ContextOS (`ctx`) is a Codex companion plugin for task-aware project context.
+ContextOS (`ctx`) is an agent companion for task-aware project context.
 
 It reads `AGENTS.md` guidance, scores the rules against the current prompt, suggests relevant files, records what context would have been injected, and reports lightweight compliance evidence after the task finishes.
 
@@ -16,10 +16,19 @@ ctx install
 
 Restart Codex after installing, then use Codex normally. ContextOS runs through Codex hooks and the `ctx-mcp` MCP server.
 
+Claude Code and Antigravity are supported through their native hook systems:
+
+```bash
+ctx install claude
+ctx install agy
+```
+
 You can also run without a global install:
 
 ```bash
 npx @minhpnq1807/contextos@latest install
+npx @minhpnq1807/contextos@latest install claude
+npx @minhpnq1807/contextos@latest install agy
 ```
 
 ## Demo Flow
@@ -31,16 +40,16 @@ ctx install
 codex
 ```
 
-Prompt Codex:
+Prompt the agent:
 
 ```text
-kiểm tra flow kiểm duyệt upload
+Recheck authen flow
 ```
 
 Expected result:
 
 - `UserPromptSubmit` injects relevant AGENTS.md rules.
-- ContextOS suggests upload/moderation files.
+- ContextOS suggests auth/authentication files.
 - `Stop` prints a ContextOS report with rule outcomes.
 - `ctx evidence` shows the specific evidence behind the last report.
 
@@ -53,16 +62,18 @@ With ContextOS, each prompt gets a compact block:
 ```text
 ## Critical ContextOS rules
 - Use code-review-graph before reading files.
-- Check upload moderation flows before editing approval code.
+- Recheck authentication flow before editing auth code.
 
 ## Suggested files to check
-- services/content-service/src/infrastructure/services/content-moderation.service.ts
-- webapp/src/features/dashboard/components/moderation-status-badge.tsx
+- services/auth-service/src/auth.controller.ts
+- services/auth-service/src/auth.service.ts
 ```
 
 ## What It Does
 
 - Hooks into Codex `UserPromptSubmit`, `SessionStart`, and `Stop`.
+- Hooks into Claude Code `UserPromptSubmit`, `SessionStart`, and `Stop`.
+- Hooks into Antigravity `PreInvocation` and `Stop` through the `agy` adapter.
 - Registers a `ctx-mcp` MCP server that owns model loading and semantic scoring.
 - Reads the active `AGENTS.md` chain for the current workspace.
 - Scores rules by relevance to the user prompt.
@@ -98,7 +109,22 @@ From this repository during local development:
 node bin/ctx.js install
 ```
 
-`ctx install` does three things:
+Agent-specific installers:
+
+```bash
+ctx install codex
+ctx install claude
+ctx install agy
+ctx install --agent codex
+ctx install --agent claude
+ctx install --agent agy
+```
+
+`ctx install` defaults to `ctx install codex`.
+
+### Codex
+
+`ctx install codex` does these things:
 
 1. Copies this package into `$CODEX_HOME/marketplaces/contextos`.
 2. Registers and installs `ctx@contextos` through Codex plugin marketplace commands.
@@ -109,13 +135,37 @@ node bin/ctx.js install
 
 Restart Codex after installing.
 
-The embedding model is mandatory. `ctx install` intentionally fails if the model cannot be prepared, because otherwise the first prompt hook would have to cold-load or download the model.
+### Claude Code
+
+`ctx install claude` copies this package into `~/.ctx/contextos/agents/claude/contextos`, merges ContextOS hooks into `~/.claude/settings.json`, and registers `ctx-mcp` as a user-scoped Claude Code MCP server in `~/.claude.json`.
+
+Claude Code receives prompt context through `UserPromptSubmit` using `hookSpecificOutput.additionalContext`, then ContextOS writes the same local workspace report files used by `ctx report`, `ctx evidence`, and `ctx stats`.
+
+Restart Claude Code after installing.
+
+### Antigravity
+
+`ctx install agy` copies this package into `~/.ctx/contextos/agents/agy/contextos`, writes a `contextos` hook group into `~/.gemini/config/hooks.json`, and registers `ctx-mcp` in Antigravity MCP config locations:
+
+```text
+~/.gemini/antigravity/mcp_config.json
+~/.gemini/antigravity-cli/mcp_config.json
+~/.gemini/config/mcp_config.json
+```
+
+The third path supports older Antigravity editor builds where `@mcp` reads the legacy Gemini config directory.
+
+Antigravity does not use `UserPromptSubmit`; ContextOS injects context through `PreInvocation` as an `ephemeralMessage`. The `Stop` adapter stores the report locally, so use `ctx report` or `ctx evidence` after the task to inspect outcomes.
+
+Restart Antigravity or `agy` after installing.
+
+The embedding model is mandatory. `ctx install` checks `~/.ctx/contextos/models` first and downloads the MiniLM model only when the required local files are missing. It intentionally fails if the model cannot be prepared, because otherwise the first prompt hook would have to cold-load or download the model.
 
 Verify the published package in any project:
 
 ```bash
 npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx --version
-npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx debug -- "fix upload moderation flow"
+npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx debug -- "Recheck authen flow"
 ```
 
 ## Modes
@@ -150,6 +200,43 @@ ctx install --copy
 
 Copies only the plugin payload into `$CODEX_HOME/plugins/ctx`. This is mostly for local experiments.
 
+## Ruler Sync
+
+Use Ruler when the project wants one rule/MCP source of truth for multiple agents:
+
+```bash
+ctx sync --rules
+```
+
+Default agents are `codex`, `claude`, and `antigravity`. You can target a subset:
+
+```bash
+ctx sync --rules --agents codex
+ctx sync --rules --agents codex,claude
+```
+
+What it does:
+
+1. Checks that `ruler` is installed. If it is missing, ContextOS asks before running `npm install -g @intellectronica/ruler`; use `--yes` for non-interactive installs.
+2. Runs `ruler init` when `.ruler/ruler.toml` is missing.
+3. Adds `ctx-mcp` to `.ruler/ruler.toml` under `[mcp_servers.ctx-mcp]`.
+4. Imports existing MCP servers from Codex `~/.codex/config.toml` and project `.mcp.json`, such as `code-review-graph`, `agentmemory`, and `mcp-rtk`, into `.ruler/ruler.toml`.
+5. Adds enabled Ruler agent entries for Codex, Claude Code, and Antigravity using merge strategy.
+6. Runs `ruler apply --agents ...`.
+7. Mirrors the Ruler MCP server list into Antigravity app/CLI MCP configs because current Ruler versions do not emit every Antigravity MCP file consistently.
+8. Verifies that generated agent config contains `ctx-mcp`.
+
+Useful flags:
+
+```bash
+ctx sync --rules --dry-run
+ctx sync --rules --force
+ctx sync --rules --yes
+ctx sync --rules --no-import-codex-mcp
+```
+
+`ctx sync --rules` is project-scoped. It writes `.ruler/ruler.toml` in the current project and lets Ruler generate agent files from that project source of truth. ContextOS runtime history still follows the project-path isolation model described below.
+
 ## Troubleshooting
 
 ### `ctx-mcp bridge socket not found`
@@ -161,7 +248,7 @@ Restart Codex after `ctx install`. The bridge socket is owned by the long-runnin
 Run:
 
 ```bash
-ctx embeddings warm -- "kiểm tra flow kiểm duyệt upload"
+ctx embeddings warm -- "Recheck authen flow"
 ```
 
 Then restart Codex.
@@ -182,14 +269,24 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 
 | Command | Meaning | Use when | Output / side effect |
 | --- | --- | --- | --- |
-| `ctx install` | Installs ContextOS into Codex with prompt context injection enabled. | Normal setup after installing the npm package. | Copies the plugin into `$CODEX_HOME/marketplaces/contextos`, registers `ctx@contextos`, registers `ctx-mcp`, installs global hooks, downloads the embedding model, and warms caches. |
-| `ctx install --quiet` | Installs ContextOS in measurement-only mode. | You want reports and stats but do not want a visible `hook context` block in Codex. | Installs the same plugin/hooks, but prompt hooks return empty `additionalContext`. |
-| `ctx install --inject` | Installs ContextOS with explicit injection mode. | You want to be explicit in scripts or docs. | Same runtime behavior as `ctx install`. |
+| `ctx install` | Installs ContextOS into Codex with prompt context injection enabled. | Normal Codex setup after installing the npm package. | Same as `ctx install codex`. |
+| `ctx install codex` | Installs ContextOS into Codex. | You use the `codex` CLI. | Copies the plugin into `$CODEX_HOME/marketplaces/contextos`, registers `ctx@contextos`, registers `ctx-mcp`, installs global hooks, downloads the embedding model, and warms caches. |
+| `ctx install claude` | Installs ContextOS into Claude Code. | You use the `claude` CLI. | Copies a stable package root to `~/.ctx/contextos/agents/claude/contextos`, merges hooks into `~/.claude/settings.json`, and registers `ctx-mcp` in `~/.claude.json`. |
+| `ctx install agy` | Installs ContextOS into Antigravity. | You use the `agy` CLI or Antigravity app/editor. | Copies a stable package root to `~/.ctx/contextos/agents/agy/contextos`, writes hooks to `~/.gemini/config/hooks.json`, and registers `ctx-mcp` in Antigravity app, CLI, and legacy editor MCP config paths. |
+| `ctx install --agent <name>` | Installs for a named agent. | You prefer explicit scripts. | Accepts `codex`, `claude`, or `agy`. |
+| `ctx install --quiet` | Installs ContextOS in measurement-only mode. | You want reports and stats but do not want visible injected context. | Installs the same hooks, but prompt hooks return empty context. |
+| `ctx install --inject` | Installs ContextOS with explicit injection mode. | You want to be explicit in scripts or docs. | Same runtime behavior as the default install mode. |
 | `ctx install --copy` | Copies only the plugin payload to `$CODEX_HOME/plugins/ctx`. | Local development or manual plugin experiments. | Does not register marketplace, MCP, or global hooks. |
 | `ctx debug -- "task"` | Runs the scheduler locally for a fake prompt. | You want to see which AGENTS.md rules and files ContextOS would inject before using Codex. | Prints rule scores, scoring reasons, suggested files, and final `additionalContext`. |
-| `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | A Codex task has finished and you want the summary again. | Reads `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
+| `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | An agent task has finished and you want the summary again. | Reads `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
 | `ctx evidence` | Shows detailed evidence behind the last report for the current workspace. | You want to inspect why a rule was marked `followed`, `ignored`, or `unknown`. | Prints rule text, source file, score, status, and evidence reason. |
 | `ctx stats` | Shows aggregate runtime metrics for the current workspace. | You want to know whether ContextOS is active and useful over time. | Prints prompt count, report count, injected/quiet ratio, average prompt analysis time, efficiency, rule outcomes, hook events, and last suggested files for the current workspace only. |
+| `ctx benchmark -- "task"` | Compares baseline AGENTS.md ordering with ContextOS task-aware scheduling. | You want a before/after signal for lost-in-the-middle risk. | Prints parsed/actionable/filtered rule counts, relevant rules in the middle of the original file, scheduled high/mid rules, and top scored rules. |
+| `ctx sync --rules` | Syncs project rules and MCP servers through Ruler. | You want Codex, Claude Code, and Antigravity to share one project rule/MCP source of truth. | Ensures `.ruler/ruler.toml`, injects `ctx-mcp`, imports existing MCP servers from Codex and project `.mcp.json`, runs `ruler apply --agents codex,claude,antigravity`, mirrors MCP servers to Antigravity MCP configs, and verifies generated config. |
+| `ctx sync --rules --agents <list>` | Syncs only selected agents through Ruler. | You want to update one or two agents without touching the others. | Accepts comma-separated values such as `codex`, `claude`, `antigravity`, or `codex,claude`. |
+| `ctx sync --rules --dry-run` | Previews Ruler sync without writing files or running apply. | You want to inspect behavior before changing project config. | Prints the same flow with dry-run status. |
+| `ctx sync --rules --force` | Rewrites ContextOS-owned Ruler sections. | You changed the ContextOS install path or need to refresh `ctx-mcp`. | Removes and re-adds ContextOS-owned `mcp`, `mcp_servers.ctx-mcp`, and selected agent sections. |
+| `ctx sync --rules --no-import-codex-mcp` | Skips Codex MCP import. | You only want ContextOS' own `ctx-mcp` in Ruler. | Does not read `~/.codex/config.toml`. |
 | `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes vectors to `~/.ctx/contextos/embeddings.db`. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
 
@@ -227,6 +324,8 @@ The workspace id is stored in the target repo at:
 
 ContextOS also adds `.contextos/` to the repo `.gitignore` so the local marker is not pushed. If the marker cannot be written, ContextOS falls back to a deterministic id generated from the workspace real path.
 
+Codex, Claude Code, and Antigravity all write prompt context, reports, evidence, stats, and telemetry through this same workspace id. The same project shares one ContextOS runtime history across agents; different project paths get different workspace directories. Claude Code hooks also use `CLAUDE_PROJECT_DIR` when the hook payload does not include `cwd`, and Antigravity uses `workspacePath` / `workspacePaths` when present.
+
 These files are local telemetry only. Hooks do not make network calls.
 
 ## Project Understanding
@@ -286,6 +385,7 @@ ContextOS uses heuristic evidence collection from git diff/status plus local run
 followed = evidence in the diff suggests the rule was applied
 ignored  = evidence in the diff suggests the rule was violated
 unknown  = the rule was relevant, but the diff does not prove either way
+unmeasurable = ContextOS lacks the required evidence source, such as git diff lines or runtime telemetry
 ```
 
 For runtime-only rules, ContextOS also checks `telemetry.jsonl` for hook-visible tool names, MCP server names, and command metadata. A rule like "use code-review-graph before reading files" can be marked `followed` when telemetry contains a matching `code-review-graph` signal.
@@ -329,7 +429,7 @@ npm pack --dry-run
 Smoke test prompt hook:
 
 ```bash
-printf '%s' '{"prompt":"fix auth validation","cwd":"'$PWD'","hook_event_name":"UserPromptSubmit"}' \
+printf '%s' '{"prompt":"Recheck authen flow","cwd":"'$PWD'","hook_event_name":"UserPromptSubmit"}' \
   | node plugins/ctx/bin/on-prompt.js
 ```
 
@@ -365,9 +465,10 @@ contextos-plan.jsx                 implementation plan/reference
 
 ## Limitations
 
-- Codex CLI only.
+- Codex and Claude Code get prompt context through `additionalContext`; Antigravity gets prompt context through `PreInvocation` `ephemeralMessage`.
+- Antigravity Stop hooks store reports locally, but they do not display the full report inline unless Antigravity adds a non-continuing Stop message surface.
 - Local marketplace plugin hooks may not fire reliably in current Codex builds, so `ctx install` also installs global hooks.
-- Injection mode may show a visible `hook context` block in Codex.
+- Injection mode may show a visible hook context block in some agents.
 - Quiet mode does not inject context into the model; it only records and measures.
 - Compliance is heuristic and mostly based on git diff/status.
 - Some rules can only be `unknown` unless ContextOS records richer telemetry such as tool calls or shell command metadata.

package/bin/ctx.js

@@ -10,11 +10,18 @@ import { scheduleContext } from "../plugins/ctx/lib/scheduler.js";
 import { formatEvidence, formatReport } from "../plugins/ctx/lib/reporter.js";
 import { installGlobalHooks } from "../plugins/ctx/lib/global-hooks.js";
 import { formatStats, loadStats } from "../plugins/ctx/lib/stats.js";
-import { modelCacheDir, warmRuleEmbeddings } from "../plugins/ctx/lib/embedding-scorer.js";
+import { isModelCacheReady, modelCacheDir, warmRuleEmbeddings } from "../plugins/ctx/lib/embedding-scorer.js";
 import { warmFileEmbeddings } from "../plugins/ctx/lib/file-embedding-retriever.js";
 import { scoreContext } from "../plugins/ctx/lib/score-context.js";
 import { defaultDataRoot, workspaceDataDir, workspaceMarkerPath } from "../plugins/ctx/lib/workspace-data.js";
 import { installMcpTelemetryProxies } from "../plugins/ctx/lib/mcp-proxy-install.js";
+import { benchmarkWorkspace, formatBenchmark } from "../plugins/ctx/lib/benchmark.js";
+import { copyDir, copyPackageRoot } from "../plugins/ctx/lib/package-install.js";
+import { installClaudeHooks } from "../plugins/ctx/lib/claude-hooks.js";
+import { installClaudeMcp } from "../plugins/ctx/lib/claude-mcp.js";
+import { installAntigravityHooks } from "../plugins/ctx/lib/antigravity-hooks.js";
+import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
+import { syncRules } from "../plugins/ctx/lib/ruler-sync.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -25,6 +32,10 @@ function usage() {
 
 Usage:
   ctx install
+  ctx install codex
+  ctx install claude
+  ctx install agy
+  ctx install --agent codex|claude|agy
   ctx install --quiet
   ctx install --inject
   ctx install --copy
@@ -32,6 +43,11 @@ Usage:
   ctx report
   ctx evidence
   ctx stats
+  ctx benchmark -- "task"
+  ctx sync --rules
+  ctx sync --rules --agents codex,claude,antigravity
+  ctx sync --rules --dry-run
+  ctx sync --rules --no-import-codex-mcp
   ctx embeddings warm -- "task"
   ctx --version
 `;
@@ -50,31 +66,6 @@ function codexHome() {
   return process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex");
 }
 
-function copyDir(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath);
-    } else if (entry.isFile()) {
-      fs.copyFileSync(srcPath, destPath);
-      fs.chmodSync(destPath, fs.statSync(srcPath).mode);
-    }
-  }
-}
-
-function copyPath(src, dest) {
-  const stat = fs.statSync(src);
-  if (stat.isDirectory()) {
-    copyDir(src, dest);
-  } else {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(src, dest);
-    fs.chmodSync(dest, stat.mode);
-  }
-}
-
 function copyInstall() {
   const target = path.join(codexHome(), "plugins", "ctx");
   fs.rmSync(target, { recursive: true, force: true });
@@ -83,19 +74,57 @@ function copyInstall() {
   console.log("Restart Codex if it was already running, then submit a task to trigger ContextOS.");
 }
 
-async function install({ copy = false, inject = true } = {}) {
+function agentInstallRoot(agent) {
+  return path.join(contextOSDataDir(), "agents", agent, "contextos");
+}
+
+async function install({ copy = false, inject = true, agent = "codex" } = {}) {
   if (copy) {
     copyInstall();
     return;
   }
 
-  const marketplaceRoot = path.join(codexHome(), "marketplaces", "contextos");
-  fs.rmSync(marketplaceRoot, { recursive: true, force: true });
-  for (const entry of [".agents", "bin", "plugins", "package.json", "package-lock.json", "README.md", "LICENSE", "node_modules"]) {
-    const src = path.join(rootDir, entry);
-    if (fs.existsSync(src)) copyPath(src, path.join(marketplaceRoot, entry));
+  if (agent === "claude") {
+    const installRoot = copyPackageRoot({ rootDir, targetRoot: agentInstallRoot("claude") });
+    const hooksPath = installClaudeHooks({ installRoot, injectPromptContext: inject });
+    const mcpConfigPath = installClaudeMcp({ installRoot });
+    const warmResult = await warmInstallEmbeddings();
+    console.log("Installed ctx hooks for Claude Code.");
+    console.log(`Stable install root: ${installRoot}`);
+    console.log(`Installed ContextOS hooks to ${hooksPath}`);
+    console.log(`Installed ctx-mcp MCP server to ${mcpConfigPath}`);
+    console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
+    console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
+    console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
+    console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
+    console.log("Restart Claude Code if it was already running, then submit a task to trigger ContextOS.");
+    return;
   }
 
+  if (agent === "agy") {
+    const installRoot = copyPackageRoot({ rootDir, targetRoot: agentInstallRoot("agy") });
+    const hooksPath = installAntigravityHooks({ installRoot, injectPromptContext: inject });
+    const mcpConfigPaths = installAntigravityMcp({ installRoot });
+    const warmResult = await warmInstallEmbeddings();
+    console.log("Installed ctx hooks for Antigravity.");
+    console.log(`Stable install root: ${installRoot}`);
+    console.log(`Installed ContextOS hooks to ${hooksPath}`);
+    console.log(`Installed ctx-mcp MCP server to ${mcpConfigPaths.join(", ")}`);
+    console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
+    console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
+    console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
+    console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
+    console.log("Restart Antigravity or agy if it was already running, then submit a task to trigger ContextOS.");
+    return;
+  }
+
+  if (agent !== "codex") {
+    throw new Error(`Unknown agent '${agent}'. Expected codex, claude, or agy.`);
+  }
+
+  const marketplaceRoot = path.join(codexHome(), "marketplaces", "contextos");
+  copyPackageRoot({ rootDir, targetRoot: marketplaceRoot });
+
   tryRunCodex(["plugin", "remove", "ctx@contextos"]);
   tryRunCodex(["plugin", "marketplace", "remove", "contextos"]);
   tryRunCodex(["mcp", "remove", "ctx-mcp"]);
@@ -105,7 +134,6 @@ async function install({ copy = false, inject = true } = {}) {
   const proxyResult = installMcpTelemetryProxies({ codexHome: codexHome(), marketplaceRoot });
   const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
 
-  console.log("Preparing required local embedding model...");
   const warmResult = await warmInstallEmbeddings();
   console.log("Installed ctx through Codex plugin marketplace.");
   console.log(`Stable marketplace root: ${marketplaceRoot}`);
@@ -121,6 +149,10 @@ async function install({ copy = false, inject = true } = {}) {
 
 async function warmInstallEmbeddings() {
   const dataDir = contextOSDataDir();
+  const modelReady = isModelCacheReady(dataDir);
+  console.log(modelReady
+    ? "Required local embedding model already cached."
+    : "Preparing required local embedding model...");
   const result = await warmRuleEmbeddings({
     rules: [
       { content: "Always use project rules that are semantically relevant to the user prompt." },
@@ -130,14 +162,14 @@ async function warmInstallEmbeddings() {
     task: "kiểm duyệt upload moderation semantic code search",
     dataDir,
     sources: [],
-    allowRemote: true
+    allowRemote: !modelReady
   });
   const fileResult = await warmFileEmbeddings({
     cwd: process.cwd(),
     dataDir,
-    allowRemote: true
+    allowRemote: !modelReady
   });
-  return { ...result, fileCount: fileResult.count };
+  return { ...result, modelAlreadyCached: modelReady, fileCount: fileResult.count };
 }
 
 function tryRunCodex(args) {
@@ -246,13 +278,24 @@ async function warmEmbeddings(task) {
 const args = process.argv.slice(2);
 const command = args[0];
 
+function installAgentFromArgs(args) {
+  const agentFlag = args.indexOf("--agent");
+  if (agentFlag >= 0) return args[agentFlag + 1] || "";
+  const firstValue = args.slice(1).find((arg) => !arg.startsWith("--"));
+  return firstValue || "codex";
+}
+
 try {
   if (!command || command === "--help" || command === "-h") {
     console.log(usage());
   } else if (command === "--version" || command === "-v") {
     console.log(packageVersion());
   } else if (command === "install") {
-    await install({ copy: args.includes("--copy"), inject: !args.includes("--quiet") });
+    await install({
+      copy: args.includes("--copy"),
+      inject: !args.includes("--quiet"),
+      agent: installAgentFromArgs(args)
+    });
   } else if (command === "debug") {
     const marker = args.indexOf("--");
     const task = marker >= 0 ? args.slice(marker + 1).join(" ") : args.slice(1).join(" ");
@@ -272,6 +315,13 @@ try {
     console.log(formatEvidence(loadLastReport()));
   } else if (command === "stats") {
     console.log(formatStats(loadStats(contextOSWorkspaceDataDir())));
+  } else if (command === "benchmark") {
+    const marker = args.indexOf("--");
+    const task = marker >= 0 ? args.slice(marker + 1).join(" ") : args.slice(1).join(" ");
+    if (!task.trim()) throw new Error('Usage: ctx benchmark -- "task"');
+    console.log(formatBenchmark(benchmarkWorkspace({ cwd: process.cwd(), task })));
+  } else if (command === "sync") {
+    await syncRules({ cwd: process.cwd(), rootDir, args: args.slice(1) });
   } else {
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.1.9",
-  "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex.",
+  "version": "0.3.1",
+  "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {
     "ctx": "bin/ctx.js"
@@ -29,6 +29,9 @@
   },
   "keywords": [
     "codex",
+    "claude-code",
+    "antigravity",
+    "agy",
     "plugin",
     "agents",
     "context",

package/plugins/ctx/bin/on-antigravity-preinvocation.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile, pluginDataRoot } from "../lib/hook-io.js";
+import { handlePromptPayload } from "../lib/prompt-hook.js";
+import { appendTelemetry } from "../lib/telemetry.js";
+import { antigravityCwd, extractPromptFromAntigravityPayload } from "../lib/antigravity-adapter.js";
+
+const started = Date.now();
+
+try {
+  const payload = await readStdinJson();
+  const cwd = antigravityCwd(payload);
+  const prompt = extractPromptFromAntigravityPayload(payload);
+  const normalized = {
+    ...payload,
+    cwd,
+    prompt,
+    hook_event_name: "PreInvocation"
+  };
+
+  logDebug("Antigravity PreInvocation", normalized);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "PreInvocation", payload: normalized });
+  const output = await handlePromptPayload(normalized, {
+    dataPath: pluginRuntimeFile("last-prompt-context.json", cwd),
+    historyPath: pluginRuntimeFile("prompt-history.jsonl", cwd),
+    mcpDataDir: pluginDataRoot(),
+    started
+  });
+  const additionalContext = output?.hookSpecificOutput?.additionalContext || "";
+  writeJson({
+    injectSteps: additionalContext ? [{ ephemeralMessage: additionalContext }] : []
+  });
+} catch (error) {
+  failOpen("PreInvocation", error, {
+    injectSteps: []
+  });
+}

package/plugins/ctx/bin/on-antigravity-stop.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile } from "../lib/hook-io.js";
+import { handleStopPayload } from "../lib/stop-hook.js";
+import { appendTelemetry } from "../lib/telemetry.js";
+import { antigravityCwd } from "../lib/antigravity-adapter.js";
+
+try {
+  const payload = await readStdinJson();
+  const cwd = antigravityCwd(payload);
+  const normalized = {
+    ...payload,
+    cwd,
+    hook_event_name: "Stop"
+  };
+  logDebug("Antigravity Stop", normalized);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "Stop", payload: normalized });
+  handleStopPayload(normalized, {
+    contextPath: pluginRuntimeFile("last-prompt-context.json", cwd),
+    reportPath: pluginRuntimeFile("last-report.json", cwd),
+    historyPath: pluginRuntimeFile("report-history.jsonl", cwd),
+    telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd)
+  });
+  writeJson({ decision: "" });
+} catch (error) {
+  failOpen("Stop", error, {
+    decision: ""
+  });
+}

package/plugins/ctx/bin/on-prompt.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile, pluginDataRoot } from "../lib/hook-io.js";
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile, pluginDataRoot, resolveHookCwd } from "../lib/hook-io.js";
 import { handlePromptPayload } from "../lib/prompt-hook.js";
 import { appendTelemetry } from "../lib/telemetry.js";
 
@@ -7,11 +7,12 @@ const started = Date.now();
 
 try {
   const payload = await readStdinJson();
-  const cwd = payload.cwd || payload.working_directory;
+  const cwd = resolveHookCwd(payload);
+  const normalized = { ...payload, cwd };
 
-  logDebug("UserPromptSubmit", payload);
-  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "UserPromptSubmit", payload });
-  writeJson(await handlePromptPayload(payload, {
+  logDebug("UserPromptSubmit", normalized);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "UserPromptSubmit", payload: normalized });
+  writeJson(await handlePromptPayload(normalized, {
     dataPath: pluginRuntimeFile("last-prompt-context.json", cwd),
     historyPath: pluginRuntimeFile("prompt-history.jsonl", cwd),
     mcpDataDir: pluginDataRoot(),

package/plugins/ctx/bin/on-session-start.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile } from "../lib/hook-io.js";
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile, resolveHookCwd } from "../lib/hook-io.js";
 import { appendTelemetry } from "../lib/telemetry.js";
 
 try {
   const payload = await readStdinJson();
-  const cwd = payload.cwd || payload.working_directory;
-  logDebug("SessionStart", payload);
-  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "SessionStart", payload });
+  const cwd = resolveHookCwd(payload);
+  const normalized = { ...payload, cwd };
+  logDebug("SessionStart", normalized);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "SessionStart", payload: normalized });
   writeJson({
     continue: true,
     suppressOutput: true,