@myclaw163/clawclaw-cli 0.6.54

package/src/commands/meeting-history.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import { meetingHistoryCommandInternals } from './history.js';
+
+const allSeats = [
+  { name: 'A', seat: 1 },
+  { name: 'B', seat: 2 },
+  { name: 'C', seat: 3 },
+];
+
+describe('meeting history builder', () => {
+  it('outputs the compact meeting shape with found-in-meeting deaths and ordered speeches', () => {
+    const records = meetingHistoryCommandInternals.buildMeetingRecords([
+      { type: 'meeting_start', tick: 10, actor_name: 'A' },
+      { type: 'meeting_briefing', tick: 10, all_seats: allSeats },
+      {
+        type: 'meeting_state',
+        round: 1,
+        tick: 10,
+        sub_phase: 'entry',
+        speech_order: ['A', 'B'],
+        alive_players: ['A', 'B'],
+      },
+      {
+        type: 'meeting_state',
+        round: 1,
+        tick: 20,
+        sub_phase: 'vote',
+        speech_order: ['A', 'B'],
+        speeches: { B: '我没问题', A: '' },
+        speech_skipped: ['A'],
+        votes_submitted: ['A'],
+        alive_players: ['A', 'B'],
+      },
+      { type: 'no_exile', tick: 30, votes: { A: 'skip', B: 'skip' } },
+      { type: 'meeting_ended', tick: 31, result: 'skip', result_target: null },
+    ]);
+    const [meeting] = meetingHistoryCommandInternals.allMeetingOutputs(records);
+    expect(Object.keys(meeting)).toEqual([
+      'round',
+      'tick',
+      'caller',
+      'corpses_found',
+      'state',
+      'exiled_player',
+      'players',
+      'votes',
+      'speeches',
+    ]);
+    expect(meeting.corpses_found).toBeNull();
+    expect(meeting.state).toBe('ended');
+    expect(meeting.players).toEqual([
+      { name: 'A', seat: 1, status: 'alive', death: null },
+      { name: 'B', seat: 2, status: 'alive', death: null },
+      { name: 'C', seat: 3, status: 'dead', death: { type: 'found_in_meeting', round: 1 } },
+    ]);
+    expect(meeting.votes).toEqual({ A: 'skip', B: 'skip' });
+    expect(meeting.speeches).toEqual([
+      { speaker: 'A', text: '', skipped: true },
+      { speaker: 'B', text: '我没问题', skipped: false },
+    ]);
+  });
+
+  it('marks exiled players and carries death status into later meetings', () => {
+    const records = meetingHistoryCommandInternals.buildMeetingRecords([
+      { type: 'meeting_start', tick: 10, actor_name: 'A' },
+      { type: 'meeting_briefing', tick: 10, all_seats: allSeats },
+      { type: 'meeting_state', round: 1, tick: 10, sub_phase: 'vote', alive_players: ['A', 'B', 'C'] },
+      { type: 'exile', tick: 20, actor_name: 'B', votes: { A: 'B', C: 'B' } },
+      { type: 'meeting_ended', tick: 21, result: 'exiled', result_target: 'B' },
+      { type: 'meeting_start', tick: 100, actor_name: 'A' },
+      { type: 'meeting_briefing', tick: 100, all_seats: allSeats },
+      { type: 'meeting_state', round: 2, tick: 100, sub_phase: 'entry', alive_players: ['A', 'C'] },
+    ]);
+    const meetings = meetingHistoryCommandInternals.allMeetingOutputs(records);
+    expect(meetings[0].players.find((player: any) => player.name === 'B')).toEqual({
+      name: 'B',
+      seat: 2,
+      status: 'dead',
+      death: { type: 'exiled', round: 1 },
+    });
+    expect(meetings[1].players.find((player: any) => player.name === 'B')?.death).toEqual({ type: 'exiled', round: 1 });
+  });
+
+  it('keeps current unfinished meeting state from meeting_state', () => {
+    const records = meetingHistoryCommandInternals.buildMeetingRecords([
+      { type: 'meeting_start', tick: 10, actor_name: 'A' },
+      { type: 'meeting_briefing', tick: 10, all_seats: allSeats },
+      { type: 'meeting_state', round: 1, tick: 11, sub_phase: 'speech', current_speaker: 'B', alive_players: ['A', 'B', 'C'] },
+    ]);
+    const [meeting] = meetingHistoryCommandInternals.allMeetingOutputs(records);
+    expect(meeting.state).toBe('speech');
+    expect(meeting.speeches).toEqual([]);
+  });
+
+  it('marks an unfinished previous meeting interrupted when a new meeting starts', () => {
+    const records = meetingHistoryCommandInternals.buildMeetingRecords([
+      { type: 'meeting_start', tick: 10, actor_name: 'A' },
+      { type: 'meeting_briefing', tick: 10, all_seats: allSeats },
+      { type: 'meeting_start', tick: 100, actor_name: 'C' },
+      { type: 'meeting_briefing', tick: 100, all_seats: allSeats },
+    ]);
+    const meetings = meetingHistoryCommandInternals.allMeetingOutputs(records);
+    expect(meetings[0].state).toBe('interrupted_or_missing_end');
+    expect(meetings[1].state).toBe('interrupted_or_missing_end');
+  });
+});

package/src/commands/memory.ts

@@ -0,0 +1,40 @@
+import { existsSync, writeFileSync } from 'fs';
+import { Command } from 'commander';
+import { AuthStore } from '../lib/auth.js';
+import { getProfileMemoryFile } from '../lib/init-command.js';
+import { loadMemorySnapshot } from '../lib/load-context.js';
+
+function getMemoryFile(): string {
+  const profile = new AuthStore().getActive();
+  if (!profile) throw new Error('Not logged in.');
+  return getProfileMemoryFile(profile);
+}
+
+function ensureMemoryFile(path: string): void {
+  if (!existsSync(path)) writeFileSync(path, '');
+}
+
+export function createMemoryCommand(): Command {
+  const memory = new Command('memory');
+  memory
+    .alias('mem')
+    .description('Persistent strategy and run memory');
+
+  memory
+    .command('path')
+    .description('Print the absolute memory file path')
+    .action(() => {
+      const path = getMemoryFile();
+      ensureMemoryFile(path);
+      console.log(JSON.stringify({ path }, null, 2));
+    });
+
+  memory
+    .command('load')
+    .description('Read the memory file')
+    .action(() => {
+      console.log(JSON.stringify(loadMemorySnapshot(), null, 2));
+    });
+
+  return memory;
+}

package/src/commands/peek.ts

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+import { join } from 'path';
+import { AuthStore } from '../lib/auth.js';
+import { getProfileStateDir } from '../lib/init-command.js';
+import { snapshotOnce } from './watch.js';
+
+export interface RunPeekOptions {
+  stdout: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+/** One-shot snapshot of the local feed.json. Returns process exit code. */
+export function runPeek(opts: RunPeekOptions): number {
+  const stderr = opts.stderr ?? ((s) => process.stderr.write(s));
+  const store = new AuthStore();
+  const profile = store.getActive();
+  if (!profile) {
+    opts.stdout(JSON.stringify({ exit_reason: ['not_logged_in'], error: 'Not logged in' }) + '\n');
+    return 0;
+  }
+  const feedPath = join(getProfileStateDir(profile), 'feed.json');
+  try {
+    snapshotOnce({ feedPath, stdout: opts.stdout });
+    return 0;
+  } catch (err: any) {
+    stderr((err?.message ?? String(err)) + '\n');
+    return 1;
+  }
+}
+
+export function createPeekCommand(): Command {
+  return new Command('peek')
+    .description('Print a one-shot snapshot of current game state from the local feed (no HTTP, no streaming). Pairs with `ccl game start` for live updates and `ccl events` for history.')
+    .action(() => {
+      const code = runPeek({ stdout: (s) => process.stdout.write(s) });
+      if (code !== 0) process.exit(code);
+    });
+}

package/src/commands/persona.ts

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+import {
+  applyPersonaPreset,
+  ensurePersonaFile,
+  getActivePersonaFile,
+  listPersonaPresets,
+} from '../lib/persona.js';
+import { loadPersonaSnapshot } from '../lib/load-context.js';
+
+export function createPersonaCommand(): Command {
+  const persona = new Command('persona');
+  persona
+    .alias('prs')
+    .description('Per-account roleplay persona notes');
+
+  persona
+    .command('list')
+    .description('List bundled persona presets')
+    .action(() => {
+      const presets = listPersonaPresets().map(({ id, name }) => ({ id, name }));
+      console.log(JSON.stringify({ presets }, null, 2));
+    });
+
+  persona
+    .command('path')
+    .description('Print the absolute persona file path for the active account')
+    .action(() => {
+      const path = getActivePersonaFile();
+      ensurePersonaFile(path);
+      console.log(JSON.stringify({ path }, null, 2));
+    });
+
+  persona
+    .command('load')
+    .description('Read the active account persona file')
+    .action(() => {
+      console.log(JSON.stringify(loadPersonaSnapshot(), null, 2));
+    });
+
+  persona
+    .command('use <preset>')
+    .description('Copy a bundled persona preset into the active account persona file')
+    .action((presetName: string) => {
+      const path = getActivePersonaFile();
+      const preset = applyPersonaPreset(presetName, path);
+      console.log(JSON.stringify({
+        path,
+        preset: {
+          id: preset.id,
+          name: preset.name,
+        },
+        message: `Persona "${preset.name}" copied to active account.`,
+      }, null, 2));
+    });
+
+  return persona;
+}

package/src/commands/setup/codex.ts

@@ -0,0 +1,248 @@
+/**
+ * `ccl setup codex` — 使用 Codex 原生 `codex mcp add` 安装 ClawClaw MCP server
+ *
+ *   优先:   codex mcp add clawclaw -- <启动命令>
+ *   回退:   直接写 ~/.codex/config.toml(codex 不可用时)
+ *
+ * 用法:
+ *   ccl setup codex           # dry-run 预览
+ *   ccl setup codex -y        # 应用
+ *   ccl setup codex --print   # 仅输出等价命令行
+ */
+
+import { Command } from 'commander';
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, readFileSync, appendFileSync, copyFileSync, readdirSync, statSync as fsStatSync } from 'fs';
+import { spawnSync } from 'child_process';
+
+// ─── 路径解析 ──────────────────────────────────────────────────
+
+function resolveCodexConfigPath(): string {
+  const home = process.env.CODEX_HOME?.trim();
+  if (home) return join(home, 'config.toml');
+  return join(homedir(), '.codex', 'config.toml');
+}
+
+function resolveCodexClawclawEntry(): { command: string; args: string[] } | null {
+  const isWin = process.platform === 'win32';
+  const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+
+  // 1. dist/mcp-server.js 优先(编译后的纯 JS,无 tsx stdout 污染,最可靠)
+  const distCandidates = [
+    join(appData, 'npm', 'node_modules', 'codex-clawclaw', 'dist', 'mcp-server.js'),
+    join('D:', 'codex-clawclaw', 'dist', 'mcp-server.js'),
+  ];
+  for (const dist of distCandidates) {
+    try { if (existsSync(dist)) return { command: 'node', args: [dist] }; } catch { /* continue */ }
+  }
+
+  // 2. .mjs 包装器(bin/codex-clawclaw.mjs, 自注册 tsx, 直接 node 运行)
+  const mjsCandidates = [
+    join(appData, 'npm', 'node_modules', 'codex-clawclaw', 'bin', 'codex-clawclaw.mjs'),
+    join('D:', 'codex-clawclaw', 'bin', 'codex-clawclaw.mjs'),
+  ];
+  for (const mjs of mjsCandidates) {
+    try { if (existsSync(mjs)) return { command: process.execPath, args: [mjs] }; } catch { /* continue */ }
+  }
+
+  // 3. PATH 上找 bin(.cmd)
+  const cmdNames = isWin
+    ? ['codex-clawclaw.cmd', 'codex-clawclaw.ps1', 'codex-clawclaw']
+    : ['codex-clawclaw'];
+  const sep = isWin ? '\\' : '/';
+  const pathDirs = (process.env.PATH || '').split(isWin ? ';' : ':').filter(Boolean);
+  for (const dir of pathDirs) {
+    for (const name of cmdNames) {
+      const full = `${dir}${sep}${name}`;
+      try { if (existsSync(full)) return { command: full, args: [] }; } catch { /* continue */ }
+    }
+  }
+
+  // 4. 旧版路径(src/mcp-server.ts, 需搭配 tsx)
+  const tsCandidates = [
+    join(appData, 'npm', 'node_modules', 'codex-clawclaw', 'src', 'mcp-server.ts'),
+    join('D:', 'codex-clawclaw', 'src', 'mcp-server.ts'),
+  ];
+  for (const ts of tsCandidates) {
+    try { if (existsSync(ts)) return { command: process.execPath, args: [resolveTsxCli(), ts] }; } catch { /* continue */ }
+  }
+
+  return null;
+}
+
+function resolveTsxCli(): string {
+  const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+  const candidates = [
+    join(appData, 'npm', 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+    join('D:', 'codex-clawclaw', 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+  ];
+  for (const c of candidates) {
+    try { if (existsSync(c)) return c; } catch { /* continue */ }
+  }
+  return 'tsx';
+}
+
+/** 解析 codex CLI 的可执行文件路径(直接 .exe,不依赖 shell shim) */
+function resolveCodexExe(): string | null {
+  // 1. 从 config.toml 读取 CODEX_CLI_PATH(ccl 自己的全局配置)
+  const configPath = join(homedir(), '.clawclaw', 'config.json');
+  try {
+    if (existsSync(configPath)) {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+      if (cfg.codexCliPath && existsSync(cfg.codexCliPath)) return cfg.codexCliPath;
+    }
+  } catch { /* ignore */ }
+
+  // 2. 从 ~/.codex/config.toml 读取 CODEX_CLI_PATH 环境变量
+  //    搜索 AppData\Local\OpenAI\Codex\bin\ 下最新的 codex.exe
+  const appData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+  const codexBinDir = join(appData, 'OpenAI', 'Codex', 'bin');
+  try {
+    if (existsSync(codexBinDir)) {
+      const dirs = readdirSync(codexBinDir).filter((d: string) => {
+        try { return fsStatSync(join(codexBinDir, d)).isDirectory(); } catch { return false; }
+      }).sort().reverse(); // 最新版本优先
+      for (const d of dirs) {
+        const exe = join(codexBinDir, d, 'codex.exe');
+        try { if (existsSync(exe)) return exe; } catch { /* continue */ }
+      }
+    }
+  } catch { /* ignore */ }
+
+  // 3. PATH 上找 codex.cmd(Windows)
+  const pathDirs = (process.env.PATH || '').split(';').filter(Boolean);
+  for (const dir of pathDirs) {
+    const full = join(dir, 'codex.cmd');
+    try { if (existsSync(full)) return full; } catch { /* continue */ }
+  }
+
+  return null;
+}
+
+function codexMcpAvailable(): boolean {
+  const exe = resolveCodexExe();
+  if (!exe) return false;
+  try {
+    const r = spawnSync(exe, ['mcp', 'list', '--json'], {
+      env: { ...process.env, NO_COLOR: '1' },
+      windowsHide: true, timeout: 10_000, encoding: 'utf-8',
+    });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function codexMcpAlreadyRegistered(): boolean {
+  const exe = resolveCodexExe();
+  if (!exe) return false;
+  try {
+    const r = spawnSync(exe, ['mcp', 'list', '--json'], {
+      env: { ...process.env, NO_COLOR: '1' },
+      windowsHide: true, timeout: 10_000, encoding: 'utf-8',
+    });
+    if (r.status !== 0 || !r.stdout) return false;
+    const servers = JSON.parse(r.stdout);
+    return Array.isArray(servers) && servers.some((s: any) => s.name === 'clawclaw');
+  } catch { return false; }
+}
+
+// ─── Commander ─────────────────────────────────────────────────
+
+export function createSetupCodexSubcommand(): Command {
+  return new Command('codex')
+    .description('使用 codex mcp add 安装 ClawClaw MCP server(codex 不可用时回退到写 config.toml)。')
+    .option('-y, --yes', '应用更改(默认 dry-run)')
+    .option('--print', '仅输出推荐命令')
+    .action((opts: { yes?: boolean; print?: boolean }) => {
+      const entry = resolveCodexClawclawEntry();
+      if (!entry) {
+        console.log('未找到 codex-clawclaw。');
+        console.log('发布后: npm install -g codex-clawclaw');
+        console.log('本地开发: 在 codex-clawclaw 目录下 npm link');
+        process.exit(1);
+      }
+
+      const addArgs = ['mcp', 'add', 'clawclaw', '--', entry.command, ...entry.args];
+
+      if (opts.print) {
+        console.log('# 推荐执行:');
+        console.log(`codex ${addArgs.join(' ')}`);
+        console.log('');
+        console.log('# 等价 config.toml:');
+        console.log('[mcp_servers.clawclaw]');
+        console.log(`command = '${entry.command.replace(/\\/g, '\\\\')}'`);
+        console.log(`args = ${JSON.stringify(entry.args)}`);
+        console.log('startup_timeout_sec = 30');
+        return;
+      }
+
+      if (codexMcpAvailable() && codexMcpAlreadyRegistered()) {
+        console.log('ClawClaw MCP server 已注册。');
+        process.exit(0);
+      }
+
+      if (!opts.yes) {
+        console.log('待执行:');
+        console.log(`  codex ${addArgs.join(' ')}`);
+        if (!codexMcpAvailable()) {
+          console.log('');
+          console.log('(codex mcp 不可用,将回退到直接写 config.toml)');
+        }
+        console.log('');
+        console.log('Dry-run 模式。加 -y 以应用更改。');
+        process.exit(2);
+      }
+
+      // ── 应用: 优先 codex mcp add ──
+      if (codexMcpAvailable()) {
+        const r = spawnSync(resolveCodexExe()!, addArgs, {
+          env: { ...process.env, NO_COLOR: '1' },
+          windowsHide: true, timeout: 30_000, encoding: 'utf-8',
+        });
+        if (r.status !== 0) {
+          console.error('codex mcp add 失败:', r.stderr?.trim() || r.stdout?.trim() || `exit ${r.status}`);
+          process.exit(1);
+        }
+        console.log('已注册 ClawClaw MCP server(无需重启 Codex)。');
+        process.exit(0);
+      }
+
+      // ── 回退: 直接写 config.toml ──
+      const configPath = resolveCodexConfigPath();
+      if (!existsSync(configPath)) {
+        console.log('Codex config 未找到:', configPath);
+        console.log('请先运行 codex 完成初始化。');
+        process.exit(1);
+      }
+
+      let raw: string;
+      try { raw = readFileSync(configPath, 'utf-8'); } catch (e: any) {
+        console.error('读取失败:', e?.message ?? e);
+        process.exit(1);
+      }
+
+      if (/^\s*\[mcp_servers\.clawclaw\]/m.test(raw)) {
+        console.log('[mcp_servers.clawclaw] 已存在于 config.toml。');
+        process.exit(0);
+      }
+
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      copyFileSync(configPath, `${configPath}.bak.${ts}`);
+
+      const snippet = [
+        '',
+        '[mcp_servers.clawclaw]',
+        `command = '${entry.command.replace(/\\/g, '\\\\')}'`,
+        `args = ${JSON.stringify(entry.args)}`,
+        'startup_timeout_sec = 30',
+        '',
+      ].join('\n');
+      appendFileSync(configPath, snippet, 'utf-8');
+
+      console.log(`已更新 ${configPath}(备份: config.toml.bak.${ts})`);
+      console.log('');
+      console.log('重启 Codex 后生效。可用工具:');
+      console.log('  clawclaw_game_start / clawclaw_game_stop / clawclaw_game_status');
+      console.log('  clawclaw_do / clawclaw_state / clawclaw_events / ...');
+    });
+}

package/src/commands/setup/hermes.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { runHermesSetup } from './hermes.js';
+import { spawnSync } from 'child_process';
+
+vi.mock('child_process', () => ({
+  spawnSync: vi.fn(),
+}));
+
+const mockedSpawnSync = vi.mocked(spawnSync);
+
+function mockSpawn(overrides: Array<{ status: number; stdout?: string; stderr?: string }>) {
+  mockedSpawnSync.mockImplementation((_cmd: any, _args?: any, _opts?: any): any => {
+    const next = overrides.shift();
+    if (!next) throw new Error('Unexpected spawnSync call');
+    return {
+      status: next.status,
+      stdout: next.stdout ?? '',
+      stderr: next.stderr ?? '',
+    };
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('runHermesSetup', () => {
+  it('returns error when hermes CLI is not found', () => {
+    mockSpawn([{ status: 1, stderr: 'command not found' }]);
+    const r = runHermesSetup({});
+    expect(r.exitCode).toBe(1);
+    expect(r.output.some((l) => l.includes('not found'))).toBe(true);
+  });
+
+  it('reports already-enabled when clawclaw is in plugins list', () => {
+    mockSpawn([
+      { status: 0 },                                  // --version
+      { status: 0, stdout: 'clawclaw\nother-plugin' }, // plugins list
+    ]);
+    const r = runHermesSetup({});
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('already enabled'))).toBe(true);
+  });
+
+  it('dry-run shows pending message when not enabled', () => {
+    mockSpawn([
+      { status: 0 },                                  // --version
+      { status: 0, stdout: 'other-plugin' },           // plugins list
+    ]);
+    const r = runHermesSetup({});
+    expect(r.exitCode).toBe(2);
+    expect(r.output.some((l) => l.includes('Dry-run'))).toBe(true);
+  });
+
+  it('--print shows the command that would run', () => {
+    mockSpawn([
+      { status: 0 },                                  // --version
+      { status: 0, stdout: 'other-plugin' },           // plugins list
+    ]);
+    const r = runHermesSetup({ print: true });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('hermes plugins enable clawclaw'))).toBe(true);
+  });
+
+  it('-y runs hermes plugins enable and succeeds', () => {
+    mockSpawn([
+      { status: 0 },                                  // --version
+      { status: 0, stdout: 'other-plugin' },           // plugins list
+      { status: 0, stdout: 'plugin enabled' },         // plugins enable
+    ]);
+    const r = runHermesSetup({ yes: true });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('enabled'))).toBe(true);
+  });
+
+  it('-y handles hermes plugins enable failure', () => {
+    mockSpawn([
+      { status: 0 },                                  // --version
+      { status: 0, stdout: 'other-plugin' },           // plugins list
+      { status: 1, stderr: 'permission denied' },      // plugins enable
+    ]);
+    const r = runHermesSetup({ yes: true });
+    expect(r.exitCode).toBe(1);
+    expect(r.output.some((l) => l.includes('Failed'))).toBe(true);
+  });
+
+  it('already-enabled short-circuits --print', () => {
+    mockSpawn([
+      { status: 0 },                                  // --version
+      { status: 0, stdout: 'clawclaw' },               // plugins list
+    ]);
+    const r = runHermesSetup({ print: true });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('already enabled'))).toBe(true);
+  });
+});

package/src/commands/setup/hermes.ts

@@ -0,0 +1,76 @@
+/**
+ * `ccl setup hermes` — enable the clawclaw plugin in Hermes via `hermes plugins enable`.
+ */
+
+import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+
+export const PLUGIN_ID = 'clawclaw';
+
+export interface SetupHermesResult {
+  exitCode: number;
+  output: string[];
+}
+
+export function runHermesSetup(flags: { yes?: boolean; print?: boolean }): SetupHermesResult {
+  const out: string[] = [];
+
+  // Check hermes is available
+  const which = spawnSync('hermes', ['--version'], { stdio: 'pipe', timeout: 5000 });
+  if (which.status !== 0) {
+    out.push('hermes CLI not found. Install it first, then re-run.');
+    return { exitCode: 1, output: out };
+  }
+
+  // Check current plugin status
+  const list = spawnSync('hermes', ['plugins', 'list'], {
+    stdio: 'pipe',
+    timeout: 5000,
+    env: { ...process.env, HERMES_PLUGINS_DEBUG: '1' },
+  });
+  const listOutput = list.stdout?.toString() ?? '';
+  const alreadyEnabled = listOutput.includes(PLUGIN_ID) && !listOutput.includes(`${PLUGIN_ID} (disabled)`);
+
+  if (alreadyEnabled) {
+    out.push(`Plugin "${PLUGIN_ID}" is already enabled in Hermes.`);
+    return { exitCode: 0, output: out };
+  }
+
+  if (flags.print) {
+    out.push(`# Will run: hermes plugins enable ${PLUGIN_ID}`);
+    return { exitCode: 0, output: out };
+  }
+
+  if (!flags.yes) {
+    out.push(`Pending: hermes plugins enable ${PLUGIN_ID}`);
+    out.push(``);
+    out.push(`Dry-run only. Re-run with -y to apply.`);
+    return { exitCode: 2, output: out };
+  }
+
+  const result = spawnSync('hermes', ['plugins', 'enable', PLUGIN_ID], {
+    stdio: 'pipe',
+    timeout: 10000,
+  });
+
+  if (result.status !== 0) {
+    out.push(`Failed to enable plugin: ${result.stderr?.toString() ?? result.stdout?.toString() ?? 'unknown error'}`);
+    return { exitCode: 1, output: out };
+  }
+
+  out.push(`Plugin "${PLUGIN_ID}" enabled in Hermes.`);
+  out.push(`Verify: HERMES_PLUGINS_DEBUG=1 hermes plugins list`);
+  return { exitCode: 0, output: out };
+}
+
+export function createSetupHermesSubcommand(): Command {
+  return new Command('hermes')
+    .description('Enable the clawclaw plugin in Hermes via "hermes plugins enable".')
+    .option('-y, --yes', 'Apply changes (default is dry-run)')
+    .option('--print', 'Only print the command that would be run; do not execute')
+    .action((opts: { yes?: boolean; print?: boolean }) => {
+      const result = runHermesSetup({ yes: opts.yes, print: opts.print });
+      for (const line of result.output) console.log(line);
+      if (result.exitCode !== 0) process.exit(result.exitCode);
+    });
+}

package/src/commands/setup/index.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { createSetupOpenclawSubcommand } from './openclaw.js';
+import { createSetupHermesSubcommand } from './hermes.js';
+import { createSetupCodexSubcommand } from './codex.js';
+
+export function createSetupCommand(): Command {
+  const setup = new Command('setup');
+  setup.description('Install recommended config snippets into agent host config files.');
+  setup.addCommand(createSetupOpenclawSubcommand());
+  setup.addCommand(createSetupHermesSubcommand());
+  setup.addCommand(createSetupCodexSubcommand());
+  return setup;
+}