@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/commands/versions.js

@@ -461,11 +461,11 @@ export function registerVersionsCommands(program) {
     useCmd.action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
-            // Auto-pull ~/.agents-system if it's a git repo with remote (silent on success)
+            // Auto-pull ~/.agents/.system if it's a git repo with remote (silent on success)
             const agentsDir = getAgentsDir();
             const pullResult = await tryAutoPull(agentsDir);
             if (pullResult.pulled) {
-                console.log(chalk.gray('Synced ~/.agents-system from remote'));
+                console.log(chalk.gray('Synced ~/.agents/.system from remote'));
             }
             // Support both "claude 2.0.65" and "claude@2.0.65" formats
             let agent;

package/dist/commands/view.d.ts

@@ -9,6 +9,17 @@
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
+/** Per-section filter flags. When any are true, only those sections render. */
+export interface ViewSectionFilter {
+    commands?: boolean;
+    skills?: boolean;
+    mcp?: boolean;
+    workflows?: boolean;
+    plugins?: boolean;
+    rules?: boolean;
+    hooks?: boolean;
+    promptcuts?: boolean;
+}
 /** Machine-readable entry for a single installed version. */
 export interface ViewJsonVersion {
     version: string;
@@ -54,6 +65,6 @@ export declare function viewAction(agentArg?: string, options?: {
     prune?: boolean;
     yes?: boolean;
     dryRun?: boolean;
-}): Promise<void>;
+} & ViewSectionFilter): Promise<void>;
 /** Register the `agents view` command. */
 export declare function registerViewCommand(program: Command): void;

package/dist/commands/view.js

@@ -8,15 +8,16 @@ import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
-import { WORKFLOW_CAPABLE_AGENTS } from '../lib/workflows.js';
+import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
-import { PLUGINS_CAPABLE_AGENTS } from '../lib/agents.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts } from '../lib/state.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
+import { resolveRunDefaults } from '../lib/run-defaults.js';
 import { listProfiles, profileSummary } from '../lib/profiles.js';
+import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
@@ -113,6 +114,29 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
+const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts'];
+/**
+ * Decide whether a section should render given the filter. If no flags are set,
+ * everything renders (current behavior). If any flag is set, only those sections
+ * render — flags are additive.
+ */
+function shouldRenderSection(key, filter) {
+    if (!filter)
+        return true;
+    const anySet = SECTION_KEYS.some((k) => filter[k]);
+    if (!anySet)
+        return true;
+    return filter[key] === true;
+}
+/** Trim a description to a column-friendly snippet. Strips newlines, collapses whitespace. */
+function summarizeDescription(desc, maxLen = 80) {
+    if (!desc)
+        return '';
+    const cleaned = desc.replace(/\s+/g, ' ').trim();
+    if (cleaned.length <= maxLen)
+        return cleaned;
+    return cleaned.slice(0, maxLen - 1).trimEnd() + '…';
+}
 function getProfileSummaries(filterAgentId) {
     return listProfiles()
         .filter((profile) => !filterAgentId || profile.host.agent === filterAgentId)
@@ -338,6 +362,12 @@ async function showInstalledVersions(filterAgentId) {
                 // Otherwise it reflects install time (misleading "just now" for fresh installs).
                 const activeStr = vInfo && hasEmail ? formatLastActive(vInfo.lastActive) : '';
                 const hasActive = activeStr.length > 0;
+                const runDefaults = resolveRunDefaults(agentId, version);
+                const runDefaultBits = [];
+                if (runDefaults.mode)
+                    runDefaultBits.push(`mode:${runDefaults.mode}`);
+                if (runDefaults.model)
+                    runDefaultBits.push(`model:${runDefaults.model}`);
                 if (!hasEmail && !hasUsage) {
                     // Installed but never signed in
                     parts.push(chalk.gray('(not signed in — run ' + agent.cliCommand + ' to log in)'));
@@ -359,6 +389,9 @@ async function showInstalledVersions(filterAgentId) {
                     if (hasActive)
                         parts.push(activeStr);
                 }
+                if (runDefaultBits.length > 0) {
+                    parts.push(chalk.gray(`run ${runDefaultBits.join(' ')}`));
+                }
                 console.log(parts.join('  '));
                 if (showPaths) {
                     const versionDir = getVersionDir(agentId, version);
@@ -519,6 +552,11 @@ async function showInstalledVersions(filterAgentId) {
     if (filterAgentId && versionManaged.length > 0) {
         const defaultVersion = getGlobalDefault(filterAgentId);
         if (defaultVersion) {
+            const manifest = loadManifest(filterAgentId, defaultVersion);
+            const cwd = process.cwd();
+            if (manifest && !isStale(manifest, filterAgentId, defaultVersion, cwd)) {
+                return;
+            }
             const available = getAvailableResources();
             const synced = getActuallySyncedResources(filterAgentId, defaultVersion);
             const projectOnly = getProjectOnlyResources();
@@ -563,7 +601,7 @@ async function showInstalledVersions(filterAgentId) {
  * Show detailed resources for a specific agent version.
  * Called when: `agents view claude@2.0.65` or `agents view claude@default`
  */
-async function showAgentResources(agentId, requestedVersion) {
+async function showAgentResources(agentId, requestedVersion, filter) {
     const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
     const cwd = process.cwd();
     const agentsDir = getAgentsDir();
@@ -655,6 +693,8 @@ async function showAgentResources(agentId, requestedVersion) {
         })),
         skills: resources.skills.map(r => ({
             ...r,
+            // ruleCount of 0 is noise — every skill has 0 unless it ships subrules, which is rare.
+            ruleCount: r.ruleCount && r.ruleCount > 0 ? r.ruleCount : undefined,
             syncState: r.scope === 'project' ? undefined : getSyncState(r.name, 'skills', skillsSync),
         })),
         skillErrors: resources.skillErrors,
@@ -700,7 +740,9 @@ async function showAgentResources(agentId, requestedVersion) {
                     : chalk.gray('[system]');
             display += ` ${sourceTag}`;
             const syncStr = r.syncState ? chalk.gray(` [${r.syncState}]`) : '';
-            console.log(`    ${display}${syncStr}`);
+            const descSnippet = summarizeDescription(r.description);
+            const descStr = descSnippet ? chalk.gray(`  ${descSnippet}`) : '';
+            console.log(`    ${display}${syncStr}${descStr}`);
         }
     }
     // Render promptcuts (cross-agent, not per-version). Shortcuts are layered
@@ -717,43 +759,53 @@ async function showAgentResources(agentId, requestedVersion) {
         const label = `${count} shortcut${count === 1 ? '' : 's'}`;
         console.log(`  ${chalk.green(label).padEnd(24)} ${chalk.gray(formatPath(getEffectivePromptcutsPath(), cwd))}`);
     }
-    // 1. Agent CLI info
-    console.log(chalk.bold('Agent CLIs\n'));
-    const accountInfo = await getAccountInfo(agentId, home);
-    const usageInfo = await getUsageInfoForIdentity({
-        agentId,
-        home,
-        cliVersion: version,
-        info: accountInfo,
-    });
-    const emailStr = accountInfo.email ? chalk.cyan(`  ${accountInfo.email}`) : '';
-    const status = chalk.green(version);
-    const usageStr = formatUsageSummary(accountInfo.plan, null);
-    const usagePart = usageStr ? `  ${usageStr}` : '';
-    console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${emailStr}${usagePart}`);
-    const usageLines = formatUsageSection(usageInfo);
-    if (usageLines.length > 0) {
-        console.log();
-        for (const line of usageLines) {
-            console.log(line);
+    const anyFilterSet = filter && SECTION_KEYS.some((k) => filter[k]);
+    // 1. Agent CLI info — skip the header entirely when the user asked for a
+    // specific section. They want "nothing more or less."
+    if (!anyFilterSet) {
+        console.log(chalk.bold('Agent CLIs\n'));
+        const accountInfo = await getAccountInfo(agentId, home);
+        const usageInfo = await getUsageInfoForIdentity({
+            agentId,
+            home,
+            cliVersion: version,
+            info: accountInfo,
+        });
+        const emailStr = accountInfo.email ? chalk.cyan(`  ${accountInfo.email}`) : '';
+        const status = chalk.green(version);
+        const usageStr = formatUsageSummary(accountInfo.plan, null);
+        const usagePart = usageStr ? `  ${usageStr}` : '';
+        console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${emailStr}${usagePart}`);
+        const usageLines = formatUsageSection(usageInfo);
+        if (usageLines.length > 0) {
+            console.log();
+            for (const line of usageLines) {
+                console.log(line);
+            }
         }
     }
     // 2. Resources
-    renderSection('Commands', agentData.commands);
-    renderSection('Skills', agentData.skills);
-    // Show skill parse errors if any
-    if (agentData.skillErrors.length > 0) {
-        console.log(`\n  ${chalk.red('Skill Errors')}:`);
-        for (const err of agentData.skillErrors) {
-            console.log(`    ${chalk.red(err.name.padEnd(20))} ${chalk.gray(err.error)}`);
-            console.log(`      ${chalk.gray(formatPath(err.path, cwd))}`);
+    if (shouldRenderSection('commands', filter)) {
+        renderSection('Commands', agentData.commands);
+    }
+    if (shouldRenderSection('skills', filter)) {
+        renderSection('Skills', agentData.skills);
+        // Show skill parse errors only when skills section is visible
+        if (agentData.skillErrors.length > 0) {
+            console.log(`\n  ${chalk.red('Skill Errors')}:`);
+            for (const err of agentData.skillErrors) {
+                console.log(`    ${chalk.red(err.name.padEnd(20))} ${chalk.gray(err.error)}`);
+                console.log(`      ${chalk.gray(formatPath(err.path, cwd))}`);
+            }
         }
     }
-    renderSection('MCP Servers', agentData.mcp);
-    if (WORKFLOW_CAPABLE_AGENTS.includes(agentId)) {
+    if (shouldRenderSection('mcp', filter)) {
+        renderSection('MCP Servers', agentData.mcp);
+    }
+    if (shouldRenderSection('workflows', filter) && isCapable(agentId, 'workflows')) {
         renderSection('Workflows', agentData.workflows);
     }
-    if (PLUGINS_CAPABLE_AGENTS.includes(agentId)) {
+    if (shouldRenderSection('plugins', filter) && isCapable(agentId, 'plugins')) {
         const plugins = discoverPlugins().filter(p => pluginSupportsAgent(p, agentId));
         console.log(chalk.bold('\nPlugins\n'));
         if (plugins.length === 0) {
@@ -842,11 +894,18 @@ async function showAgentResources(agentId, requestedVersion) {
             }
         }
     }
-    renderRulesSection();
-    renderSection('Hooks', agentData.hooks);
-    renderPromptcuts();
-    // Show legend at the end if git repo exists
-    if (hasGitRepo) {
+    if (shouldRenderSection('rules', filter)) {
+        renderRulesSection();
+    }
+    if (shouldRenderSection('hooks', filter)) {
+        renderSection('Hooks', agentData.hooks);
+    }
+    if (shouldRenderSection('promptcuts', filter)) {
+        renderPromptcuts();
+    }
+    // Show legend at the end if git repo exists and we showed all sections.
+    // Filtered single-section views skip it — noise for promptcuts or plugins.
+    if (hasGitRepo && !anyFilterSet) {
         console.log();
         console.log(chalk.gray('Legend:'), chalk.green('Tracked'), chalk.blue('Local-only'), chalk.yellow('Modified'), chalk.red('Deleted'));
     }
@@ -1126,6 +1185,17 @@ export async function viewAction(agentArg, options) {
     const prune = options?.prune === true;
     const yes = options?.yes === true;
     const dryRun = options?.dryRun === true;
+    const filter = {
+        commands: options?.commands,
+        skills: options?.skills,
+        mcp: options?.mcp,
+        workflows: options?.workflows,
+        plugins: options?.plugins,
+        rules: options?.rules,
+        hooks: options?.hooks,
+        promptcuts: options?.promptcuts,
+    };
+    const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
     if (!agentArg) {
         if (prune) {
             await pruneDuplicates(undefined, yes, dryRun);
@@ -1175,7 +1245,12 @@ export async function viewAction(agentArg, options) {
     }
     if (requestedVersion) {
         // Specific version requested: show detailed resources
-        await showAgentResources(agentId, requestedVersion);
+        await showAgentResources(agentId, requestedVersion, filter);
+    }
+    else if (filterIsSet) {
+        // `agents view claude --skills` → fall through to detail view on default.
+        // Section filters only make sense for the per-version detail view.
+        await showAgentResources(agentId, 'default', filter);
     }
     else {
         // Just agent name: show versions for that agent
@@ -1191,6 +1266,14 @@ export function registerViewCommand(program) {
         .option('--prune', 'Remove older installed versions that share an account with a newer installed version. Skips the global default.')
         .option('--dry-run', 'With --prune, show duplicate versions without deleting')
         .option('-y, --yes', 'Skip the prune confirmation prompt.')
+        .option('--commands', 'Show only commands in the detail view.')
+        .option('--skills', 'Show only skills in the detail view.')
+        .option('--mcp', 'Show only MCP servers in the detail view.')
+        .option('--workflows', 'Show only workflows in the detail view.')
+        .option('--plugins', 'Show only plugins in the detail view.')
+        .option('--rules', 'Show only rules in the detail view.')
+        .option('--hooks', 'Show only hooks in the detail view.')
+        .option('--promptcuts', 'Show only promptcuts in the detail view.')
         .addHelpText('after', `
 Examples:
   # Show all installed agents with versions, accounts, and usage
@@ -1211,6 +1294,11 @@ Examples:
   agents view claude --prune
   agents view claude --prune -y
 
+  # Filter the detail view to a single section (combinable)
+  agents view claude@default --skills
+  agents view claude@default --plugins --workflows
+  agents view claude --commands    # implicitly the default version
+
 When to use:
   - Checking which agents are installed and what their default versions are
   - Seeing which account each version is logged into (useful for multi-account setups)

package/dist/commands/workflows.js

@@ -5,8 +5,9 @@ import * as os from 'os';
 import * as path from 'path';
 import { select, checkbox } from '@inquirer/prompts';
 import { resolveAgentName, agentLabel } from '../lib/agents.js';
+import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
-import { WORKFLOW_CAPABLE_AGENTS, discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
+import { discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
 import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
@@ -210,7 +211,7 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = await resolveAgentTargetsAutoInstalling(options.agents, WORKFLOW_CAPABLE_AGENTS, { yes: options.yes });
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, capableAgents('workflows'), { yes: options.yes });
                 if (!result) {
                     console.log(chalk.gray('Cancelled.'));
                     return;
@@ -219,7 +220,7 @@ Examples:
                 versionSelections = result.versionSelections;
             }
             else {
-                const result = await promptAgentVersionSelection(WORKFLOW_CAPABLE_AGENTS, {
+                const result = await promptAgentVersionSelection(capableAgents('workflows'), {
                     skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;

package/dist/commands/worktree.d.ts

@@ -10,11 +10,10 @@
  *   agents worktree release   <terminal-id>   -> removes if clean + merged
  *   agents worktree prune                     -> removes every clean+merged one
  *
- * Worktrees live at <repo>/.history/worktrees/<terminal-id>, on a branch
- * named agent/<terminal-id>. The branch starts at HEAD of the parent repo.
- * .history/ mirrors the agents-cli runtime-state convention at ~/.agents/.history/
- * but scoped to the repo. .agents/ is reserved for project resources
- * (skills, hooks, commands) per the agents-cli DotAgents repo layout.
+ * Worktrees live at <repo>/.agents/worktrees/<terminal-id>, on a branch
+ * named agents/<terminal-id>. The branch starts at HEAD of the parent repo.
+ * This matches the agent-system rule that keeps all coding-agent worktrees
+ * under the repo-local .agents/ state directory.
  */
 import type { Command } from 'commander';
 export declare function registerWorktreeCommands(program: Command): void;

package/dist/commands/worktree.js

@@ -6,8 +6,8 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
 const execFileAsync = promisify(execFile);
-const WORKTREE_SUBDIR = path.join('.history', 'worktrees');
-const BRANCH_PREFIX = 'agent/';
+const WORKTREE_SUBDIR = path.join('.agents', 'worktrees');
+const BRANCH_PREFIX = 'agents/';
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
     process.exit(code);
@@ -165,7 +165,7 @@ export function registerWorktreeCommands(program) {
       agents worktree prune
     `,
         notes: `
-      Worktrees live at <repo>/.history/worktrees/<terminal-id> on branch agent/<terminal-id>.
+      Worktrees live at <repo>/.agents/worktrees/<terminal-id> on branch agents/<terminal-id>.
       Use --force on 'release' to skip safety checks (DANGEROUS — discards unpushed work).
     `,
     });
@@ -198,7 +198,7 @@ export function registerWorktreeCommands(program) {
         }
     });
     wt.command('prune')
-        .description('Try to release every agent worktree under .history/worktrees/. Skips dirty or unpushed ones.')
+        .description('Try to release every agent worktree under .agents/worktrees/. Skips dirty or unpushed ones.')
         .option('--root <path>', 'Repo root (defaults to current working directory)')
         .option('--dry-run', 'Report what would be removed without touching anything')
         .action(async (opts) => {