@phnx-labs/agents-cli 1.20.4 → 1.20.5

package/dist/index.js

@@ -56,11 +56,12 @@ if (IS_DEV_BUILD) {
 }
 // Import command registrations
 import { registerPullCommand } from './commands/pull.js';
+import { registerPushCommand } from './commands/push.js';
 import { registerRepoCommands } from './commands/repo.js';
 import { registerSetupCommand, runSetup } from './commands/setup.js';
-import { registerStatusCommand } from './commands/status.js';
 import { registerFeedbackCommand } from './commands/feedback.js';
 import { registerViewCommand } from './commands/view.js';
+import { registerInspectCommand } from './commands/inspect.js';
 import { registerCommandsCommands } from './commands/commands.js';
 import { registerHooksCommands } from './commands/hooks.js';
 import { registerSkillsCommands } from './commands/skills.js';
@@ -86,6 +87,7 @@ import { registerSyncCommand } from './commands/sync.js';
 import { registerRefreshRulesCommand } from './commands/refresh-rules.js';
 import { registerDriveCommands } from './commands/drive.js';
 import { registerPtyCommands } from './commands/pty.js';
+import { registerTmuxCommands } from './commands/tmux.js';
 import { registerBrowserCommand } from './commands/browser.js';
 import { registerComputerCommand } from './commands/computer.js';
 import { registerProfilesCommands } from './commands/profiles.js';
@@ -99,7 +101,7 @@ import { applyGlobalHelpConventions } from './lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './commands/utils.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
-import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
+import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
 const program = new Command();
 program
     .name('agents')
@@ -131,6 +133,7 @@ Agent versions:
   prune cleanup [target]          Remove orphan resources and older duplicate version installs
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
+  inspect <agent>[@version]       Deep details for one agent+version — paths, capabilities, resources, drill into any kind
 
 Agent configuration (synced across versions):
   rules                           Instructions given to agents (CLAUDE.md, etc.)
@@ -164,7 +167,7 @@ Diagnostics:
 
 Config sync:
   drive                           Sync session history across machines via rsync
-  pull                            Clone or pull the system repo at ~/.agents-system/
+  pull                            Clone or pull the system repo at ~/.agents/.system/
   repo init --path <dir>          Scaffold your own editable repo from a template
   repo add <path|gh:user/repo>    Merge an extra repo after the system repo
 
@@ -182,7 +185,7 @@ Options:
   -V, --version                   Show version number
   -h, --help                      Show help
 
-System config lives in ~/.agents-system/. Run 'agents <command> --help' for details.
+System config lives in ~/.agents/.system/. Run 'agents <command> --help' for details.
 `;
     }
     return originalHelpInformation();
@@ -409,10 +412,17 @@ async function checkForUpdates() {
         }
     }
 }
-async function maybeBootstrapShimIntegration(requestedCommand) {
+async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return;
     }
+    // Pure documentation paths must never trigger interactive repair — mirrors
+    // the helpOrVersionRequested gate around ensureInitialized below. Covers
+    // both bare `agents --version` (requestedCommand === undefined) and
+    // `agents <subcommand> --help` (requestedCommand === subcommand name).
+    if (helpOrVersionRequested) {
+        return;
+    }
     if (requestedCommand === 'sync' || requestedCommand === 'refresh-rules') {
         return;
     }
@@ -447,11 +457,13 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
     const shadowed = defaultAgents
         .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
         .filter((item) => Boolean(item.shadowedBy));
-    // Also check for shell aliases that shadow the shim
-    const aliased = defaultAgents.filter((agent) => hasAliasShadowingShim(agent));
-    // If shims are in PATH and nothing is binary-shadowing, we're done.
     // Shell aliases that call the same command with extra flags are intentional
-    // customization and don't break shim integration.
+    // customization and don't break shim integration — `addShimsToPath` cannot
+    // touch them, so they don't belong in the repair prompt. We previously
+    // computed an `aliased` list here and inserted it into `affected`, which
+    // contradicted the comment below and surfaced false positives (e.g. an
+    // earlier `alias codex=...` cancelled by a later `unalias codex` was
+    // reported because the detector did a static rc-file regex).
     if (shadowed.length === 0 && isShimsInPath()) {
         return;
     }
@@ -468,14 +480,11 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
     for (const { agent, shadowedBy } of shadowed) {
         affected.push(`${AGENTS[agent].cliCommand} -> ${shadowedBy}`);
     }
-    for (const agent of aliased) {
-        if (!shadowed.some((s) => s.agent === agent)) {
-            affected.push(`${AGENTS[agent].cliCommand} (alias)`);
-        }
-    }
     if (affected.length === 0) {
-        // PATH issue - show all installed agents
-        affected.push(...installedAgents.map((agent) => AGENTS[agent].cliCommand));
+        // Pure PATH-not-loaded case: rc may already have the shim block, but the
+        // running shell hasn't sourced it. Don't list agents here — they aren't
+        // broken; only the PATH is stale. The prompt + post-message handle it.
+        affected.push('PATH entry missing');
     }
     const shouldRepair = await confirm({
         message: `Repair shim integration now? ${affected.join(', ')}`,
@@ -494,15 +503,38 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
     if (!pathResult.success) {
         console.log(chalk.yellow('Could not repair shim PATH setup automatically.'));
         console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
+        // Write the sentinel even on failure — otherwise an unwritable rc file
+        // re-prompts every invocation in the same shell. The user opens a new
+        // terminal (new PPID) to retry.
+        try {
+            fs.writeFileSync(sentinelPath, '1');
+        }
+        catch { /* best-effort */ }
         return;
     }
+    // When the rc file already has the canonical shim block, `addShimsToPath`
+    // is a no-op — re-emitting produced byte-identical content. In this branch
+    // the user clicked "Yes" but nothing changed on disk, AND the underlying
+    // cause (a real binary shadow, or a stale shell PATH) is unaffected by
+    // this command. Be honest about it and point at the actual action.
     if (pathResult.alreadyPresent) {
-        console.log(chalk.yellow('Shim PATH entry is already in your shell config, but this shell has not reloaded it yet.'));
+        if (shadowed.length > 0) {
+            const targets = shadowed
+                .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
+                .join('\n');
+            console.log(chalk.yellow('Repair could not change anything — the shim is shadowed by another binary on PATH:'));
+            console.log(chalk.gray(targets));
+            console.log(chalk.gray(`Fix it by removing or reordering that binary, or making sure ${getShimsDir()} appears earlier in PATH than its parent dir.`));
+        }
+        else {
+            console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
+            console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
+        }
     }
     else {
         console.log(chalk.green(`Repaired shim PATH setup in ~/${pathResult.rcFile}`));
+        console.log(chalk.gray(getPathSetupInstructions()));
     }
-    console.log(chalk.gray(getPathSetupInstructions()));
     try {
         fs.writeFileSync(sentinelPath, '1');
     }
@@ -510,7 +542,7 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
 }
 // Register all commands
 registerViewCommand(program);
-registerStatusCommand(program);
+registerInspectCommand(program);
 registerFeedbackCommand(program);
 registerCommandsCommands(program);
 registerHooksCommands(program);
@@ -577,6 +609,7 @@ registerFactoryCommands(program);
 registerUsageCommand(program);
 registerAliasCommand(program);
 registerPtyCommands(program);
+registerTmuxCommands(program);
 registerBrowserCommand(program);
 registerComputerCommand(program);
 // Deprecated 'jobs' and 'cron' aliases for 'routines'
@@ -632,6 +665,7 @@ program
     }
 });
 registerPullCommand(program);
+registerPushCommand(program);
 registerRepoCommands(program);
 registerSetupCommand(program);
 applyGlobalHelpConventions(program);
@@ -742,6 +776,20 @@ const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
 // Help and version output are pure documentation — they must never gate on
 // setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
 const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+// Fold legacy ~/.agents-system/ into ~/.agents/.system/ BEFORE ensureInitialized
+// runs. ensureInitialized checks for .git inside the new path; if the user is
+// upgrading from a layout where .git lives under the legacy path, the check
+// would fail and exit before the migrator ever runs. Also runs outside the
+// sentinel guard below because the sentinel was set by pre-fold releases and
+// would otherwise skip this step on every existing install. Idempotent —
+// no-ops when legacy is missing or already a symlink.
+if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
+    try {
+        const { foldLegacySystemRepo } = await import('./lib/migrate.js');
+        foldLegacySystemRepo();
+    }
+    catch { /* must never block CLI startup */ }
+}
 if (!firstRun &&
     requestedCommand &&
     !SETUP_EXEMPT_COMMANDS.has(requestedCommand) &&
@@ -783,7 +831,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
     catch { /* migration must never block CLI startup */ }
 }
 try {
-    await maybeBootstrapShimIntegration(requestedCommand);
+    await maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested);
     await program.parseAsync();
 }
 catch (err) {

package/dist/lib/agents.d.ts

@@ -23,16 +23,6 @@ export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
 export declare const AGENTS: Record<AgentId, AgentConfig>;
 /** All registered agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
-/** Agents that support MCP (Model Context Protocol) server integration. */
-export declare const MCP_CAPABLE_AGENTS: AgentId[];
-/** Agents that support skills (SKILL.md + rules/ bundles). */
-export declare const SKILLS_CAPABLE_AGENTS: AgentId[];
-/** Agents that support file-based slash commands. */
-export declare const COMMANDS_CAPABLE_AGENTS: AgentId[];
-/** Agents that support event hooks (pre/post lifecycle callbacks). */
-export declare const HOOKS_CAPABLE_AGENTS: readonly AgentId[];
-/** Agents that support the plugin system. */
-export declare const PLUGINS_CAPABLE_AGENTS: AgentId[];
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export declare function colorAgent(agentId: string): (s: string) => string;
 /** Return the agent's display name, colored. */
@@ -59,6 +49,13 @@ export interface UnmanagedInstall {
     configDir: string;
     version: string | null;
 }
+/**
+ * Agents that `agents setup` probes for pre-existing native installations
+ * (i.e., a config dir present before agents-cli took over). Add an agent here
+ * once its `cliCommand` reports a usable `--version` and its session dir is
+ * wired into `getSessionDir`.
+ */
+export declare const UNMANAGED_DETECTION_CANDIDATES: AgentId[];
 /**
  * Detect existing agent installations that are NOT yet managed by agents-cli.
  * Returns agents whose config dir exists as a real directory (not a symlink).
@@ -68,6 +65,18 @@ export declare function getUnmanagedAgentInstalls(): Promise<UnmanagedInstall[]>
 export declare function ensureCommandsDir(agentId: AgentId): void;
 /** Create the agent's skills directory if it does not exist. */
 export declare function ensureSkillsDir(agentId: AgentId): void;
+/**
+ * The agent's config-dir name relative to $HOME — e.g. '.claude',
+ * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
+ *
+ * This is the path segment to join onto a (version) home root when locating an
+ * agent's commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong
+ * for every agent whose config dir is nested or lives under ~/.config —
+ * antigravity (~/.gemini/antigravity-cli), amp (~/.config/amp),
+ * goose (~/.config/goose), kimi (~/.kimi-code). Mirrors the shim `configDirName`
+ * derivation in shims.ts.
+ */
+export declare function agentConfigDirName(agentId: AgentId): string;
 /** Account identity and billing information extracted from an agent's auth config. */
 export interface AccountInfo {
     accountKey: string | null;

package/dist/lib/agents.js

@@ -203,7 +203,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
+        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'CLAUDE.md' }, workflows: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
     },
     // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
     codex: {
@@ -222,7 +222,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, modes: ['plan', 'edit', 'skip'] },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'skip'] },
     },
     gemini: {
         id: 'gemini',
@@ -241,7 +241,7 @@ export const AGENTS = {
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
         // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
-        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
+        capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'GEMINI.md' }, workflows: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
     },
     cursor: {
         id: 'cursor',
@@ -259,7 +259,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['edit', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: '.cursorrules' }, workflows: false, modes: ['edit', 'skip'] },
     },
     opencode: {
         id: 'opencode',
@@ -276,7 +276,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
     },
     openclaw: {
         id: 'openclaw',
@@ -293,7 +293,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{ARGUMENTS}}',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: false, plugins: true, modes: ['plan', 'edit', 'skip'] },
+        capabilities: { hooks: true, mcp: true, allowlist: false, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'skip'] },
     },
     copilot: {
         id: 'copilot',
@@ -310,7 +310,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -327,7 +327,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
     },
     kiro: {
         id: 'kiro',
@@ -345,7 +345,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit'] },
     },
     goose: {
         id: 'goose',
@@ -363,7 +363,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, modes: ['edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit'] },
     },
     roo: {
         id: 'roo',
@@ -381,7 +381,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, modes: ['plan', 'edit'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
     },
     // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
     // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
@@ -408,7 +408,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{args}}',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, modes: ['edit', 'skip'], rulesImports: false },
+        capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit', 'skip'], rulesImports: false },
     },
     // xAI Grok Build CLI (`grok`) — early beta, SuperGrok Heavy. Auth via OAuth on
     // first launch, or XAI_API_KEY env var for headless. MCP servers configured inline
@@ -439,23 +439,51 @@ export const AGENTS = {
             skills: true,
             commands: false, // covered by skills
             plugins: true,
+            subagents: false,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
             modes: ['plan', 'edit', 'skip'],
             rulesImports: true,
         },
     },
+    kimi: {
+        id: 'kimi',
+        name: 'Kimi',
+        color: 'magentaBright',
+        cliCommand: 'kimi-code',
+        npmPackage: '',
+        installScript: '',
+        configDir: path.join(HOME, '.kimi-code'),
+        commandsDir: '',
+        commandsSubdir: '',
+        skillsDir: path.join(HOME, '.kimi-code', 'skills'),
+        hooksDir: path.join(HOME, '.kimi-code', 'hooks'),
+        instructionsFile: 'AGENTS.md',
+        format: 'markdown',
+        variableSyntax: '$ARGUMENTS',
+        supportsHooks: true,
+        capabilities: {
+            hooks: true,
+            mcp: true,
+            allowlist: false,
+            skills: false,
+            commands: false,
+            plugins: false,
+            subagents: false,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
+            modes: ['plan', 'edit', 'skip'],
+            rulesImports: false,
+        },
+    },
 };
 /** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
-/** Agents that support MCP (Model Context Protocol) server integration. */
-export const MCP_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.mcp);
-/** Agents that support skills (SKILL.md + rules/ bundles). */
-export const SKILLS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.skills);
-/** Agents that support file-based slash commands. */
-export const COMMANDS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.commands);
-/** Agents that support event hooks (pre/post lifecycle callbacks). */
-export const HOOKS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.hooks !== false);
-/** Agents that support the plugin system. */
-export const PLUGINS_CAPABLE_AGENTS = ALL_AGENT_IDS.filter((id) => AGENTS[id].capabilities.plugins !== false);
+// Capability-filtered agent lists used to live here as `*_CAPABLE_AGENTS`
+// constants. They were a frequent source of silent-skip bugs (e.g. grok
+// rules sync gated on `COMMANDS_CAPABLE_AGENTS`). Use `capableAgents(cap)`
+// from `./capabilities.js` instead — it consults the AgentConfig matrix
+// directly, so a single source of truth drives every gate.
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export function colorAgent(agentId) {
     const agent = AGENTS[agentId];
@@ -610,14 +638,26 @@ export function isConfigured(agentId) {
     const agent = AGENTS[agentId];
     return fs.existsSync(agent.configDir);
 }
+/**
+ * Agents that `agents setup` probes for pre-existing native installations
+ * (i.e., a config dir present before agents-cli took over). Add an agent here
+ * once its `cliCommand` reports a usable `--version` and its session dir is
+ * wired into `getSessionDir`.
+ */
+export const UNMANAGED_DETECTION_CANDIDATES = [
+    'claude',
+    'codex',
+    'gemini',
+    'grok',
+    'copilot',
+];
 /**
  * Detect existing agent installations that are NOT yet managed by agents-cli.
  * Returns agents whose config dir exists as a real directory (not a symlink).
  */
 export async function getUnmanagedAgentInstalls() {
     const unmanaged = [];
-    const candidates = ['claude', 'codex', 'gemini', 'grok'];
-    for (const agentId of candidates) {
+    for (const agentId of UNMANAGED_DETECTION_CANDIDATES) {
         const agent = AGENTS[agentId];
         try {
             const stat = fs.lstatSync(agent.configDir);
@@ -646,6 +686,20 @@ export function ensureSkillsDir(agentId) {
         fs.mkdirSync(agent.skillsDir, { recursive: true });
     }
 }
+/**
+ * The agent's config-dir name relative to $HOME — e.g. '.claude',
+ * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
+ *
+ * This is the path segment to join onto a (version) home root when locating an
+ * agent's commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong
+ * for every agent whose config dir is nested or lives under ~/.config —
+ * antigravity (~/.gemini/antigravity-cli), amp (~/.config/amp),
+ * goose (~/.config/goose), kimi (~/.kimi-code). Mirrors the shim `configDirName`
+ * derivation in shims.ts.
+ */
+export function agentConfigDirName(agentId) {
+    return path.relative(os.homedir(), AGENTS[agentId].configDir);
+}
 /** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {
     const info = await getAccountInfo(agentId, home);
@@ -1280,7 +1334,7 @@ export function getMcpConfigPathForHome(agentId, home) {
         case 'grok':
             return path.join(home, '.grok', 'config.toml');
         default:
-            return path.join(home, `.${agentId}`, 'settings.json');
+            return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
 }
 /**

package/dist/lib/auto-pull-worker.d.ts

@@ -5,7 +5,7 @@
  * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
  * CLI surfaces on its next invocation.
  *
- * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Per-repo lock files at ~/.agents/.system/.fetch/<alias>.lock prevent concurrent fetches.
  * Lock mtime under 5 min => skip (another invocation already in flight).
  */
 export {};

package/dist/lib/auto-pull-worker.js

@@ -5,7 +5,7 @@
  * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
  * CLI surfaces on its next invocation.
  *
- * Per-repo lock files at ~/.agents-system/.fetch/<alias>.lock prevent concurrent fetches.
+ * Per-repo lock files at ~/.agents/.system/.fetch/<alias>.lock prevent concurrent fetches.
  * Lock mtime under 5 min => skip (another invocation already in flight).
  */
 import * as fs from 'fs';
@@ -15,7 +15,7 @@ import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCac
 import { lockFilePath, statusFilePath } from './auto-pull.js';
 const LOCK_TTL_MS = 5 * 60 * 1000;
 /**
- * Background auto-pull of ~/.agents-system/ is off by default. When enabled it
+ * Background auto-pull of ~/.agents/.system/ is off by default. When enabled it
  * silently fast-forwards a tracked source tree that the CLI then reads as a
  * source of skills, hooks, install manifests, and commands — anyone with push
  * access to that upstream gets remote code execution on every user the next

package/dist/lib/auto-pull.d.ts

@@ -1,6 +1,6 @@
 /**
  * Background sync for tracked git repos:
- *   - System repo (~/.agents-system/) is read-only locally — fast-forward auto-pull is safe.
+ *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
  *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
  *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.

package/dist/lib/auto-pull.js

@@ -1,6 +1,6 @@
 /**
  * Background sync for tracked git repos:
- *   - System repo (~/.agents-system/) is read-only locally — fast-forward auto-pull is safe.
+ *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
  *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
  *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.

package/dist/lib/beta.d.ts

@@ -3,7 +3,7 @@
  *
  * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
  * when present, and otherwise fall back to the local system state file
- * (~/.agents-system/agents.yaml). This keeps opt-ins portable for users with a
+ * (~/.agents/.system/agents.yaml). This keeps opt-ins portable for users with a
  * personal agents repo without mixing them into unrelated version capability
  * checks.
  */

package/dist/lib/beta.js

@@ -3,7 +3,7 @@
  *
  * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
  * when present, and otherwise fall back to the local system state file
- * (~/.agents-system/agents.yaml). This keeps opt-ins portable for users with a
+ * (~/.agents/.system/agents.yaml). This keeps opt-ins portable for users with a
  * personal agents repo without mixing them into unrelated version capability
  * checks.
  */

package/dist/lib/capabilities.js

@@ -46,6 +46,8 @@ export function supports(agent, cap, version) {
         return { ok: false, reason: 'unsupported' };
     if (c === true)
         return { ok: true };
+    if ('file' in c)
+        return { ok: true };
     if (!version)
         return { ok: true };
     if (c.since && compareVersions(version, c.since) < 0) {

package/dist/lib/commands.d.ts

@@ -13,7 +13,28 @@ export type CommandScope = 'user' | 'project';
 export interface CommandMetadata {
     name: string;
     description: string;
+    /** When set, sync only to these agents (aliases resolved at parse time). */
+    agents?: AgentId[];
+    /** Minimum agent CLI version (inclusive) for this command. */
+    since?: string;
+    /** Exclusive upper bound on agent CLI version for this command. */
+    until?: string;
 }
+export type CommandApplyFailReason = 'unsupported' | 'agent_excluded' | 'too_old' | 'too_new';
+export type CommandApplyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: CommandApplyFailReason;
+    need?: string;
+};
+/**
+ * Whether a slash command should sync to the given agent@version. Checks
+ * frontmatter `agents` / `since` / `until` after the agent-level commands
+ * (or commands-as-skills) capability gate.
+ */
+export declare function commandAppliesTo(agent: AgentId, version: string, metadata: Pick<CommandMetadata, 'agents' | 'since' | 'until'> | null | undefined): CommandApplyResult;
+export declare function explainCommandSkip(agent: AgentId, version: string, commandName: string, result: CommandApplyResult): string;
 /** Result of validating command metadata. */
 export interface ValidationResult {
     valid: boolean;
@@ -35,6 +56,8 @@ export interface InstalledCommand {
     path: string;
     description?: string;
 }
+/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
+export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
 /** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
 /** Find the source path for a command in a repository. */
@@ -59,6 +82,8 @@ export interface VersionCommandDiff {
     toAdd: string[];
     toUpdate: string[];
     matched: string[];
+    /** Installed but excluded by frontmatter agents/since/until — safe to remove. */
+    toRemove: string[];
     orphans: string[];
 }
 /**
@@ -72,6 +97,8 @@ export declare function diffVersionCommands(agent: AgentId, version: string): Ve
 export declare function installCommandToVersion(agent: AgentId, version: string, commandName: string, method?: 'symlink' | 'copy'): {
     success: boolean;
     error?: string;
+    skipped?: boolean;
+    skipReason?: string;
 };
 /**
  * Remove a single command from a specific version home.
@@ -112,7 +139,7 @@ export declare function installCommandCentrally(sourcePath: string, commandName:
     warnings?: string[];
 };
 /**
- * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralCommands(): string[];