@yhong91/cpac 0.1.40 → 0.1.42

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>` 恢复原配置。
 
 ## 首次引导
 
@@ -114,7 +114,7 @@ Commands:
   cpac setup            Show current Codex/Claude setup
   cpac status            Show agent support status
   cpac models            List remote CPA catalog models
-  cpac restore <codex|pi|kimi|grok|zed> | --all  Detach injected agents
+  cpac restore <codex|pi|kimi|grok|zed|hermes> | --all  Detach injected agents
   cpac --help            Show command usage
 ```
 
@@ -162,14 +162,14 @@ 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 models [--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 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
@@ -177,13 +177,13 @@ 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
 
@@ -253,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` 即可恢复。
 
 默认路径：
 
@@ -267,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 里的对应记录
 ```
@@ -309,7 +310,7 @@ cpac install zed
 cpac zed
 ```
 
-它在 `~/.config/zed/settings.json` 的 `language_models.openai_compatible.cpac` 写入 `api_url`（指向共享 loopback 代理）和 CPA 目录里的 `available_models`。模型走 Responses API（`chat_completions: false`），与 Pi / Grok 一致。密钥不写进 settings：Zed 读取 `CPAC_API_KEY`（任意非空即可，loopback 会换成真正的 `CPA_API_KEY`），也可在 Agent Settings 里为 `cpac` provider 填一次。卸载：
+它在 `~/.config/zed/settings.json` 的 `language_models.openai_compatible.cpac` 写入 `api_url`（指向共享 loopback 代理）和 CPA 目录里的 `available_models`。模型走 Responses API（`chat_completions: false`），与 Pi / Grok 一致。密钥不写进 settings：`cpac zed` 会注入占位 `CPAC_API_KEY`；从 Dock 打开 Zed 时在 Agent Settings 里给 `cpac` provider 填任意非空值（loopback 会换成真正的 `CPA_API_KEY`）。这是 Zed 内置 Agent 的 OpenAI-compatible provider，不是 Codex ACP（`codex-acp`）。卸载：
 
 ```bash
 cpac restore zed
@@ -317,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 `base_url`/`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` 保留原始快照。
+
 ## 环境变量
 
 | 变量 | 默认值 | 作用 |
@@ -326,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)";
@@ -133,7 +134,10 @@ export async function runTargetLauncher(config, targetId, args, executable = tar
         }
     }
     return await new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn(executable, args, { stdio: "inherit" });
+        const env = targetId === "zed"
+            ? { ...process.env, CPAC_API_KEY: process.env.CPAC_API_KEY || "cpac" }
+            : undefined;
+        const child = spawn(executable, args, { stdio: "inherit", env });
         child.once("error", (error) => {
             rejectPromise(new CPACError(error instanceof Error && "code" in error && error.code === "ENOENT"
                 ? `${executable} not found`
@@ -294,6 +298,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,6 +10,7 @@ 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 { 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";
@@ -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);
@@ -114,10 +118,10 @@ async function listModels(config, json) {
     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 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;
@@ -128,42 +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 models [--json]",
-        "       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]",
+        "",
+        "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]"),
         "",
-        "launch an agent with `cpac <agent> [args...]` (remaining args forwarded).",
-        "`cpac <agent> setup` configures then launches; `cpac setup [claude|codex]` writes settings only.",
+        "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) {
@@ -205,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")
@@ -257,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);
@@ -605,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 });
         }
@@ -657,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,237 @@
+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)}base_url: ${JSON.stringify(`http://[IP]:${port}/v1`)}`,
+        `${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.40",
+  "version": "0.1.42",
   "description": "Connect Codex and Claude Code to a remote CLIProxyAPI gateway",
   "type": "module",
   "bin": {