phaedo-mcp 0.3.2 → 0.3.4

package/README.md

@@ -18,12 +18,15 @@ when your phone is offline, is encrypted too.
 
 ## What you need
 
-1. **The Phaedo phone app.** Your profile lives there. The app isn't open to the
-   public yet — [phaedo.so](https://phaedo.so) has a link to hear when it is.
+1. **A profile**, from either:
+   - **the Phaedo phone app** — your full profile lives there. The app isn't open
+     to the public yet; [phaedo.so](https://phaedo.so) has a link to hear when it is.
+   - **your own Claude Code sessions** — no phone needed. Phaedo builds a starter
+     profile on this computer from how you work in Claude Code (see below).
 2. **Node.js**, free from [nodejs.org](https://nodejs.org) (the LTS button).
 
-Without the phone app there is no profile, and the server says so plainly rather
-than guessing. You can still try Phaedo with a made-up example profile.
+With neither, there is no profile, and the server says so plainly rather than
+guessing. You can still try Phaedo with a made-up example profile.
 
 ## Try it with the example profile (no phone needed)
 
@@ -63,6 +66,31 @@ example, delete the `env` line in Claude Desktop, or in Claude Code run
 `claude mcp remove -s user phaedo` and add it again without `-e …`. The server
 will then tell you there's no profile until you pair your phone.
 
+## Start a profile from your Claude Code sessions (no phone needed)
+
+If you use Claude Code, Phaedo can learn from how you work there and build a
+starter profile on this computer — for example, that you want short answers
+without headers. It starts thin and grows as you work.
+
+1. **Get this folder** as in step 1 below (Code → Download ZIP, unzip, open the
+   `mcp` folder).
+2. **Install the Claude Code hook.** In Terminal, from the `mcp` folder:
+   ```bash
+   npm install
+   ```
+   ```bash
+   npm run setup:code-hook
+   ```
+   This adds Phaedo to your AI apps and turns on three things in Claude Code:
+   loading your profile when a session starts, checking with you before it merges
+   or publishes, and learning from your sessions.
+3. **Quit and reopen Claude Code**, then keep working. The first sessions build the
+   profile, and each later session picks up what's been learned.
+
+What it reads stays on this computer: each session is reduced to counts (like "asked
+for a shorter answer, 4 times"), and the text itself is discarded. If you pair the
+phone app later, your full profile replaces the starter one and keeps what it learned.
+
 ## Use your own profile (with the phone app)
 
 1. **Get this folder.** On [the GitHub page](https://github.com/phaedo-labs/phaedo-mcp),
@@ -219,9 +247,11 @@ if you prefer.)*
 
 **Phase 1a — local JSON.** With no pairing record, reads a **vault payload**
 from `PHAEDO_FINGERPRINT` (a path, or the word `sample` for the shipped
-`mcp/sample-fingerprint.json`), then `mcp/fingerprint.json`. With neither, there
-is **no profile**: every tool returns a plain-language `decryption_failed` error
-saying so. The sample is never served unless asked for by name — until 0.3.1 it
+`mcp/sample-fingerprint.json`), then `mcp/fingerprint.json`. With neither, a
+**starter profile**: the Claude Code capture state on this computer folded onto an
+empty fingerprint (id `starter-local`), served only if it learned something. With
+nothing captured, there is **no profile**: every tool returns a plain-language
+`decryption_failed` error saying so. The sample is never served unless asked for by name — until 0.3.1 it
 was the silent fallback, so a fresh `npx phaedo-mcp` injected a made-up person's
 style without saying so. The file looks like this:
 ```json

package/capture-local.js

@@ -53,6 +53,23 @@ async function localSnapshots(now) {
   return out;
 }
 
+// How many captured sessions the local state holds, across every surface: the live ones plus
+// those evicted into the baseline (their counts are still in it). For the starter-profile
+// readout only; 0 on any failure — it describes, it never gates.
+export async function localCaptureSessionCount() {
+  try {
+    const stateMod = await loadCaptureModule('capture/state.js');
+    const state = stateMod.loadState(stateMod.defaultStatePath());
+    let n = 0;
+    for (const s of Object.values(state.surfaces || {})) {
+      n += Object.keys((s && s.sessions) || {}).length + (Array.isArray(s && s.evicted) ? s.evicted.length : 0);
+    }
+    return n;
+  } catch {
+    return 0;
+  }
+}
+
 // Fold the local capture state into a vault payload's fingerprint and return the
 // folded payload (or the input unchanged when there is nothing to fold / the
 // modules are unavailable). Pure with respect to the input object.

package/fingerprint-source.js

@@ -5,15 +5,17 @@
 //   Phase 1b (phone): if a pairing record is configured (PHAEDO_PAIRING or
 //     mcp/pairing.json), authorize → pull /v1/profile → unwrap the §7.2 envelope
 //     from the paired phone (phone-source.js). Spec-faithful; no plaintext at rest.
-//   Phase 1a (local): otherwise read a local vault-payload JSON. With neither, there is
-//     no profile — tools say so (NO_PROFILE_MESSAGE); the shipped sample is opt-in only.
+//   Phase 1a (local): otherwise read a local vault-payload JSON. With neither, a STARTER
+//     profile from this computer's own capture (loadStarterProfile), else no profile — tools
+//     say so (NO_PROFILE_MESSAGE). The shipped sample is opt-in only.
 
 import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { hasPairingRecord, loadPairingRecord, loadFingerprintFromPhone, PhoneError } from './phone-source.js';
 import { defaultStateDir, writeCache, readCache, clearCache } from './cache.js';
-import { foldLocalCapture, isLocalCaptureOwner } from './capture-local.js';
+import { foldLocalCapture, isLocalCaptureOwner, localCaptureSessionCount } from './capture-local.js';
 import { Capabilities, AuthoredSource } from './lib/phaedo-crypto.js';
 import { PhaedoError } from './errors.js';
 
@@ -78,6 +80,7 @@ export function foldConfigHome(vd) {
 // Resolution order for the local fixture (1a):
 //   1. PHAEDO_FINGERPRINT env var (absolute or cwd-relative path, or `sample`)
 //   2. ./fingerprint.json next to the server
+//   3. a starter profile folded from this computer's capture state (see loadStarterProfile)
 //   — nothing else. There is deliberately NO silent fallback to the shipped sample.
 //
 // NO PROFILE IS AN ANSWER, NOT A DEMO. Until 2026-10-20 an unpaired install with no file fell
@@ -100,8 +103,85 @@ function resolveSourcePath(baseDir) {
 export const NO_PROFILE_MESSAGE =
   'No Phaedo profile is set up on this computer, so there is nothing to load and Phaedo has ' +
   'not changed how the assistant responds. A profile comes from the Phaedo phone app, which is ' +
-  'not open to the public yet (https://phaedo.so to hear when it is). To try Phaedo with a made-up example profile ' +
-  'instead, set PHAEDO_FINGERPRINT=sample in this server\'s settings.';
+  'not open to the public yet (https://phaedo.so to hear when it is). Without the phone, Phaedo ' +
+  'can start one from your own Claude Code sessions on this computer once its Claude Code hook ' +
+  'is installed (see the README). To try a made-up example profile instead, set ' +
+  'PHAEDO_FINGERPRINT=sample in this server\'s settings.';
+
+// The same news for the server's log (Claude Desktop's MCP log shows stderr), one line.
+const NO_PROFILE_LOG =
+  'no profile is set up on this computer, so Phaedo will not change how the assistant responds. ' +
+  'Pair the Phaedo phone app, install the Claude Code hook to start one from your own sessions, ' +
+  'or set PHAEDO_FINGERPRINT=sample to try the example.';
+
+// STARTER PROFILE — the phone-less path.
+//
+// Someone without the phone app has no fingerprint to pull, but if they turned on the Claude
+// Code capture hook, this computer already holds their own signal counts (capture-local.js, the
+// tier-3 owner). Folding those onto an EMPTY fingerprint gives a profile made only of what they
+// did — never the sample's invented traits, which is what this branch fell back to until 0.3.0.
+// It is thin by construction (persona_strength 0; the projection's confidence section says
+// "treat all signals as preliminary"), and that is the honest label for it.
+//
+// Served only when the fold learned something: zero signals is still "no profile". The id is a
+// constant so receipts and the agreement metric stay on one subject across loads; pairing a
+// phone later replaces it (the phone inherits the cumulative counts — capture-local.js §5).
+export const STARTER_FINGERPRINT_ID = 'starter-local';
+
+async function loadStarterProfile(now = new Date().toISOString()) {
+  if (!await isLocalCaptureOwner(false)) return null;
+  const base = { phaedo_fingerprint: { fingerprint_id: STARTER_FINGERPRINT_ID, updated_at: now, layers: {} } };
+  const vd = await foldLocalCapture(base, { now });
+  const layers = (vd && vd.phaedo_fingerprint && vd.phaedo_fingerprint.layers) || {};
+  if (!Object.values(layers).some((l) => Array.isArray(l?.signals) && l.signals.length)) return null;
+  return markStarter(foldConfigHome(normalizeIdentity(vd)));
+}
+
+// HOW FAR ALONG a starter profile is, in words a person can act on. "Learned" counts distinct
+// traits (layer + field), not observations: ten corrections about length are one thing learned.
+// The stages are about what to do next, which is the point of saying it at all: early on, keep
+// working; once it is a solid start, the phone app is what adds the rest (its interview and the
+// decisions the subject approves, which sessions cannot show). Cut-offs are deliberately coarse
+// and are not a confidence measure — the projection's own confidence section is that.
+export const STARTER_STAGES = [
+  { min: 8, text: 'a solid start. The Phaedo phone app adds what sessions can\'t show (https://phaedo.so).' },
+  { min: 3, text: 'taking shape; it keeps learning as you work.' },
+  { min: 0, text: 'just getting started; it fills in as you work.' },
+];
+
+export async function summarizeStarter(vd) {
+  const layers = (vd && vd.phaedo_fingerprint && vd.phaedo_fingerprint.layers) || {};
+  const traits = new Set();
+  let areas = 0;
+  for (const [id, layer] of Object.entries(layers)) {
+    const sigs = (layer && Array.isArray(layer.signals)) ? layer.signals : [];
+    if (sigs.length) areas++;
+    for (const sg of sigs) if (sg && sg.field) traits.add(`${id}.${sg.field}`);
+  }
+  const learned = traits.size;
+  const sessions = await localCaptureSessionCount();
+  const stage = STARTER_STAGES.find((st) => learned >= st.min).text;
+  return { learned, areas, sessions, stage };
+}
+
+/** One line for the server log describing where the profile will come from, or null when there
+ *  is nothing a person needs told. Never touches the phone: a pull at startup would put an
+ *  "authorize" card on it with nobody asking. */
+export async function profileStatusLine(baseDir) {
+  const env = process.env.PHAEDO_FINGERPRINT;
+  if (env === SAMPLE_KEYWORD) return 'using the made-up example profile (PHAEDO_FINGERPRINT=sample).';
+  if (env) return null;
+  if (hasPairingRecord(baseDir)) return null;
+  if (existsSync(resolve(baseDir, 'fingerprint.json'))) return null;
+  const starter = await loadStarterProfile();
+  if (starter) {
+    const { learned, areas, sessions, stage } = await summarizeStarter(starter);
+    return `no phone paired; using a starter profile from your own sessions on this computer: ` +
+      `${learned} thing${learned === 1 ? '' : 's'} learned across ${areas} area${areas === 1 ? '' : 's'}` +
+      `${sessions ? ` from ${sessions} session${sessions === 1 ? '' : 's'}` : ''} — ${stage}`;
+  }
+  return NO_PROFILE_LOG;
+}
 
 // Returns the vault payload:
 //   { phaedo_fingerprint, phaedo_behavioral_signals, phaedo_linguistic_profile,
@@ -131,6 +211,18 @@ function stamp(vd, cached) {
   return vd;
 }
 
+// A starter profile is read fresh every load (live), but it did not come from a phone —
+// `pull.js` must not say it did.
+function markStarter(vd) {
+  try {
+    Object.defineProperty(vd, SOURCE, {
+      value: { live: true, cachedAt: null, ageMs: 0, starter: true },
+      enumerable: false, configurable: true, writable: true,
+    });
+  } catch { /* frozen object — provenance is best-effort, never fatal */ }
+  return vd;
+}
+
 /** Provenance of a loaded fingerprint. Absent marker → a live read. */
 export function sourceOf(vd) {
   const s = vd && vd[SOURCE];
@@ -179,6 +271,8 @@ export async function loadFingerprint(baseDir) {
     // Only the default location may be absent quietly. A path the user NAMED that doesn't
     // read is their mistake to see, not "no profile".
     if (!process.env.PHAEDO_FINGERPRINT && err?.code === 'ENOENT') {
+      const starter = await loadStarterProfile();
+      if (starter) return starter;
       throw new PhaedoError('decryption_failed', NO_PROFILE_MESSAGE);
     }
     throw new PhaedoError('decryption_failed', `Could not read the Phaedo profile at ${path} (${err?.code || err?.message || err}).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",

package/pull.js

@@ -7,12 +7,12 @@
 
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
-import { loadFingerprint, sourceOf } from './fingerprint-source.js';
+import { loadFingerprint, sourceOf, summarizeStarter } from './fingerprint-source.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 
 loadFingerprint(BASE_DIR)
-  .then((vd) => {
+  .then(async (vd) => {
     const fp = (vd && vd.phaedo_fingerprint) || {};
     const layers = fp.layers ? Object.keys(fp.layers).length : 0;
     const src = sourceOf(vd);
@@ -21,6 +21,15 @@ loadFingerprint(BASE_DIR)
     // profile went unnoticed while the agent answered authorization questions from it. The
     // whole point of this command is to verify the pairing works, so it has to distinguish
     // "your phone answered" from "your phone didn't, here's an old copy".
+    if (src.starter) {
+      const { learned, areas, sessions, stage } = await summarizeStarter(vd);
+      process.stdout.write(
+        `✓ No phone paired — serving a starter profile from your own sessions on this computer:\n` +
+        `  ${learned} thing(s) learned across ${areas} area(s)${sessions ? ` from ${sessions} session(s)` : ''} — ${stage}\n` +
+        `  Pair the Phaedo phone app (npm run pair) to replace it with your full profile.\n`
+      );
+      process.exit(0);
+    }
     if (src.live) {
       process.stdout.write(
         `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`

package/server.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { loadFingerprint, sourceOf } from './fingerprint-source.js';
+import { loadFingerprint, sourceOf, profileStatusLine } from './fingerprint-source.js';
 import { hasPairingRecord, loadPairingRecord } from './phone-source.js';
 import { depositDelegationSuggestions } from './delegation-sync.js';
 import { depositReceiptsDigest, drainAndApplyMarks } from './receipts-sync.js';
@@ -892,6 +892,12 @@ async function main() {
   await server.connect(transport);
   // stdio transport owns stdout for protocol framing — never console.log here.
   process.stderr.write('[phaedo-mcp] ready on stdio\n');
+  // Where the profile will come from, in one line, after the handshake so startup never waits
+  // on it. stderr is what Claude Desktop's MCP log shows — the one place a person debugging
+  // "why isn't Phaedo doing anything" will look. Best-effort: a failure here says nothing.
+  profileStatusLine(BASE_DIR)
+    .then((line) => { if (line) process.stderr.write(`[phaedo-mcp] ${line}\n`); })
+    .catch(() => {});
 }
 
 main().catch((err) => {

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.phaedo-labs/phaedo-mcp",
   "description": "Make AI apps answer your way, check with you before acting, and get approvals on your phone.",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "repository": {
     "url": "https://github.com/phaedo-labs/phaedo-mcp",
     "source": "github",
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "phaedo-mcp",
-      "version": "0.3.2",
+      "version": "0.3.4",
       "transport": {
         "type": "stdio"
       }