@tiny-fish/cli 0.2.1 → 0.3.0

package/README.md

@@ -26,6 +26,29 @@ The command replaces existing user- and local-scope TinyFish registrations. It i
 leaves project-scoped `.mcp.json` entries unchanged because those are shared repository
 configuration.
 
+### Connect Codex
+
+Add TinyFish, complete MCP OAuth, and start the interactive walkthrough with one command:
+
+```bash
+npx -y @tiny-fish/cli@latest connect codex --launch
+```
+
+One-command OAuth requires a Codex release whose `codex mcp add` command supports
+`--oauth-resource`. Update Codex if support is unavailable, or add TinyFish manually with
+`codex mcp add`.
+
+### Connect Hermes
+
+Add TinyFish, complete MCP OAuth, and start the interactive walkthrough with one command:
+
+```bash
+npx -y @tiny-fish/cli@latest connect hermes --launch
+```
+
+Hermes completes OAuth while adding the MCP server. After setup, the command starts the walkthrough
+in a Hermes session and leaves that session open for your replies.
+
 ## Authentication
 
 Get your API key from [agent.tinyfish.ai](https://agent.tinyfish.ai).

package/dist/commands/connect.d.ts

@@ -4,4 +4,12 @@ export declare function connectClaudeCode(options: {
     mcpUrl: string;
     launch: boolean;
 }): void;
+export declare function connectCodex(options: {
+    mcpUrl: string;
+    launch: boolean;
+}): void;
+export declare function connectHermes(options: {
+    mcpUrl: string;
+    launch: boolean;
+}): void;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -2,25 +2,104 @@ import spawn from "cross-spawn";
 import { errLine } from "../lib/output.js";
 const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
+const HERMES_SEED_TIMEOUT_MS = 120_000;
 const MCP_LOGIN_UNAVAILABLE_MESSAGE = "This Claude Code installation does not expose `claude mcp login`, which is required for " +
     "one-command MCP authentication. Update Claude Code and retry, or authenticate TinyFish " +
     "manually from /mcp.";
-export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool and walk me through it one step at a " +
-    "time. Ask for my input and wait for my reply before every tool call.";
-function requireNativeMcpLogin() {
-    const result = spawn.sync("claude", ["mcp", "--help"], {
+const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "This Codex installation does not support one-command MCP authentication. Update Codex and " +
+    "retry, or add TinyFish manually with `codex mcp add`.";
+const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "This Hermes installation does not support one-command MCP authentication. Update Hermes and " +
+    "retry, or add TinyFish manually with `hermes mcp add`.";
+export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool now to begin. Then follow its " +
+    "instructions one step at a time. Ask for my input and wait for my reply before each subsequent " +
+    "TinyFish tool call.";
+const CLAUDE_CODE = {
+    command: "claude",
+    displayName: "Claude Code",
+    supportCheck: {
+        args: ["mcp", "--help"],
+        pattern: /^\s*login(?:\s|\[)/m,
+        unavailableMessage: MCP_LOGIN_UNAVAILABLE_MESSAGE,
+    },
+    loginArgs: ["mcp", "login", "tinyfish"],
+    // Project scope is shared in .mcp.json; a user setup command must not rewrite it.
+    removals: [
+        { args: ["mcp", "remove", "tinyfish", "--scope", "user"], label: "user TinyFish registration" },
+        {
+            args: ["mcp", "remove", "tinyfish", "--scope", "local"],
+            label: "local TinyFish registration",
+        },
+    ],
+    addArgs: (mcpUrl) => ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", mcpUrl],
+};
+const CODEX = {
+    command: "codex",
+    displayName: "Codex",
+    supportCheck: {
+        args: ["mcp", "add", "--help"],
+        pattern: /--oauth-resource(?:\s|<)/,
+        unavailableMessage: CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE,
+    },
+    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
+    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl, "--oauth-resource", mcpUrl],
+};
+function launchHermesWalkthrough() {
+    const seedResult = spawn.sync("hermes", ["chat", "-Q", "-q", DEFAULT_ONBOARDING_PROMPT], {
+        encoding: "utf8",
+        timeout: HERMES_SEED_TIMEOUT_MS,
+    });
+    if (seedResult.error || seedResult.status !== 0) {
+        throw new Error("Could not start the TinyFish walkthrough in Hermes", {
+            cause: seedResult.error,
+        });
+    }
+    const sessionId = seedResult.stderr?.match(/session_id:\s*([^\s]+)/i)?.[1];
+    if (!sessionId) {
+        throw new Error("Hermes did not return a walkthrough session ID");
+    }
+    const result = spawn.sync("hermes", ["--resume", sessionId], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error("Could not launch Hermes", { cause: result.error });
+    }
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
+        return;
+    if (result.status !== 0) {
+        throw new Error(`Hermes walkthrough exited with status ${result.status ?? "unknown"}`);
+    }
+}
+const HERMES = {
+    command: "hermes",
+    displayName: "Hermes",
+    supportCheck: {
+        args: ["mcp", "add", "--help"],
+        pattern: /--auth\s+\{[^}]*oauth[^}]*\}/,
+        unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
+    },
+    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Hermes" }],
+    // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
+    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl, "--auth", "oauth"],
+    launchWalkthrough: launchHermesWalkthrough,
+};
+function requireNativeMcpSupport(client) {
+    const result = spawn.sync(client.command, client.supportCheck.args, {
         encoding: "utf8",
         timeout: NON_INTERACTIVE_TIMEOUT_MS,
     });
+    if (result.error?.code === "ENOENT") {
+        throw new Error(`${client.displayName} is not installed or not available on PATH.`, {
+            cause: result.error,
+        });
+    }
     if (result.error || result.status !== 0) {
-        throw new Error(MCP_LOGIN_UNAVAILABLE_MESSAGE, { cause: result.error });
+        throw new Error(client.supportCheck.unavailableMessage, { cause: result.error });
     }
-    if (!/^\s*login(?:\s|\[)/m.test(result.stdout ?? "")) {
-        throw new Error(MCP_LOGIN_UNAVAILABLE_MESSAGE);
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    if (!client.supportCheck.pattern.test(output)) {
+        throw new Error(client.supportCheck.unavailableMessage);
     }
 }
-function removeExistingRegistration(scope) {
-    const result = spawn.sync("claude", ["mcp", "remove", "tinyfish", "--scope", scope], {
+function removeExistingRegistration(client, removal) {
+    const result = spawn.sync(client.command, removal.args, {
         encoding: "utf8",
         timeout: NON_INTERACTIVE_TIMEOUT_MS,
     });
@@ -30,55 +109,72 @@ function removeExistingRegistration(scope) {
     if (/No MCP server named "tinyfish"/i.test(details))
         return;
     if (result.error) {
-        throw new Error(`Could not remove existing ${scope} TinyFish registration: ${details}`, {
+        throw new Error(`Could not remove existing ${removal.label}: ${details}`, {
             cause: result.error,
         });
     }
-    throw new Error(`Could not remove existing ${scope} TinyFish registration: ${details}`);
+    throw new Error(`Could not remove existing ${removal.label}: ${details}`);
 }
-export function connectClaudeCode(options) {
-    requireNativeMcpLogin();
-    // Project scope is shared in .mcp.json; a user setup command must not rewrite it.
-    removeExistingRegistration("user");
-    removeExistingRegistration("local");
-    errLine("Adding TinyFish to Claude Code...");
-    const addResult = spawn.sync("claude", ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", options.mcpUrl], { stdio: "inherit" });
+function connectNativeMcpClient(client, options) {
+    requireNativeMcpSupport(client);
+    for (const removal of client.removals)
+        removeExistingRegistration(client, removal);
+    errLine(`Adding TinyFish to ${client.displayName}...`);
+    const addResult = spawn.sync(client.command, client.addArgs(options.mcpUrl), {
+        stdio: "inherit",
+    });
     if (addResult.error || addResult.status !== 0) {
-        throw new Error("Could not add TinyFish to Claude Code", { cause: addResult.error });
+        throw new Error(`Could not add TinyFish to ${client.displayName}`, {
+            cause: addResult.error,
+        });
     }
-    errLine("Signing in to TinyFish...");
-    const loginResult = spawn.sync("claude", ["mcp", "login", "tinyfish"], { stdio: "inherit" });
-    if (loginResult.error || loginResult.status !== 0) {
-        throw new Error("Could not authenticate TinyFish in Claude Code", {
-            cause: loginResult.error,
+    if (client.loginArgs) {
+        errLine("Signing in to TinyFish...");
+        const loginResult = spawn.sync(client.command, client.loginArgs, {
+            stdio: "inherit",
         });
+        if (loginResult.error || loginResult.status !== 0) {
+            throw new Error(`Could not authenticate TinyFish in ${client.displayName}`, {
+                cause: loginResult.error,
+            });
+        }
     }
     if (!options.launch) {
-        errLine("TinyFish is connected. Open Claude Code to start using it.");
+        errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
         return;
     }
-    errLine("Starting the TinyFish walkthrough in Claude Code...");
-    const result = spawn.sync("claude", [DEFAULT_ONBOARDING_PROMPT], { stdio: "inherit" });
+    errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
+    if (client.launchWalkthrough) {
+        client.launchWalkthrough();
+        return;
+    }
+    const result = spawn.sync(client.command, [DEFAULT_ONBOARDING_PROMPT], { stdio: "inherit" });
     if (result.error) {
-        throw new Error("Could not launch Claude Code", { cause: result.error });
+        throw new Error(`Could not launch ${client.displayName}`, { cause: result.error });
     }
     if (result.signal === "SIGINT" || result.signal === "SIGTERM")
         return;
     if (result.status !== 0) {
-        throw new Error(`Claude Code walkthrough exited with status ${result.status ?? "unknown"}`);
+        throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
     }
 }
+export function connectClaudeCode(options) {
+    connectNativeMcpClient(CLAUDE_CODE, options);
+}
+export function connectCodex(options) {
+    connectNativeMcpClient(CODEX, options);
+}
+export function connectHermes(options) {
+    connectNativeMcpClient(HERMES, options);
+}
 export function registerConnect(program) {
     program
         .command("connect")
         .description("Connect TinyFish to an AI agent")
-        .argument("<client>", "Agent client to connect (claude-code)")
+        .argument("<client>", "Agent client to connect (claude-code, codex, or hermes)")
         .option("--launch", "Launch the agent and start the TinyFish walkthrough")
         .option("--url <mcpUrl>", "MCP endpoint override")
         .action((client, options) => {
-        if (client !== "claude-code") {
-            throw new Error(`Unsupported client: ${client}. Supported client: claude-code`);
-        }
         const mcpUrl = options.url ?? DEFAULT_MCP_URL;
         if (mcpUrl.startsWith("-")) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
@@ -93,9 +189,18 @@ export function registerConnect(program) {
         if (!["http:", "https:"].includes(parsedUrl.protocol)) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
-        connectClaudeCode({
-            mcpUrl,
-            launch: options.launch ?? false,
-        });
+        const connectOptions = { mcpUrl, launch: options.launch ?? false };
+        if (client === "claude-code") {
+            connectClaudeCode(connectOptions);
+        }
+        else if (client === "codex") {
+            connectCodex(connectOptions);
+        }
+        else if (client === "hermes") {
+            connectHermes(connectOptions);
+        }
+        else {
+            throw new Error(`Unsupported client: ${client}. Supported clients: claude-code, codex, hermes`);
+        }
     });
 }

package/package.json

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