@phren/cli 0.0.36 → 0.0.38

package/mcp/dist/cli-hooks-stop.js

@@ -434,6 +434,34 @@ export async function handleHookStop() {
             }
             return;
         }
+        // Check if HEAD has an upstream tracking branch before attempting sync.
+        // Detached HEAD or branches without upstream would cause silent push failures.
+        const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], phrenPath);
+        if (!upstream.ok || !upstream.output) {
+            const unsyncedCommits = await countUnsyncedCommits(phrenPath);
+            const noUpstreamDetail = "commit created; no upstream tracking branch";
+            finalizeTaskSession({
+                phrenPath,
+                sessionId: taskSessionId,
+                status: "no-upstream",
+                detail: noUpstreamDetail,
+            });
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: { at: now, status: "no-upstream", detail: noUpstreamDetail },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "no-upstream",
+                    lastPushDetail: noUpstreamDetail,
+                    unsyncedCommits,
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", "status=no-upstream");
+            if (unsyncedCommits > 3) {
+                process.stderr.write(`phren: ${unsyncedCommits} unsynced commits — no upstream tracking branch.\n`);
+            }
+            return;
+        }
         const unsyncedCommits = await countUnsyncedCommits(phrenPath);
         const scheduled = scheduleBackgroundSync(phrenPath);
         const syncDetail = scheduled

package/mcp/dist/content/learning.js

@@ -305,7 +305,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
                 return phrenOk(`Skipped duplicate finding for "${project}": already exists with similar wording.`);
             }
             const newContent = `# ${project} Findings\n\n## ${today}\n\n${preparedForNewFile.finding.bullet}\n${preparedForNewFile.finding.citationComment}\n`;
-            const tmpPath = learningsPath + ".tmp." + process.pid;
+            const tmpPath = learningsPath + `.tmp-${crypto.randomUUID()}`;
             fs.writeFileSync(tmpPath, newContent);
             fs.renameSync(tmpPath, learningsPath);
             return phrenOk({
@@ -461,7 +461,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
                 added.push(learning);
             }
             if (added.length > 0) {
-                const tmpPath = learningsPath + ".tmp." + process.pid;
+                const tmpPath = learningsPath + `.tmp-${crypto.randomUUID()}`;
                 fs.writeFileSync(tmpPath, content.endsWith("\n") ? content : `${content}\n`);
                 fs.renameSync(tmpPath, learningsPath);
             }

package/mcp/dist/governance/locks.js

@@ -24,40 +24,11 @@ function acquireFileLock(lockPath) {
             try {
                 const stat = fs.statSync(lockPath);
                 if (Date.now() - stat.mtimeMs > staleThreshold) {
-                    // Verify lock owner PID is dead before removing stale lock
-                    let ownerDead = true;
-                    try {
-                        const lockContent = fs.readFileSync(lockPath, "utf8");
-                        const lockPid = Number.parseInt(lockContent.split("\n")[0], 10);
-                        if (Number.isFinite(lockPid) && lockPid > 0) {
-                            if (process.platform !== 'win32') {
-                                try {
-                                    process.kill(lockPid, 0);
-                                    ownerDead = false;
-                                }
-                                catch {
-                                    ownerDead = true;
-                                }
-                            }
-                            else {
-                                try {
-                                    const result = require('child_process').spawnSync('tasklist', ['/FI', `PID eq ${lockPid}`, '/NH'], { encoding: 'utf8', timeout: 2000 });
-                                    if (result.stdout && result.stdout.includes(String(lockPid)))
-                                        ownerDead = false;
-                                }
-                                catch {
-                                    ownerDead = true;
-                                }
-                            }
-                        }
-                    }
-                    catch {
-                        ownerDead = true; // Can't read lock file, treat as dead
-                    }
-                    if (ownerDead) {
-                        fs.unlinkSync(lockPath);
-                        continue;
-                    }
+                    // Lock file is older than stale threshold — delete unconditionally.
+                    // This handles zombie processes, crashed hooks, and any case where
+                    // the owning process failed to clean up.
+                    fs.unlinkSync(lockPath);
+                    continue;
                 }
             }
             catch (statErr) {

package/mcp/dist/governance/policy.js

@@ -143,7 +143,7 @@ function normalizeRuntimeHealth(data) {
         normalized.lastPromptAt = data.lastPromptAt;
     if (typeof data.lastStopAt === "string")
         normalized.lastStopAt = data.lastStopAt;
-    if (isRecord(data.lastAutoSave) && typeof data.lastAutoSave.at === "string" && ["clean", "saved-local", "saved-pushed", "error"].includes(String(data.lastAutoSave.status))) {
+    if (isRecord(data.lastAutoSave) && typeof data.lastAutoSave.at === "string" && ["clean", "saved-local", "saved-pushed", "no-upstream", "error"].includes(String(data.lastAutoSave.status))) {
         normalized.lastAutoSave = {
             at: data.lastAutoSave.at,
             status: data.lastAutoSave.status,
@@ -169,7 +169,7 @@ function normalizeRuntimeHealth(data) {
             normalized.lastSync.lastSuccessfulPullAt = data.lastSync.lastSuccessfulPullAt;
         if (typeof data.lastSync.lastPushAt === "string")
             normalized.lastSync.lastPushAt = data.lastSync.lastPushAt;
-        if (["saved-local", "saved-pushed", "error"].includes(String(data.lastSync.lastPushStatus)))
+        if (["saved-local", "saved-pushed", "no-upstream", "error"].includes(String(data.lastSync.lastPushStatus)))
             normalized.lastSync.lastPushStatus = data.lastSync.lastPushStatus;
         if (typeof data.lastSync.lastPushDetail === "string")
             normalized.lastSync.lastPushDetail = data.lastSync.lastPushDetail;

package/mcp/dist/init/init-configure.js

@@ -0,0 +1,338 @@
+/**
+ * MCP target configuration, hooks setup, and onboarding preference helpers.
+ * Extracted from init.ts to keep the orchestrator focused on flow control.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { getProjectOwnershipDefault } from "../project-config.js";
+import { atomicWriteText, debugLog, readRootManifest, writeRootManifest, } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { configureAllHooks, installPhrenCliWrapper } from "../hooks.js";
+import { updateWorkflowPolicy } from "../shared/governance.js";
+import { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, logMcpTargetStatus, } from "./config.js";
+import { VERSION } from "./shared.js";
+import { writeInstallPreferences, writeGovernanceInstallPreferences, } from "./preferences.js";
+import { repairPreexistingInstall, ensureGovernanceFiles, ensureGitignoreEntry, upsertProjectEnvVar, detectProjectDir, bootstrapFromExisting, runPostInitVerify, } from "./setup.js";
+import { log } from "./shared.js";
+/**
+ * Configure MCP for all detected AI coding tools (Claude, VS Code, Cursor, Copilot, Codex).
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export function configureMcpTargets(phrenPath, opts, verb = "Configured") {
+    let claudeStatus = "no_settings";
+    try {
+        const status = configureClaude(phrenPath, { mcpEnabled: opts.mcpEnabled, hooksEnabled: opts.hooksEnabled });
+        claudeStatus = status ?? "installed";
+        if (status === "disabled" || status === "already_disabled") {
+            log(`  ${verb} Claude Code hooks (MCP disabled)`);
+        }
+        else {
+            log(`  ${verb} Claude Code MCP + hooks`);
+        }
+    }
+    catch (e) {
+        log(`  Could not configure Claude Code settings (${e}), add manually`);
+    }
+    let vsStatus = "no_vscode";
+    try {
+        vsStatus = configureVSCode(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_vscode";
+        logMcpTargetStatus("VS Code", vsStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureVSCode failed: ${errorMessage(err)}`);
+    }
+    let cursorStatus = "no_cursor";
+    try {
+        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_cursor";
+        logMcpTargetStatus("Cursor", cursorStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCursorMcp failed: ${errorMessage(err)}`);
+    }
+    let copilotStatus = "no_copilot";
+    try {
+        copilotStatus = configureCopilotMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_copilot";
+        logMcpTargetStatus("Copilot CLI", copilotStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCopilotMcp failed: ${errorMessage(err)}`);
+    }
+    let codexStatus = "no_codex";
+    try {
+        codexStatus = configureCodexMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_codex";
+        logMcpTargetStatus("Codex", codexStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCodexMcp failed: ${errorMessage(err)}`);
+    }
+    const allStatuses = [claudeStatus, vsStatus, cursorStatus, copilotStatus, codexStatus];
+    if (allStatuses.some((s) => s === "installed" || s === "already_configured"))
+        return "installed";
+    if (allStatuses.some((s) => s === "disabled" || s === "already_disabled"))
+        return "disabled";
+    return claudeStatus;
+}
+/**
+ * Configure hooks if enabled, or log a disabled message.
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export function configureHooksIfEnabled(phrenPath, hooksEnabled, verb) {
+    if (hooksEnabled) {
+        try {
+            const hooked = configureAllHooks(phrenPath, { allTools: true });
+            if (hooked.length)
+                log(`  ${verb} hooks: ${hooked.join(", ")}`);
+        }
+        catch (err) {
+            debugLog(`configureAllHooks failed: ${errorMessage(err)}`);
+        }
+    }
+    else {
+        log(`  Hooks are disabled by preference (run: npx phren hooks-mode on)`);
+    }
+    // Install phren CLI wrapper at ~/.local/bin/phren so the bare command works
+    const wrapperInstalled = installPhrenCliWrapper(phrenPath);
+    if (wrapperInstalled) {
+        log(`  ${verb} CLI wrapper: ~/.local/bin/phren`);
+    }
+    else {
+        log(`  Note: phren CLI wrapper not installed (existing non-managed binary, or no entry script found)`);
+    }
+}
+export function applyOnboardingPreferences(phrenPath, opts) {
+    if (opts.projectOwnershipDefault) {
+        writeInstallPreferences(phrenPath, { projectOwnershipDefault: opts.projectOwnershipDefault });
+    }
+    const runtimePatch = {};
+    if (opts.findingsProactivity)
+        runtimePatch.proactivityFindings = opts.findingsProactivity;
+    if (opts.taskProactivity)
+        runtimePatch.proactivityTask = opts.taskProactivity;
+    if (Object.keys(runtimePatch).length > 0) {
+        writeInstallPreferences(phrenPath, runtimePatch);
+    }
+    const governancePatch = {};
+    if (opts.findingsProactivity)
+        governancePatch.proactivityFindings = opts.findingsProactivity;
+    if (opts.taskProactivity)
+        governancePatch.proactivityTask = opts.taskProactivity;
+    if (Object.keys(governancePatch).length > 0) {
+        writeGovernanceInstallPreferences(phrenPath, governancePatch);
+    }
+    const workflowPatch = {};
+    if (typeof opts.lowConfidenceThreshold === "number")
+        workflowPatch.lowConfidenceThreshold = opts.lowConfidenceThreshold;
+    if (Array.isArray(opts.riskySections))
+        workflowPatch.riskySections = opts.riskySections;
+    if (opts.taskMode)
+        workflowPatch.taskMode = opts.taskMode;
+    if (opts.findingSensitivity)
+        workflowPatch.findingSensitivity = opts.findingSensitivity;
+    if (Object.keys(workflowPatch).length > 0) {
+        updateWorkflowPolicy(phrenPath, workflowPatch);
+    }
+}
+export function writeWalkthroughEnvDefaults(phrenPath, opts) {
+    const envFile = path.join(phrenPath, ".env");
+    let envContent = fs.existsSync(envFile) ? fs.readFileSync(envFile, "utf8") : "# phren feature flags — generated by init\n";
+    const envFlags = [];
+    const autoCaptureChoice = opts._walkthroughAutoCapture;
+    const hasAutoCaptureFlag = /^\s*PHREN_FEATURE_AUTO_CAPTURE=.*$/m.test(envContent);
+    if (typeof autoCaptureChoice === "boolean") {
+        envFlags.push({
+            flag: `PHREN_FEATURE_AUTO_CAPTURE=${autoCaptureChoice ? "1" : "0"}`,
+            label: `Auto-capture ${autoCaptureChoice ? "enabled" : "disabled"}`,
+        });
+    }
+    else if (autoCaptureChoice !== false && !hasAutoCaptureFlag) {
+        // Default to enabled on fresh installs and non-walkthrough init.
+        envFlags.push({ flag: "PHREN_FEATURE_AUTO_CAPTURE=1", label: "Auto-capture enabled" });
+    }
+    if (opts._walkthroughSemanticDedup)
+        envFlags.push({ flag: "PHREN_FEATURE_SEMANTIC_DEDUP=1", label: "Semantic dedup" });
+    if (opts._walkthroughSemanticConflict)
+        envFlags.push({ flag: "PHREN_FEATURE_SEMANTIC_CONFLICT=1", label: "Conflict detection" });
+    if (envFlags.length === 0)
+        return [];
+    let changed = false;
+    const enabledLabels = [];
+    for (const { flag, label } of envFlags) {
+        const key = flag.split("=")[0];
+        const lineRe = new RegExp(`^\\s*${key}=.*$`, "m");
+        if (lineRe.test(envContent)) {
+            const before = envContent;
+            envContent = envContent.replace(lineRe, flag);
+            if (envContent !== before) {
+                changed = true;
+                enabledLabels.push(label);
+            }
+        }
+        else {
+            if (!envContent.endsWith("\n"))
+                envContent += "\n";
+            envContent += `${flag}\n`;
+            changed = true;
+            enabledLabels.push(label);
+        }
+    }
+    if (changed) {
+        const tmpPath = `${envFile}.tmp-${crypto.randomUUID()}`;
+        fs.writeFileSync(tmpPath, envContent);
+        fs.renameSync(tmpPath, envFile);
+    }
+    return enabledLabels.map((label) => `${label} (${envFile})`);
+}
+export function collectRepairedAssetLabels(repaired) {
+    const repairedAssets = [];
+    if (repaired.createdContextFile)
+        repairedAssets.push("~/.phren-context.md");
+    if (repaired.createdRootMemory)
+        repairedAssets.push("generated MEMORY.md");
+    repairedAssets.push(...repaired.createdGlobalAssets);
+    repairedAssets.push(...repaired.createdRuntimeAssets);
+    repairedAssets.push(...repaired.createdFeatureDefaults);
+    repairedAssets.push(...repaired.createdSkillArtifacts);
+    return repairedAssets;
+}
+export function applyProjectStorageBindings(repoRoot, phrenPath) {
+    const updates = [];
+    if (ensureGitignoreEntry(repoRoot, ".phren/")) {
+        updates.push(`${path.join(repoRoot, ".gitignore")} (.phren/)`);
+    }
+    if (upsertProjectEnvVar(repoRoot, "PHREN_PATH", phrenPath)) {
+        updates.push(`${path.join(repoRoot, ".env")} (PHREN_PATH=${phrenPath})`);
+    }
+    return updates;
+}
+export async function warmSemanticSearch(phrenPath, profile) {
+    const { checkOllamaAvailable, checkModelAvailable, getOllamaUrl, getEmbeddingModel } = await import("../shared/ollama.js");
+    const ollamaUrl = getOllamaUrl();
+    if (!ollamaUrl)
+        return "Semantic search: disabled.";
+    const model = getEmbeddingModel();
+    if (!await checkOllamaAvailable()) {
+        return `Semantic search not warmed: Ollama offline at ${ollamaUrl}.`;
+    }
+    if (!await checkModelAvailable()) {
+        return `Semantic search not warmed: model ${model} is not pulled yet.`;
+    }
+    const { buildIndex, listIndexedDocumentPaths } = await import("../shared/index.js");
+    const { getEmbeddingCache, formatEmbeddingCoverage } = await import("../shared/embedding-cache.js");
+    const { backgroundEmbedMissingDocs } = await import("../startup-embedding.js");
+    const { getPersistentVectorIndex } = await import("../shared/vector-index.js");
+    const db = await buildIndex(phrenPath, profile);
+    try {
+        const cache = getEmbeddingCache(phrenPath);
+        await cache.load().catch(() => { });
+        const allPaths = listIndexedDocumentPaths(phrenPath, profile);
+        const before = cache.coverage(allPaths);
+        if (before.missing > 0) {
+            await backgroundEmbedMissingDocs(db, cache);
+        }
+        await cache.load().catch(() => { });
+        const after = cache.coverage(allPaths);
+        if (cache.size() > 0) {
+            getPersistentVectorIndex(phrenPath).ensure(cache.getAllEntries());
+        }
+        if (after.total === 0) {
+            return `Semantic search ready (${model}), but there are no indexed docs yet.`;
+        }
+        const embeddedNow = Math.max(0, after.embedded - before.embedded);
+        const prefix = after.state === "warm" ? "Semantic search warmed" : "Semantic search warming";
+        const delta = embeddedNow > 0 ? `; embedded ${embeddedNow} new docs during init` : "";
+        return `${prefix}: ${model}, ${formatEmbeddingCoverage(after)}${delta}.`;
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore close errors in init */ }
+    }
+}
+export async function runProjectLocalInit(opts = {}) {
+    const detectedRoot = detectProjectDir(process.cwd(), path.join(process.cwd(), ".phren")) || process.cwd();
+    const hasWorkspaceMarker = fs.existsSync(path.join(detectedRoot, ".git")) ||
+        fs.existsSync(path.join(detectedRoot, "CLAUDE.md")) ||
+        fs.existsSync(path.join(detectedRoot, "AGENTS.md")) ||
+        fs.existsSync(path.join(detectedRoot, ".claude", "CLAUDE.md"));
+    if (!hasWorkspaceMarker) {
+        throw new Error("project-local mode must be run inside a repo or project root");
+    }
+    const workspaceRoot = path.resolve(detectedRoot);
+    const phrenPath = path.join(workspaceRoot, ".phren");
+    const existingManifest = readRootManifest(phrenPath);
+    if (existingManifest && existingManifest.installMode !== "project-local") {
+        throw new Error(`Refusing to reuse non-local phren root at ${phrenPath}`);
+    }
+    const ownershipDefault = opts.projectOwnershipDefault
+        ?? (existingManifest ? getProjectOwnershipDefault(phrenPath) : "detached");
+    if (!existingManifest && !opts.projectOwnershipDefault) {
+        opts.projectOwnershipDefault = ownershipDefault;
+    }
+    const mcpEnabled = opts.mcp ? opts.mcp === "on" : true;
+    const projectName = path.basename(workspaceRoot).toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+    if (opts.dryRun) {
+        log("\nInit dry run. No files will be written.\n");
+        log(`Mode: project-local`);
+        log(`Workspace root: ${workspaceRoot}`);
+        log(`Phren root: ${phrenPath}`);
+        log(`Project: ${projectName}`);
+        log(`VS Code workspace MCP: ${mcpEnabled ? "on" : "off"}`);
+        log(`Hooks: unsupported in project-local mode`);
+        log("");
+        return;
+    }
+    fs.mkdirSync(phrenPath, { recursive: true });
+    writeRootManifest(phrenPath, {
+        version: 1,
+        installMode: "project-local",
+        syncMode: "workspace-git",
+        workspaceRoot,
+        primaryProject: projectName,
+    });
+    ensureGovernanceFiles(phrenPath);
+    repairPreexistingInstall(phrenPath);
+    fs.mkdirSync(path.join(phrenPath, "global", "skills"), { recursive: true });
+    fs.mkdirSync(path.join(phrenPath, ".runtime"), { recursive: true });
+    fs.mkdirSync(path.join(phrenPath, ".sessions"), { recursive: true });
+    if (!fs.existsSync(path.join(phrenPath, ".gitignore"))) {
+        atomicWriteText(path.join(phrenPath, ".gitignore"), [
+            ".runtime/",
+            ".sessions/",
+            "*.lock",
+            "*.tmp-*",
+            "",
+        ].join("\n"));
+    }
+    if (!fs.existsSync(path.join(phrenPath, "global", "CLAUDE.md"))) {
+        atomicWriteText(path.join(phrenPath, "global", "CLAUDE.md"), "# Global Context\n\nRepo-local Phren instructions shared across this workspace.\n");
+    }
+    const created = bootstrapFromExisting(phrenPath, workspaceRoot, { ownership: ownershipDefault });
+    applyOnboardingPreferences(phrenPath, opts);
+    writeInstallPreferences(phrenPath, {
+        mcpEnabled,
+        hooksEnabled: false,
+        skillsScope: opts.skillsScope ?? "global",
+        installedVersion: VERSION,
+    });
+    try {
+        const vscodeResult = configureVSCode(phrenPath, { mcpEnabled, scope: "workspace" });
+        logMcpTargetStatus("VS Code", vscodeResult, existingManifest ? "Updated" : "Configured");
+    }
+    catch (err) {
+        debugLog(`configureVSCode(workspace) failed: ${errorMessage(err)}`);
+    }
+    log(`\n${existingManifest ? "Updated" : "Created"} project-local phren at ${phrenPath}`);
+    log(`  Workspace root: ${workspaceRoot}`);
+    log(`  Project: ${created.project}`);
+    log(`  Ownership: ${created.ownership}`);
+    log(`  Sync mode: workspace-git`);
+    log(`  Hooks: off (unsupported in project-local mode)`);
+    log(`  VS Code MCP: ${mcpEnabled ? "workspace on" : "workspace off"}`);
+    const verify = runPostInitVerify(phrenPath);
+    log(`\nVerifying setup...`);
+    for (const check of verify.checks) {
+        log(`  ${check.ok ? "pass" : "FAIL"} ${check.name}: ${check.detail}`);
+    }
+}

package/mcp/dist/init/init-hooks-mode.js

@@ -0,0 +1,57 @@
+/**
+ * Hooks mode toggle: enables/disables phren lifecycle hooks for Claude and other tools.
+ */
+import { debugLog, findPhrenPath, readRootManifest } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { configureAllHooks } from "../hooks.js";
+import { configureClaude } from "./config.js";
+import { getMcpEnabledPreference, getHooksEnabledPreference, setHooksEnabledPreference, } from "./preferences.js";
+import { DEFAULT_PHREN_PATH, log } from "./shared.js";
+import { parseMcpMode } from "./init.js";
+export async function runHooksMode(modeArg) {
+    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const manifest = readRootManifest(phrenPath);
+    const normalizedArg = modeArg?.trim().toLowerCase();
+    if (!normalizedArg || normalizedArg === "status") {
+        const current = getHooksEnabledPreference(phrenPath);
+        log(`Hooks mode: ${current ? "on (active)" : "off (disabled)"}`);
+        log(`Change mode: npx phren hooks-mode on|off`);
+        return;
+    }
+    const mode = parseMcpMode(normalizedArg);
+    if (!mode) {
+        throw new Error(`Invalid mode "${modeArg}". Use: on | off | status`);
+    }
+    if (manifest?.installMode === "project-local") {
+        throw new Error("hooks-mode is unsupported in project-local mode");
+    }
+    const enabled = mode === "on";
+    let claudeStatus = "no_settings";
+    try {
+        claudeStatus = configureClaude(phrenPath, {
+            mcpEnabled: getMcpEnabledPreference(phrenPath),
+            hooksEnabled: enabled,
+        }) ?? claudeStatus;
+    }
+    catch (err) {
+        debugLog(`hooks-mode: configureClaude failed: ${errorMessage(err)}`);
+    }
+    if (enabled) {
+        try {
+            const hooked = configureAllHooks(phrenPath, { allTools: true });
+            if (hooked.length)
+                log(`Updated hooks: ${hooked.join(", ")}`);
+        }
+        catch (err) {
+            debugLog(`hooks-mode: configureAllHooks failed: ${errorMessage(err)}`);
+        }
+    }
+    else {
+        log("Hooks will no-op immediately via preference and Claude hooks are removed.");
+    }
+    // Persist preference only after config writes have been attempted
+    setHooksEnabledPreference(phrenPath, enabled);
+    log(`Hooks mode set to ${mode}.`);
+    log(`Claude status: ${claudeStatus}`);
+    log(`Restart your agent to apply changes.`);
+}

package/mcp/dist/init/init-mcp-mode.js

@@ -0,0 +1,80 @@
+/**
+ * MCP mode toggle: enables/disables phren as an MCP server across all detected tools.
+ */
+import { debugLog, findPhrenPath, readRootManifest } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, } from "./config.js";
+import { getMcpEnabledPreference, getHooksEnabledPreference, setMcpEnabledPreference, } from "./preferences.js";
+import { DEFAULT_PHREN_PATH, log } from "./shared.js";
+import { parseMcpMode } from "./init.js";
+export async function runMcpMode(modeArg) {
+    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const manifest = readRootManifest(phrenPath);
+    const normalizedArg = modeArg?.trim().toLowerCase();
+    if (!normalizedArg || normalizedArg === "status") {
+        const current = getMcpEnabledPreference(phrenPath);
+        const hooks = getHooksEnabledPreference(phrenPath);
+        log(`MCP mode: ${current ? "on (recommended)" : "off (hooks-only fallback)"}`);
+        log(`Hooks mode: ${hooks ? "on (active)" : "off (disabled)"}`);
+        log(`Change mode: npx phren mcp-mode on|off`);
+        log(`Hooks toggle: npx phren hooks-mode on|off`);
+        return;
+    }
+    const mode = parseMcpMode(normalizedArg);
+    if (!mode) {
+        throw new Error(`Invalid mode "${modeArg}". Use: on | off | status`);
+    }
+    const enabled = mode === "on";
+    if (manifest?.installMode === "project-local") {
+        const vscodeStatus = configureVSCode(phrenPath, { mcpEnabled: enabled, scope: "workspace" });
+        setMcpEnabledPreference(phrenPath, enabled);
+        log(`MCP mode set to ${mode}.`);
+        log(`VS Code status: ${vscodeStatus}`);
+        log(`Project-local mode only configures workspace VS Code MCP.`);
+        return;
+    }
+    let claudeStatus = "no_settings";
+    let vscodeStatus = "no_vscode";
+    let cursorStatus = "no_cursor";
+    let copilotStatus = "no_copilot";
+    let codexStatus = "no_codex";
+    try {
+        claudeStatus = configureClaude(phrenPath, { mcpEnabled: enabled }) ?? claudeStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureClaude failed: ${errorMessage(err)}`);
+    }
+    try {
+        vscodeStatus = configureVSCode(phrenPath, { mcpEnabled: enabled }) ?? vscodeStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureVSCode failed: ${errorMessage(err)}`);
+    }
+    try {
+        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled: enabled }) ?? cursorStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureCursorMcp failed: ${errorMessage(err)}`);
+    }
+    try {
+        copilotStatus = configureCopilotMcp(phrenPath, { mcpEnabled: enabled }) ?? copilotStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureCopilotMcp failed: ${errorMessage(err)}`);
+    }
+    try {
+        codexStatus = configureCodexMcp(phrenPath, { mcpEnabled: enabled }) ?? codexStatus;
+    }
+    catch (err) {
+        debugLog(`mcp-mode: configureCodexMcp failed: ${errorMessage(err)}`);
+    }
+    // Persist preference only after config writes have been attempted
+    setMcpEnabledPreference(phrenPath, enabled);
+    log(`MCP mode set to ${mode}.`);
+    log(`Claude status: ${claudeStatus}`);
+    log(`VS Code status: ${vscodeStatus}`);
+    log(`Cursor status: ${cursorStatus}`);
+    log(`Copilot CLI status: ${copilotStatus}`);
+    log(`Codex status: ${codexStatus}`);
+    log(`Restart your agent to apply changes.`);
+}