@yhong91/cpac 0.1.39 → 0.1.41

package/README.md

@@ -10,7 +10,7 @@ CPAC 将 Codex 和 Claude Code 接入远端 CLIProxyAPI（CPA）：
 ## 要求
 
 - [Node.js](https://nodejs.org/) 20 或更新版本（npm 随 Node 安装）
-- 已安装需要使用的 agent：`codex`、`claude`、`pi`、`kimi`、`grok` 或 `zed`
+- 已安装需要使用的 agent：`codex`、`claude`、`pi`、`kimi`、`grok`、`zed` 或 `hermes`
 - 有权访问的 CPA API key
 
 ## 安装
@@ -37,7 +37,7 @@ echo 'export CPA_API_KEY="<你的key>"' >> ~/.zshrc && source ~/.zshrc
 cpac status
 
 # 4a. 持久注入（长期生效，写入 agent 配置，可完整恢复）
-cpac install --all                     # 注入所有检测到的目标（codex/pi/kimi/grok/zed）
+cpac install --all                     # 注入所有检测到的目标（codex/pi/kimi/grok/zed/hermes）
 cpac install codex                     # 只注入 Codex（默认开启 multi-agent v2）
 cpac install codex --v2_models         # 先多选 spawn_agent 模型再注入
 cpac install codex --max_context       # 注入时把模型上下文提升到实测上限（opt-in，仅限 codex）
@@ -61,7 +61,7 @@ cpac upgrade
 
 本节面向 AI agent：按顺序执行即可完成安装与配置，**全程无交互**。注意：`cpac codex --config` 和 `cpac claude --config` 的交互向导是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。
 
-1. **检查前置**：`node --version` ≥ 20；确认用户需要哪些 agent（`codex`/`claude`/`pi`/`kimi`/`grok`/`zed` 在 PATH 上）。向用户索取 CPA API key。
+1. **检查前置**：`node --version` ≥ 20；确认用户需要哪些 agent（`codex`/`claude`/`pi`/`kimi`/`grok`/`zed`/`hermes` 在 PATH 上）。向用户索取 CPA API key。
 
 2. **安装与密钥**：
 
@@ -90,14 +90,14 @@ cpac status   # 验证：各 target 显示 ready/injected
 ```
 
 1. **统一启动与配置**：
-   - 启动：`cpac <codex|claude|kimi|grok|pi|zed> [args...]`（所有原生参数如 `-c` 等原样透明传递）
+   - 启动：`cpac <codex|claude|kimi|grok|pi|zed|hermes> [args...]`（所有原生参数如 `-c` 等原样透明传递）
      - `setup` / `--setup`：配置 Codex/Claude，然后启动
      - `clear`：还原原生配置
    - 只写配置、不启动：`cpac setup [claude|codex]`；查看当前：`cpac setup`
 
-2. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi / Grok / Zed 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
+2. **已安装后升级**：npm 发布新版本后，等 publish 成功再执行 `cpac upgrade`。它会按需 `npm install -g`，再对已接入的 Codex / Pi / Kimi / Grok / Zed / Hermes 做 `sync`。不要拆成 `npm install -g @yhong91/cpac` 再手动 `cpac sync`。只刷新配置、不升 CLI 时才用 `cpac sync`。
 
-失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac <agent> clear` 或 `cpac restore <codex|pi|kimi|grok|zed>` 恢复原配置。
+失败处理：任何一步报错时先跑 `cpac status`；密钥未配置回到步骤 2；注入后异常用 `cpac <agent> clear` 或 `cpac restore <codex|pi|kimi|grok|zed|hermes>` 恢复原配置。
 
 ## 首次引导
 
@@ -113,7 +113,8 @@ Commands:
   cpac <agent> [args...] Launch an agent through CPA
   cpac setup            Show current Codex/Claude setup
   cpac status            Show agent support status
-  cpac restore <codex|pi|kimi|grok|zed> | --all  Detach injected agents
+  cpac models            List remote CPA catalog models
+  cpac restore <codex|pi|kimi|grok|zed|hermes> | --all  Detach injected agents
   cpac --help            Show command usage
 ```
 
@@ -161,26 +162,28 @@ cpac --help
 
 ### 统一管理（detect / install / sync / restore / uninstall / upgrade）
 
-参考 vibetime 的目标式命令，对 `codex`、`pi`、`kimi`、`grok`、`zed` 五个持久注入目标统一管理（claude 是临时接管，用 `cpac claude` 启动，不属于 install 目标）：
+参考 vibetime 的目标式命令，对 `codex`、`pi`、`kimi`、`grok`、`zed`、`hermes` 六个持久注入目标统一管理（claude 是临时接管，用 `cpac claude` 启动，不属于 install 目标）：
 
 ```bash
 cpac detect [--json]
-cpac install [codex|pi|kimi|grok|zed...] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context]
-cpac sync [codex|pi|kimi|grok|zed...] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context]
-cpac restore <codex|pi|kimi|grok|zed...> | --all [--dry-run]
+cpac models [--json]
+cpac install [codex|pi|kimi|grok|zed|hermes...] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context]
+cpac sync [codex|pi|kimi|grok|zed|hermes...] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context]
+cpac restore <codex|pi|kimi|grok|zed|hermes...> | --all [--dry-run]
 cpac uninstall [--dry-run]
 cpac upgrade [--check]
 cpac -v | --version
 ```
 
+- `models` 从远端 CPA 拉取 rich catalog，默认一行一个 slug；`--json` 输出 `cpa_url` 和模型字段（`slug` / `display_name` / `context_window`）。用来核对 catalog 里有没有某个模型（例如 `*-fast`），不写本地配置。
 - `detect` 列出每个目标是否被检测到、是否已接入 CPAC；`--json` 输出机器可读结果。
-- `install` 默认作用于检测到的目标；后面直接写 agent 名（`cpac install codex pi`），`--all` 全部。`codex` 写入 catalog 并拉起 loopback 代理；`pi`/`kimi`/`grok`/`zed` 写入各自配置。`--dry-run` 只打印将要做的事，`--force` 允许重装已安装目标。
-- `sync` 按当前 `cpa_url` 和 CPA 目录强制刷新**已经接入**的目标（Codex 重新注入、Pi 按 CLI 版本决定写入 packages / `pi update` / 跳过，并清理旧的 `extensions/pi-cpac.ts`、Kimi / Grok / Zed 配置重写），用来在 CPA 地址或模型目录变化后一次对齐本地配置。不带参数只动已安装目标；`--all` 会对检测到的目标做同样的强制刷新（尚未安装的会装上）。`--max_context` 仍只对 `cpac install codex` 有效。
+- `install` 默认作用于检测到的目标；后面直接写 agent 名（`cpac install codex pi`），`--all` 全部。`codex` 写入 catalog 并拉起 loopback 代理；`pi`/`kimi`/`grok`/`zed`/`hermes` 写入各自配置。`--dry-run` 只打印将要做的事，`--force` 允许重装已安装目标。
+- `sync` 按当前 `cpa_url` 和 CPA 目录强制刷新**已经接入**的目标（Codex 重新注入、Pi 按 CLI 版本决定写入 packages / `pi update` / 跳过，并清理旧的 `extensions/pi-cpac.ts`、Kimi / Grok / Zed / Hermes 配置重写），用来在 CPA 地址或模型目录变化后一次对齐本地配置。不带参数只动已安装目标；`--all` 会对检测到的目标做同样的强制刷新（尚未安装的会装上）。`--max_context` 仍只对 `cpac install codex` 有效。
 - Codex 注入默认开启 multi-agent v2（写入 `[features.multi_agent_v2] enabled = true`，catalog 行打 `multi_agent_version: "v2"`）；`install codex --v2_off` 关掉 toml 并去掉 catalog 戳。v2 开着时会剥掉 `[agents] max_threads`（Codex 否则拒启动）。`cpac status` 对照 config 里的 `v2_off` / `max_context` 和 live toml / catalog。服务端还需在 CPA 配置中开启 `codex.optimize-multi-agent-v2`。
 - `--v2_models` 进入 arrow-key 复选框选择最多 5 个 spawn_agent 模型（勾选顺序即推荐顺序），选择结果存入配置文件的 `spawn_models`，注入时把这些模型排到 `codex-models.json` 最前——Codex 客户端只把 catalog 前 5 个可见模型广告为 spawn 覆盖项。
 - `restore` 必须带 agent 名或 `--all`，卸掉指定（或全部）已注入目标。`--all` 时未安装的目标静默跳过。
 - `uninstall` 先用和 `cpac setup codex` 相同的方向键选择器确认（默认 Cancel），再 `restore --all`，最后 `npm uninstall -g @yhong91/cpac`。不要跟 agent 名；卸载的是 cpac 包本身。非终端取消。`--dry-run` 跳过确认。
-- `upgrade` 是发布后更新本机的一次性入口：查 npm → 需要时 `npm install -g` → 对**已接入**的 Codex / Pi / Kimi / Grok / Zed 执行 `sync`。已是最新也会 sync。不要先手动 `npm install -g` 再 `cpac sync`。`--check` 只报告版本，不安装也不 sync。没有已安装目标时跳过 sync，不报错。只刷新配置、不升 CLI 时用 `cpac sync`。
+- `upgrade` 是发布后更新本机的一次性入口：查 npm → 需要时 `npm install -g` → 对**已接入**的 Codex / Pi / Kimi / Grok / Zed / Hermes 执行 `sync`。已是最新也会 sync。不要先手动 `npm install -g` 再 `cpac sync`。`--check` 只报告版本，不安装也不 sync。没有已安装目标时跳过 sync，不报错。只刷新配置、不升 CLI 时用 `cpac sync`。
 
 ### Claude Code
 
@@ -250,9 +253,9 @@ Codex App 的长驻 `app-server` 可能缓存旧目录。注入会删除 `models
 
 注入命令可选 `--max_context`（`cpac install codex --max_context`，默认不带）：把 catalog 中 `max_context_window` 高于 `context_window` 的模型提升到上限，并把 `auto_compact_token_limit` 设为上限的 90%。Codex 把 `context_window` 当输入预算而非展示标签，上游默认保留保守运营值（如 GPT-5.6 家族 272k），带上该参数后可用到实测上限（约 921k，opencodex 实测）；90% 压缩线确保在硬上限前触发 auto-compact。不带参数注入的仍是原本上下文的目录。该参数仅限 codex，与其他 target 组合使用会直接报错。
 
-`config.toml` 不存在时拒绝注入。当前是 native 时把原文件备份到 `state_dir/codex/config.toml`（覆盖更旧的 native 快照）；已注入后再装不覆盖备份。kimi/grok/zed/pi 同样：没有旧配置不写空备份，native 覆盖旧快照，已接入则保留。所有 target 的 restore 都按 Codex 规则：注入后记下文件 hash；相对注入未改则逐字节还原备份（没有备份则删除我们创建的文件）；注入后改过则只剥 CPAC 字段，用户改动留下。没有其它需要代理的 agent 时才关闭代理。
+`config.toml` 不存在时拒绝注入。当前是 native 时把原文件备份到 `state_dir/codex/config.toml`（覆盖更旧的 native 快照）；已注入后再装不覆盖备份。kimi/grok/zed/hermes/pi 同样：没有旧配置不写空备份，native 覆盖旧快照，已接入则保留。所有 target 的 restore 都按 Codex 规则：注入后记下文件 hash；相对注入未改则逐字节还原备份（没有备份则删除我们创建的文件）；注入后改过则只剥 CPAC 字段，用户改动留下。没有其它需要代理的 agent 时才关闭代理。
 
-loopback 代理是 detached 用户进程，不安装系统服务。机器重启或进程意外退出后，`cpac status` 会报告 `loopback proxy stopped`；重新执行 `cpac install codex` 或 `cpac kimi` / `cpac grok` / `cpac zed` 即可恢复。
+loopback 代理是 detached 用户进程，不安装系统服务。机器重启或进程意外退出后，`cpac status` 会报告 `loopback proxy stopped`；重新执行 `cpac install codex` 或 `cpac kimi` / `cpac grok` / `cpac zed` / `cpac hermes` 即可恢复。
 
 默认路径：
 
@@ -264,6 +267,7 @@ CPAC state：~/.cpac/state.json（公用 proxy 字段 + 已接入 agent 记录
   Kimi   ~/.cpac/kimi/config.toml
   Grok   ~/.cpac/grok/config.toml
   Zed    ~/.cpac/zed/settings.json
+  Hermes ~/.cpac/hermes/config.yaml
   Pi     ~/.cpac/pi/settings.json
 restore / `<agent> clear` 会删掉该 agent 的备份目录和 state.json 里的对应记录
 ```
@@ -314,6 +318,23 @@ cpac restore zed
 
 配置目录尊重 `ZED_CONFIG_DIR`（否则 `$XDG_CONFIG_HOME/zed` 或 `~/.config/zed`）。首次写入前若 `settings.json` 已存在，会在 `state_dir/zed/settings.json` 保留原始快照。
 
+### Hermes Agent
+
+写入 CPA 的自定义 OpenAI-compatible provider 到 Hermes：
+
+```bash
+cpac install hermes
+cpac hermes
+```
+
+它在 `~/.hermes/config.yaml` 的 `providers.cpac` 写入 loopback `api`、占位 `api_key`、`api_mode: responses`，以及 CPA catalog 的 slug 列表（`discover_models: false`）。不改当前默认模型；切换用 `hermes model` 或 `/model`。密钥由 loopback 注入，不写进 `.env`。卸载：
+
+```bash
+cpac restore hermes
+```
+
+配置目录尊重 `HERMES_HOME`（Windows 默认 `%LOCALAPPDATA%\hermes`）。首次写入前若 `config.yaml` 已存在，会在 `state_dir/hermes/config.yaml` 保留原始快照。
+
 ## 环境变量
 
 | 变量 | 默认值 | 作用 |
@@ -323,6 +344,7 @@ cpac restore zed
 | `PI_CODING_AGENT_DIR` | `~/.pi/agent` | 覆盖 Pi agent 目录（影响 `settings.json` 写入位置） |
 | `KIMI_CODE_HOME` | `~/.kimi-code` | 覆盖 Kimi Code 目录（影响 `cpac install kimi` 写入位置） |
 | `ZED_CONFIG_DIR` | `~/.config/zed` | 覆盖 Zed 配置目录（影响 `cpac install zed` 写入位置） |
+| `HERMES_HOME` | `~/.hermes` | 覆盖 Hermes 目录（影响 `cpac install hermes` 写入位置） |
 | `CPAC_CONFIG` | `~/.config/cpac/config.json` | 指定可选 JSON 配置路径 |
 | `CODEX_HOME` | `~/.codex` | Codex home 目录 |
 

package/dist/agents.js

@@ -9,6 +9,7 @@ import { grokConfigPath, grokHome, installGrokConfig, isGrokConfigInstalled, uni
 import { installKimiConfig, isKimiConfigInstalled, kimiConfigPath, uninstallKimiConfig, } from "./targets/kimi.js";
 import { PI_PACKAGE, ensurePiExtension, isPiExtensionInstalled, piAgentDir, piSettingsPath, uninstallPiExtension, } from "./targets/pi.js";
 import { installZedConfig, isZedConfigInstalled, uninstallZedConfig, zedConfigPath, zedHome, } from "./targets/zed.js";
+import { hermesConfigPath, hermesHome, installHermesConfig, isHermesConfigInstalled, uninstallHermesConfig, } from "./targets/hermes.js";
 import { CPACError, atomicWrite, checkboxPicker, compareVersions, expandUserPath, objectValue, tabWizard, } from "./util.js";
 const CODEX_CTX_STD = "Standard (default input budget, e.g. 200K~272K)";
 const CODEX_CTX_MAX = "Max Context Window (lift to full upper bound, e.g. 921K~1M, 90% auto-compact limit)";
@@ -294,6 +295,27 @@ const TARGETS = [
             await uninstallZedConfig(config);
         },
     },
+    {
+        id: "hermes",
+        home: () => hermesHome(),
+        detected: () => binaryOnPath("hermes") || existsSync(hermesHome()),
+        installed: () => isHermesConfigInstalled(),
+        version: () => detectClientVersion("hermes"),
+        install: async (config, dryRun) => {
+            if (dryRun) {
+                console.log(`would write CPA provider: ${hermesConfigPath()}`);
+                return;
+            }
+            await installHermesConfig(config);
+        },
+        uninstall: async (config, dryRun) => {
+            if (dryRun) {
+                console.log(`would remove CPA provider: ${hermesConfigPath()}`);
+                return;
+            }
+            await uninstallHermesConfig(config);
+        },
+    },
 ];
 export async function detectTargets(config) {
     return TARGETS.map((target) => ({

package/dist/config.js

@@ -22,7 +22,7 @@ const CONFIG_KEYS = new Set([
 // spawn_agent overrides (codex-rs MAX_SPAWN_AGENT_MODEL_OVERRIDES).
 export const MAX_SPAWN_MODELS = 5;
 export const CLAUDE_SLOT_KEYS = ["opus", "sonnet", "haiku"];
-export const AGENT_IDS = ["codex", "pi", "kimi", "grok", "zed"];
+export const AGENT_IDS = ["codex", "pi", "kimi", "grok", "zed", "hermes"];
 const AGENT_ID_SET = new Set(AGENT_IDS);
 const STATE_KEYS = new Set([
     "config_path",
@@ -525,7 +525,7 @@ export function needsProxy(state) {
     if (state.config_path)
         return true;
     const agents = state.agents ?? {};
-    return Boolean(agents.codex || agents.kimi || agents.grok || agents.zed);
+    return Boolean(agents.codex || agents.kimi || agents.grok || agents.zed || agents.hermes);
 }
 export function saveState(stateDir, state) {
     atomicWrite(join(stateDir, "state.json"), Buffer.from(`${JSON.stringify(state, null, 2)}\n`));

package/dist/cpac.js

@@ -10,7 +10,8 @@ import { isGrokConfigInstalled } from "./targets/grok.js";
 import { isKimiConfigInstalled } from "./targets/kimi.js";
 import { isPiExtensionInstalled } from "./targets/pi.js";
 import { isZedConfigInstalled } from "./targets/zed.js";
-import { defaultConfigPath, loadConfig, originalBytes, pickSpawnModels, readState, saveSpawnModels, stateProxy, catalogMaxContextLive, } from "./config.js";
+import { isHermesConfigInstalled } from "./targets/hermes.js";
+import { defaultConfigPath, loadConfig, originalBytes, pickSpawnModels, readState, saveSpawnModels, stateProxy, catalogMaxContextLive, catalogModelId, catalogModelRows, catalogSlugs, fetchCatalog, } from "./config.js";
 import { proxyIsHealthy, runProxyChild } from "./proxy.js";
 import { CPACError, expandUserPath, promptSecret, saveApiKeyExport, shellProfile, } from "./util.js";
 export { PROVIDER, loadConfig, saveSpawnModels, saveCodexSetup, liftContextWindows, reorderCatalog, sanitizeCatalogModalities, stampMultiAgentVersion, catalogMaxContextLive, readState, stateProxy, } from "./config.js";
@@ -23,6 +24,7 @@ export { installGrokConfig, isGrokConfigInstalled, uninstallGrokConfig, } from "
 export { installKimiConfig, isKimiConfigInstalled, uninstallKimiConfig, } from "./targets/kimi.js";
 export { ensurePiExtension, installPiExtension, isPiExtensionInstalled, piPackageAction, piPackageVersion, uninstallPiExtension, } from "./targets/pi.js";
 export { installZedConfig, isZedConfigInstalled, uninstallZedConfig, ZED_PROVIDER_ID, } from "./targets/zed.js";
+export { installHermesConfig, isHermesConfigInstalled, uninstallHermesConfig, HERMES_PROVIDER_ID, } from "./targets/hermes.js";
 export async function status(config) {
     const apiKey = process.env[config.api_key_env]?.trim();
     const keyConfigured = !!apiKey;
@@ -76,6 +78,8 @@ export async function status(config) {
     console.log(`grok: ${keyConfigured ? (grokInstalled ? "ready" : "config not installed; run: cpac install grok") : "not configured"}`);
     const zedInstalled = isZedConfigInstalled();
     console.log(`zed: ${keyConfigured ? (zedInstalled ? "ready" : "config not installed; run: cpac install zed") : "not configured"}`);
+    const hermesInstalled = isHermesConfigInstalled();
+    console.log(`hermes: ${keyConfigured ? (hermesInstalled ? "ready" : "config not installed; run: cpac install hermes") : "not configured"}`);
     if (!state)
         return 1;
     const proxy = stateProxy(state);
@@ -83,12 +87,42 @@ export async function status(config) {
         return 2;
     return 0;
 }
+async function listModels(config, json) {
+    const apiKey = process.env[config.api_key_env]?.trim();
+    if (!apiKey)
+        throw new CPACError(`environment variable ${config.api_key_env} is not set`);
+    const catalog = await fetchCatalog(config.cpa_url, apiKey);
+    if (!json) {
+        for (const slug of catalogSlugs(catalog.bytes))
+            console.log(slug);
+        return 0;
+    }
+    const document = JSON.parse(new TextDecoder().decode(catalog.bytes));
+    const models = (catalogModelRows(document) ?? []).flatMap((row) => {
+        const slug = catalogModelId(row);
+        if (!slug)
+            return [];
+        const display = typeof row.display_name === "string" && row.display_name.trim()
+            ? row.display_name.trim()
+            : slug;
+        const context = typeof row.context_window === "number" && row.context_window > 0
+            ? Math.floor(row.context_window)
+            : undefined;
+        return [
+            context !== undefined
+                ? { slug, display_name: display, context_window: context }
+                : { slug, display_name: display },
+        ];
+    });
+    console.log(JSON.stringify({ cpa_url: config.cpa_url, count: models.length, models }, null, 2));
+    return 0;
+}
 async function guide(config) {
-    console.log(`CPA Companion\n\nCPA: ${config.cpa_url}\nCPA_API_KEY: ${process.env[config.api_key_env]?.trim() ? "configured" : "not configured"}\n\nCommands:\n  cpac <agent> [args...] Launch an agent (codex, kimi, grok, pi, zed, claude) through CPA\n  cpac setup            Show current Codex/Claude setup; cpac setup <codex|claude> to change\n  cpac status            Show agent support status (Codex, Claude, Pi, Kimi, Grok, Zed)\n  cpac restore <codex|pi|kimi|grok|zed> | --all  Detach injected agents
+    console.log(`CPA Companion\n\nCPA: ${config.cpa_url}\nCPA_API_KEY: ${process.env[config.api_key_env]?.trim() ? "configured" : "not configured"}\n\nCommands:\n  cpac <agent> [args...] Launch an agent (codex, kimi, grok, pi, zed, hermes, claude) through CPA\n  cpac setup            Show current Codex/Claude setup; cpac setup <codex|claude> to change\n  cpac status            Show agent support status (Codex, Claude, Pi, Kimi, Grok, Zed, Hermes)\n  cpac restore <codex|pi|kimi|grok|zed|hermes> | --all  Detach injected agents
   cpac detect            Show supported targets and install status
-  cpac install [codex|pi|kimi|grok|zed...]  Install CPA into detected targets, or named agents
-  cpac sync              Refresh installed Codex/Pi/Kimi/Grok/Zed injections from CPA
-  cpac uninstall         Detach all agents, then remove the cpac package (confirms first)\n  cpac upgrade           Update cpac from npm and sync installed agents\n  cpac --help            Show command usage`);
+  cpac install [codex|pi|kimi|grok|zed|hermes...]  Install CPA into detected targets, or named agents
+  cpac sync              Refresh installed Codex/Pi/Kimi/Grok/Zed/Hermes injections from CPA
+  cpac uninstall         Detach all agents, then remove the cpac package (confirms first)\n  cpac upgrade           Update cpac from npm and sync installed agents\n  cpac models            List remote CPA catalog models\n  cpac --help            Show command usage`);
     if (process.env[config.api_key_env]?.trim())
         return 0;
     const apiKey = await promptSecret(config.api_key_env);
@@ -98,41 +132,77 @@ async function guide(config) {
     console.log(`\nSaved ${config.api_key_env} to ${profile}. Open a new terminal or run:\n  source ${profile}`);
     return 0;
 }
+function helpRow(left, desc, tag = "", col = 34) {
+    const gap = Math.max(2, col - left.length);
+    const body = `${left}${" ".repeat(gap)}${desc}`;
+    if (!tag)
+        return `  ${body}`;
+    return `  ${body}${" ".repeat(Math.max(2, 70 - body.length))}${tag}`;
+}
 function usage() {
+    const cmd = (left, desc, tag = "") => helpRow(left, desc, tag);
+    const opt = (left, desc, tag = "") => helpRow(left, desc, tag, 18);
     return [
-        "Usage: cpac",
-        "       cpac <codex|kimi|grok|pi|zed|claude> [args...]",
-        "              setup|--setup     configure Codex/Claude, then launch",
-        "              clear             restore native config",
-        "       cpac setup     Show current Codex/Claude setup",
-        "              claude [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset]",
-        "              codex  [--v2_off] [--v2_models] [--max_context]",
-        "       cpac restore <codex|pi|kimi|grok|zed...> | --all [--dry-run]",
-        "       cpac status",
-        "       cpac detect [--json]",
-        "       cpac install [codex|pi|kimi|grok|zed...] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context]",
-        "       cpac sync [codex|pi|kimi|grok|zed...] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context]",
-        "       cpac uninstall [--dry-run]",
-        "       cpac upgrade [--check]",
-        "       cpac -v | --version",
+        "Usage: cpac [command]",
         "",
-        "launch an agent with `cpac <agent> [args...]` (remaining args forwarded).",
-        "`cpac <agent> setup` configures then launches; `cpac setup [claude|codex]` writes settings only.",
+        "Commands:",
+        cmd("cpac", "first-run guide and key setup", "[default]"),
+        cmd("cpac <agent> [args...]", "launch an agent through CPA"),
+        cmd("cpac <agent> setup", "configure Codex/Claude, then launch"),
+        cmd("cpac <agent> clear", "restore native config"),
+        cmd("cpac setup [claude|codex]", "show or write Codex/Claude setup"),
+        cmd("cpac status", "show agent support status"),
+        cmd("cpac models", "list remote CPA catalog models"),
+        cmd("cpac detect", "show supported targets and install status"),
+        cmd("cpac install [agent...]", "install CPA into detected or named agents"),
+        cmd("cpac sync [agent...]", "refresh installed injections from CPA"),
+        cmd("cpac restore <agent...>", "detach injected agents"),
+        cmd("cpac uninstall", "detach all agents, then remove the cpac package"),
+        cmd("cpac upgrade", "update cpac from npm and sync installed agents"),
+        "",
+        "Positionals:",
+        helpRow("agent", "codex, kimi, grok, pi, zed, hermes, or claude (claude is launch-only)", "", 18),
+        "",
+        "Options:",
+        opt("-h, --help", "show help", "[boolean]"),
+        opt("-v, --version", "show version number", "[boolean]"),
+        opt("    --config", "path to cpac config.json", "[string]"),
+        "",
+        "Command options:",
+        opt("--json", "JSON output", "[models, detect]"),
+        opt("--all", "every detected or installed agent", "[install, sync, restore]"),
+        opt("--dry-run", "print actions without writing", "[install, sync, restore, uninstall]"),
+        opt("--force", "allow reinstall of already-injected agents", "[install]"),
+        opt("--check", "report upgrade status without installing", "[upgrade]"),
+        opt("--v2_off", "disable Codex multi-agent v2", "[install, sync, setup codex]"),
+        opt("--v2_models", "pick spawn_agent models interactively", "[install, sync, setup codex]"),
+        opt("--max_context", "lift Codex context windows to measured max", "[install, sync, setup codex]"),
     ].join("\n");
 }
 function setupUsage() {
+    const cmd = (left, desc, tag = "") => helpRow(left, desc, tag);
+    const opt = (left, desc, tag = "") => helpRow(left, desc, tag, 18);
     return [
-        "Usage: cpac setup     Show current Codex/Claude setup",
-        "              claude [--opus [M]] [--sonnet [M]] [--haiku [M]] [--reset]",
-        "              codex  [--v2_off] [--v2_models] [--max_context]",
+        "Usage: cpac setup [claude|codex]",
         "",
-        "Claude slots (saved to config, applied on every `cpac claude`):",
-        "  --opus        heavy reasoning / planning fallback (ANTHROPIC_DEFAULT_OPUS_MODEL)",
-        "  --sonnet      main conversation default (ANTHROPIC_DEFAULT_SONNET_MODEL)",
-        "  --haiku       high-frequency small tasks (ANTHROPIC_DEFAULT_HAIKU_MODEL)",
+        "Commands:",
+        cmd("cpac setup", "show current Codex/Claude setup", "[default]"),
+        cmd("cpac setup claude", "configure Claude model slots"),
+        cmd("cpac setup codex", "configure Codex injection"),
         "",
-        "A slot without a value opens an arrow-key picker; --reset clears overrides.",
-        "No flags on a TTY opens the wizard. Does not launch; use `cpac claude setup` / `cpac codex setup` to start.",
+        "Claude options:",
+        opt("--opus [M]", "opus slot (omit M to pick)", "[string]"),
+        opt("--sonnet [M]", "sonnet slot (omit M to pick)", "[string]"),
+        opt("--haiku [M]", "haiku slot (omit M to pick)", "[string]"),
+        opt("--reset", "clear Claude slot overrides", "[boolean]"),
+        "",
+        "Codex options:",
+        opt("--v2_off", "disable Codex multi-agent v2", "[boolean]"),
+        opt("--v2_models", "pick spawn_agent models interactively", "[boolean]"),
+        opt("--max_context", "lift Codex context windows to measured max", "[boolean]"),
+        "",
+        "A slot without a value opens an arrow-key picker. No flags on a TTY opens the wizard.",
+        "Does not launch; use `cpac claude setup` / `cpac codex setup` to start.",
     ].join("\n");
 }
 function printSetup(config, configPath) {
@@ -157,7 +227,8 @@ function parseArgs(args) {
         args[0] === "sync" ||
         args[0] === "uninstall" ||
         args[0] === "restore" ||
-        args[0] === "upgrade") {
+        args[0] === "upgrade" ||
+        args[0] === "models") {
         const parsed = {
             command: args[0],
             configPath: defaultConfigPath(),
@@ -173,6 +244,10 @@ function parseArgs(args) {
         };
         for (let index = 1; index < args.length; index++) {
             const arg = args[index];
+            if (arg === "-h" || arg === "--help") {
+                console.log(usage());
+                return null;
+            }
             if (arg === "--json")
                 parsed.json = true;
             else if (arg === "--all")
@@ -225,7 +300,7 @@ function parseArgs(args) {
         }
         return parsed;
     }
-    if (["codex", "kimi", "grok", "pi", "zed", "claude"].includes(args[0])) {
+    if (["codex", "kimi", "grok", "pi", "zed", "hermes", "claude"].includes(args[0])) {
         const targetId = args[0];
         let configPath = defaultConfigPath();
         const raw = args.slice(1);
@@ -531,6 +606,8 @@ export async function main(args = process.argv.slice(2)) {
         const config = loadConfig(parsed.configPath, true);
         if (parsed.command === "guide")
             return await guide(config);
+        if (parsed.command === "models")
+            return await listModels(config, parsed.json);
         if (parsed.command === "detect")
             return await runDetect(config, parsed.json);
         if (parsed.command === "install") {
@@ -571,7 +648,7 @@ export async function main(args = process.argv.slice(2)) {
             });
         if (parsed.command === "uninstall") {
             if (parsed.targets.length || parsed.all) {
-                throw new CPACError("uninstall removes the cpac package; detach agents with: cpac restore <codex|pi|kimi|grok|zed> | --all");
+                throw new CPACError("uninstall removes the cpac package; detach agents with: cpac restore <codex|pi|kimi|grok|zed|hermes> | --all");
             }
             return await runUninstall(config, { dryRun: parsed.dryRun });
         }
@@ -623,7 +700,8 @@ export async function main(args = process.argv.slice(2)) {
         if (parsed.command === "kimi" ||
             parsed.command === "grok" ||
             parsed.command === "pi" ||
-            parsed.command === "zed") {
+            parsed.command === "zed" ||
+            parsed.command === "hermes") {
             return await runTargetLauncher(config, parsed.command, parsed.args);
         }
         return await status(config);

package/dist/proxy.js

@@ -329,7 +329,7 @@ export async function runProxy(config) {
         throw new CPACError("no active CPAC state; run cpac inject or install an agent first");
     const recorded = stateProxy(state);
     if (!recorded) {
-        throw new CPACError("state has no loopback proxy; run cpac inject or install kimi/grok/zed first");
+        throw new CPACError("state has no loopback proxy; run cpac inject or install kimi/grok/zed/hermes first");
     }
     if (await proxyIsHealthy(recorded)) {
         throw new CPACError(`loopback proxy is already running on 127.0.0.1:${recorded.port}`);

package/dist/targets/hermes.js

@@ -0,0 +1,236 @@
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { catalogModelId, catalogModelRows, dropAgent, fetchCatalog, recordWrittenConfig, restoreOwnedConfig, } from "../config.js";
+import { ensureLoopbackProxy, stopProxyProcess } from "../proxy.js";
+import { CPACError, atomicWrite, ensureCpacBackup, expandUserPath, resolveApiKey, } from "../util.js";
+export const HERMES_PROVIDER_ID = "cpac";
+export function hermesHome() {
+    const override = process.env.HERMES_HOME?.trim();
+    if (override)
+        return expandUserPath(override);
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA?.trim();
+        return join(local || join(homedir(), "AppData", "Local"), "hermes");
+    }
+    return join(homedir(), ".hermes");
+}
+export function hermesConfigPath() {
+    return join(hermesHome(), "config.yaml");
+}
+function lineIndent(line) {
+    const match = line.match(/^( *)/);
+    return match ? match[1].length : 0;
+}
+function mappingEnd(lines, startIdx, keyIndent) {
+    let i = startIdx + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            i += 1;
+            continue;
+        }
+        const indent = lineIndent(line);
+        if (indent > keyIndent) {
+            i += 1;
+            continue;
+        }
+        break;
+    }
+    while (i > startIdx + 1 && lines[i - 1].trim() === "")
+        i -= 1;
+    return i;
+}
+function providersRange(lines) {
+    const idx = lines.findIndex((line) => /^providers:\s*(?:#.*)?$/.test(line));
+    if (idx === -1)
+        return undefined;
+    return { idx, end: mappingEnd(lines, idx, 0) };
+}
+function childIndent(lines, mapStart, mapEnd, parentIndent) {
+    for (let i = mapStart + 1; i < mapEnd; i++) {
+        const line = lines[i];
+        if (!line.trim() || line.trimStart().startsWith("#"))
+            continue;
+        const indent = lineIndent(line);
+        if (indent > parentIndent)
+            return indent;
+    }
+    return parentIndent + 2;
+}
+function findCpacChild(lines, mapStart, mapEnd, indent) {
+    const prefix = `${" ".repeat(indent)}${HERMES_PROVIDER_ID}:`;
+    for (let i = mapStart + 1; i < mapEnd; i++) {
+        if (lines[i] === prefix ||
+            lines[i].startsWith(`${prefix} `) ||
+            lines[i].startsWith(`${prefix}\t`)) {
+            return { idx: i, end: mappingEnd(lines, i, indent) };
+        }
+    }
+    return undefined;
+}
+function yamlKey(key) {
+    if (/^[A-Za-z_][\w.-]*$/.test(key))
+        return key;
+    return JSON.stringify(key);
+}
+function cpacChildLines(port, rows, indent) {
+    const pad = (n) => " ".repeat(n);
+    const lines = [
+        `${pad(indent)}${HERMES_PROVIDER_ID}:`,
+        `${pad(indent + 2)}api: ${JSON.stringify(`http://[IP]:${port}/v1`)}`,
+        `${pad(indent + 2)}api_key: cpac`,
+        `${pad(indent + 2)}api_mode: responses`,
+        `${pad(indent + 2)}discover_models: false`,
+        `${pad(indent + 2)}models:`,
+    ];
+    let count = 0;
+    for (const row of rows) {
+        const slug = catalogModelId(row);
+        if (!slug)
+            continue;
+        const context = typeof row.context_window === "number" && row.context_window > 0
+            ? Math.floor(row.context_window)
+            : 200000;
+        lines.push(`${pad(indent + 4)}${yamlKey(slug)}:`);
+        lines.push(`${pad(indent + 6)}context_length: ${context}`);
+        count += 1;
+    }
+    if (count === 0)
+        throw new CPACError("CPA catalog contains no models");
+    return lines;
+}
+function mappingIsEmpty(lines, start, end, keyIndent) {
+    for (let i = start + 1; i < end; i++) {
+        const line = lines[i];
+        if (!line.trim() || line.trimStart().startsWith("#"))
+            continue;
+        if (lineIndent(line) > keyIndent)
+            return false;
+    }
+    return true;
+}
+function hasProvidersCpac(content) {
+    const lines = content.split(/\r?\n/);
+    const range = providersRange(lines);
+    if (!range)
+        return false;
+    const indent = childIndent(lines, range.idx, range.end, 0);
+    return Boolean(findCpacChild(lines, range.idx, range.end, indent));
+}
+export function isHermesConfigInstalled() {
+    try {
+        return hasProvidersCpac(readFileSync(hermesConfigPath(), "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+function stripProvidersCpac(content) {
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const lines = content.split(/\r?\n/);
+    const range = providersRange(lines);
+    if (!range)
+        return content;
+    const indent = childIndent(lines, range.idx, range.end, 0);
+    const child = findCpacChild(lines, range.idx, range.end, indent);
+    if (!child)
+        return content;
+    const next = [...lines.slice(0, child.idx), ...lines.slice(child.end)];
+    const providersEnd = mappingEnd(next, range.idx, 0);
+    if (mappingIsEmpty(next, range.idx, providersEnd, 0)) {
+        next.splice(range.idx, providersEnd - range.idx);
+    }
+    return next.join(eol).replace(/(?:\r?\n){3,}/g, `${eol}${eol}`);
+}
+function upsertProvidersCpac(content, port, rows) {
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const stripped = stripProvidersCpac(content);
+    const lines = stripped === "" ? [] : stripped.split(/\r?\n/);
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    const range = providersRange(lines);
+    if (!range) {
+        const block = ["providers:", ...cpacChildLines(port, rows, 2)];
+        if (lines.length === 0)
+            return `${block.join(eol)}${eol}`;
+        return `${lines.join(eol)}${eol}${block.join(eol)}${eol}`;
+    }
+    const inline = lines[range.idx]
+        .replace(/^providers:\s*/, "")
+        .replace(/#.*$/, "")
+        .trim();
+    if (inline && inline !== "{}" && inline !== "null") {
+        throw new CPACError("Hermes providers: must be a block mapping");
+    }
+    if (inline === "{}" || inline === "null")
+        lines[range.idx] = "providers:";
+    const end = mappingEnd(lines, range.idx, 0);
+    const indent = childIndent(lines, range.idx, end, 0);
+    const child = findCpacChild(lines, range.idx, end, indent);
+    const replacement = cpacChildLines(port, rows, indent);
+    if (child) {
+        return [
+            ...lines.slice(0, child.idx),
+            ...replacement,
+            ...lines.slice(child.end),
+        ].join(eol);
+    }
+    return [
+        ...lines.slice(0, range.idx + 1),
+        ...replacement,
+        ...lines.slice(range.idx + 1),
+    ].join(eol);
+}
+function writeHermesProvider(path, port, rows) {
+    let content = existsSync(path) ? readFileSync(path, "utf8") : "";
+    content = upsertProvidersCpac(content, port, rows);
+    if (!content.endsWith("\n"))
+        content += "\n";
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const mode = existsSync(path) ? statSync(path).mode & 0o7777 : 0o600;
+    atomicWrite(path, Buffer.from(content), mode);
+}
+export async function installHermesConfig(config) {
+    const apiKey = await resolveApiKey(config.api_key_env);
+    const catalog = await fetchCatalog(config.cpa_url, apiKey);
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder("utf-8").decode(catalog.bytes));
+    }
+    catch {
+        throw new CPACError("invalid CPA catalog");
+    }
+    const rows = catalogModelRows(document) ?? [];
+    if (rows.length === 0)
+        throw new CPACError("CPA catalog contains no models");
+    const { proxy, fingerprint, started } = await ensureLoopbackProxy(config, apiKey);
+    const target = hermesConfigPath();
+    const hadFile = existsSync(target);
+    try {
+        ensureCpacBackup(config.state_dir, "hermes", target, !isHermesConfigInstalled());
+        writeHermesProvider(target, proxy.port, rows);
+        recordWrittenConfig(config.state_dir, "hermes", target, {
+            id: proxy.id,
+            pid: proxy.pid,
+            port: proxy.port,
+            fingerprint,
+        }, hadFile);
+    }
+    catch (error) {
+        if (started)
+            await stopProxyProcess(proxy);
+        throw error;
+    }
+    console.log(`Installed Hermes provider "${HERMES_PROVIDER_ID}": ${target}`);
+}
+export async function uninstallHermesConfig(config) {
+    const target = hermesConfigPath();
+    if (!isHermesConfigInstalled())
+        throw new CPACError("Hermes CPAC provider is not installed");
+    restoreOwnedConfig(config.state_dir, "hermes", target, (current) => Buffer.from(stripProvidersCpac(new TextDecoder("utf-8").decode(current))));
+    const { stopProxy } = dropAgent(config.state_dir, "hermes");
+    if (stopProxy)
+        await stopProxyProcess(stopProxy);
+    console.log(`Removed Hermes provider "${HERMES_PROVIDER_ID}": ${target}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yhong91/cpac",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Connect Codex and Claude Code to a remote CLIProxyAPI gateway",
   "type": "module",
   "bin": {