tirtc-device-builder 0.8.0 → 0.9.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 This project follows Semantic Versioning.
 
+## 0.9.0
+
+- Add native Skill-directory installation for Codex, Claude Code, OpenCode,
+  Gemini CLI, GitHub Copilot, Qwen Code, Windsurf Cascade, Cline, and Kiro.
+- Add `--client` support to both `install` and the resumable `setup` workflow,
+  plus a `clients` command that reports resolved user directories.
+- Keep one portable `SKILL.md` and supporting resource tree across clients,
+  while preserving explicit replacement and hardware-operation approvals.
+
+## 0.8.1
+
+- Separate rapid `idf.py flash` iteration from portable evidence-bundle export,
+  so active development keeps the normal `build/` tree and does not require a
+  new multi-BIN archive for every device test.
+- Add deterministic ESP-IDF application-descriptor inspection for explicit
+  firmware versions, application-BIN SHA-256, and full ELF SHA-256 matching.
+- Add product-control rules that distinguish MCU buttons, boot straps, reset
+  lines and PMIC/power-latch keys across baseboard and battery-carrier variants,
+  and route button gestures through the runtime's intent queue.
+- Add trace-based diagnosis for repeated AI/H5 downlink audio across SDK
+  callbacks, bounded queues, playback, resampling, and codec/I2S writes.
+
 ## 0.8.0
 
 - Add an evidence-backed board identity and curated registry workflow with exact,

package/README.md

@@ -1,6 +1,6 @@
 # TiRTC Device Builder
 
-TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Codex Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
+TiRTC Device Builder 用于把 ESP32-S3/ESP32-P4 开发板接入 TiRTC。输入可以只有开发板型号，也可以包含原理图、BSP、引脚表和外设示例。安装后的 Agent Skill 会先检查环境、整理有依据的硬件事实，再生成或移植独立的 ESP-IDF 工程并完成板级适配和编译。烧录和实机验证只有在开发者明确给出目标串口并授权后才会执行。
 
 当前仓库提供一个 Skill：
 
@@ -43,9 +43,15 @@ npm --version
 npx --yes tirtc-device-builder@latest setup esp32 --install
 ```
 
+默认安装到 Codex。使用其他客户端时增加 `--client`，例如：
+
+```bash
+npx --yes tirtc-device-builder@latest setup esp32 --install --client qwen-code
+```
+
 这条命令会：
 
-- 把 `tirtc-esp32-builder` 安装到 Codex Skill 目录；
+- 把 `tirtc-esp32-builder` 安装到所选 Agent 客户端的 Skill 目录；
 - 下载 ESP32 Device Kit 并校验 SHA-256；
 - 复用当前可用的 ESP-IDF 5.5.x，找不到时安装 ESP-IDF 5.5.4；
 - 安装 Espressif 管理的 ESP32-S3 工具链；
@@ -59,21 +65,21 @@ npx --yes tirtc-device-builder@latest setup esp32 --install
 ```text
 OVERALL: PASS
 SETUP: READY
-Start a new Codex session and invoke $tirtc-esp32-builder.
+Start a new Codex session, then ask it to use tirtc-esp32-builder.
 ```
 
 如果看到 `OVERALL: NEEDS_SETUP`、`MISS` 或 `FAIL`，先看[常见问题](#常见问题)。
 
-### 3. 重新打开 Codex
+### 3. 重新打开 Agent 客户端
 
-Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex 会话，再打开一个新会话。
+Skill 通常在 Agent 会话启动时被发现。安装完成后，关闭当前会话，再打开一个新会话。
 
-### 4. 把板卡和目标告诉 Codex
+### 4. 把板卡和目标告诉 Agent
 
 把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。先指定工作区根目录，本地路径尽量相对工作区填写；不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
 
 ```text
-请使用 $tirtc-esp32-builder 完成这块开发板的 TiRTC 移植。
+请使用 tirtc-esp32-builder Skill 完成这块开发板的 TiRTC 移植。
 
 开发板：
 - 厂商、完整型号、PCB/硬件版本：<填写>
@@ -339,25 +345,52 @@ tirtc-device-builder setup esp32 --install
 
 安装命令是 `npm install`，不要写成 `npm --install`。
 
-只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Codex Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
+只执行 `npm install --global tirtc-device-builder` 会安装 CLI，不会准备完整开发环境。随后还要运行 `setup esp32 --install`，由它安装 Agent Skill、下载 Device Kit，并在需要时安装 ESP-IDF。npm 包没有 `preinstall`、`install` 或 `postinstall` 生命周期脚本，因此不会在安装 CLI 时改动这些目录。
 
 安装公开包不需要执行 `npm login`；这个命令只和维护者发布新版本有关。
 
 ### 只安装 Skill
 
-如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Codex Skill：
+如果 ESP-IDF 和 Device Kit 已经由团队统一准备，可以只复制 Agent Skill：
 
 ```bash
 npx --yes tirtc-device-builder@latest install esp32
+npx --yes tirtc-device-builder@latest install esp32 --client gemini
 ```
 
 这条命令不安装 ESP-IDF，也不下载 Device Kit。完整的新用户环境仍建议使用 `setup esp32 --install`。
 
+### 支持的 Agent 客户端
+
+同一个 `tirtc-esp32-builder` Skill 会完整复制到所选客户端的原生目录，不维护客户端专用的内容副本。先用下面的命令查看当前机器解析出的目录：
+
+```bash
+npx --yes tirtc-device-builder@latest clients
+```
+
+| `--client` | 客户端 | 默认 Skill 根目录 |
+|---|---|---|
+| `codex` | Codex（默认） | `${CODEX_HOME:-~/.codex}/skills` |
+| `claude-code` | Claude Code | `~/.claude/skills` |
+| `opencode` | OpenCode | `${XDG_CONFIG_HOME:-~/.config}/opencode/skills` |
+| `gemini` | Gemini CLI | `~/.gemini/skills` |
+| `copilot` | GitHub Copilot | `~/.copilot/skills` |
+| `qwen-code` | Qwen Code | `~/.qwen/skills` |
+| `windsurf` | Windsurf Cascade | `~/.codeium/windsurf/skills` |
+| `cline` | Cline | `~/.cline/skills` |
+| `kiro` | Kiro | `~/.kiro/skills` |
+
+也可以使用 `claude`、`gemini-cli`、`github-copilot`、`qwen`、`cascade`、`kiro-cli` 等别名。`--skills-dir` 的优先级高于默认目录，适合项目级安装或客户端使用非默认配置目录的情况。
+
+`--client` 只选择 Skill 的安装目录和提示文案，不绑定模型服务。DeepSeek、Qwen、GLM、Kimi、OpenAI 或 Claude 等模型仍在对应客户端中配置；只要客户端能发现 Skill 并允许文件、终端等所需工具，就继续使用同一份工作流。
+
+Cline 当前还需要在 `Settings → Features → Enable Skills` 中启用实验性 Skills 功能；安装器不会修改客户端自身的权限或功能开关。
+
 ### 默认目录
 
 | 内容 | 默认位置 |
 |---|---|
-| Codex Skill | `${CODEX_HOME:-~/.codex}/skills/tirtc-esp32-builder` |
+| Agent Skill | 上表中所选目录下的 `tirtc-esp32-builder` |
 | 托管根目录 | `~/.tirtc-device-builder` |
 | Device Kit | `~/.tirtc-device-builder/kits/esp32s3/1.1.1` |
 | ESP-IDF | `~/.tirtc-device-builder/esp-idf-v5.5.4` |
@@ -436,6 +469,7 @@ npx --yes tirtc-device-builder@latest setup esp32
 ```bash
 npx --yes tirtc-device-builder@latest --help
 npx --yes tirtc-device-builder@latest list
+npx --yes tirtc-device-builder@latest clients
 npx --yes tirtc-device-builder@latest setup esp32 --help
 ```
 
@@ -549,7 +583,19 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/install_video_gate.py .
 idf.py build
 ```
 
-只安装实际请求能力的门禁。编译后把 BIN/ELF 的路径、大小和 SHA-256 写入 Hardware IR 的 `build_evidence.artifacts[]`，再运行 build 阶段评估。编译成功但语义门禁缺失或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
+只安装实际请求能力的门禁。编译后先核对固件内嵌版本、应用 BIN
+SHA-256 和完整 ELF SHA-256：
+
+```bash
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/firmware_identity.py \
+  build/<app>.bin --elf build/<app>.elf --expect-version <expected-version>
+```
+
+随后按
+[`firmware-delivery.md`](skills/tirtc-esp32-builder/references/firmware-delivery.md)
+选择快速真机迭代或可移植证据包；该文档也规定从 `build/` 记录迁移到
+`artifacts/` 时如何保持 Hardware IR 和报告一致。编译成功但语义门禁缺失
+或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
 
 生成器会把 TiRTC SDK 复制到工程的 `third_party/tirtc/`。此后工程不再依赖 `tirtc-server-example`，但换机编译仍需准备兼容的 ESP-IDF 5.5.x 工具链。
 
@@ -599,7 +645,10 @@ cd /absolute/path/my-esp32-device
 idf.py -p /dev/ttyACM0 flash monitor
 ```
 
-使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB 拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
+普通开发烧录优先使用这一条命令，让 ESP-IDF 从当前构建目录解析
+bootloader、分区表和应用镜像；无需手工维护多条 `esptool.py` 地址参数。
+使用 `Ctrl+]` 退出 ESP-IDF Monitor。多个串口同时存在时，需要通过 USB
+拔插、设备标识或芯片探测确认目标，不能默认烧录第一个端口。
 
 ### Wi-Fi 凭证和设备绑定
 
@@ -744,15 +793,16 @@ npx --yes tirtc-device-builder@latest setup esp32 --install \
 
 如果指定目录已存在但内容不完整或版本错误，安装器会拒绝覆盖。换一个空的新路径，或先人工备份原目录。
 
-### 安装完成后 Codex 找不到 Skill
+### 安装完成后 Agent 客户端找不到 Skill
 
-关闭当前 Codex 会话并重新打开。再检查默认文件是否存在：
+关闭当前 Agent 会话并重新打开。先查看客户端目录，再检查对应文件是否存在：
 
 ```bash
-ls -l ~/.codex/skills/tirtc-esp32-builder/SKILL.md
+npx --yes tirtc-device-builder@latest clients
+ls -l <skills-dir>/tirtc-esp32-builder/SKILL.md
 ```
 
-设置过 `CODEX_HOME` 或 `--skills-dir` 时，要检查对应目录。不要同时把 Skill 安装到多个位置。
+确认安装和启动的是同一个客户端，例如 Qwen Code 要使用 `--client qwen-code`。设置过 `CODEX_HOME`、`XDG_CONFIG_HOME` 或 `--skills-dir` 时，要检查对应目录。项目级目录由客户端自身规则决定，可以用 `--skills-dir` 显式指定。
 
 ### 已有 Skill，安装器拒绝覆盖
 
@@ -911,8 +961,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.8.0 -m "v0.8.0"
-git push origin v0.8.0
+git tag -a v0.9.0 -m "v0.9.0"
+git push origin v0.9.0
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/agent-clients.js

@@ -0,0 +1,141 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DEFAULT_AGENT_CLIENT = "codex";
+
+const CLIENTS = [
+  {
+    id: "codex",
+    displayName: "Codex",
+    aliases: ["codex"],
+    skillsDir(environment, home) {
+      const codexHome = environment.CODEX_HOME
+        ? resolve(environment.CODEX_HOME)
+        : join(home, ".codex");
+      return join(codexHome, "skills");
+    },
+  },
+  {
+    id: "claude-code",
+    displayName: "Claude Code",
+    aliases: ["claude-code", "claude"],
+    skillsDir(_environment, home) {
+      return join(home, ".claude", "skills");
+    },
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    aliases: ["opencode", "open-code"],
+    skillsDir(environment, home) {
+      const configHome = environment.XDG_CONFIG_HOME
+        ? resolve(environment.XDG_CONFIG_HOME)
+        : join(home, ".config");
+      return join(configHome, "opencode", "skills");
+    },
+  },
+  {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    aliases: ["gemini", "gemini-cli"],
+    skillsDir(_environment, home) {
+      return join(home, ".gemini", "skills");
+    },
+  },
+  {
+    id: "copilot",
+    displayName: "GitHub Copilot",
+    aliases: ["copilot", "github-copilot"],
+    skillsDir(_environment, home) {
+      return join(home, ".copilot", "skills");
+    },
+  },
+  {
+    id: "qwen-code",
+    displayName: "Qwen Code",
+    aliases: ["qwen-code", "qwen"],
+    skillsDir(_environment, home) {
+      return join(home, ".qwen", "skills");
+    },
+  },
+  {
+    id: "windsurf",
+    displayName: "Windsurf Cascade",
+    aliases: ["windsurf", "cascade"],
+    skillsDir(_environment, home) {
+      return join(home, ".codeium", "windsurf", "skills");
+    },
+  },
+  {
+    id: "cline",
+    displayName: "Cline",
+    aliases: ["cline"],
+    activationNote:
+      "Cline may require Settings > Features > Enable Skills before discovery.",
+    skillsDir(_environment, home) {
+      return join(home, ".cline", "skills");
+    },
+  },
+  {
+    id: "kiro",
+    displayName: "Kiro",
+    aliases: ["kiro", "kiro-cli"],
+    skillsDir(_environment, home) {
+      return join(home, ".kiro", "skills");
+    },
+  },
+];
+
+const CLIENT_BY_ALIAS = new Map(
+  CLIENTS.flatMap((client) =>
+    client.aliases.map((alias) => [alias, client]),
+  ),
+);
+
+function userHome(environment) {
+  if (process.platform === "win32") {
+    if (environment.USERPROFILE) {
+      return resolve(environment.USERPROFILE);
+    }
+    if (environment.HOMEDRIVE && environment.HOMEPATH) {
+      return resolve(`${environment.HOMEDRIVE}${environment.HOMEPATH}`);
+    }
+  } else if (environment.HOME) {
+    return resolve(environment.HOME);
+  }
+  return homedir();
+}
+
+export function listAgentClients() {
+  return CLIENTS;
+}
+
+export function resolveAgentClient(identifier) {
+  return CLIENT_BY_ALIAS.get(String(identifier).trim().toLowerCase()) ?? null;
+}
+
+export function requireAgentClient(identifier) {
+  const client = resolveAgentClient(identifier);
+  if (!client) {
+    throw new Error(
+      `unsupported client: ${identifier}; supported clients: ${CLIENTS.map((item) => item.id).join(", ")}`,
+    );
+  }
+  return client;
+}
+
+export function defaultSkillsDir(client, environment = process.env) {
+  const resolvedClient =
+    typeof client === "string" ? requireAgentClient(client) : client;
+  return resolvedClient.skillsDir(environment, userHome(environment));
+}
+
+export function clientSessionHint(client, skillName) {
+  const lines = [
+    `Start a new ${client.displayName} session, then ask it to use ${skillName}.`,
+  ];
+  if (client.activationNote) {
+    lines.push(client.activationNote);
+  }
+  return lines.join("\n");
+}

package/bin/setup-esp32.js

@@ -10,6 +10,13 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
+import {
+  clientSessionHint,
+  DEFAULT_AGENT_CLIENT,
+  defaultSkillsDir,
+  listAgentClients,
+  requireAgentClient,
+} from "./agent-clients.js";
 import { ESP32_KIT } from "./esp32-kit-metadata.js";
 
 const EXPECTED_IDF_LINE = "5.5";
@@ -43,10 +50,10 @@ function setupRootFrom(environment) {
   );
 }
 
-function takeValue(args, index, option) {
+function takeValue(args, index, option, kind = "a path") {
   const value = args[index + 1];
   if (!value || value.startsWith("--")) {
-    throw new Error(`${option} requires a path`);
+    throw new Error(`${option} requires ${kind}`);
   }
   return value;
 }
@@ -54,13 +61,15 @@ function takeValue(args, index, option) {
 export function parseSetupOptions(args, defaults = {}) {
   const environment = defaults.environment ?? process.env;
   const options = {
+    client:
+      defaults.client ?? requireAgentClient(DEFAULT_AGENT_CLIENT),
     forceSkill: false,
     help: false,
     idfDir: null,
     install: false,
     kitArchive: null,
     rootDir: setupRootFrom(environment),
-    skillsDir: defaults.skillsDir,
+    skillsDir: null,
     thingConnectRoot: null,
   };
 
@@ -78,6 +87,13 @@ export function parseSetupOptions(args, defaults = {}) {
       options.forceSkill = true;
       continue;
     }
+    if (argument === "--client") {
+      options.client = requireAgentClient(
+        takeValue(args, index, argument, "a name"),
+      );
+      index += 1;
+      continue;
+    }
     if (
       argument === "--root" ||
       argument === "--skills-dir" ||
@@ -103,9 +119,7 @@ export function parseSetupOptions(args, defaults = {}) {
     throw new Error(`unknown setup option: ${argument}`);
   }
 
-  if (!options.skillsDir) {
-    throw new Error("setup requires a default skills directory");
-  }
+  options.skillsDir ??= defaultSkillsDir(options.client, environment);
   if (options.forceSkill && !options.install) {
     throw new Error("--force-skill requires --install");
   }
@@ -123,8 +137,9 @@ Usage:
 
 Options:
   --install                    Install missing user-space components
+  --client <name>              Agent client (default: codex)
   --root <path>                Managed files (default: ~/.tirtc-device-builder)
-  --skills-dir <path>          Codex skills directory
+  --skills-dir <path>          Override the selected client's Skill directory
   --thing-connect-root <path>  Reuse an existing Device Kit or legacy workspace
   --kit-archive <path>         Install from a local verified Kit archive
   --idf-dir <path>             Reuse or install ESP-IDF at this path
@@ -133,12 +148,13 @@ Options:
 
 Examples:
   npx tirtc-device-builder setup esp32
-  npx tirtc-device-builder setup esp32 --install
+  npx tirtc-device-builder setup esp32 --install --client gemini
   npx tirtc-device-builder setup esp32 --install --root /opt/tirtc-dev
 
 Check mode is read-only. --install downloads the pinned ESP32 Device Kit,
 may clone ESP-IDF v5.5.4, runs Espressif's user-space tool installer, and
-installs the Codex Skill. It does not run sudo or edit shell profiles.`);
+installs the Agent Skill. It does not run sudo or edit shell profiles.
+Supported clients: ${listAgentClients().map((client) => client.id).join(", ")}.`);
 }
 
 function printCheck(status, name, detail) {
@@ -420,6 +436,7 @@ function writeManagedEnvironment(context, packageVersion) {
     device_kit_version: context.deviceKit.version,
     device_kit_root: context.thingConnectRoot,
     thing_connect_root: context.thingConnectRoot,
+    client: context.client.id,
     skills_dir: context.skillsDir,
   };
   writeAtomic(
@@ -542,6 +559,7 @@ function setupContext(options, runtime) {
   const skillVersion = readSkillVersion(skillTarget);
   return {
     activeIdf: active,
+    client: options.client,
     configPath,
     idf,
     idfDir,
@@ -569,8 +587,8 @@ function printState(context, runtime) {
   printCheck("INFO", "setup root", context.rootDir);
   printCheck(
     context.skillReady ? "PASS" : "MISS",
-    "Codex Skill",
-    `${context.skillTarget} (version ${
+    "Agent Skill",
+    `${context.client.displayName}: ${context.skillTarget} (version ${
       context.skillVersion || "missing"
     }; expected ${runtime.packageVersion})`,
   );
@@ -639,13 +657,13 @@ function installSkill(options, context, runtime) {
   const present = existsSync(join(context.skillTarget, "SKILL.md"));
   if (present && context.skillReady && !options.forceSkill) {
     console.log(
-      `SKIP  Codex Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
+      `SKIP  ${context.client.displayName} Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
     );
     return;
   }
   if (present && !options.forceSkill) {
     throw new Error(
-      `Codex Skill at ${context.skillTarget} has version ${
+      `${context.client.displayName} Skill at ${context.skillTarget} has version ${
         context.skillVersion || "missing"
       }, expected ${runtime.packageVersion}; rerun with --force-skill to replace it`,
     );
@@ -654,6 +672,8 @@ function installSkill(options, context, runtime) {
     runtime.cliPath,
     "install",
     runtime.platform.name,
+    "--client",
+    context.client.id,
     "--skills-dir",
     options.skillsDir,
   ];
@@ -830,8 +850,8 @@ export function runEsp32Setup(args, input) {
   let options;
   try {
     options = parseSetupOptions(args, {
+      client: input.defaultClient,
       environment: runtime.environment,
-      skillsDir: input.defaultSkillsDir,
     });
   } catch (error) {
     console.error(
@@ -849,8 +869,12 @@ export function runEsp32Setup(args, input) {
   if (!options.install) {
     if (!isReady(context)) {
       console.log("OVERALL: NEEDS_SETUP");
+      const clientOption =
+        context.client.id === "codex"
+          ? ""
+          : ` --client ${context.client.id}`;
       console.log(
-        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install`,
+        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install${clientOption}`,
       );
       return 1;
     }
@@ -867,7 +891,9 @@ export function runEsp32Setup(args, input) {
     return 1;
   }
   console.log("INSTALL PLAN:");
-  console.log(`  Skill:        ${context.skillTarget}`);
+  console.log(
+    `  Skill:        ${context.skillTarget} (${context.client.displayName})`,
+  );
   console.log(`  Device Kit:   ${context.thingConnectRoot} (${ESP32_KIT.version})`);
   console.log(`  ESP-IDF:      ${context.idfDir} (${PINNED_IDF_VERSION})`);
   console.log(`  IDF tools:    ${context.idfToolsPath || "existing default"}`);
@@ -917,6 +943,6 @@ export function runEsp32Setup(args, input) {
   }
   console.log("SETUP: READY");
   console.log(`Environment helper: ${join(context.rootDir, "env.sh")}`);
-  console.log("Start a new Codex session and invoke $tirtc-esp32-builder.");
+  console.log(clientSessionHint(context.client, runtime.platform.skill));
   return 0;
 }

package/bin/tirtc-device-builder.js

@@ -9,9 +9,15 @@ import {
   renameSync,
   rmSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  clientSessionHint,
+  DEFAULT_AGENT_CLIENT,
+  defaultSkillsDir,
+  listAgentClients,
+  requireAgentClient,
+} from "./agent-clients.js";
 import { runEsp32Setup } from "./setup-esp32.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -35,7 +41,8 @@ function printHelp() {
 
 Usage:
   tirtc-device-builder list
-  tirtc-device-builder install <platform> [--skills-dir <path>] [--force]
+  tirtc-device-builder clients
+  tirtc-device-builder install <platform> [--client <name>] [--skills-dir <path>] [--force]
   tirtc-device-builder setup <platform> [setup options]
   tirtc-device-builder doctor <platform> [doctor options]
   tirtc-device-builder boards <platform> <list|validate|match|init-identity|candidate> [options]
@@ -46,15 +53,18 @@ Platforms:
 
 Examples:
   npx tirtc-device-builder install esp32
+  npx tirtc-device-builder install esp32 --client qwen-code
   npx tirtc-device-builder setup esp32
-  npx tirtc-device-builder setup esp32 --install
+  npx tirtc-device-builder setup esp32 --install --client gemini
   npx tirtc-device-builder install esp32 --skills-dir /absolute/path/skills
   npx tirtc-device-builder doctor esp32 --project /absolute/path/project
   npx tirtc-device-builder boards esp32 match --identity ./board-identity.json
 
-Install defaults to ${"$"}{CODEX_HOME:-~/.codex}/skills. Existing skills are
-preserved unless --force is explicitly supplied. Setup checks are read-only;
-setup --install installs missing user-space components without running sudo.`);
+Install defaults to the selected client's user Skill directory; Codex is the
+default client. Run "clients" to list supported names and resolved directories.
+Existing skills are preserved unless --force is explicitly supplied. Setup
+checks are read-only; setup --install installs missing user-space components
+without running sudo.`);
 }
 
 function fail(message) {
@@ -71,17 +81,11 @@ function resolvePlatform(identifier) {
   return null;
 }
 
-function defaultSkillsDir() {
-  const codexHome = process.env.CODEX_HOME
-    ? resolve(process.env.CODEX_HOME)
-    : join(homedir(), ".codex");
-  return join(codexHome, "skills");
-}
-
 function parseInstallOptions(args) {
   const options = {
+    client: requireAgentClient(DEFAULT_AGENT_CLIENT),
     force: false,
-    skillsDir: defaultSkillsDir(),
+    skillsDir: null,
   };
 
   for (let index = 0; index < args.length; index += 1) {
@@ -90,6 +94,15 @@ function parseInstallOptions(args) {
       options.force = true;
       continue;
     }
+    if (argument === "--client") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--client requires a name");
+      }
+      options.client = requireAgentClient(value);
+      index += 1;
+      continue;
+    }
     if (argument === "--skills-dir") {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) {
@@ -102,6 +115,7 @@ function parseInstallOptions(args) {
     throw new Error(`unknown install option: ${argument}`);
   }
 
+  options.skillsDir ??= defaultSkillsDir(options.client);
   return options;
 }
 
@@ -151,8 +165,10 @@ function installSkill(platform, options) {
   if (movedExisting && existsSync(backup)) {
     rmSync(backup, { force: true, recursive: true });
   }
-  console.log(`Installed ${platform.skill} ${PACKAGE.version} to ${target}`);
-  console.log(`Start a new Codex session, then invoke $${platform.skill}.`);
+  console.log(
+    `Installed ${platform.skill} ${PACKAGE.version} for ${options.client.displayName} to ${target}`,
+  );
+  console.log(clientSessionHint(options.client, platform.skill));
 }
 
 function runDoctor(platform, args) {
@@ -214,6 +230,15 @@ function main(args) {
     }
     return 0;
   }
+  if (args[0] === "clients") {
+    for (const client of listAgentClients()) {
+      const marker = client.id === DEFAULT_AGENT_CLIENT ? " (default)" : "";
+      console.log(
+        `${client.id}\t${client.displayName}${marker}\t${defaultSkillsDir(client)}`,
+      );
+    }
+    return 0;
+  }
 
   const [command, identifier, ...rest] = args;
   if (
@@ -244,7 +269,7 @@ function main(args) {
     }
     return runEsp32Setup(rest, {
       cliPath: fileURLToPath(import.meta.url),
-      defaultSkillsDir: defaultSkillsDir(),
+      defaultClient: requireAgentClient(DEFAULT_AGENT_CLIENT),
       packageRoot: PACKAGE_ROOT,
       packageVersion: PACKAGE.version,
       platform,