brainclaw 1.6.0 → 1.7.0

package/README.md

@@ -14,7 +14,7 @@ If you've ever:
 - watched two coworkers (or two agents) **edit the same files** without knowing it,
 - or **gave up running multiple agents in parallel** because keeping them in sync was a pain,
 
-brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
+brainclaw gives you durable shared state across sessions, agents, and teammates. Plans, claims, handoffs, decisions, and traps live in `.brainclaw/`, work identically across any compatible agent (Claude Code, Codex, Copilot, Cline, OpenCode, Cursor, Windsurf, Kilocode, Roo Code, Continue, Mistral Vibe, Hermes, Antigravity/Gemini CLI, …), and stay accessible whether you orchestrate them in parallel or pick them up one after another.
 
 Use it two ways — **together or separately**:
 
@@ -81,7 +81,8 @@ brainclaw is designed to sit alongside the coding agents teams are already using
 
 | Logo | Agent | Tier | What brainclaw configures |
 |---|---|---|---|
-| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
+| [![OpenClaw](https://img.shields.io/badge/OpenClaw-FF6B35?logoColor=white)](https://github.com/openclaw/openclaw) | **[OpenClaw](https://github.com/openclaw/openclaw)** | B | MCP + brainclaw skill (SKILL.md) for structured project memory |
+| [![Hermes](https://img.shields.io/badge/Hermes-111111?logoColor=white)](https://github.com/NousResearch/hermes-agent) | **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** | B | MCP + universal `.agents/skills/brainclaw/SKILL.md` |
 | [![NanoClaw](https://img.shields.io/badge/NanoClaw-4A90D9?logoColor=white)](https://github.com/qwibitai/nanoclaw) | **[NanoClaw](https://github.com/qwibitai/nanoclaw)** | C | brainclaw skill — messaging agent (WhatsApp, Telegram, Slack) |
 | [![NemoClaw](https://img.shields.io/badge/NemoClaw-76B900?logo=nvidia&logoColor=white)](https://github.com/NVIDIA/NemoClaw) | **[NemoClaw](https://github.com/NVIDIA/NemoClaw)** | C | brainclaw skill — NVIDIA enterprise agent stack |
 | [![PicoClaw](https://img.shields.io/badge/PicoClaw-00ADD8?logo=go&logoColor=white)](https://github.com/sipeed/picoclaw) | **[PicoClaw](https://github.com/sipeed/picoclaw)** | C | brainclaw skill — edge/IoT agent (Go, <10MB RAM) |
@@ -132,7 +133,7 @@ npm install -g brainclaw
 brainclaw setup-machine --yes
 ```
 
-This detects the installed agents on the current machine, writes the machine-level MCP and user config Brainclaw manages, and does **not** scan or initialize repositories.
+This detects the installed coding agents on the current machine, writes the machine-level MCP and user config Brainclaw manages for that detected set, and does **not** scan or initialize repositories.
 
 ### 4. Initialize or refresh the current project
 
@@ -231,7 +232,7 @@ Still sharp:
 1. **Same-checkout concurrent edits** — running two agents in the *same* working tree (no per-claim worktree) is still the wrong answer. Use the dispatch path (auto-worktree per claim) instead of raw concurrent CLI sessions.
 2. **Cross-machine sync** — federation across machines is on the roadmap, not in v1.x. Today brainclaw's store is local and one-machine-per-project.
 3. **Spawn-and-forget assumptions** — spawned workers don't always commit their work cleanly. The brief-ack file confirms the spawn started; in the worst case the coordinator harvests open changes.
-4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
+4. **Live state for hook-less agents** — Tier B/C agents without lifecycle hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, Hermes) get live context via `.live.md` companions regenerated on session-end and handoff, not via real-time push.
 
 Recommended use today:
 

package/dist/commands/mcp-schemas.generated.js

@@ -106,6 +106,25 @@ export const generatedSchemas = {
                                 ],
                                 "additionalProperties": false
                             },
+                            {
+                                "type": "object",
+                                "properties": {
+                                    "kind": {
+                                        "type": "string",
+                                        "const": "min_iterations"
+                                    },
+                                    "n": {
+                                        "type": "integer",
+                                        "exclusiveMinimum": 0,
+                                        "maximum": 9007199254740991
+                                    }
+                                },
+                                "required": [
+                                    "kind",
+                                    "n"
+                                ],
+                                "additionalProperties": false
+                            },
                             {
                                 "type": "object",
                                 "properties": {
@@ -161,6 +180,19 @@ export const generatedSchemas = {
                                 ],
                                 "additionalProperties": false
                             },
+                            {
+                                "type": "object",
+                                "properties": {
+                                    "kind": {
+                                        "type": "string",
+                                        "const": "no_open_questions"
+                                    }
+                                },
+                                "required": [
+                                    "kind"
+                                ],
+                                "additionalProperties": false
+                            },
                             {
                                 "type": "object",
                                 "properties": {
@@ -254,6 +286,7 @@ export const generatedSchemas = {
                     "open",
                     "assigned",
                     "working",
+                    "waiting_input",
                     "done",
                     "failed",
                     "cancelled"

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { buildClaimEnvPrefix } from '../core/execution-profile.js';
 import { fileURLToPath } from 'node:url';
@@ -35,10 +36,11 @@ import { buildOperationalIdentity, loadAllSessions, loadSessionById } from '../c
 import { validateMcpInput, validateMcpField } from '../core/input-validation.js';
 import { createCapability, createTool as createRegistryTool } from '../core/registries.js';
 import { detectAiAgent } from '../core/ai-agent-detection.js';
-import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
+import { checkGitPresence, scanGitRepos, parseRoots, parseRepoSelection, parseAgentSelection, getDetectedSetupAgentNames, getInstalledAgentNames, runGlobalInstall, initReposAndConfigureAgents, readSetupState, ALL_KNOWN_AGENTS, } from './setup.js';
+import { buildAgentInventory } from '../core/agent-inventory.js';
 import { resolveEffectiveCwd, resolveProjectRef, resolveTargetStore } from '../core/store-resolution.js';
 import { probeForQuickSetup, buildQuickSetupProbeResponse, buildOnboardingPreview } from '../core/setup-flow.js';
-import { ensureUserStore } from '../core/setup-state.js';
+import { ensureUserStore, resolveHomeDir } from '../core/setup-state.js';
 import { createPlan, addStep as addStepOp, completeStep as completeStepOp, updateStep as updateStepOp, deleteStep as deleteStepOp, deletePlan as deletePlanOp } from '../core/operations/plan.js';
 import { sendMessage, ackMessage, countActionable, getThread, hasActiveAssignment } from '../core/messaging.js';
 import { dispatch, dispatchReview, generateDispatchBrief } from '../core/dispatcher.js';
@@ -421,7 +423,7 @@ export const MCP_READ_TOOLS = [
 const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_dispatch',
-        description: 'Unified dispatch entry for sequence-lane parallelization (parallelize plans across lanes). To open a NEW review of a commit/branch, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` instead — bclaw_dispatch is for sequence-driven execution, NOT for opening reviews. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send to agents), review (routes an EXISTING already-reflected handoff to a reviewer — only for handoffs produced by `session-end --reflect-handoff` or similar). Consolidates the legacy bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review. Returns FacadeResponse; for verification semantics see the same response-validation guidance documented on `bclaw_coordinate`.',
+        description: 'Unified dispatch entry for sequence-lane parallelization (parallelize plans across lanes). To open a NEW review of a commit/branch, use `bclaw_coordinate(intent="review", open_loop=true, targetAgents=[…])` instead — bclaw_dispatch is for sequence-driven execution, NOT for opening new reviews. `intent` discriminator: analysis (sequence lane status, read-only), execute (default — analyze + generate briefs + send to agents), review (routes an EXISTING already-reflected handoff to a reviewer — only for handoffs produced by `session-end --reflect-handoff` or similar). Consolidates the legacy bclaw_dispatch_analysis / bclaw_dispatch / bclaw_dispatch_review. Returns FacadeResponse; for verification semantics see the same response-validation guidance documented on `bclaw_coordinate`.',
         annotations: { tier: 'facade', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
@@ -947,6 +949,8 @@ const MCP_WRITE_TOOLS = [
                 agent: { type: 'string', description: 'Caller agent name.' },
                 agentId: { type: 'string', description: 'Caller registered agent id.' },
                 project: { type: 'string', description: 'Optional (pln#359 phase 1b): name of a linked project to dispatch into. When set, claim/assignment/message all land in the target project — the target agent picks the brief up async via its own bclaw_work. Auto-spawn is disabled in cross-project mode. Accepts cross_project_links and workspace store-chain children (see `brainclaw link list`).' },
+                allow_dirty: { type: 'boolean', description: 'Override the scope-aware dirty-working-tree guard (trp#371 Tier 2). The guard runs only for worktree-spawning intents (assign/review/reroute) and blocks only when uncommitted files overlap — or cannot be proven disjoint from — the dispatch scope (the worker spawns from HEAD and will not see them). `.brainclaw/` and `.git/` are always excluded. Set true to proceed anyway (the block is downgraded to a warning that lists the overlapping files). Boolean; the string "true"/"false" are also coerced.' },
+                ref: { type: 'string', description: 'Optional git ref (commit/branch/tag) for assign/review/reroute: the dispatched worker builds its worktree from this ref instead of HEAD. When set, uncommitted working-tree changes are intentionally out of scope and the dirty guard allows the dispatch. Ignored by consult/ideate/summarize (no worktree).' },
             },
             required: ['intent', 'task'],
         },
@@ -1260,6 +1264,7 @@ export const FACADE_ORDER = [
     'bclaw_context',
     'bclaw_coordinate',
     'bclaw_dispatch',
+    'bclaw_dispatch_status',
     'bclaw_loop',
     'bclaw_setup',
 ];
@@ -2390,8 +2395,14 @@ async function _executeMcpToolCallInner(payload) {
                 const repos = scanGitRepos(roots);
                 const selectedRepos = parseRepoSelection(choice, repos, cwd);
                 const detected = detectAiAgent(env);
-                const agentList = ALL_KNOWN_AGENTS.map((a, i) => `  ${i + 1}) ${a}${a === detected?.name ? ' ← detected' : ''}`).join('\n');
-                return { response: toolResponse({ content: [{ type: 'text', text: `Selected ${selectedRepos.length} repo(s). Detected AI agent: ${detected?.name ?? 'none'}.\n\nAvailable agents:\n${agentList}\n\nAsk the user which agents to configure.` }], structuredContent: { pending_question: 'agent_selection', roots: rootsArg, repo_selection: choice, selected_repos: selectedRepos.map((r) => ({ path: r.path, name: r.name })), detected_agent: detected?.name ?? null, all_agents: ALL_KNOWN_AGENTS, prompt: 'Please ask the user: "Which agents to configure? Reply: (d)etected, (a)ll, or agent names like claude-code,cursor"' } }) };
+                const installedAgents = getInstalledAgentNames(buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env));
+                const detectedSetupAgents = getDetectedSetupAgentNames(detected?.name, installedAgents);
+                const agentList = ALL_KNOWN_AGENTS.map((a, i) => {
+                    const tag = a === detected?.name ? ' ← detected' : installedAgents.includes(a) ? ' ← installed' : '';
+                    return `  ${i + 1}) ${a}${tag}`;
+                }).join('\n');
+                const detectedLine = detectedSetupAgents.length > 0 ? `\nDetected install set: ${detectedSetupAgents.join(', ')}\n` : '\n';
+                return { response: toolResponse({ content: [{ type: 'text', text: `Selected ${selectedRepos.length} repo(s). Detected AI agent: ${detected?.name ?? 'none'}.${detectedLine}\nAvailable agents:\n${agentList}\n\nAsk the user which agents to configure.` }], structuredContent: { pending_question: 'agent_selection', roots: rootsArg, repo_selection: choice, selected_repos: selectedRepos.map((r) => ({ path: r.path, name: r.name })), detected_agent: detected?.name ?? null, installed_agents: installedAgents, detected_setup_agents: detectedSetupAgents, all_agents: ALL_KNOWN_AGENTS, prompt: 'Please ask the user: "Which agents to configure? Reply: (d)etected installed, (a)ll, or agent names like claude-code,cursor"' } }) };
             }
             if (step === 'agent_selection') {
                 if (!rootsArg || !repoSelectionArg) {
@@ -2401,7 +2412,8 @@ async function _executeMcpToolCallInner(payload) {
                 const repos = scanGitRepos(roots);
                 const selectedRepos = parseRepoSelection(repoSelectionArg, repos, cwd);
                 const detected = detectAiAgent(env);
-                const selectedAgents = parseAgentSelection(choice, detected?.name);
+                const installedAgents = getInstalledAgentNames(buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env));
+                const selectedAgents = parseAgentSelection(choice, detected?.name, installedAgents);
                 const summary = [];
                 const written = runGlobalInstall(selectedAgents, env);
                 for (const f of written)
@@ -4426,31 +4438,11 @@ async function _executeMcpToolCallInner(payload) {
                     };
                 }
             }
-            // can_30c295b4 — pre-flight uncommitted-changes check.
-            // Dispatches that spawn a worker (review/assign/consult/ideate) clone
-            // the source repo at HEAD into a worktree. Any uncommitted edits in
-            // the source cwd are invisible to the worker, so the worker reviews
-            // stale code without any error signal. Refuse the dispatch by default
-            // when the source cwd is a git repo with a dirty working tree.
-            // Override via allow_dirty=true when the caller knows the dispatched
-            // work doesn't depend on the modified files (e.g. tests, docs-only
-            // worker tasks). Has no effect when cwd is not a git repo.
-            if (!req.allow_dirty && (req.intent === 'review' || req.intent === 'assign' || req.intent === 'consult' || req.intent === 'ideate')) {
-                try {
-                    const { spawnSync } = await import('node:child_process');
-                    const probe = spawnSync('git', ['-C', cwd, 'status', '--porcelain'], { encoding: 'utf8', timeout: 5000 });
-                    if (probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim().length > 0) {
-                        const fileCount = probe.stdout.trim().split('\n').length;
-                        return {
-                            response: createToolErrorResponse('dirty_working_tree', `Refusing to dispatch: source working tree has ${fileCount} uncommitted file(s). The spawned worker will not see these changes (worktrees branch from HEAD). Commit or stash before dispatching, or pass allow_dirty=true to override. Source cwd: ${cwd}`),
-                        };
-                    }
-                    // probe.status !== 0 → not a git repo (or git unavailable) → skip the check silently
-                }
-                catch {
-                    // best-effort: never block dispatch on a pre-flight check failure unrelated to the actual dirty state
-                }
-            }
+            // can_30c295b4 / trp#371 Tier 2 — the scope-aware dirty-working-tree
+            // guard runs LOWER DOWN, after dispatchCwd / isCrossProject are
+            // resolved (so it probes the dispatch TARGET, not the source, and only
+            // for the intents that actually spawn a worktree worker). See the
+            // assessDirtyDispatchGuard call after the cross-project block.
             const warnings = [];
             const artifacts = [];
             const side_effects = [];
@@ -4504,6 +4496,43 @@ async function _executeMcpToolCallInner(payload) {
                 warnings.push(`cross-project dispatch (project='${req.project}') — auto-spawn disabled; the target agent picks up the brief async via its own bclaw_work.`);
             }
             const effectiveAutoExecute = isCrossProject ? false : req.autoExecute;
+            // can_30c295b4 / trp#371 Tier 2 — scope-aware dirty-working-tree guard.
+            // Only intents that spawn a worktree worker from HEAD can review/edit
+            // stale code, so consult/ideate/summarize are NOT guarded (no worktree
+            // → nothing to protect). Cross-project dispatch is inbox-only (no local
+            // worktree spawned here) so it is skipped too — the target agent builds
+            // its own worktree later via bclaw_work. The guard compares the dirty
+            // files against the dispatch scope and only blocks when overlap can't be
+            // ruled out; allow_dirty=true downgrades a block to a warning, and an
+            // explicit ref makes working-tree dirt intentionally out of scope.
+            const WORKTREE_SPAWNING_INTENTS = new Set(['assign', 'review', 'reroute']);
+            if (!isCrossProject && WORKTREE_SPAWNING_INTENTS.has(req.intent)) {
+                // Probe with the SAME scope the dispatch will actually claim, so the
+                // resolution mirrors reality (codex r1): assign falls back to the task
+                // text (mcp ~assignScope), reroute to the targeted active claim's scope.
+                let guardScope = req.scope;
+                if (req.intent === 'assign') {
+                    guardScope = req.scope ?? req.task;
+                }
+                else if (req.intent === 'reroute' && !req.scope) {
+                    guardScope = listClaims(dispatchCwd).find((c) => c.status === 'active')?.scope;
+                }
+                const { assessDirtyDispatchGuard } = await import('../core/dirty-scope.js');
+                const assessment = assessDirtyDispatchGuard({
+                    cwd: dispatchCwd,
+                    scope: guardScope,
+                    allowDirty: req.allow_dirty,
+                    checkoutRef: req.ref,
+                });
+                if (assessment.decision === 'block') {
+                    return {
+                        response: createToolErrorResponse('dirty_working_tree', `${assessment.reason} (cwd: ${dispatchCwd})`),
+                    };
+                }
+                if (assessment.decision === 'warn') {
+                    warnings.push(`dirty_working_tree: ${assessment.reason}`);
+                }
+            }
             /** Run E2E execution phase on prepared delivery entries. Returns overall execution status. */
             const runCoordinateExecution = async (prepared, opts) => {
                 let overall = 'inbox_only';
@@ -4756,6 +4785,10 @@ async function _executeMcpToolCallInner(payload) {
                         dispatcherAgent: senderAgent,
                         sessionId: connectionSessionId,
                         cwd: dispatchCwd,
+                        // createCoordinatorClaim guarantees the worktree reflects this ref
+                        // (resets a stale branch / re-points a reused worktree) — see the
+                        // worktreeBaseRef invariant there (pln#520 Tier 2).
+                        worktreeBaseRef: req.ref,
                     });
                     const claimId = claimResult.claimId;
                     if (claimResult.worktreeWarning) {
@@ -4996,6 +5029,7 @@ async function _executeMcpToolCallInner(payload) {
                                     dispatcherAgent: senderAgent,
                                     sessionId: connectionSessionId,
                                     cwd: dispatchCwd,
+                                    worktreeBaseRef: req.ref,
                                 });
                                 if (claimResult.worktreeWarning)
                                     out.warnings.push(claimResult.worktreeWarning);
@@ -5184,6 +5218,7 @@ async function _executeMcpToolCallInner(payload) {
                             dispatcherAgent: senderAgent,
                             sessionId: connectionSessionId,
                             cwd: dispatchCwd,
+                            worktreeBaseRef: req.ref,
                         });
                         newClaimId = rerouteClaimResult.claimId;
                         if (rerouteClaimResult.worktreeWarning) {

package/dist/commands/setup.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
@@ -7,7 +8,7 @@ import { detectAiAgent } from '../core/ai-agent-detection.js';
 import { buildAiSurfaceInventory, renderAiSurfaceUsageHints } from '../core/ai-surface-inventory.js';
 import { buildMachineProfile, saveMachineProfile, loadMachineProfile } from '../core/machine-profile.js';
 import { buildAgentInventory, saveAgentInventory, loadAgentInventory } from '../core/agent-inventory.js';
-import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
+import { ensureClaudeCodeUserSettings, ensureClaudeCodeUserCommand, ensureCursorMcpConfig, ensureWindsurfMcpConfig, ensureAntigravityMcpConfig, ensureContinueUserMcpConfig, ensureContinueUserPermissions, ensureCodexMcpConfig, ensureHermesMcpConfig, writeDetectedAgentAutoConfig, describeAutoConfigWrite, ensureGitignoreEntries, collectWorkspaceGitignoreEntries, BRAINCLAW_EXCLUSIVE_DIRECTORIES, } from '../core/agent-files.js';
 import { MEMORY_DIR, memoryExists, ensureMemoryDir } from '../core/io.js';
 import { saveConfig, defaultConfig } from '../core/config.js';
 import { readSetupState, resolveHomeDir, writeSetupState } from '../core/setup-state.js';
@@ -25,6 +26,9 @@ export const ALL_KNOWN_AGENTS = [
     'antigravity',
     'continue',
     'roo',
+    'kilocode',
+    'mistral-vibe',
+    'hermes',
     'openclaw',
     'nanoclaw',
     'nemoclaw',
@@ -135,13 +139,46 @@ export function parseRepoSelection(choice, repos, cwd = process.cwd()) {
     return indices.map((i) => repos[i]);
 }
 // ─── Step 4: Agent selection ──────────────────────────────────────────────────
-export function parseAgentSelection(choice, detected) {
+function uniqueKnownAgents(names) {
+    const seen = new Set();
+    const result = [];
+    for (const name of names) {
+        if (!name || !ALL_KNOWN_AGENTS.includes(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        result.push(name);
+    }
+    return result;
+}
+export function getInstalledAgentNames(inventory) {
+    return uniqueKnownAgents(inventory?.agents.filter((agent) => agent.installed).map((agent) => agent.name) ?? []);
+}
+export function getDetectedSetupAgentNames(detected, installedAgents = []) {
+    return uniqueKnownAgents([
+        detected,
+        ...ALL_KNOWN_AGENTS.filter((agent) => installedAgents.includes(agent)),
+    ]);
+}
+export function parseAgentSelection(choice, detected, installedAgents = []) {
     const c = choice.trim().toLowerCase();
     if (c === 'a' || c === 'all')
         return [...ALL_KNOWN_AGENTS];
-    if (c === 'd' || c === 'detected')
-        return detected ? [detected] : [];
-    return c.split(',').map((a) => a.trim()).filter((a) => ALL_KNOWN_AGENTS.includes(a));
+    if (c === 'd' || c === 'detected' || c === 'installed') {
+        return getDetectedSetupAgentNames(detected, installedAgents);
+    }
+    const selected = [];
+    for (const token of c.split(',').map((a) => a.trim()).filter(Boolean)) {
+        const index = Number.parseInt(token, 10);
+        if (/^\d+$/.test(token) && index >= 1 && index <= ALL_KNOWN_AGENTS.length) {
+            selected.push(ALL_KNOWN_AGENTS[index - 1]);
+            continue;
+        }
+        if (ALL_KNOWN_AGENTS.includes(token))
+            selected.push(token);
+    }
+    return uniqueKnownAgents(selected);
 }
 // ─── Step 5: Global install ───────────────────────────────────────────────────
 export function initUserStore(home, env = process.env) {
@@ -237,6 +274,11 @@ export function runGlobalInstall(selectedAgents, env = process.env) {
         if (r && (r.created || r.updated))
             written.push(r.filePath);
     }
+    if (selectedAgents.includes('hermes')) {
+        const r = ensureHermesMcpConfig(home);
+        if (r && (r.created || r.updated))
+            written.push(r.filePath);
+    }
     return written;
 }
 // ─── Step 6: Init repos + configure agents ────────────────────────────────────
@@ -331,30 +373,35 @@ function logDetectedAgentSurfaces(detectedName, detectedSurfaces) {
         console.log('These surfaces are tracked separately from coding agents and will use tailored onboarding flows.');
     }
 }
-async function resolveSelectedAgentsForSetup(options, detectedName) {
+async function resolveSelectedAgentsForSetup(options, detectedName, installedAgents = []) {
+    const detectedSetupAgents = getDetectedSetupAgentNames(detectedName, installedAgents);
     console.log('Supported agents:');
     ALL_KNOWN_AGENTS.forEach((a, i) => {
         const tag = a === detectedName ? ' ← detected' : '';
-        console.log(`  ${i + 1}) ${a}${tag}`);
+        const installedTag = installedAgents.includes(a) ? ' ← installed' : '';
+        console.log(`  ${i + 1}) ${a}${tag}${tag ? '' : installedTag}`);
     });
+    if (detectedSetupAgents.length > 0) {
+        console.log(`Detected install set: ${detectedSetupAgents.join(', ')}`);
+    }
     let agentChoice;
     if (options.agents) {
         agentChoice = options.agents;
     }
     else if (options.yes || !process.stdin.isTTY) {
-        agentChoice = detectedName ? 'detected' : 'all';
+        agentChoice = detectedSetupAgents.length > 0 ? 'detected' : 'all';
     }
     else {
-        const defaultChoice = detectedName ? 'detected' : 'all';
+        const defaultChoice = detectedSetupAgents.length > 0 ? 'detected' : 'all';
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         try {
-            agentChoice = (await rl.question(`Configure agents: (d)etected, (a)ll, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
+            agentChoice = (await rl.question(`Configure agents: (d)etected installed, (a)ll, names, or numbers e.g. 1,3 [${defaultChoice}]: `)).trim() || defaultChoice;
         }
         finally {
             rl.close();
         }
     }
-    const selectedAgents = parseAgentSelection(agentChoice, detectedName);
+    const selectedAgents = parseAgentSelection(agentChoice, detectedName, installedAgents);
     console.log(`Selected agents: ${selectedAgents.length === 0 ? '(none)' : selectedAgents.join(', ')}`);
     return selectedAgents;
 }
@@ -364,10 +411,12 @@ export async function runSetupMachine(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    const agentInventory = testMode ? undefined : buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env);
+    const installedAgents = getInstalledAgentNames(agentInventory);
     console.log(BRAINCLAW_ASCII);
     console.log('Machine bootstrap only — no repositories will be scanned or initialized.');
     logDetectedAgentSurfaces(detectedName, detectedSurfaces);
-    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName, installedAgents);
     console.log('\n→ Installing machine-level brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);
     if (written.length > 0) {
@@ -484,8 +533,10 @@ export async function runSetup(options = {}) {
     const detectedName = detectedAi?.name;
     const testMode = process.env.BRAINCLAW_TEST_MODE === '1';
     const detectedSurfaces = testMode ? [] : buildAiSurfaceInventory();
+    const agentInventory = testMode ? undefined : buildAgentInventory(resolveHomeDir(env) ?? os.homedir(), env);
+    const installedAgents = getInstalledAgentNames(agentInventory);
     logDetectedAgentSurfaces(detectedName, detectedSurfaces);
-    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName);
+    const selectedAgents = await resolveSelectedAgentsForSetup(options, detectedName, installedAgents);
     // Step 5: Global install
     console.log('\n→ Installing global brainclaw prerequisites...');
     const written = runGlobalInstall(selectedAgents, env);

package/dist/core/agent-capability.js

@@ -23,6 +23,7 @@ const AGENT_ALIASES = {
     'gemini': 'antigravity',
     'mistral': 'mistral-vibe',
     'vibe': 'mistral-vibe',
+    'hermes-agent': 'hermes',
 };
 /** Resolve an alias to its canonical agent name, or return the input unchanged. */
 export function resolveAgentAlias(name) {
@@ -227,6 +228,24 @@ const PROFILES = {
         invoke_review_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 5',
         invoke_consult_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 3',
     },
+    // Hermes Agent (Nous Research) — autonomous, skills-first agent with native
+    // MCP client support via ~/.hermes/config.yaml. Brainclaw uses Hermes as a
+    // Tier B surface for now: MCP + universal .agents/skills/ skill, no native
+    // Brainclaw hooks until a dedicated Hermes plugin is shipped and validated.
+    hermes: {
+        name: 'hermes', category: 'autonomous-agent', workflowModel: 'task-based',
+        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
+        instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'B',
+        role_capabilities: ['execute', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'temp_file'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'hermes chat -q "{prompt}"',
+        invoke_binary: 'hermes',
+        invoke_review_template: 'hermes chat -q "{prompt}"',
+        invoke_consult_template: 'hermes chat -q "{prompt}"',
+    },
     // --- Autonomous agents (headless, task-based or scheduled) ---
     openclaw: {
         name: 'openclaw', category: 'autonomous-agent', workflowModel: 'task-based',

package/dist/core/agent-files.js

@@ -338,6 +338,7 @@ export const AGENT_EXPORT_REGISTRY = [
     { agentName: 'roo', format: 'roo', relativePath: '.roo/rules/brainclaw.md' },
     { agentName: 'kilocode', format: 'kilocode', relativePath: '.kilo/rules/brainclaw.md' },
     { agentName: 'mistral-vibe', format: 'agents-md', relativePath: 'AGENTS.md' },
+    { agentName: 'hermes', format: 'agents-md', relativePath: 'AGENTS.md' },
     { agentName: 'opencode', format: 'agents-md', relativePath: 'AGENTS.md' },
     { agentName: 'antigravity', format: 'gemini-md', relativePath: 'GEMINI.md' },
     { agentName: 'brainclaw', format: 'board-md', relativePath: 'BOARD.md' },
@@ -456,6 +457,8 @@ const ROO_MCP_RELATIVE_PATH = '.roo/mcp.json';
 const KILOCODE_MCP_RELATIVE_PATH = '.kilo/mcp.json';
 const KILOCODE_CONFIG_RELATIVE_PATH = 'kilo.jsonc';
 const MISTRAL_VIBE_CONFIG_RELATIVE_PATH = '.vibe/config.toml';
+const HERMES_CONFIG_RELATIVE_PATH = '.hermes/config.yaml';
+const HERMES_EXTERNAL_SKILLS_RELATIVE_PATH = '.agents/skills';
 const CONTINUE_CONFIG_RELATIVE_PATH = '.continue/config.json';
 const CONTINUE_PERMISSIONS_RELATIVE_PATH = '.continue/permissions.yaml';
 const OPENCODE_CONFIG_RELATIVE_PATH = 'opencode.json';
@@ -493,6 +496,7 @@ export const LOCAL_ONLY_AGENT_WORKSPACE_FILES = [
     KILOCODE_MCP_RELATIVE_PATH,
     KILOCODE_CONFIG_RELATIVE_PATH,
     MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
+    HERMES_CONFIG_RELATIVE_PATH,
     CONTINUE_CONFIG_RELATIVE_PATH,
     OPENCODE_CONFIG_RELATIVE_PATH,
     WINDSURF_MCP_RELATIVE_PATH,
@@ -1278,6 +1282,78 @@ export function ensureMistralVibeMcpConfig(cwd) {
         relativePath: MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
     };
 }
+const HERMES_BRAINCLAW_MCP_TOOLS = [
+    'bclaw_work',
+    'bclaw_context',
+    'bclaw_find',
+    'bclaw_get',
+    'bclaw_create',
+    'bclaw_update',
+    'bclaw_transition',
+];
+export function ensureHermesMcpConfig(homeDir, workspacePath) {
+    if (!homeDir)
+        return undefined;
+    const filePath = path.join(homeDir, HERMES_CONFIG_RELATIVE_PATH);
+    let existing = {};
+    let existed = false;
+    if (fs.existsSync(filePath)) {
+        existed = true;
+        try {
+            const parsed = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
+            existing = isJsonObject(parsed) ? { ...parsed } : {};
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const mcpServers = isJsonObject(existing.mcp_servers) ? { ...existing.mcp_servers } : {};
+    const current = isJsonObject(mcpServers.brainclaw) ? { ...mcpServers.brainclaw } : {};
+    const currentEnv = isJsonObject(current.env) ? { ...current.env } : {};
+    const currentTools = isJsonObject(current.tools) ? { ...current.tools } : {};
+    const skills = isJsonObject(existing.skills) ? { ...existing.skills } : {};
+    const externalDirs = Array.isArray(skills.external_dirs)
+        ? skills.external_dirs.filter((value) => typeof value === 'string')
+        : [];
+    if (workspacePath) {
+        const projectSkillsDir = path.resolve(workspacePath, HERMES_EXTERNAL_SKILLS_RELATIVE_PATH);
+        const normalized = projectSkillsDir.replace(/\\/g, '/').toLowerCase();
+        if (!externalDirs.some((dir) => dir.replace(/\\/g, '/').toLowerCase() === normalized)) {
+            externalDirs.push(projectSkillsDir);
+        }
+    }
+    const mcpCmd = getBrainclawMcpCommand();
+    mcpServers.brainclaw = {
+        ...current,
+        command: typeof current.command === 'string' ? current.command : mcpCmd.command,
+        args: Array.isArray(current.args) ? current.args : mcpCmd.args,
+        env: {
+            ...currentEnv,
+            BRAINCLAW_AGENT: 'hermes',
+        },
+        tools: {
+            ...currentTools,
+            include: Array.isArray(currentTools.include) ? currentTools.include : HERMES_BRAINCLAW_MCP_TOOLS,
+            prompts: typeof currentTools.prompts === 'boolean' ? currentTools.prompts : false,
+            resources: typeof currentTools.resources === 'boolean' ? currentTools.resources : false,
+        },
+    };
+    const nextConfig = {
+        ...existing,
+        mcp_servers: mcpServers,
+        ...(externalDirs.length > 0 ? { skills: { ...skills, external_dirs: externalDirs } } : {}),
+    };
+    const content = `# Managed by brainclaw — preserves existing Hermes settings\n${yaml.stringify(nextConfig)}`;
+    const { created, updated } = writeTextFileIfChanged(filePath, content);
+    return {
+        kind: 'mcp',
+        label: 'Hermes MCP settings',
+        created: !existed && created,
+        updated: existed && updated,
+        filePath,
+        relativePath: HERMES_CONFIG_RELATIVE_PATH,
+    };
+}
 export function ensureCodexMcpConfig(homeDir, env = process.env) {
     const codexHome = env.CODEX_HOME?.trim() || (homeDir ? path.join(homeDir, '.codex') : null);
     if (!codexHome)
@@ -1814,6 +1890,13 @@ export function writeDetectedAgentAutoConfig(agentName, cwd, env = process.env)
             return [ensureKilocodeMcpConfig(cwd), ensureKilocodeConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
         case 'mistral-vibe':
             return [ensureMistralVibeMcpConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
+        case 'hermes': {
+            const results = [ensureUniversalBrainclawSkill(cwd)];
+            const mcp = ensureHermesMcpConfig(resolveHomeDir(env), cwd);
+            if (mcp)
+                results.push(mcp);
+            return results;
+        }
         case 'codex': {
             const results = [ensureUniversalBrainclawSkill(cwd)];
             const result = ensureCodexMcpConfig(resolveHomeDir(env), env);
@@ -1916,6 +1999,8 @@ export function writeExportCompanionFiles(format, cwd, env = process.env) {
                 results.push(hooks);
             return results;
         }
+        case 'agents-md':
+            return [ensureUniversalBrainclawSkill(cwd)];
         default:
             return [];
     }
@@ -1956,6 +2041,7 @@ export function patchAllMcpConfigs(cwd, env = process.env) {
             ensureAntigravityMcpConfig(homeDir),
             ensureOpenClawMcpConfig(homeDir),
             ensureCodexMcpConfig(homeDir, env),
+            ensureHermesMcpConfig(homeDir),
         ];
         for (const r of userConfigs) {
             if (r)