@zhihand/mcp 0.19.1 → 0.20.0

package/bin/zhihand

@@ -6,7 +6,7 @@ import { startStdioServer } from "../dist/index.js";
 import { startDaemon, stopDaemon, isAlreadyRunning } from "../dist/daemon/index.js";
 import { detectCLITools, formatDetectedTools } from "../dist/cli/detect.js";
 import { detectAndSetupOpenClaw } from "../dist/cli/openclaw.js";
-import { loadDefaultCredential, loadBackendConfig, saveBackendConfig } from "../dist/core/config.js";
+import { loadDefaultCredential, loadBackendConfig, saveBackendConfig, DEFAULT_MODELS } from "../dist/core/config.js";
 import { executePairing } from "../dist/core/pair.js";
 import { configureMCP, displayName } from "../dist/cli/mcp-config.js";
 
@@ -23,6 +23,7 @@ const { positionals, values } = parseArgs({
   strict: false,
   options: {
     device: { type: "string" },
+    model: { type: "string", short: "m" },
     help: { type: "boolean", short: "h", default: false },
     detach: { type: "boolean", short: "d", default: false },
     port: { type: "string" },
@@ -41,9 +42,10 @@ Usage:
   zhihand stop               Stop daemon
   zhihand status             Show status (pairing, backend, brain)
 
-  zhihand gemini             Switch backend to Gemini CLI
-  zhihand claude             Switch backend to Claude Code
-  zhihand codex              Switch backend to Codex CLI
+  zhihand gemini             Switch backend to Gemini CLI (default model: flash)
+  zhihand claude             Switch backend to Claude Code (default model: sonnet)
+  zhihand codex              Switch backend to Codex CLI (default model: gpt-5.4-mini)
+  zhihand gemini --model pro Switch backend with custom model
 
   zhihand setup              Interactive setup: pair + configure + start
   zhihand pair               Pair with a phone device
@@ -53,6 +55,7 @@ Usage:
 
 Options:
   --device <name>    Use a specific paired device
+  --model, -m <name> Set model alias (e.g. flash, pro, sonnet, opus, gpt-5.4-mini)
   --port <port>      Override daemon port (default: 18686)
   -d, --detach       Run daemon in background
   -h, --help         Show this help
@@ -82,12 +85,15 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
   const config = loadBackendConfig();
   const previous = config.activeBackend;
 
-  if (previous === backendName) {
-    console.log(`Already using ${displayName(backendName)} as backend.`);
+  const userModel = values.model ?? null;
+  const effectiveModel = userModel ?? DEFAULT_MODELS[backendName];
+
+  if (previous === backendName && !userModel) {
+    console.log(`Already using ${displayName(backendName)} as backend (model: ${effectiveModel}).`);
     process.exit(0);
   }
 
-  console.log(`Switching backend to ${displayName(backendName)}...`);
+  console.log(`Switching backend to ${displayName(backendName)} (model: ${effectiveModel})...`);
 
   // Configure MCP (HTTP transport)
   const { configured, removed } = configureMCP(backendName, previous);
@@ -100,7 +106,7 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
         const res = await fetch(`http://127.0.0.1:${port}/internal/backend`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ backend: backendName }),
+          body: JSON.stringify({ backend: backendName, model: userModel }),
           signal: AbortSignal.timeout(5000),
         });
         if (res.ok) {
@@ -108,11 +114,11 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
         }
       } catch {
         // Daemon not responding, just save config
-        saveBackendConfig({ activeBackend: backendName });
+        saveBackendConfig({ activeBackend: backendName, model: userModel });
         console.log(`\nBackend config saved. Daemon not responding — restart with 'zhihand start'.`);
       }
     } else {
-      saveBackendConfig({ activeBackend: backendName });
+      saveBackendConfig({ activeBackend: backendName, model: userModel });
       console.log(`\nBackend switched to ${displayName(backendName)}.`);
       console.log(`Start the daemon to receive prompts: zhihand start`);
     }
@@ -199,7 +205,11 @@ switch (command) {
     } else {
       console.log("No paired device. Run: zhihand setup");
     }
-    console.log(`Active backend: ${backend.activeBackend ? displayName(backend.activeBackend) : "(none)"}`);
+    const backendLabel = backend.activeBackend ? displayName(backend.activeBackend) : "(none)";
+    const modelLabel = backend.activeBackend
+      ? (backend.model ?? DEFAULT_MODELS[backend.activeBackend])
+      : "-";
+    console.log(`Active backend: ${backendLabel} (model: ${modelLabel})`);
     console.log(`Daemon: ${daemonPid ? `running (PID ${daemonPid})` : "not running"}`);
 
     // If daemon running, get live status

package/dist/core/config.d.ts

@@ -19,7 +19,16 @@ export interface ZhiHandConfig {
 export type BackendName = "claudecode" | "codex" | "gemini" | "openclaw";
 export interface BackendConfig {
     activeBackend: BackendName | null;
+    model?: string | null;
 }
+/**
+ * Default model aliases per backend.
+ * These are generic aliases that the respective CLIs resolve to the latest version:
+ *   - Gemini CLI: "flash" → latest flash model (e.g. gemini-2.5-flash)
+ *   - Claude Code: "sonnet" → latest sonnet (e.g. claude-sonnet-4-20250514)
+ *   - Codex CLI: requires full model name, no alias support
+ */
+export declare const DEFAULT_MODELS: Record<Exclude<BackendName, "openclaw">, string>;
 export declare function resolveZhiHandDir(): string;
 export declare function ensureZhiHandDir(): void;
 export declare function loadCredentialStore(): CredentialStore | null;

package/dist/core/config.js

@@ -1,6 +1,18 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+/**
+ * Default model aliases per backend.
+ * These are generic aliases that the respective CLIs resolve to the latest version:
+ *   - Gemini CLI: "flash" → latest flash model (e.g. gemini-2.5-flash)
+ *   - Claude Code: "sonnet" → latest sonnet (e.g. claude-sonnet-4-20250514)
+ *   - Codex CLI: requires full model name, no alias support
+ */
+export const DEFAULT_MODELS = {
+    gemini: "flash", // Gemini CLI resolves to latest flash
+    claudecode: "sonnet", // Claude Code resolves to latest sonnet
+    codex: "gpt-5.4-mini", // Codex default: latest GPT mini model
+};
 const ZHIHAND_DIR = path.join(os.homedir(), ".zhihand");
 const CREDENTIALS_PATH = path.join(ZHIHAND_DIR, "credentials.json");
 const STATE_PATH = path.join(ZHIHAND_DIR, "state.json");

package/dist/daemon/dispatcher.js

@@ -3,6 +3,7 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_MODELS } from "../core/config.js";
 import { resolveGemini, resolveClaude, resolveCodex } from "../core/resolve-path.js";
 const CLI_TIMEOUT = 120_000; // 120s
 const SIGKILL_DELAY = 2_000; // 2s after SIGTERM
@@ -367,14 +368,17 @@ ${userPrompt}`;
 export function dispatchToCLI(backend, prompt, log, model) {
     const startTime = Date.now();
     const wrappedPrompt = wrapPrompt(prompt);
+    // Resolve model: explicit > env > default
+    const resolvedModel = resolveModel(backend, model);
+    log(`[dispatch] Backend: ${backend}, Model: ${resolvedModel}`);
     if (backend === "gemini") {
-        return dispatchGemini(wrappedPrompt, startTime, log, model);
+        return dispatchGemini(wrappedPrompt, startTime, log, resolvedModel);
     }
     if (backend === "codex") {
-        return dispatchCodex(wrappedPrompt, startTime, model);
+        return dispatchCodex(wrappedPrompt, startTime, resolvedModel);
     }
     if (backend === "claudecode") {
-        return dispatchClaude(wrappedPrompt, startTime, model);
+        return dispatchClaude(wrappedPrompt, startTime, resolvedModel);
     }
     return Promise.resolve({
         text: `Unsupported backend: ${backend}`,
@@ -382,12 +386,38 @@ export function dispatchToCLI(backend, prompt, log, model) {
         durationMs: 0,
     });
 }
+/**
+ * Resolve the model to use for a backend.
+ * Priority: explicit parameter > ZHIHAND_MODEL env > backend-specific env > default alias.
+ *
+ * Each backend CLI handles alias→full-name resolution natively:
+ *   - Gemini CLI: "flash" → gemini-2.5-flash, "pro" → gemini-2.5-pro
+ *   - Claude Code: "sonnet" → claude-sonnet-4-*, "opus" → claude-opus-4-*, "haiku" → claude-haiku-4-*
+ *   - Codex CLI: no alias support — pass full model name directly (e.g. "o4-mini", "codex-mini")
+ */
+function resolveModel(backend, explicit) {
+    if (explicit)
+        return explicit;
+    // Global env override
+    const globalEnv = process.env.ZHIHAND_MODEL;
+    if (globalEnv)
+        return globalEnv;
+    // Per-backend env override
+    const envMap = {
+        gemini: process.env.ZHIHAND_GEMINI_MODEL,
+        claudecode: process.env.ZHIHAND_CLAUDE_MODEL,
+        codex: process.env.ZHIHAND_CODEX_MODEL,
+    };
+    const perBackend = envMap[backend];
+    if (perBackend)
+        return perBackend;
+    return DEFAULT_MODELS[backend];
+}
 // ── Gemini Dispatch (PTY + Session File Monitoring) ────────
 function dispatchGemini(prompt, startTime, log, model) {
-    const geminiModel = model ?? process.env.CLAUDE_GEMINI_MODEL ?? "gemini-3.1-pro-preview";
     const cliArgs = [
         "--approval-mode", "yolo",
-        "--model", geminiModel,
+        "--model", model,
         "-i", prompt,
     ];
     const env = {
@@ -414,10 +444,7 @@ function dispatchCodex(prompt, startTime, model) {
     // --dangerously-bypass-approvals-and-sandbox is required so MCP tool calls
     // are not auto-cancelled in non-interactive mode (--full-auto cancels them)
     const args = ["exec", "--dangerously-bypass-approvals-and-sandbox", "--skip-git-repo-check", "--json"];
-    const codexModel = model ?? process.env.CLAUDE_CODEX_MODEL;
-    if (codexModel) {
-        args.push("-m", codexModel);
-    }
+    args.push("-m", model);
     args.push(prompt);
     const codexPath = resolveCodex();
     const child = spawn(codexPath, args, {
@@ -431,7 +458,7 @@ function dispatchCodex(prompt, startTime, model) {
 // ── Claude Dispatch ────────────────────────────────────────
 function dispatchClaude(prompt, startTime, model) {
     const claudePath = resolveClaude();
-    const child = spawn(claudePath, ["-p", prompt, "--output-format", "json"], {
+    const child = spawn(claudePath, ["-p", prompt, "--model", model, "--output-format", "json"], {
         env: process.env,
         stdio: ["ignore", "pipe", "pipe"],
         detached: false,

package/dist/daemon/index.js

@@ -5,7 +5,8 @@ import path from "node:path";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 // Transport type used only for cleanup interface
 import { createServer as createMcpServer } from "../index.js";
-import { resolveConfig, loadBackendConfig, saveBackendConfig, resolveZhiHandDir, ensureZhiHandDir, } from "../core/config.js";
+import { resolveConfig, loadBackendConfig, saveBackendConfig, resolveZhiHandDir, ensureZhiHandDir, DEFAULT_MODELS, } from "../core/config.js";
+import { PACKAGE_VERSION } from "../index.js";
 import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline } from "./heartbeat.js";
 import { PromptListener } from "./prompt-listener.js";
 import { dispatchToCLI, postReply, killActiveChild } from "./dispatcher.js";
@@ -13,6 +14,7 @@ const DEFAULT_PORT = 18686;
 const PID_FILE = "daemon.pid";
 // ── State ──────────────────────────────────────────────────
 let activeBackend = null;
+let activeModel = null; // user-selected model alias, null = use default
 let isProcessing = false;
 const promptQueue = [];
 function log(msg) {
@@ -28,7 +30,7 @@ async function processPrompt(config, prompt) {
     }
     const preview = prompt.text.length > 40 ? prompt.text.slice(0, 40) + "..." : prompt.text;
     log(`[relay] Prompt: "${preview}" → dispatching to ${activeBackend}...`);
-    const result = await dispatchToCLI(activeBackend, prompt.text, log);
+    const result = await dispatchToCLI(activeBackend, prompt.text, log, activeModel ?? undefined);
     const ok = await postReply(config, prompt.id, result.text);
     const dur = (result.durationMs / 1000).toFixed(1);
     if (ok) {
@@ -69,7 +71,7 @@ function handleInternalAPI(req, res) {
         });
         req.on("end", () => {
             try {
-                const { backend } = JSON.parse(body);
+                const { backend, model } = JSON.parse(body);
                 const allowed = ["claudecode", "codex", "gemini"];
                 if (!allowed.includes(backend)) {
                     res.writeHead(400, { "Content-Type": "application/json" });
@@ -77,10 +79,12 @@ function handleInternalAPI(req, res) {
                     return;
                 }
                 activeBackend = backend;
-                saveBackendConfig({ activeBackend });
-                log(`[config] Backend switched to ${activeBackend}.`);
+                activeModel = model ?? null;
+                saveBackendConfig({ activeBackend, model: activeModel });
+                const effectiveModel = activeModel ?? DEFAULT_MODELS[activeBackend];
+                log(`[config] Backend switched to ${activeBackend}, model: ${effectiveModel}`);
                 res.writeHead(200, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ ok: true, backend: activeBackend }));
+                res.end(JSON.stringify({ ok: true, backend: activeBackend, model: effectiveModel }));
             }
             catch {
                 res.writeHead(400, { "Content-Type": "application/json" });
@@ -90,9 +94,12 @@ function handleInternalAPI(req, res) {
         return true;
     }
     if (url === "/internal/status" && req.method === "GET") {
+        const effectiveModel = activeBackend ? (activeModel ?? DEFAULT_MODELS[activeBackend]) : null;
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify({
+            version: PACKAGE_VERSION,
             backend: activeBackend,
+            model: effectiveModel,
             processing: isProcessing,
             queueLength: promptQueue.length,
             pid: process.pid,
@@ -155,9 +162,19 @@ export async function startDaemon(options) {
         log("Run 'zhihand setup' to pair a device first.");
         process.exit(1);
     }
-    // Load backend
+    // Load backend + model
     const backendConfig = loadBackendConfig();
     activeBackend = backendConfig.activeBackend ?? null;
+    activeModel = backendConfig.model ?? null;
+    // Log startup info
+    log(`ZhiHand v${PACKAGE_VERSION} starting...`);
+    if (activeBackend) {
+        const effectiveModel = activeModel ?? DEFAULT_MODELS[activeBackend];
+        log(`[config] Backend: ${activeBackend}, Model: ${effectiveModel}`);
+    }
+    else {
+        log(`[config] No backend configured. Use: zhihand gemini / zhihand claude / zhihand codex`);
+    }
     // MCP sessions: each client gets its own McpServer + Transport pair
     // because McpServer.connect() can only be called once per instance
     const MAX_MCP_SESSIONS = 20;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const PACKAGE_VERSION = "0.20.0";
 export declare function createServer(deviceName?: string): McpServer;
 export declare function startStdioServer(deviceName?: string): Promise<void>;

package/dist/index.js

@@ -5,7 +5,7 @@ import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js"
 import { executeControl } from "./tools/control.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-const PACKAGE_VERSION = "0.19.1";
+export const PACKAGE_VERSION = "0.20.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",