@pharaoh-so/mcp 0.3.53 → 0.3.56

package/.mcp.json

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

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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).
 
+## [Unreleased]
+
+### Added
+- `plugins/pharaoh/`: the Claude directory plugin, generated from the same skills (plan, review, refactor and pharaoh) with the hosted connector at `https://mcp.pharaoh.so/mcp`. It has no hooks or commands and isn't part of the npm package.
+- `NOTICE`: the brainstorm, debug, tdd and verify skills are adapted from [superpowers](https://github.com/obra/superpowers) (MIT, Copyright (c) 2025 Jesse Vincent). Each skill's `license:` field says so too.
+
+### Changed
+- Every tool declares `openWorldHint: false` (Pharaoh reaches only your own connected repos), and `pharaoh_account`'s description says it links the plans page.
+- When a repo isn't live, and in `pharaoh_account` for free workspaces, replies link to the plans page on pharaoh.so instead of showing a price and a checkout link.
+- `get_unused_code` says a Dead function's file has no import that could reach it, instead of "file not imported". An import that names other functions from the same file doesn't count, and never did.
+- The Trace card draws its bars in block characters (`█ ▏ ░`) in your client's monospace font instead of solid CSS bars.
+- `/review` works as before, second opinion from Codex or Claude included. It no longer calls itself "the definitive code review", and Phase 0 says that `gh pr view` asks GitHub for the open PR's target branch with your gh login.
+- `/plan` says "This is a review: make no code changes during it" instead of claiming plan mode. A plain "yes" or "yes to all" still doesn't pick BIG or SMALL, so it asks once more; if the reply still doesn't pick one, or you tell it to choose, it picks and says which. `.claude/plan-review.md` adds review criteria, and your own instructions come first.
+- `pharaoh:refactor` runs the six steps its description lists: module context, blast radius, reachability, dependencies, naming conflicts, and a search for the tests to change.
+- Skills install from `npx-skills/`, this package's build of `skills/`.
+- `pharaoh_account` only reads now: your plan, live repo and upgrade link. Switching the live repo and refreshing a repo moved to the new `pharaoh_manage_repo`, which Claude Code asks about before it runs. The interactive setup's allow rules need no change: they already list the read-only tools, `pharaoh_account` among them, and leave `pharaoh_manage_repo` out.
+- Every tool has a title, and the tool descriptions say what each tool returns instead of which other tool to avoid.
+- The steering that used to sit in the server instructions moved to the npx `pharaoh` skill. Registrations are pinned to a version, so it takes effect when you upgrade. Codex gets only the review skill, so it doesn't get this.
+- The `pharaoh` skill's connection URL is `https://mcp.pharaoh.so/mcp` instead of `/sse`. The skill also carries the guidance that was only in the server instructions: one Pharaoh call answers what grep and file reads take many turns to piece together, load Pharaoh's tools before the first code search when your client defers them, summarize a block marked "Trace view available" instead of reproducing it, and check related repos when a change touches shared interfaces.
+- The server instructions state facts: what Pharaoh maps, which tool answers which question, what the graph leaves to grep, how repos are mapped and what each account tool does. Asking Pharaoh first, not re-checking its answers with grep, surfacing and crediting its ★ blocks and the rest of that guidance now live in the `pharaoh` skill. Claude Code and OpenClaw list the skill in every session and load its body only when they use it. The Grep hook and the optional `~/.claude/CLAUDE.md` line are unchanged and apply from the start of a session.
+
+## [0.3.56] - 2026-11-04
+
+### Fixed
+- A connected project that is still mapping during normal setup now starts memory on an ordinary prompt after its mapped revision is verified.
+
+## [0.3.55] - 2026-11-04
+
+### Added
+- Normal interactive setup and upgrades configure local project-memory hooks for accounts with an existing pilot grant. Codex uses its native hook review.
+
+## [0.3.54] - 2026-10-24
+
+### Added
+- The interactive setup (`npx @pharaoh-so/mcp` in a terminal) asks once whether to add one line to `~/.claude/CLAUDE.md`: "In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists." Enter means yes. In Pharaoh's adoption benchmark, Claude Code called Pharaoh first when this line was in a CLAUDE.md, and rarely when the same sentence came from the server instructions or a plugin hook.
+- The line sits between `<!-- pharaoh-mcp:start … -->` and `<!-- pharaoh-mcp:end -->` markers. Setup appends that block or replaces the line inside it, and nothing else in the file changes. A symlinked file is left alone, and a proxy start (Claude Code launching the server) never asks or writes. Your answer is saved in `~/.pharaoh/claude-md-answer`, so a no stands.
+
+### Changed
+- `--clean` and `--logout` also remove that block, leaving the rest of the file byte for byte, and delete the saved answer so the next setup asks again.
+- `--logout` deletes the saved credentials first, so a cleanup step that fails can't leave them behind.
+
 ## [0.3.53] - 2026-10-23
 
 ### Changed

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Pharaoh, Inc.
+Copyright (c) 2026 2407066 Alberta Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/NOTICE

@@ -0,0 +1,28 @@
+@pharaoh-so/mcp includes third-party material.
+
+The brainstorm, debug, tdd and verify skills (skills/ and npx-skills/) are
+adapted from the brainstorming, systematic-debugging, test-driven-development
+and verification-before-completion skills of superpowers
+(https://github.com/obra/superpowers), used under this license:
+
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,9 +5,9 @@
 [![node](https://img.shields.io/node/v/@pharaoh-so/mcp)](https://nodejs.org)
 [![pharaoh MCP server](https://glama.ai/mcp/servers/Pharaoh-so/pharaoh/badges/score.svg)](https://glama.ai/mcp/servers/Pharaoh-so/pharaoh)
 
-MCP proxy for [Pharaoh](https://pharaoh.so) — maps codebases into queryable knowledge graphs for AI agents.
+MCP proxy for [Pharaoh](https://pharaoh.so) — maps codebases into queryable knowledge graphs for coding agents.
 
-Pharaoh gives AI coding assistants a complete architectural map of your codebase: every function, dependency, module, and connection. Instead of reading files one at a time, your AI agent queries the knowledge graph and gets instant answers about blast radius, unused code, dependency chains, and more.
+Pharaoh gives coding agents such as Claude Code, Cursor, Codex and OpenClaw a complete architectural map of your codebase: every function, dependency, module, and connection. Instead of reading files one at a time, your agent queries the knowledge graph and gets instant answers about blast radius, unused code, dependency chains, and more.
 
 This package enables [Claude Code](https://docs.anthropic.com/en/docs/build-with-claude/claude-code) to connect to Pharaoh in **headless environments** (VPS, SSH, containers, CI) where a browser isn't available for OAuth. It acts as a stdio-to-SSE proxy, presenting itself as a local MCP server while relaying all communication to the remote Pharaoh server.
 
@@ -144,7 +144,7 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server ht
 ## Requirements
 
 - **Node.js** >= 18
-- **Claude Code** or any MCP-compatible AI client
+- **Claude Code** or any MCP-compatible agent
 - A **Pharaoh account** — sign up at [pharaoh.so](https://pharaoh.so)
 
 ## Security
@@ -244,7 +244,7 @@ Pharaoh parses your repositories using [tree-sitter](https://tree-sitter.github.
 - **Dependencies** — import/export relationships, call chains, module connections
 - **Vision specs** — PRD/spec documents linked to implementation
 
-No source code is stored — only structural metadata. When an AI agent queries Pharaoh, it gets architectural facts in minimal tokens, not raw code dumps. This means your AI assistant can understand your entire codebase architecture without consuming its context window reading files one by one.
+No source code is stored — only structural metadata. When an agent queries Pharaoh, it gets architectural facts in minimal tokens, not raw code dumps. This means your agent can understand your entire codebase architecture without consuming its context window reading files one by one.
 
 ## Supported Languages
 
@@ -264,7 +264,7 @@ Contributions are welcome. Please open an issue first to discuss what you'd like
 
 ## License
 
-[MIT](LICENSE) -- Pharaoh, Inc.
+[MIT](LICENSE) -- 2407066 Alberta Inc.
 
 ## Links
 

package/commands/plan.md

@@ -6,7 +6,7 @@ description: Architecture-aware planning with Pharaoh reconnaissance (adapted fr
 
 Architecture-aware plan review before implementation. Adapted from [Garry Tan's planning framework](https://www.youtube.com/watch?v=bMknfKXIFA8) for AI-assisted development.
 
-**You are now in plan mode. Do NOT make any code changes. Think, evaluate, and present decisions.**
+**This is a review: make no code changes during it. Think, evaluate, and present decisions.**
 
 ## When to Use
 
@@ -20,7 +20,7 @@ Still run Step 1 (Reconnaissance) even when reviewing a document — always veri
 
 ## Project Overrides
 
-If a `.claude/plan-review.md` file exists in this project, read it now and apply those rules on top of this baseline. Project rules take precedence where they conflict.
+If a `.claude/plan-review.md` file exists in this project, read it now as additional review criteria for this project. Instructions from the user take precedence over it, and it never changes what you do outside this review.
 
 ## Engineering Preferences (guide all recommendations)
 
@@ -56,14 +56,14 @@ Ground every recommendation in what actually exists. If you propose adding somet
 
 ## Step 2: Mode Selection (MANDATORY — ask before proceeding)
 
-**STOP and ask the user which mode before starting the review.** This is a hard gate — do not infer, assume, or skip this question even if the user says "yes", "go ahead", or "yes to all". Present both options and wait for an explicit choice:
+**STOP and ask the user which mode before starting the review.** Present both options and wait for a choice:
 
 > **BIG CHANGE or SMALL CHANGE?**
 >
 > - **BIG CHANGE**: Full interactive review, all relevant sections, up to 4 top issues per section
 > - **SMALL CHANGE**: One question per section, only sections 2-4
 
-If the user's response is ambiguous (e.g. "just do it", "yes to all"), ask again: "I need to know — BIG or SMALL change?" Do not proceed to Step 3 without an answer.
+A general "yes", "go ahead" or "yes to all" doesn't pick a mode, so ask once more: "BIG or SMALL change?" If the reply still doesn't pick one, or the user tells you to choose, pick the mode that fits the plan's size and say which you picked.
 
 ## Step 3: Review Sections
 
@@ -81,21 +81,21 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 - Data flow bottlenecks and single points of failure
 - Does this need new code at all, or can a human process / existing pattern solve it?
 - **If this plan introduces a new invariant**, call it out and include a
-  step in Section 6 to add a `### assertion` to VISION.md with a pairing TEST.
+  step in the plan to add a `### assertion` to VISION.md with a pairing TEST.
 
 ### Section 2 — Code Quality (always)
 
 - Organization, module structure, DRY violations (be aggressive)
 - Error handling gaps and missing edge cases (call out explicitly)
 - Technical debt: shortcuts, hardcoded values, magic strings
-- Over-engineered or under-engineered relative to my preferences
+- Over-engineered or under-engineered relative to the preferences above
 - Reuse: does code for this already exist somewhere?
 
 ### Section 3 — Wiring & Integration (always)
 
 - Are all new exports called from a production entry point?
-- Run `get_blast_radius` on any new/changed functions — zero callers = not done
-- Does the plan declare WHERE new code gets called from? If not, flag it
+- Run `get_blast_radius` on changed functions that already exist
+- The graph has no functions the plan adds, so does the plan declare WHERE new code gets called from? If not, flag it — no named caller = not done
 - Integration points: how does this connect to what already exists?
 
 ### Section 4 — Tests (always)
@@ -127,16 +127,16 @@ For every specific issue (bug, smell, design concern, risk, missing wiring):
 1. **Describe concretely** — file, line/function reference, what's wrong
 2. **Present 2-3 options** including "do nothing" where reasonable
 3. **For each option** — implementation effort, risk, blast radius, maintenance burden
-4. **Recommend one** mapped to my preferences above, and say why
+4. **Recommend one** mapped to the preferences above, and say why
 5. **Ask** whether I agree or want a different direction
 
-Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option is always listed first. Use AskUserQuestion with clear labels like "Issue 1 Option A", "Issue 1 Option B".
+Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option is always listed first. If your client has a question tool (AskUserQuestion in Claude Code), use it with clear labels like "Issue 1 Option A", "Issue 1 Option B".
 
 ## Pharaoh Checkpoints (use throughout, not just at the end)
 
 - **Before reviewing**: recon (Step 1 above)
 - **During review**: `get_blast_radius` when evaluating impact of changes; `search_functions` before suggesting new code
-- **Final sweep**: `get_blast_radius` on ALL new exports — zero callers on non-entry-points = plan is incomplete
+- **Final sweep**: every new export has a caller named in the plan, and `get_blast_radius` covers every changed export that already exists — zero callers on non-entry-points = plan is incomplete
 
 ## Workflow Rules
 

package/commands/review.md

@@ -4,7 +4,7 @@ description: Architecture-aware code review with Pharaoh
 
 # Review with Pharaoh
 
-The definitive code review, for any codebase. Architecture-aware, branch-aware, multi-agent, adversarial. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent second opinion from a different model. Every phase works without Pharaoh too; Pharaoh makes the architecture picture exact and cheap where it maps the repo.
+Architecture-aware, branch-aware, multi-agent, adversarial code review. Five phases that combine Pharaoh's knowledge graph with parallel specialized reviewers and an independent second opinion from a different model. Every phase works without Pharaoh too; Pharaoh makes the architecture picture exact and cheap where it maps the repo.
 
 A review always reaches a verdict. When a phase needs something your client doesn't have (Pharaoh, a shell, subagents, a second model), it says how to carry on without it: do that, and name what was missing in the review output. Ask the user only when someone is there to answer.
 
@@ -30,7 +30,7 @@ No shell, or no git? Review the diff you were given (a file, a pasted patch, a p
    git log --oneline -1                   # latest commit
    ```
 
-2. Determine the base (where this branch diverged from the branch it merges into). The target is the first of these that resolves:
+2. Determine the base (where this branch diverged from the branch it merges into). The target is the first of these that resolves (`gh pr view` asks GitHub, with your own gh login, for the open PR's target branch):
    ```bash
    TARGET=$(gh pr view --json baseRefName --jq '"origin/" + .baseRefName' 2>/dev/null)   # the open PR's target branch
    [ -n "$TARGET" ] || TARGET=$(git symbolic-ref -q --short refs/remotes/origin/HEAD)    # the default branch, set by git clone

package/dist/auth.d.ts

@@ -25,6 +25,11 @@ export interface TokenResponse {
     github_login?: string;
     tenant_name?: string;
     repos?: string[];
+    project_memory?: Array<{
+        repo: string;
+        revision: string | null;
+    }>;
+    project_memory_status?: "unavailable";
     provisional?: boolean;
     install_url?: string;
 }

package/dist/credentials.d.ts

@@ -21,6 +21,14 @@ export interface Credentials {
     github_login: string | null;
     tenant_name: string | null;
     repos: string[];
+    /** Device sign-in hint only; the server authorizes every memory operation. */
+    project_memory?: Array<{
+        repo: string;
+        revision: string | null;
+    }>;
+    project_memory_status?: "unavailable";
+    /** Local readiness binding, stable only across refreshes of this sign-in. */
+    project_memory_session?: string;
 }
 /** Default credential file path (route-grep-hook.ts checks the same file to know Pharaoh is signed in). */
 export declare const CREDENTIALS_PATH: string;

package/dist/gateway.js

@@ -105,7 +105,7 @@ export function createGateway(opts) {
      */
     function persistAuthorizedToken(token) {
         const sseUrl = resolveSseUrl(token.sse_url, opts.server);
-        const creds = tokenToCredentials(token, sseUrl);
+        const creds = tokenToCredentials(token, sseUrl, opts.server);
         writeCredentials(creds, opts.credentialsPath);
         lastCreds = creds;
         pending = null;

package/dist/helpers.d.ts

@@ -1,13 +1,23 @@
-/**
- * Pure helper functions for the mcp-proxy CLI — no side effects on import.
- * Separated from index.ts so tests can import without triggering main().
- */
 import type { TokenResponse } from "./auth.js";
 import type { Credentials } from "./credentials.js";
 /** The npx command users run to set up Pharaoh. Single source of truth for all output. */
 export declare const NPX_COMMAND = "npx @pharaoh-so/mcp";
 /** Write one or more lines to stderr. */
 export declare function printLines(...lines: string[]): void;
+/**
+ * Ask a yes/no question that defaults to yes: Enter, `y` or `yes` is yes; `n`
+ * or `no` is no; anything else asks again. Ctrl-C exits (130). On a terminal,
+ * keys pressed before the question showed (an Enter while sign-in waited) are
+ * dropped, so only a key pressed after reading it answers.
+ *
+ * @param question - The prompt, ending in something like `[Y/n] `.
+ * @param input - Where the answer is read (defaults to stdin).
+ * @param output - Where the prompt is written (defaults to stderr, like every other line).
+ * @returns The answer, or null when input ended before one.
+ */
+export declare function askYesNo(question: string, input?: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}, output?: NodeJS.WritableStream): Promise<boolean | null>;
 /** Parse CLI arguments. */
 export declare function parseArgs(argv?: string[]): {
     server: string;
@@ -28,7 +38,7 @@ export declare function resolveSseUrl(tokenSseUrl: string | undefined, server: s
  * will eventually hit the same silent-expiry cliff we're trying to eliminate.
  * Fail loud so the server regression surfaces instead of being absorbed.
  */
-export declare function tokenToCredentials(token: TokenResponse, sseUrl: string): Credentials;
+export declare function tokenToCredentials(token: TokenResponse, sseUrl: string, server?: string): Credentials;
 /** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
 export declare function formatTtl(expiresAt: string): string;
 /** Format a credential identity string (e.g. "alice (my-org)"). */

package/dist/helpers.js

@@ -1,3 +1,9 @@
+/**
+ * Pure helper functions for the mcp-proxy CLI — no side effects on import.
+ * Separated from index.ts so tests can import without triggering main().
+ */
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
 import { isExpired } from "./credentials.js";
 const DEFAULT_SERVER = "https://mcp.pharaoh.so";
 /** The npx command users run to set up Pharaoh. Single source of truth for all output. */
@@ -6,6 +12,54 @@ export const NPX_COMMAND = "npx @pharaoh-so/mcp";
 export function printLines(...lines) {
     process.stderr.write(`${lines.join("\n")}\n`);
 }
+/** How long to read and drop input that was typed before a question showed. */
+const TYPE_AHEAD_MS = 50;
+/**
+ * Ask a yes/no question that defaults to yes: Enter, `y` or `yes` is yes; `n`
+ * or `no` is no; anything else asks again. Ctrl-C exits (130). On a terminal,
+ * keys pressed before the question showed (an Enter while sign-in waited) are
+ * dropped, so only a key pressed after reading it answers.
+ *
+ * @param question - The prompt, ending in something like `[Y/n] `.
+ * @param input - Where the answer is read (defaults to stdin).
+ * @param output - Where the prompt is written (defaults to stderr, like every other line).
+ * @returns The answer, or null when input ended before one.
+ */
+export async function askYesNo(question, input = process.stdin, output = process.stderr) {
+    if (input.isTTY)
+        await dropTypedAhead(input);
+    const rl = createInterface({ input, output });
+    rl.on("SIGINT", () => {
+        output.write("\n");
+        process.exit(130);
+    });
+    rl.setPrompt(question);
+    rl.prompt();
+    try {
+        // The iterator ends on EOF; rl.question never settles then.
+        for await (const reply of rl) {
+            const answer = reply.trim().toLowerCase();
+            if (answer === "" || answer === "y" || answer === "yes")
+                return true;
+            if (answer === "n" || answer === "no")
+                return false;
+            rl.prompt();
+        }
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Read and drop the input already waiting, in raw mode so a half-typed line goes too. */
+async function dropTypedAhead(input) {
+    input.setRawMode?.(true);
+    const drop = () => { };
+    input.on("data", drop);
+    await new Promise((resolve) => setTimeout(resolve, TYPE_AHEAD_MS));
+    input.off("data", drop);
+    input.pause();
+}
 /** Parse CLI arguments. */
 export function parseArgs(argv = process.argv.slice(2)) {
     let server = DEFAULT_SERVER;
@@ -42,7 +96,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", "  --version, -v     Print the version", "  --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, the Claude Code plugin and the CLAUDE.md line, then exit", "  --clean           Remove Pharaoh setup, including managed local project memory hooks", "  --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.
@@ -74,12 +128,20 @@ export function resolveSseUrl(tokenSseUrl, server) {
  * will eventually hit the same silent-expiry cliff we're trying to eliminate.
  * Fail loud so the server regression surfaces instead of being absorbed.
  */
-export function tokenToCredentials(token, sseUrl) {
+export function tokenToCredentials(token, sseUrl, server) {
     if (!token.refresh_token || !token.refresh_token_expires_in) {
         throw new Error("Pharaoh server response missing refresh_token — server is older than this client. " +
             "Update the server to a version that issues refresh tokens, or downgrade the client.");
     }
     const now = Date.now();
+    const production = server === DEFAULT_SERVER && new URL(sseUrl).origin === DEFAULT_SERVER;
+    const memory = production && Array.isArray(token.project_memory)
+        ? token.project_memory.filter((entry) => typeof entry?.repo === "string" &&
+            /^[a-z0-9][a-z0-9-]{0,38}\/[a-z0-9_.-]{1,100}$/i.test(entry.repo) &&
+            (entry.revision === null ||
+                (typeof entry.revision === "string" &&
+                    /^(?!0{40}$)[a-f0-9]{40}$/.test(entry.revision))))
+        : [];
     return {
         version: 2,
         access_token: token.access_token,
@@ -91,6 +153,13 @@ export function tokenToCredentials(token, sseUrl) {
         github_login: token.github_login ?? null,
         tenant_name: token.tenant_name ?? null,
         repos: token.repos ?? [],
+        ...(memory.length ? { project_memory: memory } : {}),
+        ...(memory.some((entry) => entry.revision === null)
+            ? { project_memory_session: randomUUID() }
+            : {}),
+        ...(production && token.project_memory_status === "unavailable"
+            ? { project_memory_status: "unavailable" }
+            : {}),
     };
 }
 /** Format remaining TTL as human-readable string (e.g. "5d 12h"). */

package/dist/index.js

@@ -12,12 +12,13 @@
  *                      mode until device flow completes, then swap to SSE in
  *                      place — the stdio session never disconnects.
  */
+import { syncMemoryHooks } from "../project-memory/setup.mjs";
 import { pollForToken, printActivationPrompt, printAuthSuccess, requestDeviceCode, } from "./auth.js";
 import { AuthRequiredBackend, createSseBackend } from "./backend.js";
 import { deleteCredentials, readCredentials, writeCredentials, } from "./credentials.js";
 import { createGateway } from "./gateway.js";
-import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
-import { allowReadTools, describeAllowReadTools, formatKeptCommands, runInstallSkills, } from "./install-skills.js";
+import { askYesNo, formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
+import { allowReadTools, CLAUDE_MD_QUESTION, describeAllowReadTools, describeClaudeMdOutcome, formatKeptCommands, offerClaudeMdLine, runInstallSkills, } from "./install-skills.js";
 import { handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { startInAuthRequiredMode, startInSseMode } from "./proxy-server.js";
@@ -31,6 +32,16 @@ const BANNER = [
     " |_|  |_||_/_/ \\_\\_|_\\/_/ \\_\\\\___/|_||_|",
     "",
 ].join("\n");
+function reportMemorySetup(options) {
+    try {
+        const notices = syncMemoryHooks(options);
+        if (notices.length)
+            printLines(...notices);
+    }
+    catch {
+        printLines("Pharaoh: project memory setup could not update local activation.");
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes("--help") || args.includes("-h")) {
@@ -57,21 +68,26 @@ async function main() {
     // Clean mode — remove all pharaoh traces from Claude Code config (MCP entries,
     // disabled states, project-scoped configs). Useful for resetting broken installs.
     if (args.includes("--clean")) {
-        const { cleanSlate } = await import("./setup.js");
+        const { cleanCodexSetup, cleanSlate } = await import("./setup.js");
         const { uninstallClaudePlugin } = await import("./install-skills.js");
         cleanSlate();
         uninstallClaudePlugin();
-        printLines("Pharaoh: cleaned all MCP entries and the plugin from Claude Code config");
+        cleanCodexSetup();
+        reportMemorySetup({ removeLegacy: true });
+        printLines("Pharaoh: local setup cleanup finished.");
         process.exit(0);
     }
     const { server, logout } = parseArgs(args);
     if (logout) {
-        const { cleanSlate } = await import("./setup.js");
+        const { cleanCodexSetup, cleanSlate } = await import("./setup.js");
         const { uninstallClaudePlugin } = await import("./install-skills.js");
+        // Credentials first: a cleanup step that fails must never leave the tokens behind.
+        deleteCredentials();
         cleanSlate();
         uninstallClaudePlugin();
-        deleteCredentials();
-        printLines("Pharaoh: credentials, MCP config and the Claude Code plugin cleared");
+        cleanCodexSetup();
+        reportMemorySetup({ removeLegacy: true });
+        printLines("Pharaoh: credentials cleared and local setup cleanup finished.");
         process.exit(0);
     }
     const isInteractive = Boolean(process.stdin.isTTY);
@@ -80,10 +96,10 @@ 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()) {
+        const { claudeCliMissing, hasClaude, hasCodex, runCodexSetup, runSetup } = await import("./setup.js");
+        const claude = hasClaude();
+        const codex = hasCodex();
+        if (!claude && !codex) {
             printLines(...claudeCliMissing());
             process.exit(1);
         }
@@ -96,23 +112,32 @@ async function main() {
             printLines(`Pharaoh: provisional access — install the GitHub App to map your repos: ${token.install_url ?? ""}`);
         }
         const sseUrl = resolveSseUrl(token.sse_url, server);
-        const newCreds = tokenToCredentials(token, sseUrl);
+        const newCreds = tokenToCredentials(token, sseUrl, server);
         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).
-        // runSetup has printed the failure and the command to run by hand; no success line.
-        if (!runSetup({ silent: true }))
+        const clients = [];
+        if (claude && runSetup({ silent: true }))
+            clients.push("claude-code");
+        // Existing Claude-only installs stay unchanged for nonpilot accounts.
+        if (codex && (!claude || newCreds.project_memory?.length)) {
+            if (runCodexSetup())
+                clients.push("codex");
+        }
+        if (!clients.length)
             process.exit(1);
-        process.stderr.write("  Setting up...");
-        const { keptCommands } = runInstallSkills(undefined, { silent: true });
-        process.stderr.write(" done.\n");
-        // Two things the user must hear about: their settings.json (the only
-        // place this setup edits permissions, never a silent start) and any
-        // command file of theirs that was left alone.
-        printLines(describeAllowReadTools(allowReadTools()));
-        const kept = formatKeptCommands(keptCommands);
-        if (kept)
-            printLines(kept);
+        if (clients.includes("claude-code")) {
+            process.stderr.write("  Setting up...");
+            const { keptCommands } = runInstallSkills(undefined, { silent: true });
+            process.stderr.write(" done.\n");
+            printLines(describeAllowReadTools(allowReadTools()));
+            const kept = formatKeptCommands(keptCommands);
+            if (kept)
+                printLines(kept);
+            const claudeMd = describeClaudeMdOutcome(await offerClaudeMdLine(() => askYesNo(CLAUDE_MD_QUESTION), Boolean(process.stdin.isTTY && process.stderr.isTTY)));
+            if (claudeMd)
+                printLines(claudeMd);
+        }
+        reportMemorySetup({ credentials: newCreds, clients });
         // The registration is pinned to this version; upgrading is a deliberate
         // re-run. Interactive only, and quiet when the registry can't be reached.
         const latest = await fetchLatestVersion();
@@ -120,7 +145,7 @@ async function main() {
         if (latest && isNewerVersion(latest, running)) {
             printLines(`Pharaoh: ${latest} is available (this is ${running}). Upgrade: ${UPGRADE_COMMAND}`);
         }
-        printLines("", "Pharaoh is ready. Try these in a new Claude Code conversation:", "", '  "What modules does this codebase have?"', '  "Search for functions related to authentication"', '  "What breaks if I change this file?"', "");
+        printLines("", "Pharaoh is ready. Try these in a new conversation:", "", '  "What modules does this codebase have?"', '  "Search for functions related to authentication"', '  "What breaks if I change this file?"', "");
         process.exit(0);
     }
     // ── Proxy mode (Claude Code spawned us as a stdio MCP server) ──

package/dist/install-skills.d.ts

@@ -7,8 +7,9 @@ import { type ClaudeCli } from "./setup.js";
  */
 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.
+ * Uninstall Pharaoh's Claude Code plugin (through the CLI, then the local
+ * marketplace directory and any pre-marketplace install) and its block in
+ * ~/.claude/CLAUDE.md. Run by --clean and --logout.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
@@ -55,10 +56,11 @@ export declare function installSkills(home?: string): number;
 export declare function mergeOpenClawConfig(home?: string): boolean;
 /**
  * Rules the interactive setup adds to `permissions.allow` in
- * ~/.claude/settings.json: the six read-only tools and `pharaoh_account`,
+ * ~/.claude/settings.json: the seven read-only tools (`readOnlyHint: true`),
  * each by full name. Never a prefix rule — `mcp__pharaoh` also auto-approves
- * account deletion and `pharaoh_admin`, so a prompt injection could run them
- * with no human in the loop (security review SC-6). Those tools keep prompting.
+ * the tools that change things (`pharaoh_manage_repo`, which queues a re-map,
+ * and the superadmin tools), so a prompt injection could run them with
+ * no human in the loop (security review SC-6). Those tools keep prompting.
  */
 export declare const PHARAOH_ALLOW_RULES: readonly string[];
 /** What `allowReadTools` did to ~/.claude/settings.json. */
@@ -83,6 +85,29 @@ export declare function allowReadTools(home?: string): AllowReadToolsResult;
  * @param result - What `allowReadTools` returned.
  */
 export declare function describeAllowReadTools(result: AllowReadToolsResult): string;
+/** What the interactive setup asks before writing the line. */
+export declare const CLAUDE_MD_QUESTION = "Pharaoh: add one line to ~/.claude/CLAUDE.md so Claude checks Pharaoh before searching your code?\n  \"In repos Pharaoh has mapped, before searching or reading files, ask Pharaoh where the relevant code is, what calls it, and whether what you need already exists.\"\n[Y/n] ";
+/** What `offerClaudeMdLine` did; `describeClaudeMdOutcome` words it. */
+export type ClaudeMdOutcome = "added" | "updated" | "declined" | "kept" | "failed" | "current" | "answered" | "cancelled" | "no-terminal" | "no-claude";
+/**
+ * Offer the Pharaoh-first line in ~/.claude/CLAUDE.md. Interactive setup only,
+ * never a proxy start. Asks only when the block is absent and the user hasn't
+ * answered before; a stale block (an earlier yes) is updated without asking.
+ * The line is appended inside markers, and nothing else in the file changes.
+ *
+ * @param ask - Asks the user: true for yes, false for no, null when input ended.
+ * @param isTerminal - Whether stdin and stderr are a terminal; false asks and writes nothing.
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns What happened, for `describeClaudeMdOutcome`.
+ */
+export declare function offerClaudeMdLine(ask: () => Promise<boolean | null>, isTerminal: boolean, home?: string): Promise<ClaudeMdOutcome>;
+/**
+ * The line the interactive setup prints for an `offerClaudeMdLine` outcome, or
+ * null when there is nothing to say (already current, already answered, no terminal).
+ *
+ * @param outcome - What `offerClaudeMdLine` returned.
+ */
+export declare function describeClaudeMdOutcome(outcome: ClaudeMdOutcome): string | null;
 /** What `runInstallSkills` wants the caller to tell the user. */
 export interface InstallResult {
     /** Files in ~/.claude/commands/ left as they were because they are not Pharaoh's. */