@tiny-fish/cli 0.53.1-next.445 → 0.53.1-next.447

package/dist/commands/connect.js

@@ -4,6 +4,7 @@ import { Option } from 'commander';
 import { saveConnectConfigDir, validateKeyFormat, validatedApiKey } from '../lib/auth.js';
 import { runConnectAll } from '../lib/connect-all.js';
 import { ALL_HARNESSES } from '../lib/harness/harness-detect.js';
+import { HARNESS_CHOICES, resolveHarnessName } from '../lib/harness/harness-spec.js';
 import { detectHumanInitiated } from '../lib/harness.js';
 import { emitNotice } from '../lib/notice.js';
 import { errLine } from '../lib/output.js';
@@ -76,7 +77,7 @@ async function connectManyPath(options, mcpUrl, attemptId) {
 }
 async function connectSingleClient(client, options, mcpUrl, attemptId) {
     if (!ALL_HARNESSES.includes(client)) {
-        throw new Error('Unsupported client: ' + client + '. Supported clients: ' + ALL_HARNESSES.join(', '));
+        throw new Error('Unsupported client: ' + client + '. Supported clients: ' + HARNESS_CHOICES.join(', '));
     }
     const connectOptions = {
         apiKey: options.apiKey,
@@ -112,7 +113,7 @@ export function registerConnect(program) {
     program
         .command('connect')
         .description('Connect TinyFish to an AI agent')
-        .argument('[client]', `Agent client to connect (${ALL_HARNESSES.join(', ')}); omit to pick from the agents detected on this machine`)
+        .argument('[client]', `Agent client to connect (${HARNESS_CHOICES.join(', ')}); omit to pick from the agents detected on this machine`)
         .option('--all', 'Detect and connect every supported harness found on this machine')
         .option('--dry-run', 'Print planned writes per harness without touching anything (--all only)')
         .option('--uninstall', 'Remove TinyFish entries written by connect --all')
@@ -144,7 +145,7 @@ export function registerConnect(program) {
             await connectManyPath(options, mcpUrl, attemptId);
             return;
         }
-        await connectSingleClient(client, options, mcpUrl, attemptId);
+        await connectSingleClient(resolveHarnessName(client), options, mcpUrl, attemptId);
         // Deferred to here so the notice lands after install output, not interleaved with it.
         emitNotice();
     });

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { DOCTOR_COULD_NOT_RUN, DOCTOR_INVALID_INPUT, DOCTOR_SCHEMA_VERSION, doct
 import { applyRepairs, repairsFor } from '../lib/doctor-repairs.js';
 import { couldNotRunPayload, telemetryKey, telemetryPayload } from '../lib/doctor-telemetry.js';
 import { ALL_HARNESSES } from '../lib/harness/harness-detect.js';
+import { HARNESS_CHOICES, resolveHarnessName } from '../lib/harness/harness-spec.js';
 import { err, errLine, out, outLine } from '../lib/output.js';
 import { detectRegistrations } from '../lib/registration-detect.js';
 import { sendDoctorCompleted } from '../lib/setup-telemetry.js';
@@ -63,13 +64,15 @@ export function registerDoctor(program) {
         .command('doctor')
         .description('Diagnose your TinyFish setup')
         .option('--pretty', 'Human-readable check list instead of JSON')
-        .option('--harness <name>', `Restrict to one harness (${ALL_HARNESSES.join(', ')})`)
+        .option('--harness <name>', `Restrict to one harness (${HARNESS_CHOICES.join(', ')})`)
         .option('--url <mcpUrl>', 'MCP endpoint override')
         .option('--fix', 'Repair what can be repaired by re-running tinyfish connect')
         .option('--yes', 'Allow --fix to run without a terminal (unattended-safe repairs only)')
         .action(async (options) => {
+        if (options.harness)
+            options.harness = resolveHarnessName(options.harness);
         if (options.harness && !ALL_HARNESSES.includes(options.harness)) {
-            err({ error: `Unknown --harness value: ${options.harness}`, valid: ALL_HARNESSES });
+            err({ error: `Unknown --harness value: ${options.harness}`, valid: HARNESS_CHOICES });
             process.exitCode = DOCTOR_INVALID_INPUT;
             return;
         }

package/dist/lib/auth.d.ts

@@ -12,6 +12,8 @@ interface ConnectEntry {
     auth_mode?: RecordedAuthMode;
     /** `connect cline --config-dir`: uninstall and doctor must find the same store. */
     config_dir?: string;
+    /** Claude Code Directory plugin, not `mcp add` + vendored skills. */
+    plugin?: true;
 }
 interface PendingConnectAttempt {
     id: string;
@@ -35,7 +37,7 @@ export declare function takePendingConnectAttempt(): string | undefined;
 export declare function writeConfig(apiKey: string): void;
 export declare function saveConfig(apiKey: string): void;
 /** `authMode` omitted rewrites the entry without one: a reconnect that degraded must not keep a stale key claim. */
-export declare function saveConnectContext(client: string, attemptId: string, authMode?: RecordedAuthMode): void;
+export declare function saveConnectContext(client: string, attemptId: string, authMode?: RecordedAuthMode, plugin?: boolean): void;
 /** Merged after connect wrote the entry; a missing entry means the install never landed. */
 export declare function saveConnectConfigDir(client: string, configDir: string): void;
 /** Distinguishes a missing entry from an unreadable config file. */

package/dist/lib/auth.js

@@ -60,6 +60,7 @@ function parseConnectMap(value) {
                 ? { auth_mode: authMode }
                 : {}),
             ...(typeof configDir === 'string' ? { config_dir: configDir } : {}),
+            ...(record?.plugin === true ? { plugin: true } : {}),
         };
     }
     return Object.keys(out).length > 0 ? out : undefined;
@@ -132,10 +133,12 @@ export function saveConfig(apiKey) {
     }
 }
 /** `authMode` omitted rewrites the entry without one: a reconnect that degraded must not keep a stale key claim. */
-export function saveConnectContext(client, attemptId, authMode) {
-    const entry = authMode
-        ? { attempt_id: attemptId, auth_mode: authMode }
-        : { attempt_id: attemptId };
+export function saveConnectContext(client, attemptId, authMode, plugin) {
+    const entry = {
+        attempt_id: attemptId,
+        ...(authMode ? { auth_mode: authMode } : {}),
+        ...(plugin ? { plugin: true } : {}),
+    };
     try {
         updateConfig((config) => ({
             ...config,

package/dist/lib/claude-plugin.d.ts

@@ -0,0 +1,19 @@
+export declare const CLAUDE_PLUGIN_SERVER = "plugin:tinyfish:tinyfish";
+export type ClaudePluginInstall = {
+    installed: true;
+    note?: string;
+} | {
+    installed: false;
+    fallbackReason: string;
+};
+/** Seeds the key first; a fallback restores the prior value. */
+export declare function installClaudeDirectoryPlugin(options: {
+    command: string;
+    attemptId: string;
+    apiKey?: string;
+    verbose: boolean;
+}): ClaudePluginInstall;
+/** Compare-only: a key the user set themselves stays. */
+export declare function removeClaudeSettingsKey(): void;
+/** Recorded by connect; upgrade, uninstall and the walkthrough branch on it. */
+export declare function connectedViaClaudePlugin(): boolean;

package/dist/lib/claude-plugin.js

@@ -0,0 +1,101 @@
+import spawn from 'cross-spawn';
+import { z } from 'zod';
+import { CONNECT_SOURCE, loadConfig, matchesCliKey } from './auth.js';
+import { captureStdio, capturedOutput, replay } from './cli-install.js';
+import { throwIfInterrupted } from './connect-runtime.js';
+import { CLAUDE_PLUGIN_ID, HARNESS_PROBE_TIMEOUT_MS, TINYFISH_API_KEY_VAR } from './constants.js';
+import { claudeSettingsPath, readSettingsEnv, writeSettingsEnv } from './config/claude-config.js';
+import { noColourEnv, parseJson } from './output.js';
+export const CLAUDE_PLUGIN_SERVER = 'plugin:tinyfish:tinyfish';
+const installResultSchema = z.looseObject({
+    outcome: z.string(),
+    failureCode: z.string().optional(),
+});
+const pluginListSchema = z.array(z.looseObject({ id: z.string(), enabled: z.boolean() }));
+function claudeJson(command, args, timeout) {
+    const result = spawn.sync(command, args, {
+        ...captureStdio(false),
+        ...(timeout ? { timeout } : {}),
+        env: noColourEnv(),
+    });
+    throwIfInterrupted(result);
+    return result;
+}
+// Directory off fails the install, yet installed plugins keep updating.
+function pluginEnabled(command) {
+    const result = claudeJson(command, ['plugin', 'list', '--json'], HARNESS_PROBE_TIMEOUT_MS);
+    const parsed = pluginListSchema.safeParse(parseJson(String(result.stdout ?? '')));
+    return parsed.success && parsed.data.some((p) => p.id === CLAUDE_PLUGIN_ID && p.enabled);
+}
+function runInstall(command, attemptId, verbose) {
+    const config = {
+        connect_source: CONNECT_SOURCE,
+        connect_client: 'claude-code',
+        connect_attempt_id: attemptId,
+    };
+    const configArgs = Object.entries(config).flatMap(([k, v]) => ['--config', `${k}=${v}`]);
+    const result = claudeJson(command, [
+        'plugin',
+        'install',
+        CLAUDE_PLUGIN_ID,
+        '--json',
+        '-y',
+        ...configArgs,
+    ]);
+    if (verbose)
+        replay(capturedOutput(result));
+    const parsed = installResultSchema.safeParse(parseJson(String(result.stdout ?? '').trim()));
+    if (parsed.success && parsed.data.outcome === 'ok')
+        return { installed: true };
+    if (pluginEnabled(command))
+        return { installed: true };
+    // Older Claude Code prints usage here, not a result line.
+    if (!parsed.success)
+        return { installed: false, fallbackReason: 'unsupported' };
+    // The connect-event route folds codes it cannot hold to `other`.
+    return { installed: false, fallbackReason: parsed.data.failureCode ?? 'unknown' };
+}
+/** Seeds the key first; a fallback restores the prior value. */
+export function installClaudeDirectoryPlugin(options) {
+    const { command, attemptId, apiKey, verbose } = options;
+    let restore;
+    if (apiKey) {
+        try {
+            const previous = readSettingsEnv(TINYFISH_API_KEY_VAR);
+            writeSettingsEnv(TINYFISH_API_KEY_VAR, apiKey);
+            restore = () => writeSettingsEnv(TINYFISH_API_KEY_VAR, previous);
+        }
+        catch {
+            // Malformed settings.json: the header-keyed `mcp add` still works.
+            return { installed: false, fallbackReason: 'settings-unwritable' };
+        }
+    }
+    let outcome;
+    try {
+        outcome = runInstall(command, attemptId, verbose);
+    }
+    catch (error) {
+        restore?.();
+        throw error;
+    }
+    if (!outcome.installed) {
+        restore?.();
+        return outcome;
+    }
+    return apiKey
+        ? {
+            installed: true,
+            note: `Wrote ${TINYFISH_API_KEY_VAR} to ${claudeSettingsPath()} — Claude Code reads the key from there.`,
+        }
+        : outcome;
+}
+/** Compare-only: a key the user set themselves stays. */
+export function removeClaudeSettingsKey() {
+    if (matchesCliKey(readSettingsEnv(TINYFISH_API_KEY_VAR))) {
+        writeSettingsEnv(TINYFISH_API_KEY_VAR, undefined);
+    }
+}
+/** Recorded by connect; upgrade, uninstall and the walkthrough branch on it. */
+export function connectedViaClaudePlugin() {
+    return loadConfig().connect?.['claude-code']?.plugin === true;
+}

package/dist/lib/config/claude-config.d.ts

@@ -4,6 +4,9 @@ export declare const TINYFISH_PERMISSION = "Bash(tinyfish:*)";
 export declare const CLAUDE_MD_MARKER = "<!-- tinyfish-configure-claude -->";
 export declare function readSettingsJson(): Record<string, unknown>;
 export declare function writeSettingsJson(settings: Record<string, unknown>): void;
+export declare function readSettingsEnv(name: string): string | undefined;
+/** `undefined` deletes the variable; every other setting survives. */
+export declare function writeSettingsEnv(name: string, value: string | undefined): void;
 export declare function mergeSettings(existing: Record<string, unknown>): Record<string, unknown>;
 export declare function removeFromSettings(existing: Record<string, unknown>): Record<string, unknown>;
 export declare function readClaudeMd(): string;

package/dist/lib/config/claude-config.js

@@ -1,9 +1,9 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
+import { agentHome } from '../skill-paths.js';
 // ─── Path helpers ─────────────────────────────────────────────────────────────
 function claudeDir() {
-    return path.join(os.homedir(), '.claude');
+    return agentHome('CLAUDE_CONFIG_DIR', '.claude');
 }
 export function claudeSettingsPath() {
     return path.join(claudeDir(), 'settings.json');
@@ -89,7 +89,34 @@ export function readSettingsJson() {
 }
 export function writeSettingsJson(settings) {
     fs.mkdirSync(claudeDir(), { recursive: true });
-    fs.writeFileSync(claudeSettingsPath(), JSON.stringify(settings, null, 2) + '\n');
+    const file = claudeSettingsPath();
+    // Settings `env` can hold the key; `mode` only applies on create.
+    if (fs.existsSync(file))
+        fs.chmodSync(file, 0o600);
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
+}
+function settingsEnv(settings) {
+    const env = settings.env;
+    return env !== null && typeof env === 'object' && !Array.isArray(env)
+        ? env
+        : {};
+}
+export function readSettingsEnv(name) {
+    const value = settingsEnv(readSettingsJson())[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/** `undefined` deletes the variable; every other setting survives. */
+export function writeSettingsEnv(name, value) {
+    const settings = readSettingsJson();
+    const env = { ...settingsEnv(settings) };
+    if (value === undefined)
+        delete env[name];
+    else
+        env[name] = value;
+    const next = { ...settings, env };
+    if (Object.keys(env).length === 0)
+        delete next.env;
+    writeSettingsJson(next);
 }
 // ─── settings.json merge / remove ─────────────────────────────────────────────
 export function mergeSettings(existing) {

package/dist/lib/connect-all-uninstall.js

@@ -8,6 +8,8 @@ import { planOmpWrite, removeOmpMcpServer } from './config/omp-config.js';
 import { piMcpPath, planPiWrite, removePiMcpServer } from './config/pi-config.js';
 import { HERMES_KEY_VAR, hermesEnvPath, removeHermesKey, resolveHermesHome } from './hermes-env.js';
 import { clearHermesWebBackends } from './hermes-plugin.js';
+import { removeClaudeSettingsKey } from './claude-plugin.js';
+import { claudeSettingsPath } from './config/claude-config.js';
 import { HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, harnessDisplayPath, } from './harness/harness-detect.js';
 import { ALL_HARNESSES, harnessSpec } from './harness/harness-spec.js';
 import { skillRootDir } from './skill-paths.js';
@@ -156,6 +158,23 @@ function hermesKeyKeptAdvisory() {
     return (`left ${HERMES_KEY_VAR} in Hermes' .env because the entry was not removed. ` +
         'Run the command above, then re-run `tinyfish connect --all --uninstall` to clear it.');
 }
+/** Every Claude Code subprocess inherits settings `env`. */
+function clearClaudeSettingsKey() {
+    try {
+        removeClaudeSettingsKey();
+        return undefined;
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        return `could not clear TINYFISH_API_KEY from ${claudeSettingsPath()} (${detail}); delete it from \`env\` by hand.`;
+    }
+}
+function localStateAdvisory(harness, removed) {
+    if (harness === 'hermes')
+        return removed ? clearHermesLocalState() : hermesKeyKeptAdvisory();
+    // Not removed: the plugin still reads the key.
+    return harness === 'claude-code' && removed ? clearClaudeSettingsKey() : undefined;
+}
 function runRemovalCommands(detection, removal, verbose) {
     const { harness } = detection;
     let removed = false;
@@ -280,8 +299,10 @@ export function uninstallHarness(harness, configPath, verbose, binaryOnPath) {
     // Clearing state the entry still references would break a working install.
     const removed = !result.removalFailed &&
         (result.outcome === 'uninstalled' || result.outcome === 'uninstall_noop');
-    const hermesAdvisory = harness !== 'hermes' ? undefined : removed ? clearHermesLocalState() : hermesKeyKeptAdvisory();
-    const advisory = [removed ? removeHarnessSkills(harness) : undefined, hermesAdvisory]
+    const advisory = [
+        removed ? removeHarnessSkills(harness) : undefined,
+        localStateAdvisory(harness, removed),
+    ]
         .filter((text) => text !== undefined)
         .join(' ');
     if (!advisory)

package/dist/lib/connect-all.d.ts

@@ -39,4 +39,5 @@ export interface ConnectAllOptions {
 /** The harness has never created its dir, so connecting would build one it does not own. */
 export declare function needsFirstRun(detection: HarnessDetection): boolean;
 export declare function runConnectAll(opts: ConnectAllOptions): Promise<number>;
+export declare const firstTaskPrompt: (server?: string) => string;
 export declare const FIRST_TASK_PROMPT: string;

package/dist/lib/connect-all.js

@@ -1,3 +1,4 @@
+import { CLAUDE_PLUGIN_SERVER, connectedViaClaudePlugin } from './claude-plugin.js';
 import * as readline from 'node:readline/promises';
 import { harnessSpec } from './harness/harness-spec.js';
 import spawn from 'cross-spawn';
@@ -9,7 +10,7 @@ import { authGate, mapConnectError, OAUTH_SIGN_IN_TIMEOUT_MS } from './connect-a
 import { actionable, computeExitCode, reloadHint, renderSummary } from './connect-all-summary.js';
 import { planText, uninstallHarness, uninstallPlanText } from './connect-all-uninstall.js';
 import { createStdinPrompt, runCliFallback } from './connect-fallback.js';
-import { KEYLESS_ONBOARDING_PROMPT } from './connect-clients.js';
+import { KEYLESS_ONBOARDING_PROMPT, useServerLine } from './connect-clients.js';
 import { gateApiKey } from './connect-preflight.js';
 import { ConnectInterruptedError } from './connect-runtime.js';
 import { pickHarnesses } from './connect-picker.js';
@@ -386,13 +387,13 @@ export async function runConnectAll(opts) {
     }
     return finishRun(results, opts, isTTY);
 }
-export const FIRST_TASK_PROMPT = 'My TinyFish setup just finished — verify it with a real run. Use the MCP server named ' +
-    '`tinyfish` for every TinyFish tool call; if another TinyFish server is also registered, still ' +
-    "use `tinyfish` and do not ask me which. Then use the TinyFish search tool to find today's " +
-    'top Hacker News story, fetch that page with the TinyFish fetch tool, and give me a two-line ' +
+export const firstTaskPrompt = (server = 'tinyfish') => `My TinyFish setup just finished — verify it with a real run. ${useServerLine(server)} ` +
+    "Then use the TinyFish search tool to find today's top Hacker News story," +
+    ' fetch that page with the TinyFish fetch tool, and give me a two-line ' +
     'summary. Show which tools you call. If a tool call comes back blocked or not approved, tell ' +
     'me which tool needs approval and how to grant it, then wait for me instead of abandoning the ' +
     'task.';
+export const FIRST_TASK_PROMPT = firstTaskPrompt();
 // Launchable seeded agents, best-first — cursor-agent shares ~/.cursor/mcp.json with the IDE.
 const LAUNCHERS = [
     { harness: 'cursor', args: [FIRST_TASK_PROMPT] },
@@ -430,7 +431,12 @@ async function launchFirstTask(results) {
     outLine(`Starting ${DISPLAY_NAMES[chosen.harness]} with your first TinyFish task...`);
     const keyless = chosen.harness === 'omp' &&
         results.some((result) => result.harness === 'omp' && !result.keyAuthed);
-    const args = keyless ? [KEYLESS_ONBOARDING_PROMPT] : chosen.args;
+    const pluginServer = chosen.harness === 'claude-code' && connectedViaClaudePlugin();
+    const args = keyless
+        ? [KEYLESS_ONBOARDING_PROMPT]
+        : pluginServer
+            ? [firstTaskPrompt(CLAUDE_PLUGIN_SERVER)]
+            : chosen.args;
     const result = spawn.sync(HARNESS_COMMANDS[chosen.harness], args, { stdio: 'inherit' });
     return !result.error;
 }

package/dist/lib/connect-clients.d.ts

@@ -1,6 +1,7 @@
 import spawn from 'cross-spawn';
 import { type AgentClient, type SupportedCommand } from './connect-runtime.js';
 import { type HarnessSpec, type SkillAgent } from './harness/harness-spec.js';
+import { installClaudeDirectoryPlugin } from './claude-plugin.js';
 export declare function openclawSkillInstallArgs(ackFlag: string | undefined): string[];
 /** `openclaw skills` has no uninstall; ClawHub removes from the global dir. */
 export declare function openclawSkillUninstall(): {
@@ -9,6 +10,8 @@ export declare function openclawSkillUninstall(): {
     /** npx fetches the package first; the 10s removal bound starves a cold cache. */
     timeoutMs: number;
 };
+export declare const useServerLine: (server: string) => string;
+export declare const onboardingPrompt: (server?: string) => string;
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
 export declare const KEYLESS_ONBOARDING_PROMPT: string;
@@ -70,6 +73,13 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
         args: string[];
         label: string;
     };
+    pluginInstall?: PluginInstall;
+}
+/** Replaces `mcp add`; a fallback reason means the add runs instead. */
+export interface PluginInstall {
+    install: typeof installClaudeDirectoryPlugin;
+    loginArgs: string[];
+    serverName: string;
 }
 /** Keyless installs use this argv; the harness signs itself in. */
 interface OauthCapableMcpClient extends BaseMcpClient {

package/dist/lib/connect-clients.js

@@ -9,6 +9,7 @@ import { HARNESS_SPECS, NATIVE_HARNESSES, harnessSpec, } from './harness/harness
 import { HERMES_KEY_VAR, captureHermesKeyRestore, hermesEnvPath, resolveHermesHome, writeHermesKey, } from './hermes-env.js';
 import { hermesConfigPath, readHermesEntry } from './config/hermes-config.js';
 import { installHermesPlugin, removeHermesMcpEntry, setHermesWebBackends, writeHermesMcpEntry, } from './hermes-plugin.js';
+import { CLAUDE_PLUGIN_SERVER, installClaudeDirectoryPlugin } from './claude-plugin.js';
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 const OPENCLAW_SKILL = '@tinyfish/tinyfish';
 // --force makes this an unconditional overwrite, so the same call installs and refreshes.
@@ -33,13 +34,15 @@ export function openclawSkillUninstall() {
         timeoutMs: SKILL_INSTALL_TIMEOUT_MS,
     };
 }
-export const DEFAULT_ONBOARDING_PROMPT = 'I just connected TinyFish. Use the MCP server named `tinyfish` for every TinyFish tool call; ' +
-    'if another TinyFish server is also registered, still use `tinyfish` and do not ask me which. ' +
+export const useServerLine = (server) => `Use the MCP server named \`${server}\` for every TinyFish tool call; if another TinyFish ` +
+    `server is also registered, still use \`${server}\` and do not ask me which.`;
+export const onboardingPrompt = (server = 'tinyfish') => `I just connected TinyFish. ${useServerLine(server)} ` +
     'Start by asking me what I want to look up on the web, and wait for my reply. Then call ' +
     '`guide_next_step` and follow its instructions one step at a time, asking for my input and ' +
     'waiting for my reply before each subsequent TinyFish tool call. If a tool call comes back ' +
     'blocked or not approved, tell me which tool needs approval and how to grant it, then wait for ' +
     'me instead of ending the walkthrough.';
+export const DEFAULT_ONBOARDING_PROMPT = onboardingPrompt();
 export const OPENCLAW_ONBOARDING_PROMPT = 'I just installed the TinyFish skill. Guide me through it interactively: first ask what topic I ' +
     'want to search and wait for my reply before using TinyFish Search. Show me the results, ask ' +
     'which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task ' +
@@ -258,6 +261,13 @@ function specKeyAuth(spec) {
 }
 /** Descriptor behaviour the spec cannot hold; every other field is spec data. */
 const HARNESS_OVERRIDES = {
+    'claude-code': {
+        pluginInstall: {
+            install: installClaudeDirectoryPlugin,
+            loginArgs: ['mcp', 'login', CLAUDE_PLUGIN_SERVER],
+            serverName: CLAUDE_PLUGIN_SERVER,
+        },
+    },
     cline: { launchWalkthrough: launchCline },
     codex: { detachedLaunch: launchCodexWalkthrough },
     hermes: {
@@ -301,6 +311,7 @@ function toNativeClient(harness) {
         extraPostInstall: overrides.extraPostInstall,
         uninstallExtra: spec.uninstallExtra,
         verifyListed: spec.verifyListed,
+        pluginInstall: overrides.pluginInstall,
     };
     if (spec.keyRequired) {
         if (!keyAuth)

package/dist/lib/connect-native.js

@@ -1,6 +1,6 @@
 import spawn from 'cross-spawn';
 import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validatedApiKey, } from './auth.js';
-import { KEYLESS_ONBOARDING_PROMPT, launchNativeMcpClient, } from './connect-clients.js';
+import { KEYLESS_ONBOARDING_PROMPT, launchNativeMcpClient, onboardingPrompt, } from './connect-clients.js';
 import { captureStdio, capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
 import { ensureCliAuthenticated } from './connect-auth.js';
 import { installWebSkill } from './skill-install.js';
@@ -14,7 +14,8 @@ import { SIGN_IN_PROBES, TINYFISH_LIST_ROW } from './registration-detect.js';
 import { errLine, sanitizeLine, warnLine } from './output.js';
 import { verifyMcpAuth } from './verify.js';
 import { dotenvMarkerHead, harnessDotenvPath, writeDotenvKey } from './dotenv-file.js';
-import { apiBaseFromMcpUrl } from './mcp-endpoint.js';
+import { apiBaseFromMcpUrl, isDefaultEndpoint } from './mcp-endpoint.js';
+import { removeWebSkills } from './skill-vendor.js';
 import { finishSetupHint, requireKeylessMcp, requireSupportOrRescue, runCliInstallStep, trackPostInstallFailure, walkthroughPhase, } from './connect-steps.js';
 /** Several installs can disagree; every later spawn reuses this one. */
 function pinExecutable(client) {
@@ -243,8 +244,27 @@ function performDirectInstall(client, install, mcpUrl) {
     const detail = registered.detail ? `: ${registered.detail}` : '';
     throw new ConnectStepError(`${client.displayName} reported success but TinyFish is not enabled there${detail}.`, 'invalid_config', { failureDetail: registered.tag });
 }
-/** Returns the seeded-credential note when a key was written into a user-owned file. */
+/** Directory plugin first; on any fallback reason, the harness add. */
 function performMcpAdd(client, options, plan, attemptId) {
+    if (!client.pluginInstall)
+        return performHarnessAdd(client, options, plan, attemptId);
+    let pluginFallbackReason = 'custom-url';
+    // The plugin pins the prod endpoint; `--url` needs the add.
+    if (isDefaultEndpoint(options.mcpUrl)) {
+        errLine(`Installing the TinyFish plugin in ${client.displayName}...`);
+        const plugin = client.pluginInstall.install({
+            command: client.command,
+            attemptId,
+            apiKey: plan.keyedAdd?.key,
+            verbose: options.verbose ?? false,
+        });
+        if (plugin.installed)
+            return { note: plugin.note, plugin: true };
+        pluginFallbackReason = plugin.fallbackReason;
+    }
+    return { ...performHarnessAdd(client, options, plan, attemptId), pluginFallbackReason };
+}
+function performHarnessAdd(client, options, plan, attemptId) {
     const { keyedAdd, buildAddArgs, directInstall } = plan;
     const mcpUrl = new URL(options.mcpUrl);
     mcpUrl.searchParams.set('source', CONNECT_SOURCE);
@@ -363,6 +383,10 @@ async function completeAuthFlow(client, options, state, telemetry, ctx) {
             : AuthMode.OAuth;
     return { authMode, signInDeferred };
 }
+/** A degraded harness keeps sign-in deferred on the plugin path too. */
+function authLoginArgs(client, loginArgs, plugin) {
+    return plugin ? loginArgs && client.pluginInstall?.loginArgs : loginArgs;
+}
 export async function connectNativeMcpClient(unpinned, options) {
     const client = pinExecutable(unpinned);
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
@@ -391,8 +415,9 @@ export async function connectNativeMcpClient(unpinned, options) {
         // A probed client authenticates inside `mcp add` too, so a failure there is either.
         state.stage =
             loginArgs && !probeAuthenticated ? 'registration' : 'registration_or_authentication';
-        const { note: seededNote, seededHome } = performMcpAdd(client, options, plan, telemetry.attemptId);
-        telemetry.track('checkpoint', { phase: 'registered' });
+        const { note: seededNote, seededHome, plugin, pluginFallbackReason, } = performMcpAdd(client, options, plan, telemetry.attemptId);
+        state.plugin = plugin;
+        telemetry.track('checkpoint', { phase: 'registered', pluginFallbackReason });
         // Only 2.x lists a variant, and only 2.x wrote the project file (PF-6613).
         const twoPointX = client.verifyListed && matchedVariant !== undefined;
         for (const stray of twoPointX ? strayProjectKeyFiles() : []) {
@@ -402,7 +427,7 @@ export async function connectNativeMcpClient(unpinned, options) {
             useKeyAuth,
             useKeyless,
             loginDegraded,
-            loginArgs,
+            loginArgs: authLoginArgs(client, loginArgs, plugin),
             detachedLogin: !!client.detachedLoginVariant && matchedVariant === client.detachedLoginVariant,
             probeAuthenticated,
             seededNote,
@@ -470,13 +495,18 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
     };
     try {
         // Above every step: a Ctrl+C below must not lose a registration already reported (PF-3803).
-        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
+        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode, state.plugin);
         if (options.cliInstall !== false) {
             await attempt('cli_install', () => runCliInstallStep(options, telemetry));
         }
-        if (client.skillAgent) {
+        const { skillAgent } = client;
+        if (skillAgent) {
             await attempt('skill_install', () => {
-                installWebSkill(client, { verbose: options.verbose ?? false });
+                // The plugin ships its own skills; vendored copies would duplicate them.
+                if (state.plugin)
+                    removeWebSkills(skillAgent);
+                else
+                    installWebSkill(client, { verbose: options.verbose ?? false });
                 telemetry.track('checkpoint', { phase: 'skill_installed' });
             });
         }
@@ -509,7 +539,9 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                     telemetry.track('checkpoint', { phase: walkthroughPhase(outcome) });
                     // Flushed pre-block; the session-long handover would strand the delivery.
                     await telemetry.flush();
-                }, state.authMode === AuthMode.Keyless ? KEYLESS_ONBOARDING_PROMPT : undefined);
+                }, state.authMode === AuthMode.Keyless
+                    ? KEYLESS_ONBOARDING_PROMPT
+                    : onboardingPrompt(state.plugin ? client.pluginInstall?.serverName : undefined));
             });
         }
     }

package/dist/lib/connect-runtime.d.ts

@@ -62,6 +62,8 @@ export interface ConnectRunState {
     harnessDegraded?: boolean;
     /** Resolved after the probe, so callers read real key use rather than key presence. */
     authMode?: ConnectAuthMode;
+    /** The Directory plugin replaced `mcp add` and the vendored skills. */
+    plugin?: boolean;
 }
 interface ConnectStageDetail {
     failedStage?: ConnectFailureStage;
@@ -79,6 +81,8 @@ interface ConnectStageDetail {
     failureDetail?: string;
     /** pi only: without the adapter its MCP entry is dormant. */
     piAdapterState?: PiAdapterState;
+    /** claude-code only: why connect skipped the Directory plugin. */
+    pluginFallbackReason?: string;
 }
 export interface ConnectTelemetry {
     attemptId: string;

package/dist/lib/connect-runtime.js

@@ -195,9 +195,9 @@ function isBelowMin(version, minVersion) {
 // Flags go unseen for reasons besides age; state facts, not causes.
 function unavailableMessage(client, version) {
     const { minVersion } = client.supportCheck;
-    const found = version ? ` (found ${version})` : '';
-    const required = minVersion && (isBelowMin(version, minVersion) ?? version === undefined)
-        ? ` ${client.displayName} ${minVersion} or newer is required${found}.`
+    // A known version below the minimum already failed in requireMinVersion.
+    const required = minVersion && version === undefined
+        ? ` ${client.displayName} ${minVersion} or newer is required.`
         : '';
     return (`${client.supportCheck.unavailableMessage}${required}` +
         ' Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.');
@@ -292,8 +292,8 @@ export function requireCommandSupport(client) {
 }
 // Old releases can list the flags yet mishandle them; unknown passes.
 function requireMinVersion(client, harnessVersion) {
-    const { minVersion, updateCommand, enforceMinVersion } = client.supportCheck;
-    if (!enforceMinVersion || !isBelowMin(harnessVersion, minVersion))
+    const { minVersion, updateCommand } = client.supportCheck;
+    if (!isBelowMin(harnessVersion, minVersion))
         return;
     const fix = updateCommand ? `Run \`${updateCommand}\`` : `Update ${client.displayName}`;
     throw new ConnectStepError(`${client.displayName} ${minVersion} or newer is required (found ${harnessVersion}). ` +
@@ -353,22 +353,24 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
         });
     }
     function eventBody(stage, detail, stageDurationMs) {
+        const d = detail ?? {};
         return JSON.stringify({
             attempt_id: attemptId,
             client,
             stage,
-            failed_stage: detail?.failedStage,
-            phase: detail?.phase,
-            failure_reason: detail?.failureReason,
+            failed_stage: d.failedStage,
+            phase: d.phase,
+            failure_reason: d.failureReason,
             // Only with failed_stage: the route refine 400s the event otherwise.
-            failure_detail: detail?.failedStage ? detail.failureDetail : undefined,
+            failure_detail: d.failedStage ? d.failureDetail : undefined,
             // Terminal rows only: rescue checkpoints stay wire-identical to normal ones.
             fallback_outcome: stage === 'failed' || stage === 'aborted' ? fallbackOutcome : undefined,
-            harness_version: detail?.harnessVersion ?? harnessVersion,
-            plugin_version: detail?.pluginVersion,
-            auth_mode: detail?.authMode,
-            harness_degraded: detail?.harnessDegraded,
-            pi_adapter_state: detail?.piAdapterState,
+            harness_version: d.harnessVersion ?? harnessVersion,
+            plugin_version: d.pluginVersion,
+            auth_mode: d.authMode,
+            harness_degraded: d.harnessDegraded,
+            pi_adapter_state: d.piAdapterState,
+            plugin_fallback_reason: d.pluginFallbackReason,
             stage_duration_ms: stageDurationMs,
             runtime_platform: process.platform,
             node_version: process.version,

package/dist/lib/constants.d.ts

@@ -21,3 +21,4 @@ export declare const HARNESS_PROBE_TIMEOUT_MS = 15000;
 export declare const HERMES_COLD_START_TIMEOUT_MS = 60000;
 /** Hermes' own id for the TinyFish web plugin. */
 export declare const HERMES_PLUGIN_NAME = "tinyfish";
+export declare const CLAUDE_PLUGIN_ID = "tinyfish@anthropic-plugin-directory";

package/dist/lib/constants.js

@@ -66,3 +66,4 @@ export const HARNESS_PROBE_TIMEOUT_MS = 15_000;
 export const HERMES_COLD_START_TIMEOUT_MS = 60_000;
 /** Hermes' own id for the TinyFish web plugin. */
 export const HERMES_PLUGIN_NAME = 'tinyfish';
+export const CLAUDE_PLUGIN_ID = 'tinyfish@anthropic-plugin-directory';

package/dist/lib/harness/harness-spec.d.ts

@@ -16,8 +16,6 @@ export interface HarnessSupportCheck {
     timeoutMs?: number;
     /** First release with the probed flags; bisected upstream, not derivable. */
     minVersion?: string;
-    /** Refuse below minVersion even when the probed flags are listed. */
-    enforceMinVersion?: true;
     /** Shown in the below-minVersion error as the one-step fix. */
     updateCommand?: string;
     unavailableMessage: string;
@@ -125,6 +123,10 @@ export declare const HARNESS_SPECS: {
             args: string[];
             label: string;
         }[];
+        uninstallExtra: {
+            args: string[];
+            label: string;
+        };
     };
     cline: {
         command: string;
@@ -229,7 +231,6 @@ export declare const HARNESS_SPECS: {
             keyAuthPattern: RegExp;
             timeoutMs: number;
             minVersion: string;
-            enforceMinVersion: true;
             updateCommand: string;
             unavailableMessage: string;
         };
@@ -334,6 +335,8 @@ export declare const HARNESS_SPECS: {
 /** Derived from spec keys; one entry extends every union. */
 export type Harness = keyof typeof HARNESS_SPECS;
 export declare const ALL_HARNESSES: readonly Harness[];
+export declare const HARNESS_CHOICES: string[];
+export declare function resolveHarnessName(name: string): string;
 export declare function harnessSpec(harness: Harness): HarnessSpec;
 /** The rest of the union: every one of these must supply a connect and launch override. */
 export type NonNativeHarness = {

package/dist/lib/harness/harness-spec.js

@@ -1,4 +1,4 @@
-import { HERMES_COLD_START_TIMEOUT_MS, HERMES_PLUGIN_NAME } from '../constants.js';
+import { CLAUDE_PLUGIN_ID, HERMES_COLD_START_TIMEOUT_MS, HERMES_PLUGIN_NAME, } from '../constants.js';
 import { CLAUDE_CODE_DEFERRED_AUTH_NOTE, CLAUDE_CODE_KEYED_FALLBACK_NOTE, CLINE_MCP_ADD_UNAVAILABLE_MESSAGE, CODEX_DEFERRED_AUTH_NOTE, CODEX_KEYED_FALLBACK_NOTE, CODEX_MCP_URL_UNAVAILABLE_MESSAGE, GROK_HTTP_UNAVAILABLE_MESSAGE, GROK_SIGN_IN_HINT, HERMES_OAUTH_UNAVAILABLE_MESSAGE, HERMES_RESTART_NOTE, KILO_MCP_ADD_UNAVAILABLE_MESSAGE, MCP_ADD_UNAVAILABLE_MESSAGE, OPENCLAW_SKILL_UNAVAILABLE_MESSAGE, OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE, OPENCODE_MODEL_NOTE, } from './harness-messages.js';
 const HEADER_FLAG = /(?:^|\s)--header(?:[\s<=]|$)/m;
 /** One entry per harness; every per-harness list derives from it. */
@@ -35,7 +35,17 @@ export const HARNESS_SPECS = {
                 args: ['mcp', 'remove', 'tinyfish', '--scope', 'local'],
                 label: 'local TinyFish registration',
             },
+            // Cookbook plugin server is also plugin:tinyfish:tinyfish; it shadows ours.
+            {
+                args: ['plugin', 'uninstall', 'tinyfish@tinyfish-marketplace'],
+                label: 'TinyFish cookbook plugin',
+            },
         ],
+        // Not a removal: those run pre-add and would undo a Directory-off keep.
+        uninstallExtra: {
+            args: ['plugin', 'uninstall', CLAUDE_PLUGIN_ID],
+            label: 'TinyFish Directory plugin',
+        },
     },
     cline: {
         command: 'cline',
@@ -145,7 +155,6 @@ export const HARNESS_SPECS = {
             timeoutMs: HERMES_COLD_START_TIMEOUT_MS,
             // Older `config set` saves our JSON entry as an unusable string.
             minVersion: '0.21.2',
-            enforceMinVersion: true,
             updateCommand: 'hermes update',
             unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
         },
@@ -257,6 +266,12 @@ export const HARNESS_SPECS = {
     },
 };
 export const ALL_HARNESSES = Object.keys(HARNESS_SPECS);
+// Input-only: telemetry, insights and the cookbook doctor skill key on `claude-code`.
+const HARNESS_ALIASES = { claude: 'claude-code' };
+export const HARNESS_CHOICES = [...ALL_HARNESSES, ...Object.keys(HARNESS_ALIASES)];
+export function resolveHarnessName(name) {
+    return Object.hasOwn(HARNESS_ALIASES, name) ? HARNESS_ALIASES[name] : name;
+}
 export function harnessSpec(harness) {
     return HARNESS_SPECS[harness];
 }

package/dist/lib/skill-install.js

@@ -31,13 +31,16 @@ function freshBundleDir() {
 export function updateWebSkill({ verbose }) {
     // One entry per `tinyfish connect <client>`, persisted by PF-3169.
     const connected = loadConfig().connect ?? {};
-    const skillAgents = ALL_HARNESSES.filter((harness) => connected[harness])
+    // A plugin install ships and updates its own skills.
+    const skillAgents = ALL_HARNESSES.filter((h) => connected[h] && !connected[h].plugin)
         .map((harness) => harnessSpec(harness).skillAgent)
         .filter((agent) => agent !== undefined);
     const hasOpenClaw = Boolean(connected['openclaw']);
     // No recorded skill install means no target dirs; connect is the install path.
     if (skillAgents.length === 0 && !hasOpenClaw) {
-        errLine('No TinyFish skills to refresh. Run `tinyfish connect <client>` to install them.');
+        if (!Object.values(connected).some((entry) => entry.plugin)) {
+            errLine('No TinyFish skills to refresh. Run `tinyfish connect <client>` to install them.');
+        }
         return false;
     }
     let refreshed = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.53.1-next.445",
+  "version": "0.53.1-next.447",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {