@pharaoh-so/mcp 0.3.51 → 0.3.53

package/.mcp.json

@@ -3,7 +3,7 @@
 		"pharaoh": {
 			"command": "npx",
 			"args": [
-				"@pharaoh-so/mcp@0.3.51"
+				"@pharaoh-so/mcp@0.3.53"
 			]
 		}
 	}

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to `@pharaoh-so/mcp` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.53] - 2026-10-23
+
+### Changed
+- The Trace card is a compact receipt: the finding with its counts, a verdict such as risk, and one bar showing where the results sit (callers by module, dead or possibly unused, matches by module, code by module). The evidence opens on Details. A single-tool card is about 80px tall instead of 290 to 2,200px.
+- While a tool runs, the card says what Pharaoh is doing ("Tracing callers of parseEvent…"). Caveats such as an incomplete graph or a stale map stay visible while the evidence is closed.
+
+### Fixed
+- With no `claude` CLI on PATH, `npx @pharaoh-so/mcp` stops before sign-in and says why: setup registers Pharaoh through that CLI, and the Claude desktop app's built-in Claude Code isn't on PATH. The message gives the CLI installer. It used to link the desktop app download, write the slash commands anyway and end with "Pharaoh is ready".
+- When `claude mcp add` fails, setup ends without "Pharaoh is ready" and names the `claude mcp add` command to run by hand.
+
+## [0.3.52] - 2026-10-23
+
+### Added
+- The proxy tells Pharaoh which client it serves (its `initialize` name and version) and whether Pharaoh's Claude Code plugin is enabled in `~/.claude/settings.json`, once per upstream session. Pharaoh stores it with that session, to compare adoption with and without the plugin. Nothing else is sent.
+
+### Removed
+- The `sessions` and `parallel` skills, the `/sessions` slash command and their MCP prompts (`session-decomposition`, `parallel-agents`). Claude Code and Codex now run subagents and parallel sessions on their own.
+- The installer deletes the `~/.claude/commands/sessions.md` it wrote, only while it carries the `# managed-by: pharaoh-mcp` marker. A file of your own with that name, or a symlink, is kept.
+
+### Fixed
+- `npx @pharaoh-so/mcp --version` (or `-v`) prints the version and exits, as README § Custom Server says. It used to start setup: in a terminal it deleted saved credentials and signed in again against mcp.pharaoh.so; on a pipe it started the proxy.
+
 ## [0.3.51] - 2026-10-23
 
 ### Added

package/README.md

@@ -166,9 +166,10 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server ht
 | `~/.pharaoh/` | `0700`, set again on every start | Always | Credentials and the Claude Code plugin marketplace |
 | `~/.pharaoh/credentials.json` | `0600` | After sign-in | Access token, refresh token, expiry |
 | `~/.pharaoh/claude-marketplace/` | — | `~/.claude/` exists | The one-plugin marketplace Claude Code installs as `pharaoh@pharaoh`: the skills and the Grep routing hook. Rewritten when the package version changes |
-| `~/.claude/commands/plan.md`, `review.md`, `sessions.md` | — | `~/.claude/` exists | Slash commands. A file is written only when it is absent or is Pharaoh's: it carries the front-matter comment `# managed-by: pharaoh-mcp`, or has the exact header and `$ARGUMENTS` footer of a Pharaoh command from 0.3.46 or earlier. Any other file with that name is yours: it is kept, a symlink is never followed, and the setup output names it. Rename your file to keep both |
+| `~/.claude/commands/plan.md`, `review.md` | — | `~/.claude/` exists | Slash commands. A file is written only when it is absent or is Pharaoh's: it carries the front-matter comment `# managed-by: pharaoh-mcp`, or has the exact header and `$ARGUMENTS` footer of a Pharaoh command from 0.3.46 or earlier. Any other file with that name is yours: it is kept, a symlink is never followed, and the setup output names it. Rename your file to keep both. 0.3.51 and earlier also wrote `sessions.md`; later versions delete it while it carries the marker |
 | `~/.claude.json` | — | Interactive setup | Removes earlier `pharaoh` entries, then `claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version>` |
 | `~/.claude/settings.json` | — | Interactive setup, and only if the file already exists | Adds to `permissions.allow`, each by full name: `mcp__pharaoh__get_codebase_map`, `mcp__pharaoh__get_module_context`, `mcp__pharaoh__search_functions`, `mcp__pharaoh__get_blast_radius`, `mcp__pharaoh__get_unused_code`, `mcp__pharaoh__pharaoh_recon`, `mcp__pharaoh__pharaoh_account`. The setup prints a line saying what it did. The proxy never creates this file and never touches it on a start |
+| `~/.agents/skills/pharaoh-review/` | — | `~/.codex/` exists | The review skill for Codex (`$pharaoh-review`), rewritten on every start. Other tools share `~/.agents/skills/`, so nothing else there is touched |
 | `~/.openclaw/skills/`, `~/.openclaw/openclaw.json` | — | `~/.openclaw/` exists | Skills prefixed `pharaoh-`, and an `mcpServers.pharaoh` entry running `npx @pharaoh-so/mcp@<version>`. An entry that is not an `npx @pharaoh-so/mcp` command is left alone |
 
 Versions 0.3.46 and earlier wrote one rule, `mcp__pharaoh`, on every proxy start. That prefix auto-approved every Pharaoh tool, including account deletion and `pharaoh_admin`, so a prompt injection could run them without a human prompt. The next interactive setup replaces that rule with the list above; account deletion, `pharaoh_admin` and any tool not listed prompt before they run. To take the blanket rule out by hand, delete `mcp__pharaoh` from `permissions.allow`.

package/dist/backend.d.ts

@@ -17,6 +17,22 @@
  */
 import type { CallToolResult, ClientCapabilities, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { DeviceFlowGateway } from "./gateway.js";
+/**
+ * Notification that tells Pharaoh which client the proxy serves. Pharaoh sees
+ * the proxy itself as `pharaoh-proxy`; this lands on the session's row.
+ * Mirrors PROXY_CLIENT_NOTIFICATION in src/mcp/server.ts.
+ */
+export declare const CLIENT_NOTIFICATION = "notifications/pharaoh/client";
+/** What the proxy reports about the client behind it. */
+export type DownstreamClient = {
+    /** The client's own `initialize` clientInfo (e.g. claude-code 2.1.3). */
+    client: {
+        name?: string;
+        version?: string;
+    };
+    /** Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. */
+    plugin: "enabled" | "disabled" | "absent";
+};
 /** The contract ProxyServer uses to delegate tool handling. */
 export interface Backend {
     readonly name: "auth-required" | "sse";
@@ -34,6 +50,8 @@ export interface Backend {
     waitForExit?(): Promise<void>;
     /** Return an unstarted replacement only if the negotiated UI support changed. */
     withClientCapabilities?(capabilities: ClientCapabilities): Backend;
+    /** Report the client behind the proxy to every upstream session, reconnects included. */
+    identifyClient?(downstream: DownstreamClient): void;
 }
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
@@ -78,7 +96,20 @@ export declare class SseProxyBackend implements Backend {
     private stopped;
     private reconnectPromise;
     private readonly clientCapabilities;
+    private downstream;
+    /** The client whose `connect` has finished; null while connecting or after its transport closed. */
+    private connectedClient;
+    /** Set once a report fails; see reportClient. */
+    private reportsOff;
     constructor(sseUrl: string, token: string, capabilities?: ClientCapabilities);
+    identifyClient(downstream: DownstreamClient): void;
+    /**
+     * Tell the connected session which client the proxy serves. Never awaited.
+     * The SDK also hands a failed POST to the transport's onerror, which
+     * reconnects, so after one failure this backend stops reporting: a server
+     * that rejects reports costs one reconnect, not a loop.
+     */
+    private reportClient;
     withClientCapabilities(capabilities: ClientCapabilities): Backend;
     start(): Promise<void>;
     /**

package/dist/backend.js

@@ -21,6 +21,12 @@ import { loadBundledCatalog } from "./catalog.js";
 import { classifySSEError, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { TRACE_MIME_TYPE } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
+/**
+ * Notification that tells Pharaoh which client the proxy serves. Pharaoh sees
+ * the proxy itself as `pharaoh-proxy`; this lands on the session's row.
+ * Mirrors PROXY_CLIENT_NOTIFICATION in src/mcp/server.ts.
+ */
+export const CLIENT_NOTIFICATION = "notifications/pharaoh/client";
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
  * gateway; returns a structured auth-required response. Once the gateway
@@ -145,6 +151,11 @@ export class SseProxyBackend {
     stopped = false;
     reconnectPromise = null;
     clientCapabilities;
+    downstream = null;
+    /** The client whose `connect` has finished; null while connecting or after its transport closed. */
+    connectedClient = null;
+    /** Set once a report fails; see reportClient. */
+    reportsOff = false;
     constructor(sseUrl, token, capabilities = {}) {
         this.sseUrl = sseUrl;
         this.token = token;
@@ -156,6 +167,29 @@ export class SseProxyBackend {
                 ? { extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [TRACE_MIME_TYPE] } } }
                 : {};
     }
+    identifyClient(downstream) {
+        this.downstream = downstream;
+        void this.reportClient();
+    }
+    /**
+     * Tell the connected session which client the proxy serves. Never awaited.
+     * The SDK also hands a failed POST to the transport's onerror, which
+     * reconnects, so after one failure this backend stops reporting: a server
+     * that rejects reports costs one reconnect, not a loop.
+     */
+    async reportClient() {
+        const client = this.connectedClient;
+        if (!client || !this.downstream || this.reportsOff)
+            return;
+        await client
+            .notification({ method: CLIENT_NOTIFICATION, params: this.downstream })
+            .catch((error) => {
+            // ALLOWED-CATCH: telemetry; reportsOff bounds the reconnect a failed POST triggers
+            this.reportsOff = true;
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Pharaoh: client report not sent, not retrying (${msg})\n`);
+        });
+    }
     withClientCapabilities(capabilities) {
         const next = new SseProxyBackend(this.sseUrl, this.token, capabilities);
         return JSON.stringify(next.clientCapabilities) === JSON.stringify(this.clientCapabilities)
@@ -207,6 +241,13 @@ export class SseProxyBackend {
                 classifySSEError(error);
             throw error;
         }
+        // A stop or a newer connect while this one was in flight owns the backend now.
+        if (this.stopped || this.client !== client)
+            return;
+        this.connectedClient = client;
+        // Every new upstream session (reconnects too) hears which client this is,
+        // without holding up startup or reconnect supervision.
+        void this.reportClient();
     }
     /** Wait for the current transport to close, then decide what to do. */
     waitForClose() {
@@ -216,8 +257,14 @@ export class SseProxyBackend {
                 return;
             }
             const sse = this.transport;
-            sse.onclose = () => resolve();
+            // The client is gone the moment its transport closes or errors,
+            // whichever way the loop then leaves (backoff or typed recovery).
+            sse.onclose = () => {
+                this.connectedClient = null;
+                resolve();
+            };
             sse.onerror = (err) => {
+                this.connectedClient = null;
                 try {
                     classifySSEError(err);
                 }
@@ -302,6 +349,7 @@ export class SseProxyBackend {
     }
     async stop() {
         this.stopped = true;
+        this.connectedClient = null;
         if (this.transport) {
             await this.transport.close().catch(() => { });
             this.transport = null;

package/dist/helpers.js

@@ -42,7 +42,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
     return { server, logout };
 }
 export function printUsage() {
-    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config and the Claude Code plugin, then exit", "  --clean           Remove Pharaoh's MCP entries and plugin from Claude Code config", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config and the Claude Code plugin, then exit", "  --clean           Remove Pharaoh's MCP entries and plugin from Claude Code config", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/index.js

@@ -37,6 +37,11 @@ async function main() {
         printUsage();
         process.exit(0);
     }
+    // Stdout, alone on its line, so a script can capture the version to pin
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`${getPackageVersion()}\n`);
+        return;
+    }
     // Inspect mode — serve tool schemas over stdio for Glama directory inspection
     if (args.includes("--inspect")) {
         const { runInspect } = await import("./inspect.js");
@@ -75,6 +80,13 @@ async function main() {
     // Running `npx @pharaoh-so/mcp` is the only command a user needs.
     if (isInteractive) {
         process.stderr.write(`${BANNER}\n`);
+        // Setup registers everything through the `claude` CLI on PATH. Without it,
+        // stop before sign-in: nothing is written and saved credentials stay.
+        const { claudeCliMissing, hasClaude, runSetup } = await import("./setup.js");
+        if (!hasClaude()) {
+            printLines(...claudeCliMissing());
+            process.exit(1);
+        }
         // Always re-authenticate for a fresh session
         deleteCredentials();
         const deviceCode = await requestDeviceCode(server);
@@ -87,10 +99,11 @@ async function main() {
         const newCreds = tokenToCredentials(token, sseUrl);
         writeCredentials(newCreds);
         printAuthSuccess(token.github_login ?? null, token.tenant_name ?? null, token.repos?.length ?? 0);
-        // Register MCP server + install skills (silent — user doesn't need internals)
+        // Register MCP server + install skills (silent — user doesn't need internals).
+        // runSetup has printed the failure and the command to run by hand; no success line.
+        if (!runSetup({ silent: true }))
+            process.exit(1);
         process.stderr.write("  Setting up...");
-        const { runSetup } = await import("./setup.js");
-        runSetup({ silent: true });
         const { keptCommands } = runInstallSkills(undefined, { silent: true });
         process.stderr.write(" done.\n");
         // Two things the user must hear about: their settings.json (the only

package/dist/install-skills.d.ts

@@ -1,11 +1,11 @@
 import { type ClaudeCli } from "./setup.js";
 /**
- * Detect whether OpenClaw is installed by checking for ~/.openclaw/.
+ * Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. The proxy
+ * reports this to Pharaoh, so adoption can be compared with and without it.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns True if ~/.openclaw/ exists.
  */
-export declare function detectOpenClaw(home?: string): boolean;
+export declare function claudePluginState(home?: string): "enabled" | "disabled" | "absent";
 /**
  * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
  * marketplace directory and any pre-marketplace install.

package/dist/install-skills.js

@@ -11,7 +11,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensurePharaohHome } from "./credentials.js";
-import { claudeCliFor } from "./setup.js";
+import { CLAUDE_CLI_SETUP_URL, claudeCliFor } from "./setup.js";
 import { getPackageVersion, PACKAGE_NAME, pinnedPackageSpec } from "./version.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to the bundled package root (one level up from dist/). */
@@ -63,7 +63,7 @@ function detectCodex(home = homedir()) {
  * @param home - Home directory override (defaults to os.homedir()).
  * @returns True if ~/.openclaw/ exists.
  */
-export function detectOpenClaw(home = homedir()) {
+function detectOpenClaw(home = homedir()) {
     return existsSync(join(home, ".openclaw"));
 }
 // ── Claude Code plugin ──────────────────────────────────────────────
@@ -151,6 +151,18 @@ function pluginSetting(home) {
         return undefined;
     }
 }
+/**
+ * Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. The proxy
+ * reports this to Pharaoh, so adoption can be compared with and without it.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ */
+export function claudePluginState(home = homedir()) {
+    const setting = pluginSetting(home);
+    if (setting === undefined)
+        return "absent";
+    return setting ? "enabled" : "disabled";
+}
 /**
  * Install the plugin through Claude Code's CLI (both commands are idempotent).
  * Skipped when it's already enabled, and when the user disabled it: that choice stands.
@@ -408,6 +420,13 @@ function cleanupRemovedSkills(srcDir, dstDir, oldManifest) {
  * and is left alone (security review SC-7).
  */
 export const PHARAOH_COMMAND_MARKER = "# managed-by: pharaoh-mcp";
+/**
+ * Commands an earlier installer wrote that this version no longer ships. Each
+ * is deleted only while it is still Pharaoh's marked file; a user's own file
+ * or a symlink with the name stays. A pre-marker copy (0.3.46 and earlier) is
+ * left too: without the bundled file there is nothing to prove it is ours.
+ */
+const RETIRED_COMMANDS = ["sessions.md"];
 /** The full marker line, with the one thing a reader of the file needs to know. */
 const COMMAND_MARKER_LINE = `${PHARAOH_COMMAND_MARKER} (rewritten by npx ${PACKAGE_NAME} on upgrade; rename this file to keep your own version)`;
 /** The front-matter block of a bundled command, `---` to `---` inclusive. */
@@ -438,13 +457,14 @@ function isPharaohCommand(existing, bundled) {
  * Install the bundled slash commands (`.md` files in the package's `commands/`
  * directory) to `~/.claude/commands/`. A destination that is missing or is
  * Pharaoh's own file is written; anything else (the user's file, or a symlink,
- * which is never followed) is kept and reported.
+ * which is never followed) is kept and reported. Pharaoh's copies of
+ * `RETIRED_COMMANDS` are removed.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns How many commands were written, and the names of the files kept.
+ * @returns How many commands were written, and the names of the files kept and removed.
  */
 function installClaudeCodeCommands(home) {
-    const result = { installed: 0, kept: [] };
+    const result = { installed: 0, kept: [], removed: [] };
     if (!existsSync(BUNDLED_COMMANDS_DIR))
         return result;
     const commandsDst = join(home, ".claude", "commands");
@@ -463,6 +483,15 @@ function installClaudeCodeCommands(home) {
         writeFileSync(dst, markCommand(bundled));
         result.installed++;
     }
+    for (const name of RETIRED_COMMANDS) {
+        const dst = join(commandsDst, name);
+        if (!lstatSync(dst, { throwIfNoEntry: false })?.isFile())
+            continue;
+        if (!readFileSync(dst, "utf-8").includes(PHARAOH_COMMAND_MARKER))
+            continue;
+        rmSync(dst);
+        result.removed.push(name);
+    }
     return result;
 }
 /**
@@ -691,6 +720,7 @@ export function runInstallSkills(home = homedir(), options) {
                     ]
                     : []),
                 ...(keptLine ? [`  → ${keptLine}`] : []),
+                ...commands.removed.map((name) => `  → Removed retired ~/.claude/commands/${name}`),
                 "",
             ].join("\n"));
         }
@@ -736,7 +766,7 @@ export function runInstallSkills(home = homedir(), options) {
             "Pharaoh: no supported skill platform detected.",
             "",
             "Supported platforms:",
-            "  • Claude Code — install from https://claude.ai/download",
+            `  • Claude Code — install the CLI from ${CLAUDE_CLI_SETUP_URL}`,
             "  • Codex      — install from https://developers.openai.com/codex",
             "  • OpenClaw   — install from https://openclaw.dev/install",
             "",

package/dist/proxy-server.d.ts

@@ -37,6 +37,7 @@ export declare class ProxyServer {
     private stopping;
     private clientCapabilities;
     private clientInitialized;
+    private downstream;
     private capabilityUpdate;
     private transportClosed;
     private transportClosedResolve;

package/dist/proxy-server.js

@@ -24,9 +24,10 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { AuthRequiredBackend, createSseBackend } from "./backend.js";
+import { AuthRequiredBackend, createSseBackend, } from "./backend.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { createGateway } from "./gateway.js";
+import { claudePluginState } from "./install-skills.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
@@ -42,6 +43,7 @@ export class ProxyServer {
     stopping = false;
     clientCapabilities = {};
     clientInitialized = false;
+    downstream = null;
     capabilityUpdate = Promise.resolve();
     transportClosed;
     transportClosedResolve;
@@ -64,10 +66,21 @@ export class ProxyServer {
             if (this.clientInitialized)
                 return;
             this.clientInitialized = true;
+            const info = this.server.getClientVersion();
+            const downstream = {
+                client: { name: info?.name, version: info?.version },
+                plugin: claudePluginState(),
+            };
+            this.downstream = downstream;
             this.clientCapabilities = this.server.getClientCapabilities() ?? {};
             const next = this.backend.withClientCapabilities?.(this.clientCapabilities) ?? this.backend;
-            if (next === this.backend)
+            // Only the backend that serves this client is told about it: a warm
+            // session replaced below never takes a tool call. setBackend names the
+            // client to its replacement once that has started.
+            if (next === this.backend) {
+                this.backend.identifyClient?.(downstream);
                 return;
+            }
             // Warm startup happens before the frontend initializes. Replace that
             // conservative connection only when real UI support is negotiated.
             this.capabilityUpdate = this.setBackend(next).catch((error) => {
@@ -75,6 +88,7 @@ export class ProxyServer {
                     throw error;
                 // UI negotiation is optional: keep the already-started plain-text
                 // backend healthy when its replacement hits a transient failure.
+                this.backend.identifyClient?.(downstream);
                 process.stderr.write("Pharaoh: compact UI negotiation unavailable; continuing with text responses.\n");
             });
             this.capabilityUpdate.catch(() => {
@@ -201,6 +215,9 @@ export class ProxyServer {
             return;
         }
         this.backend = next;
+        // Read the client after start: it may have initialized during the await.
+        if (this.downstream)
+            next.identifyClient?.(this.downstream);
         this.capabilityUpdate = Promise.resolve();
         // Fire the notification after the swap so a client that races a list
         // request against it sees the new catalog.

package/dist/setup.d.ts

@@ -1,5 +1,24 @@
 /** Runs one `claude` CLI command; true on success. */
 export type ClaudeCli = (args: string[]) => boolean;
+/** Anthropic's Claude Code CLI install page: every platform and install method. */
+export declare const CLAUDE_CLI_SETUP_URL = "https://code.claude.com/docs/en/setup";
+/**
+ * Whether a `claude` CLI on PATH starts. It is launched the way `runClaude`
+ * launches it, so the check and the commands agree, with no `which` (minimal
+ * containers lack it). The Claude desktop app's bundled copy isn't on PATH.
+ *
+ * @returns True when `claude --version` runs.
+ */
+export declare function hasClaude(): boolean;
+/**
+ * What setup prints when no `claude` CLI is on PATH: npx registers everything
+ * through that CLI, the desktop app's copy doesn't count, and the CLI shares
+ * ~/.claude with the desktop app, so installing it covers the Code tab too.
+ *
+ * @param platform - Picks the one-line installer (PowerShell on Windows).
+ * @returns The lines to print.
+ */
+export declare function claudeCliMissing(platform?: NodeJS.Platform): string[];
 /**
  * A `claude` CLI runner for the Claude Code config under `home`: true when the
  * command succeeded, false when it failed or `claude` isn't installed. Another

package/dist/setup.js

@@ -11,20 +11,54 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { NPX_COMMAND, printLines } from "./helpers.js";
 import { pinnedPackageSpec } from "./version.js";
-/** Check if `claude` CLI is available in PATH. */
-function hasClaude() {
+/** Anthropic's Claude Code CLI install page: every platform and install method. */
+export const CLAUDE_CLI_SETUP_URL = "https://code.claude.com/docs/en/setup";
+/** Pharaoh's setup guide for agents other than Claude Code (stdio server, sign-in on first call). */
+const HEADLESS_SETUP_URL = "https://pharaoh.so/docs/connect/headless";
+/**
+ * Whether a `claude` CLI on PATH starts. It is launched the way `runClaude`
+ * launches it, so the check and the commands agree, with no `which` (minimal
+ * containers lack it). The Claude desktop app's bundled copy isn't on PATH.
+ *
+ * @returns True when `claude --version` runs.
+ */
+export function hasClaude() {
     try {
-        const which = process.platform === "win32" ? "where" : "which";
-        execFileSync(which, ["claude"], {
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-        });
+        execFileSync("claude", ["--version"], { stdio: "pipe", timeout: 10_000 });
         return true;
     }
     catch {
+        // A `claude` that can't be started is one setup can't use either.
         return false;
     }
 }
+/**
+ * What setup prints when no `claude` CLI is on PATH: npx registers everything
+ * through that CLI, the desktop app's copy doesn't count, and the CLI shares
+ * ~/.claude with the desktop app, so installing it covers the Code tab too.
+ *
+ * @param platform - Picks the one-line installer (PowerShell on Windows).
+ * @returns The lines to print.
+ */
+export function claudeCliMissing(platform = process.platform) {
+    // The shell goes in the label: anything after the command gets pasted with it.
+    const [shell, installer] = platform === "win32"
+        ? [" (PowerShell)", "irm https://claude.ai/install.ps1 | iex"]
+        : ["", "curl -fsSL https://claude.ai/install.sh | bash"];
+    return [
+        "Pharaoh: the claude command isn't on your PATH, so setup stopped.",
+        "",
+        "npx adds Pharaoh to Claude Code through the Claude Code CLI. The desktop app runs its own copy of Claude Code, and that copy isn't on your PATH.",
+        "",
+        `  Install the CLI${shell}: ${installer}`,
+        `  Other ways: ${CLAUDE_CLI_SETUP_URL}`,
+        `  Then, in a new terminal: ${NPX_COMMAND}`,
+        "",
+        "The CLI and the desktop app share ~/.claude, so the desktop app's Code tab gets Pharaoh too.",
+        `Not using Claude Code? OpenClaw: ${NPX_COMMAND} --install-skills. Other agents: ${HEADLESS_SETUP_URL}`,
+        "",
+    ];
+}
 /** Run a claude CLI command, returning true on success. Surfaces stderr on failure. */
 function runClaude(args, env = process.env) {
     try {
@@ -128,7 +162,7 @@ export function runSetup(options) {
     const silent = options?.silent ?? false;
     const home = options?.home ?? homedir();
     if (!options?.claude && !hasClaude()) {
-        printLines("Pharaoh: Claude Code CLI not found.", "", "Install Claude Code first: https://claude.ai/download", `Then re-run: ${NPX_COMMAND}`, "");
+        printLines(...claudeCliMissing());
         return false;
     }
     const claude = options?.claude ?? claudeCliFor(home);
@@ -142,9 +176,9 @@ export function runSetup(options) {
     claude(["mcp", "remove", "pharaoh", "-s", "project"]);
     // Step 3: Register as global stdio MCP server, pinned to the running version
     const spec = pinnedPackageSpec();
-    const added = claude(["mcp", "add", "--scope", "user", "pharaoh", "--", "npx", spec]);
-    if (!added) {
-        printLines("Pharaoh: failed to register MCP server.", `Try manually: ${NPX_COMMAND}`, "");
+    const addArgs = ["mcp", "add", "--scope", "user", "pharaoh", "--", "npx", spec];
+    if (!claude(addArgs)) {
+        printLines("Pharaoh: failed to register MCP server.", `Try manually: claude ${addArgs.join(" ")}`, "");
         return false;
     }
     if (!silent)

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.51",
+	"version": "0.3.53",
 	"description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
 	"type": "module",
 	"main": "dist/index.js",