@minhpnq1807/contextos 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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:
@@ -302,7 +307,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,12 +315,12 @@ 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`. |

package/bin/ctx.js

@@ -59,6 +59,68 @@ Usage:
 `;
 }
 
+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 +147,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 });
 
-  if (agent === "agy") {
-    const installRoot = copyPackageRoot({ rootDir, targetRoot: agentInstallRoot("agy") });
-    const hooksPath = installAntigravityHooks({ installRoot, injectPromptContext: inject });
-    const mcpConfigPaths = installAntigravityMcp({ installRoot });
+    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 });
+
+    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 +396,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 +409,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") {

package/package.json

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

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";