@phnx-labs/agents-cli 1.20.3 → 1.20.5

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## Unreleased
+
+## 1.20.5
+
+**`agents inspect` — per-agent+version detail view with drill-down (#217)**
+
+- New top-level command `agents inspect <agent>[@version]`. Summary mode shows install path, config symlink target, shim path, versioned alias, run strategy, capability table (`hooks`/`mcp`/`skills`/`commands`/`subagents`/`plugins`/`workflows`/`rules`/`allowlist`), resource counts with project/user/system scope breakdown, and session total. Replaces the awkward `agents view <agent>@<version>` deep-detail mode as a dedicated verb; `view` itself is unchanged.
+- Drill-down flags for every resource kind — `--commands`, `--skills`, `--hooks`, `--mcp`, `--rules`, `--plugins`, `--workflows`, `--subagents`. Bare flag lists every entry; passing a positional query fuzzy-searches that kind, ranking exact > substring > Damerau-Levenshtein. Zero matches exit 1 with the three closest names as suggestions. One drill-down at a time (validation error otherwise). `--json` works with summary and every drill-down for scriptable consumption.
+- Resource names render as OSC-8 terminal hyperlinks to the marker file (`SKILL.md` / `WORKFLOW.md` / `AGENT.md`) for clickable navigation in modern terminals (Ghostty, iTerm2, WezTerm) — no inline path noise. Plain text on terminals without OSC-8 support.
+- MCP detail intentionally suppresses path and env values to avoid leaking secrets — only the server name, scope, and version reach the output.
+- Removes the deprecated `agents status` alias for `view @default`. Top-level help text updated; no consumers referenced it.
+
+**Headless Linux: encrypted-file fallback when libsecret collection is locked (#183)**
+
+- On server-class Linux (Ubuntu 24.04 over SSH on the reporter's box), `agents secrets create x` failed with `secret-tool: Cannot create an item in a locked collection`. Diagnosis in the issue: `gnome-keyring-daemon` is running and D-Bus is reachable, but the default `login` collection is locked because no graphical login has fed the daemon the passphrase, and `secret-tool` from `libsecret-tools` has no `--collection` flag so it can't target the unlocked `session` collection. This made `agents secrets` effectively macOS-only on any headless box.
+- `src/lib/secrets/linux.ts` now transparently falls back to a file-based AES-256-GCM encrypted store at `~/.agents/.cache/secrets/<item>.enc` (mode 0600, per-file random scrypt salt + 96-bit IV, GCM auth tag). The encryption key is scrypt-derived from a passphrase read from `AGENTS_SECRETS_PASSPHRASE` (preferred) or a TTY prompt via `/dev/tty` with `stty -echo` for non-echoing input. The fallback also activates when `libsecret-tools` is not installed at all but `AGENTS_SECRETS_PASSPHRASE` is set, so a fresh install can store secrets without any apt-get step.
+- The decision is cached per process; on first activation we emit one stderr line: `[agents] secret-service collection locked, using file-based store at <dir>`. The `KeychainBackend` interface in `src/lib/secrets/index.ts` is unchanged — `has`/`get`/`set`/`delete`/`list` work identically against either backend, so `bundles.ts`, `sync.ts`, and every consumer above it sees no API change.
+- Items written into the file store before the fallback was added remain accessible only via libsecret if/when the collection is later unlocked; this PR does not migrate stranded items in either direction — the user simply re-creates them on a freshly headless box.
+
+## 1.20.4
+
+**Plugin marketplace sync (skip outside-pointing symlinks)**
+
+- `copyPluginToMarketplace` used `fs.cpSync(plugin.root, dest, { recursive: true, dereference: false })`, which faithfully preserved every symlink — including the ones plugin authors put at the top of their plugin source for prompt-side references (the rush plugin's `app -> ../../../rush/app`, `web -> rush/web`, `widgets -> rush/widgets`). Those targets resolve to the rush monorepo (~8.7 GB of `app/` including node_modules + .next builds, 782 MB of `web/`, plus 463 MB brand-assets). Every claude version got a full set of those symlinks in `~/.claude/plugins/marketplaces/agents-cli/plugins/rush/`. When the consumer (Claude Code, OpenClaw) discovers plugins, it walks the marketplace tree and follows those symlinks — producing multi-minute startup hangs.
+- The copy now walks the source tree and drops symlinks whose `realpath` escapes the plugin root, leaving internal symlinks intact (cpSync rewrites internal targets to absolute paths into the source tree, which the consumer still resolves correctly). One informational line per plugin lists the skipped names so plugin authors notice.
+- Existing per-version marketplace directories still hold the bloat from prior syncs; clean up with `rm` against `~/.claude/plugins/marketplaces/agents-cli/plugins/*/{app,web,widgets,*-symlinks-that-escaped}` then re-run `agents pull` or any plugin sync to re-copy with the filter.
+
 ## 1.20.3
 
 **`agents run` startup latency (stale-while-revalidate the usage probe + memoize agents.yaml)**

package/README.md

@@ -641,23 +641,54 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 ## Compatibility
 
-| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Plugins | Permissions | Routines | Teams |
-|-------|----------|-----|----------|--------|-------|-------|---------|-------------|----------|-------|
-| Claude Code | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes | yes | yes |
-| Codex CLI | yes | yes | yes | yes | AGENTS.md | yes (>= 0.116.0) | -- | yes | yes | yes |
-| Gemini CLI | yes | yes | yes | yes | GEMINI.md | yes (>= 0.26.0) | -- | -- | yes | yes |
-| OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | yes | -- | -- | -- |
-| Cursor | yes | yes | yes | yes | .cursorrules | -- | -- | -- | -- | yes |
-| OpenCode | yes | yes | yes | yes | AGENTS.md | -- | -- | yes | -- | yes |
-| Copilot | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Amp | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Kiro | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-| Goose | yes | yes | -- | -- | AGENTS.md | -- | -- | -- | -- | -- |
-| Roo Code | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
-
-Hooks columns marked `yes (>= X.Y.Z)` are version-gated: `agents hooks add` skips with a clear message when the installed binary is older than the listed version, instead of writing config the older binary would silently ignore. OpenCode's plugin-based hook system is on the roadmap; the entry is `--` until a writer ships.
-
-Codex command sync is version-aware: Codex `0.116.x` and older receive slash commands in `.codex/prompts/`; Codex `0.117.0+` receives those commands as generated skills so they can be invoked with `$name`.
+Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](src/lib/capabilities.ts). Full matrix also in [docs/00-concepts.md](docs/00-concepts.md).
+
+| Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows |
+|-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------|
+| Claude Code | yes | yes | yes | yes | yes | yes | yes | yes | `CLAUDE.md` | yes |
+| Codex CLI | yes | >= 0.116.0 | yes | no | yes | < 0.117.0 · skills ($name, >= 0.117) | >= 0.128.0 | no | `AGENTS.md` | no |
+| Gemini CLI | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
+| Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no |
+| Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no |
+| OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no |
+| Cursor | yes | no | yes | no | yes | yes | no | no | `.cursorrules` | no |
+| OpenCode | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Copilot | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Amp | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Kiro | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Goose | yes | no | yes | no | no | no | no | no | `AGENTS.md` | no |
+| Roo Code | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+
+**Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message.
+
+**Host CLIs** (`agents cli`) are separate: YAML manifests under `~/.agents/cli/` install binaries onto your PATH (`gh`, `higgsfield`, etc.). They are not copied into per-agent version homes.
+
+### agents-cli features (not agent-native resources)
+
+| Agent | Routines | Teams | Session index |
+|-------|----------|-------|---------------|
+| Claude Code | yes | yes | yes |
+| Codex CLI | yes | yes | yes |
+| Gemini CLI | yes | yes | yes |
+| Cursor | -- | yes | -- |
+| OpenCode | -- | yes | -- |
+| Grok Build | -- | yes | yes |
+| Antigravity | -- | yes | -- |
+| Copilot | -- | -- | yes |
+| OpenClaw, Amp, Kiro, Goose, Roo | -- | -- | -- |
+
+### Version-gated sync
+
+| Capability | Agent | Gate |
+|------------|-------|------|
+| Hooks | Codex | >= 0.116.0 |
+| Hooks | Gemini | >= 0.26.0 |
+| File-based commands | Codex | < 0.117.0 (0.117+ uses command-as-skill) |
+| Plugins | Codex | >= 0.128.0 |
+
+Codex `0.117.0+` no longer reads `.codex/prompts/`; agents-cli converts slash commands into skills so they stay invocable as `$name`. OpenCode's plugin-based hook system is on the roadmap; hooks stay `no` until a writer ships.
+
+Slash commands can declare per-agent/version targeting in frontmatter (`agents:`, `since:`, `until:`). Gating applies when syncing from `~/.agents/commands/` (user/system) into version homes — project `.agents/commands/` files are read in place and are not filtered by `agents:`. This repo ships `.agents/commands/version.md` as `/version` for Claude, Codex, Gemini, Cursor, OpenCode, Copilot, and Grok; Antigravity excluded until verified.
 
 ## FAQ
 

package/dist/commands/cli.js

@@ -52,7 +52,7 @@ Examples:
   agents cli check
 
 When to use:
-  - After 'agents pull' on a new machine, to materialize host binaries
+  - After 'agents repo refresh' on a new machine, to materialize host binaries
   - In a team setup: commit cli/ entries so teammates get the same toolchain
 `);
     cliCmd

package/dist/commands/cloud.js

@@ -123,7 +123,7 @@ Examples:
   # Codex Cloud
   agents cloud run "add auth tests" --provider codex --env env_abc123
 
-  # Default provider (set in ~/.agents-system/agents.yaml)
+  # Default provider (set in ~/.agents/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
 `)
         .action(async (positionalPrompt, options) => {

package/dist/commands/commands.js

@@ -506,6 +506,8 @@ function buildCommandRows(opts) {
                 status = 'synced';
             else if (diff.toUpdate.includes(name))
                 status = 'stale';
+            else if (diff.toRemove.includes(name))
+                status = 'stale';
             else
                 status = 'missing';
             targets.push({

package/dist/commands/doctor.js

@@ -310,7 +310,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents sync ${report.agent}@${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
     }
 }
 // ─── command registration ────────────────────────────────────────────────────

package/dist/commands/exec.js

@@ -85,7 +85,7 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -202,10 +202,20 @@ export function registerRunCommand(program) {
             process.stderr.write(chalk.gray(`Workflow '${rawAgent}' → claude (${subagentCount} subagents)\n`));
         }
         else {
-            console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-            console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
-            console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
-            process.exit(1);
+            // Smart pick: auto-correct a single typo (insertion/deletion/substitution/transposition)
+            // against the known agent ids before giving up. Example: `cladue` -> `claude`, `grk` -> `grok`.
+            const { fuzzyMatch, FUZZY_PRESETS } = await import('../lib/fuzzy.js');
+            const suggested = fuzzyMatch(rawAgent, ALL_AGENT_IDS, FUZZY_PRESETS.agents);
+            if (suggested && isValidAgent(suggested)) {
+                process.stderr.write(chalk.gray(`Resolved '${rawAgent}' -> '${suggested}' (single-edit match)\n`));
+                agent = suggested;
+            }
+            else {
+                console.error(chalk.red(`Unknown agent: ${rawAgent}`));
+                console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
+                console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
+                process.exit(1);
+            }
         }
         version = resolveVersionAlias(agent, version);
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
@@ -254,20 +264,34 @@ export function registerRunCommand(program) {
         }
         // Accept the four canonical modes plus 'full' as a permanent silent
         // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
-        const mode = options.mode;
+        let mode = options.mode;
         if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
             process.exit(1);
         }
-        // Surface capability errors as a clean CLI message instead of a stack
-        // trace from buildExecCommand. resolveMode degrades 'auto' silently and
-        // throws on unsupported 'plan'/'skip' — we catch and pretty-print.
+        // When the user did not pass --mode explicitly, the default is the
+        // generic 'plan'. Some agents (antigravity: edit/skip only, grok in some
+        // configurations) do not support plan. For implicit defaults, degrade
+        // silently to the agent's first listed mode rather than throwing — the
+        // user did not ask for read-only, they asked for "just run it." An
+        // explicit --mode plan still throws (see resolveMode), because silently
+        // elevating an explicit read-only request to edit is unsafe.
+        const modeSource = runCmd.getOptionValueSource('mode');
+        const modeIsDefault = modeSource === 'default';
         try {
             resolveMode(agent, normalizeMode(mode));
         }
         catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
+            if (modeIsDefault) {
+                mode = defaultModeFor(agent);
+                if (!options.quiet) {
+                    process.stderr.write(chalk.gray(`[agents] ${agent} has no '${options.mode}' mode; using '${mode}'\n`));
+                }
+            }
+            else {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
         }
         const effort = options.effort;
         if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(effort)) {
@@ -344,12 +368,24 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const entries = options.fallback.split(',').map(s => s.trim()).filter(Boolean);
+            const { fuzzyMatch: fuzzyFb, FUZZY_PRESETS: PRESETS_FB } = await import('../lib/fuzzy.js');
             for (const entry of entries) {
-                const [fbAgent, fbVersion] = entry.split('@');
-                if (!isValidAgent(fbAgent)) {
-                    console.error(chalk.red(`Unknown fallback agent: ${fbAgent}`));
-                    console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
-                    process.exit(1);
+                const [rawFbAgent, fbVersion] = entry.split('@');
+                let fbAgent;
+                if (isValidAgent(rawFbAgent)) {
+                    fbAgent = rawFbAgent;
+                }
+                else {
+                    const suggested = fuzzyFb(rawFbAgent, ALL_AGENT_IDS, PRESETS_FB.agents);
+                    if (suggested && isValidAgent(suggested)) {
+                        process.stderr.write(chalk.gray(`Resolved fallback '${rawFbAgent}' -> '${suggested}' (single-edit match)\n`));
+                        fbAgent = suggested;
+                    }
+                    else {
+                        console.error(chalk.red(`Unknown fallback agent: ${rawFbAgent}`));
+                        console.error(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
+                        process.exit(1);
+                    }
                 }
                 if (fbAgent === agent) {
                     console.error(chalk.red(`Fallback cannot include the primary agent (${agent}). Rate-limit fallback only helps when switching providers.`));

package/dist/commands/hooks.js

@@ -4,8 +4,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { checkbox } from '@inquirer/prompts';
-import { AGENTS, HOOKS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
-import { supports } from '../lib/capabilities.js';
+import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { supports, capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, getHookInfo, parseHookManifest, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
@@ -58,7 +58,7 @@ When to use:
             agentId = resolveAgentName(agentName);
             if (!agentId) {
                 spinner.stop();
-                console.log(chalk.red(formatAgentError(agentName, [...HOOKS_CAPABLE_AGENTS])));
+                console.log(chalk.red(formatAgentError(agentName, [...capableAgents('hooks')])));
                 process.exit(1);
             }
             requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
@@ -185,7 +185,7 @@ When to use:
         }
         // No agent specified - show default version for each hooks-capable agent
         console.log(chalk.bold('Installed Hooks\n'));
-        for (const aid of HOOKS_CAPABLE_AGENTS) {
+        for (const aid of capableAgents('hooks')) {
             const agent = AGENTS[aid];
             const installedVersions = listInstalledVersions(aid);
             const defaultVer = getGlobalDefault(aid);
@@ -338,7 +338,7 @@ Examples:
             // Get agent and version selection
             let selectedAgents;
             let versionSelections;
-            const hooksCapableAgents = Array.from(HOOKS_CAPABLE_AGENTS);
+            const hooksCapableAgents = Array.from(capableAgents('hooks'));
             if (options.agents) {
                 const result = await resolveAgentTargetsAutoInstalling(options.agents, hooksCapableAgents, { yes: options.yes });
                 if (!result) {
@@ -468,7 +468,7 @@ Examples:
             // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = hookInfo.targets;
             if (options?.agents) {
-                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...HOOKS_CAPABLE_AGENTS]);
+                const requestedTargets = resolveInstalledAgentTargets(options.agents, [...capableAgents('hooks')]);
                 const requested = new Set();
                 for (const aid of requestedTargets.directAgents) {
                     for (const ver of listInstalledVersions(aid)) {

package/dist/commands/import.js

@@ -23,12 +23,13 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { AGENTS, getCliPath, getCliVersion, agentLabel } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
-import { finalizeImport, importAgentBinary, importAgentConfig, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
+import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 function isValidAgentId(value) {
     return ALL_AGENT_IDS.includes(value);
@@ -41,54 +42,94 @@ async function runImport(agentArg, opts) {
     }
     const agentId = agentArg;
     const agent = AGENTS[agentId];
-    // Reject agents that don't ship via npm before we spin up PATH lookups and
-    // prompts. cursor/kiro/goose/roo all have npmPackage='' and use custom
-    // install scripts — the symlink-farm import doesn't apply to them.
-    if (!agent.npmPackage) {
-        console.error(chalk.red(`${agentLabel(agentId)} doesn't install via npm — \`agents import\` only handles npm-style packages.`));
-        console.error(chalk.gray(`Use \`agents add ${agentId}\` to install via its native script.`));
-        process.exit(1);
-    }
+    // installScript-based agents (Grok, Antigravity, Cursor, Kiro, Goose, Roo)
+    // don't have an npm package; their binary lives wherever the curl/brew
+    // installer dropped it. We adopt by symlinking that PATH binary directly
+    // into the version's `node_modules/.bin/`. No package.json walk.
+    const isInstallScriptAgent = !agent.npmPackage;
     let globalPath = null;
+    let installScriptBinary = null;
     if (opts.fromPath) {
         globalPath = path.resolve(opts.fromPath);
         if (!fs.existsSync(globalPath)) {
             console.error(chalk.red(`Path does not exist: ${globalPath}`));
             process.exit(1);
         }
+        if (isInstallScriptAgent) {
+            // With --from-path on an installScript agent, the path is the binary
+            // itself (or a directory containing it). Accept either.
+            if (fs.statSync(globalPath).isDirectory()) {
+                const candidate = path.join(globalPath, agent.cliCommand);
+                if (!fs.existsSync(candidate)) {
+                    console.error(chalk.red(`No "${agent.cliCommand}" in ${globalPath}`));
+                    process.exit(1);
+                }
+                installScriptBinary = candidate;
+            }
+            else {
+                installScriptBinary = globalPath;
+            }
+        }
     }
     else {
         const binary = await getCliPath(agentId);
         if (!binary) {
-            // Use || (not ??) so empty-string npmPackage falls back to cliCommand.
-            // Defensive: agents with empty npmPackage are rejected above, but keep
-            // the operator correct in case that early check is ever relaxed.
-            const installName = agent.npmPackage || agent.cliCommand;
+            const installHint = isInstallScriptAgent
+                ? `Run \`agents add ${agentId}\` to install via the official script, or pass --from-path.`
+                : `Install it first (e.g. \`npm i -g ${agent.npmPackage || agent.cliCommand}\`) or pass --from-path.`;
             console.error(chalk.red(`No "${agent.cliCommand}" found on PATH.`));
-            console.error(chalk.gray(`Install it first (e.g. \`npm i -g ${installName}\`) or pass --from-path.`));
+            console.error(chalk.gray(installHint));
             process.exit(1);
         }
-        globalPath = resolvePackageDirFromBinary(binary);
-        if (!globalPath) {
-            console.error(chalk.red(`Could not resolve npm package for binary: ${binary}`));
-            console.error(chalk.gray('Pass --from-path <dir> with the package directory explicitly.'));
-            process.exit(1);
+        if (isInstallScriptAgent) {
+            installScriptBinary = binary;
+        }
+        else {
+            globalPath = resolvePackageDirFromBinary(binary);
+            if (!globalPath) {
+                console.error(chalk.red(`Could not resolve npm package for binary: ${binary}`));
+                console.error(chalk.gray('Pass --from-path <dir> with the package directory explicitly.'));
+                process.exit(1);
+            }
+        }
+    }
+    // For Grok, the binary on PATH is typically `~/.grok/bin/grok` (a moving
+    // pointer to the latest install). Prefer the exact versioned file in
+    // `~/.grok/downloads/` so the v<x.y.z> alias is pinned to that file and
+    // doesn't drift when the user upgrades externally.
+    if (isInstallScriptAgent && agentId === 'grok' && !opts.fromPath) {
+        const detected = await getCliVersion(agentId);
+        if (detected) {
+            const downloads = path.join(os.homedir(), '.grok', 'downloads');
+            try {
+                const entries = fs.readdirSync(downloads);
+                const exact = entries.find((e) => e.startsWith('grok-') && e.includes(detected));
+                if (exact) {
+                    installScriptBinary = path.join(downloads, exact);
+                }
+            }
+            catch {
+                /* fall back to PATH binary already set above */
+            }
         }
     }
     let version = opts.version;
     if (!version) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(path.join(globalPath, 'package.json'), 'utf8'));
-            version = typeof pkg.version === 'string' ? pkg.version : undefined;
-        }
-        catch {
-            /* fall through */
+        if (!isInstallScriptAgent && globalPath) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(path.join(globalPath, 'package.json'), 'utf8'));
+                version = typeof pkg.version === 'string' ? pkg.version : undefined;
+            }
+            catch {
+                /* fall through */
+            }
         }
         // Only fall back to running the PATH binary's --version when we're
-        // auto-detecting. With --from-path, the PATH binary may belong to a
-        // different install entirely; reporting its version here would silently
-        // mis-attribute the imported version.
-        if (!version && !opts.fromPath) {
+        // auto-detecting. With --from-path on an npm agent, the PATH binary may
+        // belong to a different install entirely; reporting its version here
+        // would silently mis-attribute the imported version. installScript agents
+        // always use `<bin> --version` since they have no package.json to read.
+        if (!version && (isInstallScriptAgent || !opts.fromPath)) {
             const detected = await getCliVersion(agentId);
             version = detected ?? undefined;
         }
@@ -104,8 +145,9 @@ async function runImport(agentArg, opts) {
         process.exit(1);
     }
     const versionDir = getVersionDir(agentId, version);
+    const fromLabel = isInstallScriptAgent ? installScriptBinary : globalPath;
     console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
-    console.log(`  from: ${chalk.gray(globalPath)}`);
+    console.log(`  from: ${chalk.gray(fromLabel)}`);
     console.log(`  into: ${chalk.gray(versionDir)}`);
     const configDirExists = fs.existsSync(agent.configDir);
     let configAlreadyManaged = false;
@@ -146,7 +188,8 @@ async function runImport(agentArg, opts) {
         const cfgSpinner = ora(`Importing config dir for ${agentLabel(agentId)} v${version}...`).start();
         const cfgResult = await importAgentConfig(agentId, version);
         if (cfgResult.success) {
-            cfgSpinner.succeed(`Config imported (${agent.configDir} -> ${versionDir}/home/.${agentId})`);
+            const relConfig = path.relative(os.homedir(), agent.configDir);
+            cfgSpinner.succeed(`Config imported (${agent.configDir} -> ${versionDir}/home/${relConfig})`);
         }
         else if (cfgResult.skipped) {
             cfgSpinner.warn(`Config: ${cfgResult.error}`);
@@ -157,9 +200,11 @@ async function runImport(agentArg, opts) {
         }
     }
     const binSpinner = ora(`Registering ${agentLabel(agentId)} v${version} binary...`).start();
-    const binResult = importAgentBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, globalPath, versionDir);
+    const binResult = isInstallScriptAgent
+        ? importInstallScriptBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, installScriptBinary, versionDir)
+        : importAgentBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, globalPath, versionDir);
     if (binResult.success) {
-        binSpinner.succeed(`Binary registered (${agent.cliCommand} -> ${globalPath})`);
+        binSpinner.succeed(`Binary registered (${agent.cliCommand} -> ${binResult.resolvedFromPath})`);
     }
     else if (binResult.skipped) {
         binSpinner.warn(`Binary: ${binResult.error}`);
@@ -198,11 +243,19 @@ Examples:
   $ agents import openclaw --version 2026.3.8       Pin a version label
   $ agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
 
+  # installScript-based agents (curl/brew installers, no npm package):
+  $ agents import grok                              Adopt ~/.grok/downloads/grok-<ver>
+  $ agents import antigravity                       Adopt ~/.local/bin/agy
+  $ agents import cursor                            Adopt ~/.local/bin/cursor-agent
+  $ agents import antigravity --from-path ~/.local/bin/agy
+
 When to use:
-  When an agent CLI is already installed globally via npm or homebrew and you
-  want to bring it under agents-cli management without reinstalling. Creates a
-  symlink farm pointing at the existing install — nothing is copied or moved
-  (except the agent's config dir, which is moved into the version's home).
+  When an agent CLI is already installed globally and you want to bring it
+  under agents-cli management without reinstalling. Creates a symlink farm
+  pointing at the existing install — nothing is copied or moved (except the
+  agent's config dir, which is moved into the version's home). Works for both
+  npm-style packages (claude, codex, gemini, opencode, openclaw) and
+  installScript-based agents (grok, antigravity, cursor, kiro, goose, roo).
 `)
         .action(runImport);
 }

package/dist/commands/inspect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ *
+ * Summary mode shows the per-version header (paths, shim, capabilities, resource
+ * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
+ * one resource kind; passing a positional query to the same flag fuzzy-searches
+ * for a single resource and prints its detail. Resource names render as OSC-8
+ * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
+ * itself) so users can click straight to the source.
+ */
+import { Command } from 'commander';
+interface InspectOptions {
+    brief?: boolean;
+    json?: boolean;
+    commands?: boolean | string;
+    skills?: boolean | string;
+    hooks?: boolean | string;
+    mcp?: boolean | string;
+    rules?: boolean | string;
+    plugins?: boolean | string;
+    workflows?: boolean | string;
+    subagents?: boolean | string;
+}
+export declare function registerInspectCommand(program: Command): void;
+export declare function inspectAction(target: string, options: InspectOptions): Promise<void>;
+export {};