@minhpnq1807/contextos 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.7
+
+- Adds thin passthrough commands `ctx ruler -- <args>` and `ctx skillshare -- <args>` for upstream admin/debug workflows without reimplementing those CLIs.
+- Preserves upstream output and exit status for passthrough commands, with install hints when the upstream binary is missing.
+
+## 0.5.6
+
+- Adds visible `ctx install` progress from 0-100 so long model/file/skill embedding warmups no longer look stalled.
+- Accepts `agy` as the Antigravity alias for install, Ruler sync, and skillshare sync while still passing Ruler/skillshare their official `antigravity` agent id.
+- Makes `ctx install --inject` explicitly override `--quiet` when both flags are present.
+
 ## 0.5.5
 
 - Discovers all skill roots containing `SKILL.md` under global/project `.gemini`, `.codex`, and `.claude` directories before `ctx sync --skills`.

package/README.md

@@ -162,6 +162,8 @@ 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.
 
+During install, ContextOS prints a 0-100 progress indicator. The longest stage is usually embedding warmup; if the model is already cached, install skips the download and only refreshes vectors.
+
 Verify the published package in any project:
 
 ```bash
@@ -191,6 +193,7 @@ Useful variants:
 ctx sync --skills --dry-run
 ctx sync --skills --no-collect
 ctx sync --skills --agents codex,claude
+ctx sync --skills --agents codex,claude,agy
 ```
 
 After this, `ctx debug -- "task"` and prompt hooks can suggest skills from `~/.config/skillshare/skills/` plus agent-specific skill folders.
@@ -235,11 +238,13 @@ Use Ruler when the project wants one rule/MCP source of truth for multiple agent
 ctx sync --rules
 ```
 
-Default agents are `codex`, `claude`, and `antigravity`. You can target a subset:
+Default agents are `codex`, `claude`, and `agy` (Antigravity). Ruler's official identifier is still `antigravity`, so ContextOS accepts both `agy` and `antigravity` and normalizes them before calling Ruler. You can target a subset:
 
 ```bash
 ctx sync --rules --agents codex
 ctx sync --rules --agents codex,claude
+ctx sync --rules --agents codex,claude,agy
+ctx sync --rules --agents codex,claude,antigravity
 ```
 
 What it does:
@@ -264,6 +269,20 @@ 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.
 
+## Upstream Passthrough
+
+ContextOS exposes thin passthrough commands for Ruler and skillshare admin/debug workflows:
+
+```bash
+ctx ruler -- apply --agents codex,claude,antigravity
+ctx ruler -- init
+ctx skillshare -- status
+ctx skillshare -- target list
+ctx skillshare -- doctor
+```
+
+Everything after `--` is forwarded unchanged to the upstream CLI. ContextOS does not reinterpret those args, and it preserves the upstream output and exit status. Use `ctx sync --rules` and `ctx sync --skills` for ContextOS-managed workflows; use passthrough when you need a native Ruler or skillshare command.
+
 ## Troubleshooting
 
 ### `ctx-mcp bridge socket not found`
@@ -302,7 +321,7 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `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 --inject` | Installs ContextOS with explicit injection mode. | You want to be explicit in scripts or docs. | Same runtime behavior as the default install mode; if combined with `--quiet`, `--inject` wins. |
 | `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. | An agent task has finished and you want the summary again. | Reads `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
@@ -310,15 +329,17 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `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 --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`, `agy`, `antigravity`, or `codex,claude,agy`; `agy` is normalized to Ruler's `antigravity`. |
 | `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 sync --skills` | Syncs agent skills through skillshare. | You want Codex, Claude Code, and Antigravity to share one skill source. | Installs or verifies `skillshare`, initializes it if needed, backs up and collects existing skills unless skipped, runs `skillshare sync`, and rebuilds ContextOS skill embeddings. |
-| `ctx sync --skills --agents <list>` | Syncs skills only for selected agents. | You want to target a subset such as `codex,claude`. | Runs `skillshare sync --agents <list>` and refreshes skill embeddings. |
+| `ctx sync --skills --agents <list>` | Syncs skills only for selected agents. | You want to target a subset such as `codex,claude` or `codex,claude,agy`. | Runs `skillshare sync --agents <list>` with `agy` normalized to `antigravity`, then refreshes skill embeddings. |
 | `ctx sync --skills --dry-run` | Previews skillshare sync. | You want to inspect behavior before changing skill directories. | Runs `skillshare sync --dry-run` and skips embedding rebuild. |
 | `ctx sync --skills --no-collect` | Skips collecting existing agent skills into skillshare. | You already manage `~/.config/skillshare/skills` and only want to push it out. | Initializes/syncs skillshare without running `skillshare backup` or `skillshare collect --all`. |
 | `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, and skill vectors to `~/.ctx/contextos/embeddings.db`. |
+| `ctx ruler -- <args>` | Forwards args to the installed `ruler` CLI. | You need native Ruler commands such as `init`, `apply`, or `revert`. | Preserves Ruler stdout/stderr and exit status. |
+| `ctx skillshare -- <args>` | Forwards args to the installed `skillshare` CLI. | You need native skillshare commands such as `status`, `target list`, `doctor`, `push`, or `pull`. | Preserves skillshare stdout/stderr and exit status. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
 
 ## Runtime Files

package/bin/ctx.js

@@ -24,6 +24,7 @@ import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
 import { syncRules } from "../plugins/ctx/lib/ruler-sync.js";
 import { syncSkills } from "../plugins/ctx/lib/skillshare-sync.js";
 import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
+import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthrough.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -55,10 +56,74 @@ Usage:
   ctx sync --skills --no-collect
   ctx sync --skills --agents codex,claude,antigravity
   ctx embeddings warm -- "task"
+  ctx ruler -- <ruler args>
+  ctx skillshare -- <skillshare args>
   ctx --version
 `;
 }
 
+function normalizeInstallAgent(agent) {
+  const normalized = String(agent || "").trim().toLowerCase();
+  if (normalized === "antigravity") return "agy";
+  return normalized;
+}
+
+function createInstallProgress({ quiet = false } = {}) {
+  const enabled = !quiet && process.stderr.isTTY;
+  const frames = ["-", "\\", "|", "/"];
+  let percent = 0;
+  let label = "starting";
+  let frame = 0;
+  let timer = null;
+
+  function render() {
+    if (!enabled) return;
+    const text = `[ctx] install ${String(percent).padStart(3)}% ${frames[frame % frames.length]} ${label}`;
+    process.stderr.write(`\r${text.padEnd(92)}`);
+    frame += 1;
+  }
+
+  return {
+    start(initialLabel = "starting") {
+      label = initialLabel;
+      percent = 0;
+      if (enabled) {
+        render();
+        timer = setInterval(render, 120);
+      } else if (!quiet) {
+        console.log(`[ctx] install 0% ${label}`);
+      }
+    },
+    step(nextPercent, nextLabel) {
+      percent = Math.max(percent, Math.min(100, nextPercent));
+      label = nextLabel;
+      if (enabled) render();
+      else if (!quiet) console.log(`[ctx] install ${percent}% ${label}`);
+    },
+    done(finalLabel = "done") {
+      percent = 100;
+      label = finalLabel;
+      if (timer) clearInterval(timer);
+      timer = null;
+      if (enabled) {
+        render();
+        process.stderr.write("\n");
+      } else if (!quiet) {
+        console.log(`[ctx] install 100% ${label}`);
+      }
+    },
+    fail(errorLabel = "failed") {
+      label = errorLabel;
+      if (timer) clearInterval(timer);
+      timer = null;
+      if (enabled) {
+        render();
+        process.stderr.write("\n");
+      }
+    }
+  };
+}
+
 function packageVersion() {
   try {
     const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
@@ -85,75 +150,100 @@ function agentInstallRoot(agent) {
 }
 
 async function install({ copy = false, inject = true, agent = "codex" } = {}) {
+  agent = normalizeInstallAgent(agent);
   if (copy) {
     copyInstall();
     return;
   }
+  const progress = createInstallProgress({ quiet: false });
+  progress.start(`installing ${agent || "codex"}`);
 
-  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(`Skill embeddings warmed: ${warmResult.skillCount || 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;
-  }
+  try {
+    if (agent === "claude") {
+      progress.step(10, "copying package");
+      const installRoot = copyPackageRoot({ rootDir, targetRoot: agentInstallRoot("claude") });
+      progress.step(25, "installing hooks");
+      const hooksPath = installClaudeHooks({ installRoot, injectPromptContext: inject });
+      progress.step(40, "installing mcp");
+      const mcpConfigPath = installClaudeMcp({ installRoot });
+      progress.step(55, "warming embeddings");
+      const warmResult = await warmInstallEmbeddings();
+      progress.done("claude installed");
+      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(`Skill embeddings warmed: ${warmResult.skillCount || 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") {
+      progress.step(10, "copying package");
+      const installRoot = copyPackageRoot({ rootDir, targetRoot: agentInstallRoot("agy") });
+      progress.step(25, "installing hooks");
+      const hooksPath = installAntigravityHooks({ installRoot, injectPromptContext: inject });
+      progress.step(40, "installing mcp");
+      const mcpConfigPaths = installAntigravityMcp({ installRoot });
+      progress.step(55, "warming embeddings");
+      const warmResult = await warmInstallEmbeddings();
+      progress.done("agy installed");
+      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(`Skill embeddings warmed: ${warmResult.skillCount || 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.`);
+    }
+
+    progress.step(10, "copying marketplace");
+    const marketplaceRoot = path.join(codexHome(), "marketplaces", "contextos");
+    copyPackageRoot({ rootDir, targetRoot: marketplaceRoot });
+
+    progress.step(20, "refreshing codex plugin");
+    tryRunCodex(["plugin", "remove", "ctx@contextos"]);
+    tryRunCodex(["plugin", "marketplace", "remove", "contextos"]);
+    tryRunCodex(["mcp", "remove", "ctx-mcp"]);
+    runCodex(["plugin", "marketplace", "add", marketplaceRoot]);
+    runCodex(["plugin", "add", "ctx@contextos"]);
+    progress.step(40, "installing mcp");
+    runCodex(["mcp", "add", "ctx-mcp", "--", "node", path.join(marketplaceRoot, "plugins", "ctx", "mcp", "server.js")]);
+    progress.step(50, "installing telemetry proxies");
+    const proxyResult = installMcpTelemetryProxies({ codexHome: codexHome(), marketplaceRoot });
+    progress.step(60, "installing hooks");
+    const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
 
-  if (agent === "agy") {
-    const installRoot = copyPackageRoot({ rootDir, targetRoot: agentInstallRoot("agy") });
-    const hooksPath = installAntigravityHooks({ installRoot, injectPromptContext: inject });
-    const mcpConfigPaths = installAntigravityMcp({ installRoot });
+    progress.step(70, "warming embeddings");
     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(", ")}`);
+    progress.done("codex installed");
+    console.log("Installed ctx through Codex plugin marketplace.");
+    console.log(`Stable marketplace root: ${marketplaceRoot}`);
+    console.log(`Installed ContextOS global hooks to ${hooksPath}`);
+    console.log("Installed ctx-mcp MCP server.");
+    console.log(`MCP telemetry proxies: ${proxyResult.wrapped.length ? proxyResult.wrapped.map((item) => item.name).join(", ") : "none changed"}`);
     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(`Skill embeddings warmed: ${warmResult.skillCount || 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.`);
+    console.log("Restart Codex if it was already running, then submit a task to trigger ContextOS.");
+  } catch (error) {
+    progress.fail("install failed");
+    throw error;
   }
-
-  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"]);
-  runCodex(["plugin", "marketplace", "add", marketplaceRoot]);
-  runCodex(["plugin", "add", "ctx@contextos"]);
-  runCodex(["mcp", "add", "ctx-mcp", "--", "node", path.join(marketplaceRoot, "plugins", "ctx", "mcp", "server.js")]);
-  const proxyResult = installMcpTelemetryProxies({ codexHome: codexHome(), marketplaceRoot });
-  const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
-
-  const warmResult = await warmInstallEmbeddings();
-  console.log("Installed ctx through Codex plugin marketplace.");
-  console.log(`Stable marketplace root: ${marketplaceRoot}`);
-  console.log(`Installed ContextOS global hooks to ${hooksPath}`);
-  console.log("Installed ctx-mcp MCP server.");
-  console.log(`MCP telemetry proxies: ${proxyResult.wrapped.length ? proxyResult.wrapped.map((item) => item.name).join(", ") : "none changed"}`);
-  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(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
-  console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
-  console.log("Restart Codex if it was already running, then submit a task to trigger ContextOS.");
 }
 
 async function warmInstallEmbeddings() {
@@ -309,9 +399,9 @@ const command = args[0];
 
 function installAgentFromArgs(args) {
   const agentFlag = args.indexOf("--agent");
-  if (agentFlag >= 0) return args[agentFlag + 1] || "";
+  if (agentFlag >= 0) return normalizeInstallAgent(args[agentFlag + 1] || "");
   const firstValue = args.slice(1).find((arg) => !arg.startsWith("--"));
-  return firstValue || "codex";
+  return normalizeInstallAgent(firstValue || "codex");
 }
 
 try {
@@ -322,7 +412,7 @@ try {
   } else if (command === "install") {
     await install({
       copy: args.includes("--copy"),
-      inject: !args.includes("--quiet"),
+      inject: args.includes("--inject") || !args.includes("--quiet"),
       agent: installAgentFromArgs(args)
     });
   } else if (command === "debug") {
@@ -364,6 +454,15 @@ try {
     } else {
       await syncRules({ cwd: process.cwd(), rootDir, args: args.slice(1) });
     }
+  } else if (command === "ruler" || command === "skillshare") {
+    const passthrough = parsePassthroughArgs(args);
+    const result = runPassthrough(passthrough);
+    if (result.signal) {
+      console.error(`${passthrough.command} terminated by signal ${result.signal}`);
+      process.exitCode = 1;
+    } else {
+      process.exitCode = result.status;
+    }
   } else {
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/lib/passthrough.js

@@ -0,0 +1,50 @@
+import { spawnSync } from "node:child_process";
+
+const SUPPORTED_COMMANDS = new Set(["ruler", "skillshare"]);
+
+export function parsePassthroughArgs(args = []) {
+  const command = args[0];
+  if (!SUPPORTED_COMMANDS.has(command)) {
+    throw new Error(`Unsupported passthrough command: ${command || ""}`);
+  }
+
+  const separator = args.indexOf("--");
+  if (separator < 0) {
+    throw new Error(`Usage: ctx ${command} -- <${command} args>`);
+  }
+
+  return {
+    command,
+    args: args.slice(separator + 1)
+  };
+}
+
+export function runPassthrough({
+  command,
+  args = [],
+  spawn = spawnSync,
+  cwd = process.cwd(),
+  env = process.env
+} = {}) {
+  if (!SUPPORTED_COMMANDS.has(command)) {
+    throw new Error(`Unsupported passthrough command: ${command || ""}`);
+  }
+
+  const result = spawn(command, args, {
+    cwd,
+    env,
+    stdio: "inherit"
+  });
+
+  if (result.error) {
+    const hint = command === "ruler"
+      ? "Install it with `npm install -g @intellectronica/ruler`."
+      : "Install it with `curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh`.";
+    throw new Error(`Failed to run ${command}: ${result.error.message}. ${hint}`);
+  }
+
+  return {
+    status: typeof result.status === "number" ? result.status : 1,
+    signal: result.signal || null
+  };
+}

package/plugins/ctx/lib/ruler-sync.js

@@ -7,6 +7,12 @@ import { execFileSync } from "node:child_process";
 const DEFAULT_AGENTS = ["codex", "claude", "antigravity"];
 const CTX_MCP_NAME = "ctx-mcp";
 const CONTEXTOS_PROXY_MARKER = "/contextos/plugins/ctx/mcp/proxy.js";
+const AGENT_ALIASES = new Map([
+  ["agy", "antigravity"],
+  ["antigravity", "antigravity"],
+  ["codex", "codex"],
+  ["claude", "claude"]
+]);
 
 function statusLine(label, value) {
   return `[ctx] ${label.padEnd(38)} ${value}`;
@@ -21,7 +27,7 @@ function runCommand(command, args, { cwd = process.cwd(), stdio = "pipe", dryRun
 export function parseSyncRulesArgs(args = []) {
   const agentsFlag = args.indexOf("--agents");
   const agents = agentsFlag >= 0
-    ? String(args[agentsFlag + 1] || "").split(",").map((item) => item.trim()).filter(Boolean)
+    ? normalizeAgentList(String(args[agentsFlag + 1] || "").split(","))
     : DEFAULT_AGENTS;
   return {
     rules: args.includes("--rules"),
@@ -33,6 +39,19 @@ export function parseSyncRulesArgs(args = []) {
   };
 }
 
+export function normalizeAgentName(agent) {
+  const key = String(agent || "").trim().toLowerCase();
+  return AGENT_ALIASES.get(key) || key;
+}
+
+export function normalizeAgentList(agents = []) {
+  return [...new Set(agents.map(normalizeAgentName).filter(Boolean))];
+}
+
+function displayAgentName(agent) {
+  return agent === "antigravity" ? "agy" : agent;
+}
+
 function codexConfigPath() {
   return path.join(process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex"), "config.toml");
 }
@@ -378,7 +397,7 @@ export function injectCtxMcp({ tomlPath, mcpServerPath, agents = DEFAULT_AGENTS,
 }
 
 export function runRulerApply({ agents = DEFAULT_AGENTS, cwd = process.cwd(), run = runCommand, dryRun = false } = {}) {
-  run("ruler", ["apply", "--agents", agents.join(",")], { cwd, stdio: "inherit", dryRun });
+  run("ruler", ["apply", "--agents", normalizeAgentList(agents).join(",")], { cwd, stdio: "inherit", dryRun });
 }
 
 function fileContains(filePath, pattern) {
@@ -481,7 +500,7 @@ export async function syncRules({
   logger("[ctx] Verifying sync...");
   const checks = options.dryRun ? options.agents.map((agent) => ({ agent, ok: true, filePath: "(dry-run)" })) : verifySync({ cwd, agents: options.agents });
   for (const check of checks) {
-    logger(`      → ctx-mcp in ${check.agent.padEnd(12)} ${check.ok ? "✓" : "not found"}${check.filePath ? ` ${check.filePath}` : ""}`);
+    logger(`      → ctx-mcp in ${displayAgentName(check.agent).padEnd(12)} ${check.ok ? "✓" : "not found"}${check.filePath ? ` ${check.filePath}` : ""}`);
   }
 
   const okCount = checks.filter((check) => check.ok).length;

package/plugins/ctx/lib/skillshare-sync.js

@@ -8,6 +8,12 @@ import { execFileSync, execSync } from "node:child_process";
 const DEFAULT_AGENTS = ["codex", "claude", "antigravity"];
 const INSTALL_SH_URL = "https://raw.githubusercontent.com/runkids/skillshare/main/install.sh";
 const INSTALL_PS_URL = "https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1";
+const AGENT_ALIASES = new Map([
+  ["agy", "antigravity"],
+  ["antigravity", "antigravity"],
+  ["codex", "codex"],
+  ["claude", "claude"]
+]);
 
 function statusLine(label, value) {
   return `[ctx] ${label.padEnd(38)} ${value}`;
@@ -28,7 +34,7 @@ function runShell(command, { cwd = process.cwd(), stdio = "inherit", dryRun = fa
 export function parseSyncSkillsArgs(args = []) {
   const agentsFlag = args.indexOf("--agents");
   const agents = agentsFlag >= 0
-    ? String(args[agentsFlag + 1] || "").split(",").map((item) => item.trim()).filter(Boolean)
+    ? normalizeAgentList(String(args[agentsFlag + 1] || "").split(","))
     : DEFAULT_AGENTS;
   return {
     skills: args.includes("--skills"),
@@ -39,6 +45,15 @@ export function parseSyncSkillsArgs(args = []) {
   };
 }
 
+function normalizeAgentName(agent) {
+  const key = String(agent || "").trim().toLowerCase();
+  return AGENT_ALIASES.get(key) || key;
+}
+
+function normalizeAgentList(agents = []) {
+  return [...new Set(agents.map(normalizeAgentName).filter(Boolean))];
+}
+
 export function detectOS(platform = process.platform) {
   if (platform === "darwin") return "mac";
   if (platform === "win32") return "windows";