@phnx-labs/agents-cli 1.14.7 → 1.16.0

package/dist/lib/subagents.js

@@ -9,7 +9,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSubagentsDir, getUserSubagentsDir } from './state.js';
+import { getSubagentsDir, getUserSubagentsDir, getTrashSubagentsDir } from './state.js';
+import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { safeJoin } from './paths.js';
 /**
  * Parse AGENT.md frontmatter to extract subagent metadata
@@ -407,3 +408,99 @@ export function listSubagentsForAgent(agentId, home) {
     }
     return subagents;
 }
+// Agents that support subagents
+const SUBAGENTS_CAPABLE_AGENTS = ['claude', 'openclaw'];
+/**
+ * Compare a version home's subagents against discovered subagents.
+ * Returns orphan subagent names.
+ */
+export function diffVersionSubagents(agent, version) {
+    const versionHome = getVersionHomePath(agent, version);
+    const orphans = [];
+    // Get all discovered subagent names
+    const discovered = new Set();
+    for (const dir of [getSubagentsDir(), getUserSubagentsDir()]) {
+        if (fs.existsSync(dir)) {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    discovered.add(entry.name);
+                }
+            }
+        }
+    }
+    // Check what's installed
+    if (agent === 'claude') {
+        const agentsDir = path.join(versionHome, '.claude', 'agents');
+        if (fs.existsSync(agentsDir)) {
+            for (const file of fs.readdirSync(agentsDir)) {
+                if (!file.endsWith('.md'))
+                    continue;
+                const name = path.basename(file, '.md');
+                if (!discovered.has(name)) {
+                    orphans.push(name);
+                }
+            }
+        }
+    }
+    else if (agent === 'openclaw') {
+        const openclawDir = path.join(versionHome, '.openclaw');
+        if (fs.existsSync(openclawDir)) {
+            for (const entry of fs.readdirSync(openclawDir, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                if (!discovered.has(entry.name)) {
+                    orphans.push(entry.name);
+                }
+            }
+        }
+    }
+    return { agent, version, orphans: orphans.sort() };
+}
+/**
+ * Iterate all (agent, version) pairs that support subagents and are installed.
+ */
+export function iterSubagentsCapableVersions(filter) {
+    const pairs = [];
+    const agents = filter?.agent ? [filter.agent] : SUBAGENTS_CAPABLE_AGENTS;
+    for (const agent of agents) {
+        if (!SUBAGENTS_CAPABLE_AGENTS.includes(agent))
+            continue;
+        const versions = listInstalledVersions(agent);
+        for (const version of versions) {
+            if (filter?.version && filter.version !== version)
+                continue;
+            pairs.push({ agent, version });
+        }
+    }
+    return pairs;
+}
+/**
+ * Remove a single subagent from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/subagents/.
+ */
+export function removeSubagentFromVersion(agent, version, subagentName) {
+    const versionHome = getVersionHomePath(agent, version);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const trashDir = path.join(getTrashSubagentsDir(), agent, version, subagentName);
+    try {
+        if (agent === 'claude') {
+            const targetPath = path.join(versionHome, '.claude', 'agents', `${subagentName}.md`);
+            if (fs.existsSync(targetPath)) {
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetPath, path.join(trashDir, `${subagentName}.md.${stamp}`));
+            }
+        }
+        else if (agent === 'openclaw') {
+            const targetDir = path.join(versionHome, '.openclaw', subagentName);
+            if (fs.existsSync(targetDir)) {
+                const trashDest = path.join(trashDir, stamp);
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(targetDir, trashDest);
+            }
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}

package/dist/lib/sync-manifest.d.ts

@@ -47,7 +47,7 @@ interface RulesEntry {
 /** Permissions: all group files across all scopes (merged). */
 interface PermEntry {
     groups: Record<string, FileEntry>;
-    permissionSet: string | null;
+    permissionPreset: string | null;
 }
 export interface SyncManifest {
     v: typeof MANIFEST_VERSION;

package/dist/lib/sync-manifest.js

@@ -28,7 +28,7 @@ import { getVersionsDir, getProjectAgentsDir, getUserAgentsDir, getSkillsDir, ge
 import { resolveResource } from './resources.js';
 import { listMcpServerConfigs } from './mcp.js';
 import { isRulesStale } from './rules/compile.js';
-import { getActivePermissionSetName } from './permissions.js';
+import { getActivePermissionPresetName } from './permissions.js';
 import { listInstalledSubagents } from './subagents.js';
 import { safeJoin } from './paths.js';
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -341,7 +341,7 @@ export function buildManifest(agent, version, available, cwd) {
         mcp,
         permissions: {
             groups: permGroups,
-            permissionSet: getActivePermissionSetName(),
+            permissionPreset: getActivePermissionPresetName(),
         },
         subagents,
     };
@@ -420,7 +420,7 @@ export function isSyncStale(manifest, available, agent, version, cwd) {
             return true;
     }
     // ── Permissions ───────────────────────────────────────────────────────────
-    if (manifest.permissions.permissionSet !== getActivePermissionSetName())
+    if (manifest.permissions.permissionPreset !== getActivePermissionPresetName())
         return true;
     const currentGroups = collectPermissionGroupFiles();
     if (nameSetDiffers(Object.keys(manifest.permissions.groups), Object.keys(currentGroups)))

package/dist/lib/teams/persistence.js

@@ -13,7 +13,7 @@ import { homedir, tmpdir } from 'os';
 import { constants as fsConstants } from 'fs';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getUserAgentsDir } from '../state.js';
+import { getTeamsDir, getTeamsAgentsDir } from '../state.js';
 /**
  * Atomic JSON write: writes to a sibling tmp file then renames over the
  * target. rename(2) is atomic on POSIX, so a crashed/interrupted write
@@ -62,8 +62,9 @@ async function withConfigLock(p, fn) {
 }
 // All supported teammate agent types
 const ALL_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode'];
-// Teams data lives under ~/.agents/teams/
-const TEAMS_DIR = path.join(getUserAgentsDir(), 'teams');
+// Teams config + registry live under ~/.agents/teams/ (definitions);
+// per-run agent execution dirs live under ~/.agents/.history/teams/agents/.
+const TEAMS_DIR = getTeamsDir();
 // Legacy paths (for migration)
 const LEGACY_CONFIG_DIR = path.join(homedir(), '.agents');
 // Legacy migration from pre-OSS brand; safe to remove after 2026-07
@@ -100,8 +101,17 @@ export async function resolveBaseDir() {
     throw new Error('Unable to determine a writable data directory for teams');
 }
 async function resolveAgentsPath() {
-    const base = await resolveBaseDir();
-    return path.join(base, 'agents');
+    const historyAgents = getTeamsAgentsDir();
+    if (await ensureWritableDir(historyAgents)) {
+        return historyAgents;
+    }
+    // Last-resort temp fallback so dispatch keeps working when ~/.agents is unwritable.
+    const tmpAgents = path.join(TMP_FALLBACK_DIR, 'agents');
+    if (await ensureWritableDir(tmpAgents)) {
+        console.warn(`[agents teams] Falling back to temp agents dir at ${tmpAgents}`);
+        return tmpAgents;
+    }
+    throw new Error('Unable to determine a writable agents directory');
 }
 async function resolveConfigPath() {
     await fs.mkdir(TEAMS_DIR, { recursive: true });

package/dist/lib/teams/registry.js

@@ -10,9 +10,9 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getUserAgentsDir } from '../state.js';
+import { getTeamsDir } from '../state.js';
 async function registryPath() {
-    return path.join(getUserAgentsDir(), 'teams', 'registry.json');
+    return path.join(getTeamsDir(), 'registry.json');
 }
 /**
  * Atomic JSON write: writes to a unique sibling tmp file then renames over

package/dist/lib/types.d.ts

@@ -186,9 +186,9 @@ export interface RepoInfo {
     lastSync: string;
 }
 /** Canonical system repo cloned into ~/.agents-system/. */
-export declare const DEFAULT_SYSTEM_REPO = "gh:muqsitnawaz/.agents-system";
-/** Mirror system repo (phnx-labs) — will become the default once fully released. */
-export declare const MIRROR_SYSTEM_REPO = "gh:phnx-labs/.agents-system";
+export declare const DEFAULT_SYSTEM_REPO = "gh:phnx-labs/.agents-system";
+/** Legacy system repo — kept so existing installs still recognize their origin. */
+export declare const MIRROR_SYSTEM_REPO = "gh:muqsitnawaz/.agents-system";
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export declare function systemRepoSlug(repo?: string): string;
 /** Kind of package that can be searched and installed from a registry. */
@@ -378,6 +378,35 @@ export interface Meta {
      * once. Tracked so a user `registry remove` won't silently re-seed.
      */
     seededPresets?: string[];
+    /**
+     * Hook manifest entries keyed by hook name. Folded into agents.yaml so the
+     * user has a single file to sync. Each entry shape matches ManifestHook
+     * (script, events, timeout, matches, enabled).
+     */
+    hooks?: Record<string, ManifestHook>;
+    /**
+     * Browser profile definitions keyed by profile name. Portable user config
+     * that syncs with `agents repo push/pull`. Runtime state (chrome-data, pids)
+     * lives separately in ~/.agents/.cache/browser/<profile>/.
+     */
+    browser?: Record<string, BrowserProfileConfig>;
+}
+/** Browser profile definition stored in agents.yaml. */
+export interface BrowserProfileConfig {
+    description?: string;
+    browser: 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | 'custom';
+    binary?: string;
+    electron?: boolean;
+    endpoints: string[];
+    chrome?: {
+        headless?: boolean;
+        args?: string[];
+    };
+    secrets?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 /** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */
 export interface SyncOptions {

package/dist/lib/types.js

@@ -6,9 +6,9 @@
  * formats for each supported agent.
  */
 /** Canonical system repo cloned into ~/.agents-system/. */
-export const DEFAULT_SYSTEM_REPO = 'gh:muqsitnawaz/.agents-system';
-/** Mirror system repo (phnx-labs) — will become the default once fully released. */
-export const MIRROR_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
+export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
+/** Legacy system repo — kept so existing installs still recognize their origin. */
+export const MIRROR_SYSTEM_REPO = 'gh:muqsitnawaz/.agents-system';
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export function systemRepoSlug(repo = DEFAULT_SYSTEM_REPO) {
     return repo.replace(/^gh:/, '').replace(/\.git$/, '');

package/dist/lib/usage.d.ts

@@ -79,7 +79,7 @@ export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Prom
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
-/** Load Claude OAuth credentials from the macOS Keychain. */
+/** Load Claude OAuth credentials from the system keychain/keyring. */
 export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
 /**
  * Derive the Keychain service name for a Claude home directory.

package/dist/lib/usage.js

@@ -15,7 +15,8 @@ import * as readline from 'readline';
 import { promisify } from 'util';
 import chalk from 'chalk';
 import { walkForFiles } from './fs-walk.js';
-import { getAgentsDir } from './state.js';
+import { getKeychainToken, setKeychainToken, deleteKeychainToken, } from './secrets/index.js';
+import { getCacheDir } from './state.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -30,7 +31,7 @@ const CLAUDE_SCOPES = [
     'user:file_upload',
 ];
 const CLAUDE_KEYCHAIN_SERVICE = 'Claude Code-credentials';
-const getClaudeUsageCachePath = () => path.join(getAgentsDir(), 'cache', 'claude-usage.json');
+const getClaudeUsageCachePath = () => path.join(getCacheDir(), 'claude-usage.json');
 const CACHED_CLAUDE_USAGE_SOURCE_LABEL = 'last seen live account data';
 const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
@@ -343,27 +344,15 @@ function normalizeClaudeWindow(window, key, label, shortLabel) {
         windowMinutes: inferWindowMinutes(key),
     };
 }
-let warnedNonDarwin = false;
-/** Load Claude OAuth credentials from the macOS Keychain. */
+/** Load Claude OAuth credentials from the system keychain/keyring. */
 export async function loadClaudeOauth(home) {
-    if (process.platform !== 'darwin') {
-        if (!warnedNonDarwin && process.stderr.isTTY) {
-            process.stderr.write('[agents] Usage tracking requires macOS Keychain. Skipped on this platform.\n');
-            warnedNonDarwin = true;
-        }
+    // Windows not yet supported
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
         return null;
     }
     try {
-        const account = os.userInfo().username;
-        const { stdout } = await execFileAsync('security', [
-            'find-generic-password',
-            '-a',
-            account,
-            '-s',
-            // Managed Claude homes must stay pinned to their own service name.
-            getClaudeKeychainService(home),
-            '-w',
-        ]);
+        const service = getClaudeKeychainService(home);
+        const stdout = getKeychainToken(service);
         const payload = JSON.parse(stdout.trim());
         if (typeof payload?.claudeAiOauth?.accessToken !== 'string')
             return null;
@@ -380,27 +369,20 @@ export async function loadClaudeOauth(home) {
     }
 }
 /**
- * Save Claude OAuth credentials to the macOS Keychain.
+ * Save Claude OAuth credentials to the system keychain/keyring.
  * Reads the existing payload, merges the new OAuth fields, and writes back.
  */
 async function saveClaudeOauth(home, credentials) {
-    if (process.platform !== 'darwin') {
+    // Windows not yet supported
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
         return false;
     }
     try {
-        const account = os.userInfo().username;
         const service = getClaudeKeychainService(home);
         // Read existing payload to preserve other fields
         let existingPayload = {};
         try {
-            const { stdout } = await execFileAsync('security', [
-                'find-generic-password',
-                '-a',
-                account,
-                '-s',
-                service,
-                '-w',
-            ]);
+            const stdout = getKeychainToken(service);
             existingPayload = JSON.parse(stdout.trim());
         }
         catch {
@@ -418,29 +400,14 @@ async function saveClaudeOauth(home, credentials) {
             },
         };
         const payloadJson = JSON.stringify(newPayload);
-        // Delete existing entry first (security add-generic-password -U can fail)
+        // Delete existing entry first, then add updated entry
         try {
-            await execFileAsync('security', [
-                'delete-generic-password',
-                '-a',
-                account,
-                '-s',
-                service,
-            ]);
+            deleteKeychainToken(service);
         }
         catch {
             // Entry might not exist, ignore
         }
-        // Add updated entry
-        await execFileAsync('security', [
-            'add-generic-password',
-            '-a',
-            account,
-            '-s',
-            service,
-            '-w',
-            payloadJson,
-        ]);
+        setKeychainToken(service, payloadJson);
         return true;
     }
     catch {

package/dist/lib/versions.js

@@ -23,10 +23,10 @@ import { promisify } from 'util';
 import chalk from 'chalk';
 import * as TOML from 'smol-toml';
 import { checkbox, select } from '@inquirer/prompts';
-import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, recordVersionResources, getProjectAgentsDir, getPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, clearVersionResources, recordVersionResources, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
 import { resolveResource } from './resources.js';
 import { AGENTS, getAccountEmail, MCP_CAPABLE_AGENTS, COMMANDS_CAPABLE_AGENTS, getMcpConfigPathForHome, parseMcpConfig, resolveAgentName, formatAgentError } from './agents.js';
-import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME, getActivePermissionSetName, readPermissionSetRecipe, PERMISSION_SET_ENV_VAR } from './permissions.js';
+import { applyPermissionsToVersion as applyPermsToVersion, PERMISSIONS_CAPABLE_AGENTS, discoverPermissionGroups, buildPermissionsFromGroups, CODEX_RULES_FILENAME, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { installMcpServers, parseMcpServerConfig } from './mcp.js';
 import { markdownToToml } from './convert.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
@@ -192,10 +192,9 @@ export function getAvailableResources(cwd = process.cwd()) {
     // Plugins (directories with .claude-plugin/plugin.json)
     const allPlugins = discoverPlugins();
     result.plugins = allPlugins.map(p => p.name);
-    // Promptcuts — single file at ~/.agents/promptcuts.yaml, not per-agent.
-    // Project-scoped .agents/promptcuts.yaml is intentionally not supported
-    // (user-global shortcuts only — they follow the user, not the repo).
-    result.promptcuts = fs.existsSync(getPromptcutsPath());
+    // Promptcuts — present if either layer exists. Reads merge user + system
+    // with user precedence (see readMergedPromptcuts); writes always go to user.
+    result.promptcuts = fs.existsSync(getUserPromptcutsPath()) || fs.existsSync(getPromptcutsPath());
     return result;
 }
 // Files/dirs that are never synced into a version home (OS metadata, local tooling).
@@ -676,14 +675,14 @@ export async function promptResourceSelection(agent) {
     ];
     const availableCategories = categories.filter(c => c.available);
     if (availableCategories.length === 0) {
-        console.log(chalk.gray('No resources available in ~/.agents/'));
+        console.log(chalk.gray('No resources available to sync.'));
         return {};
     }
     // Step 1: Select categories (with "Select All" shortcut at the top)
     console.log();
     const SELECT_ALL_KEY = '__select_all__';
     const selectedCategories = await checkbox({
-        message: 'Which resources from ~/.agents/ would you like to sync?',
+        message: 'Which resources would you like to sync?',
         choices: [
             { name: chalk.bold('Select All (sync everything)'), value: SELECT_ALL_KEY, checked: false },
             ...availableCategories.map(c => ({
@@ -945,6 +944,17 @@ export async function installVersion(agent, version, onProgress) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
     try {
+        // Check npm is available
+        try {
+            await execFileAsync('which', ['npm']);
+        }
+        catch {
+            return {
+                success: false,
+                installedVersion: version,
+                error: 'npm is not installed. Install Node.js and npm first: https://nodejs.org/',
+            };
+        }
         onProgress?.(`Installing ${packageSpec}...`);
         const { stdout } = await execFileAsync('npm', ['install', packageSpec], { cwd: versionDir });
         // Determine the actual installed version
@@ -1178,7 +1188,7 @@ export function resolveVersionAliasLoose(agent, raw) {
  * Get version specified in a project-root agents.yaml (not the user ~/.agents-system/agents.yaml).
  */
 export function getProjectVersion(agent, startPath) {
-    const userAgentsYaml = path.join(getAgentsDir(), 'agents.yaml');
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
     let dir = path.resolve(startPath);
     while (dir !== path.dirname(dir)) {
         const manifestPath = path.join(dir, 'agents.yaml');
@@ -1630,39 +1640,39 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     }
     // Apply permissions (if agent supports them).
     // Groups live in ~/.agents/permissions/groups/. Optional recipes in
-    // ~/.agents/permissions/sets/<name>.yaml pick a subset via `includes:`.
-    // If AGENTS_PERMISSION_SET is set, we resolve that recipe and use its
+    // ~/.agents/permissions/presets/<name>.yaml pick a subset via `includes:`.
+    // If AGENTS_PERMISSION_PRESET is set, we resolve that recipe and use its
     // includes list as the group filter (intersected with groups on disk).
     const permissionGroups = discoverPermissionGroups();
     const allGroupNames = permissionGroups.map(g => g.name);
-    const activeSetName = getActivePermissionSetName();
-    let setFilteredGroups = null;
-    if (activeSetName) {
-        const recipe = readPermissionSetRecipe(activeSetName);
+    const activePresetName = getActivePermissionPresetName();
+    let presetFilteredGroups = null;
+    if (activePresetName) {
+        const recipe = readPermissionPresetRecipe(activePresetName);
         if (recipe) {
             const available = new Set(allGroupNames);
-            setFilteredGroups = recipe.includes.filter(g => available.has(g));
+            presetFilteredGroups = recipe.includes.filter(g => available.has(g));
         }
         else {
-            console.warn(`${PERMISSION_SET_ENV_VAR}=${activeSetName} but no recipe at ~/.agents/permissions/sets/${activeSetName}.yaml — falling back to all groups`);
+            console.warn(`${PERMISSION_PRESET_ENV_VAR}=${activePresetName} but no recipe at ~/.agents/permissions/presets/${activePresetName}.yaml — falling back to all groups`);
         }
     }
     let permsToSync;
     if (selection) {
         permsToSync = resolveSelection(selection.permissions, allGroupNames);
-        // If a set recipe is active, the recipe's includes list always wins —
+        // If a preset recipe is active, the recipe's includes list always wins —
         // even when the caller passed an explicit array via selection. Without
         // this intersection, `agents add`'s buildAutomaticSelection would pass
         // every group name discovered on disk (including 99-deny), bypassing
         // the sandbox filter.
-        if (setFilteredGroups) {
-            const filterSet = new Set(setFilteredGroups);
+        if (presetFilteredGroups) {
+            const filterSet = new Set(presetFilteredGroups);
             permsToSync = permsToSync.filter(g => filterSet.has(g));
         }
     }
     else {
         permsToSync = PERMISSIONS_CAPABLE_AGENTS.includes(agent)
-            ? (setFilteredGroups ?? allGroupNames)
+            ? (presetFilteredGroups ?? allGroupNames)
             : [];
     }
     if (permsToSync.length > 0 && PERMISSIONS_CAPABLE_AGENTS.includes(agent)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.14.7",
+  "version": "1.16.0",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",

package/scripts/postinstall.js

@@ -13,8 +13,15 @@ const SHIMS_DIR = path.join(HOME, '.agents-system', 'shims');
 const SYSTEM_DIR = path.join(HOME, '.agents-system');
 const USER_DIR = path.join(HOME, '.agents');
 
-// Only run for global installs
-if (!process.env.npm_config_global && !process.argv.includes('-g')) {
+// For local installs, create directories and show a message
+const isGlobalInstall = process.env.npm_config_global || process.argv.includes('-g');
+if (!isGlobalInstall) {
+  // Still create user directories for local installs
+  fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+  console.log(`
+agents-cli installed locally.
+To complete setup, run: npx agents setup
+`);
   process.exit(0);
 }
 
@@ -165,17 +172,38 @@ async function main() {
     return;
   }
 
-  // Default: print PATH instructions, then offer aliases interactively.
-  console.log(`
-agents-cli installed.
-To enable version-aware shims, add the following line to your shell config:
+  // Default: offer to auto-add shims to PATH (like homebrew does)
+  const rcFile = getShellRc();
+  let alreadyConfigured = false;
+  if (fs.existsSync(rcFile)) {
+    const content = fs.readFileSync(rcFile, 'utf-8');
+    alreadyConfigured = content.includes('.agents-system/shims');
+  }
 
-  ${exportLine}
+  console.log(`\nagents-cli installed.`);
 
-(zsh: ~/.zshrc, bash: ~/.bashrc, fish: ~/.config/fish/config.fish)
+  if (!alreadyConfigured && process.stdin.isTTY && process.stdout.isTTY) {
+    const answer = await ask(`\nAdd shims to PATH in ~/${path.basename(rcFile)}? [Y/n] `);
+    if (answer === '' || answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+      const addition = `\n# agents-cli: version switching for AI coding agents\n${exportLine}\n`;
+      fs.mkdirSync(path.dirname(rcFile), { recursive: true });
+      fs.appendFileSync(rcFile, addition);
+      console.log(`\n  Added ${SHIMS_DIR} to PATH in ${path.basename(rcFile)}`);
+      console.log(`  Restart your shell or run: source ~/${path.basename(rcFile)}\n`);
+    } else {
+      console.log(`
+To enable version-aware shims, add this to your shell config:
 
-Or re-run with AGENTS_INIT_SHELL=1 to have the installer add it for you.
+  ${exportLine}
 `);
+    }
+  } else if (!alreadyConfigured) {
+    console.log(`
+To enable version-aware shims, add this to your shell config:
+
+  ${exportLine}
+`);
+  }
 
   const choice = await promptForAliases();
   if (choice === 'install') {