pi-continuous-learning 0.3.0

package/dist/tool-observer.js

@@ -0,0 +1,77 @@
+/**
+ * Tool call observation handlers for pi-continuous-learning.
+ * Captures tool_execution_start and tool_execution_end events as JSONL observations.
+ */
+import { getCurrentActiveInstincts } from "./active-instincts.js";
+import { appendObservation } from "./observations.js";
+import { shouldSkipObservation } from "./observer-guard.js";
+import { scrubSecrets } from "./scrubber.js";
+import { logError } from "./error-logger.js";
+export const MAX_TOOL_INPUT_LENGTH = 5000;
+export const MAX_TOOL_OUTPUT_LENGTH = 5000;
+function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen);
+}
+function getSessionId(ctx) {
+    return ctx.sessionManager.getSessionId();
+}
+function buildActiveInstincts() {
+    const ids = getCurrentActiveInstincts();
+    return ids.length > 0 ? { active_instincts: ids } : {};
+}
+/**
+ * Handles tool_execution_start events.
+ * Records an observation with event: tool_start, tool name, and scrubbed/truncated input.
+ */
+export function handleToolStart(event, ctx, project, baseDir) {
+    try {
+        if (shouldSkipObservation())
+            return;
+        const raw = typeof event.args === "string" ? event.args : JSON.stringify(event.args);
+        const input = truncate(scrubSecrets(raw), MAX_TOOL_INPUT_LENGTH);
+        const observation = {
+            timestamp: new Date().toISOString(),
+            event: "tool_start",
+            session: getSessionId(ctx),
+            project_id: project.id,
+            project_name: project.name,
+            tool: event.toolName,
+            input,
+            ...buildActiveInstincts(),
+        };
+        appendObservation(observation, project.id, baseDir);
+    }
+    catch (err) {
+        logError(project.id, "tool-observer:handleToolStart", err, baseDir);
+    }
+}
+/**
+ * Handles tool_execution_end events.
+ * Records an observation with event: tool_complete, tool name, scrubbed/truncated output, and is_error.
+ */
+export function handleToolEnd(event, ctx, project, baseDir) {
+    try {
+        if (shouldSkipObservation())
+            return;
+        const raw = typeof event.result === "string" ? event.result : JSON.stringify(event.result);
+        const output = truncate(scrubSecrets(raw), MAX_TOOL_OUTPUT_LENGTH);
+        const observation = {
+            timestamp: new Date().toISOString(),
+            event: "tool_complete",
+            session: getSessionId(ctx),
+            project_id: project.id,
+            project_name: project.name,
+            tool: event.toolName,
+            output,
+            is_error: event.isError,
+            ...buildActiveInstincts(),
+        };
+        appendObservation(observation, project.id, baseDir);
+    }
+    catch (err) {
+        logError(project.id, "tool-observer:handleToolEnd", err, baseDir);
+    }
+}
+//# sourceMappingURL=tool-observer.js.map

package/dist/tool-observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-observer.js","sourceRoot":"","sources":["../src/tool-observer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C,SAAS,QAAQ,CAAC,IAAY,EAAE,MAAc;IAC5C,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,YAAY,CAAC,GAAqB;IACzC,OAAO,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,oBAAoB;IAC3B,MAAM,GAAG,GAAG,yBAAyB,EAAE,CAAC;IACxC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,KAA8B,EAC9B,GAAqB,EACrB,OAAqB,EACrB,OAAgB;IAEhB,IAAI,CAAC;QACH,IAAI,qBAAqB,EAAE;YAAE,OAAO;QAEpC,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,qBAAqB,CAAC,CAAC;QAEjE,MAAM,WAAW,GAAgB;YAC/B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,YAAY;YACnB,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC;YAC1B,UAAU,EAAE,OAAO,CAAC,EAAE;YACtB,YAAY,EAAE,OAAO,CAAC,IAAI;YAC1B,IAAI,EAAE,KAAK,CAAC,QAAQ;YACpB,KAAK;YACL,GAAG,oBAAoB,EAAE;SAC1B,CAAC;QAEF,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,+BAA+B,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA4B,EAC5B,GAAqB,EACrB,OAAqB,EACrB,OAAgB;IAEhB,IAAI,CAAC;QACH,IAAI,qBAAqB,EAAE;YAAE,OAAO;QAEpC,MAAM,GAAG,GACP,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,sBAAsB,CAAC,CAAC;QAEnE,MAAM,WAAW,GAAgB;YAC/B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,eAAe;YACtB,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC;YAC1B,UAAU,EAAE,OAAO,CAAC,EAAE;YACtB,YAAY,EAAE,OAAO,CAAC,IAAI;YAC1B,IAAI,EAAE,KAAK,CAAC,QAAQ;YACpB,MAAM;YACN,QAAQ,EAAE,KAAK,CAAC,OAAO;YACvB,GAAG,oBAAoB,EAAE;SAC1B,CAAC;QAEF,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,6BAA6B,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared TypeScript interfaces for pi-continuous-learning.
+ * All modules import from this file for consistent data contracts.
+ */
+export type ObservationEvent = "tool_start" | "tool_complete" | "user_prompt" | "agent_end";
+export interface Observation {
+    timestamp: string;
+    event: ObservationEvent;
+    session: string;
+    project_id: string;
+    project_name: string;
+    tool?: string;
+    input?: string;
+    output?: string;
+    is_error?: boolean;
+    active_instincts?: string[];
+}
+export type InstinctScope = "project" | "global";
+export type InstinctSource = "personal" | "inherited";
+export interface Instinct {
+    id: string;
+    title: string;
+    trigger: string;
+    action: string;
+    confidence: number;
+    domain: string;
+    source: InstinctSource;
+    scope: InstinctScope;
+    project_id?: string;
+    project_name?: string;
+    created_at: string;
+    updated_at: string;
+    observation_count: number;
+    confirmed_count: number;
+    contradicted_count: number;
+    inactive_count: number;
+    evidence?: string[];
+    flagged_for_removal?: boolean;
+}
+export interface ProjectEntry {
+    id: string;
+    name: string;
+    root: string;
+    remote: string;
+    created_at: string;
+    last_seen: string;
+}
+export interface InstalledSkill {
+    name: string;
+    description: string;
+}
+export interface Config {
+    run_interval_minutes: number;
+    min_observations_to_analyze: number;
+    min_confidence: number;
+    max_instincts: number;
+    max_injection_chars: number;
+    model: string;
+    timeout_seconds: number;
+    active_hours_start: number;
+    active_hours_end: number;
+    max_idle_seconds: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAMD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AACjD,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,MAAM;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,MAAM,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared TypeScript interfaces for pi-continuous-learning.
+ * All modules import from this file for consistent data contracts.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-continuous-learning",
+  "version": "0.3.0",
+  "description": "A Pi extension that observes coding sessions and distills patterns into reusable instincts.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matt Devy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MattDevy/pi-continuous-learning.git"
+  },
+  "homepage": "https://github.com/MattDevy/pi-continuous-learning#readme",
+  "bugs": {
+    "url": "https://github.com/MattDevy/pi-continuous-learning/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "continuous-learning",
+    "instincts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "pi": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "bin": {
+    "pi-cl-analyze": "dist/cli/analyze.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "check": "vitest run && eslint src/ && tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run check"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@mariozechner/pi-ai": "^0.62.0",
+    "@mariozechner/pi-tui": "^0.62.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/active-instincts.ts

@@ -0,0 +1,13 @@
+let activeInstincts: string[] = [];
+
+export function getCurrentActiveInstincts(): string[] {
+  return [...activeInstincts];
+}
+
+export function setCurrentActiveInstincts(ids: string[]): void {
+  activeInstincts = [...ids];
+}
+
+export function clearActiveInstincts(): void {
+  activeInstincts = [];
+}

package/src/agents-md.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility for reading AGENTS.md files.
+ * Provides a safe wrapper around filesystem access that returns null on any failure.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+/**
+ * Reads an AGENTS.md file and returns its content.
+ * Returns null if the file does not exist or cannot be read.
+ *
+ * @param filePath - Absolute path to the AGENTS.md file
+ */
+export function readAgentsMd(filePath: string): string | null {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}

package/src/cli/analyze-prompt.ts

@@ -0,0 +1,71 @@
+export function buildAnalyzerSystemPrompt(): string {
+  return `You are a coding behavior analyst. Your job is to read session observations
+and produce or update instinct files that capture reusable coding patterns.
+
+Use the instinct_read tool to examine existing instincts and the instinct_write tool
+to create or update instincts based on patterns you discover.
+
+## Pattern Detection Heuristics
+
+Analyze observations for these categories:
+
+### User Corrections
+- User rephrases a request after an agent response
+- User explicitly rejects an approach
+- Trigger: the corrected behavior; Action: the preferred approach
+
+### Error Resolutions
+- Tool call returns is_error: true followed by a successful retry
+- Trigger: the error condition; Action: the proven resolution
+
+### Repeated Workflows
+- Same sequence of tool calls appears 3+ times
+- Trigger: the workflow start condition; Action: the efficient path
+
+### Tool Preferences
+- Agent consistently uses one tool over alternatives
+- Trigger: the task type; Action: the preferred tool and parameters
+
+### Anti-Patterns
+- Actions that consistently lead to errors or user corrections
+- Trigger: the bad pattern situation; Action: what to do instead
+
+## Feedback Analysis
+
+Each observation may include an active_instincts field listing instinct IDs
+that were injected into the agent's system prompt before that turn.
+
+Use this to update existing instinct confidence scores:
+- Confirmed (+0.05): instinct was active and agent followed the guidance without correction
+- Contradicted (-0.15): instinct was active but user corrected the agent
+- Inactive (no change): instinct was injected but trigger never arose
+
+When updating, increment the corresponding count field and recalculate confidence.
+
+## Confidence Scoring Rules
+
+### Initial Confidence (new instincts)
+- 1-2 observations  -> 0.3
+- 3-5 observations  -> 0.5
+- 6-10 observations -> 0.7
+- 11+ observations  -> 0.85
+
+### Clamping
+- Always clamp to [0.1, 0.9]
+
+## Scope Decision Guide
+
+Use project scope when the pattern is specific to this project's tech stack or conventions.
+Use global scope when the pattern applies universally to any coding session.
+When in doubt, prefer project scope.
+
+## Conservativeness Rules
+
+1. Only create a new instinct with 3+ clear independent observations supporting the pattern.
+2. No code snippets in the action field - plain language only.
+3. Each instinct must have one well-defined trigger.
+4. New instincts from observation data alone are capped at 0.85 confidence.
+5. Before creating, use instinct_list to check for duplicates. Update existing instincts instead.
+6. Write actions as clear instructions starting with a verb.
+7. Be skeptical of outliers - patterns seen only in unusual circumstances should not become instincts.`;
+}

package/src/cli/analyze.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import {
+  createAgentSession,
+  SessionManager,
+  AuthStorage,
+  ModelRegistry,
+  DefaultResourceLoader,
+} from "@mariozechner/pi-coding-agent";
+import { getModel } from "@mariozechner/pi-ai";
+
+import { loadConfig, DEFAULT_CONFIG } from "../config.js";
+import type { ProjectEntry } from "../types.js";
+import {
+  getBaseDir,
+  getProjectsRegistryPath,
+  getObservationsPath,
+  getProjectDir,
+} from "../storage.js";
+import { countObservations } from "../observations.js";
+import { runDecayPass } from "../instinct-decay.js";
+import { buildAnalyzerUserPrompt, tailObservationsSince } from "../prompts/analyzer-user.js";
+import { buildAnalyzerSystemPrompt } from "./analyze-prompt.js";
+import {
+  createInstinctListTool,
+  createInstinctReadTool,
+  createInstinctWriteTool,
+  createInstinctDeleteTool,
+} from "../instinct-tools.js";
+import { readAgentsMd } from "../agents-md.js";
+import { homedir } from "node:os";
+import type { InstalledSkill } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Lockfile guard — ensures only one instance runs at a time
+// ---------------------------------------------------------------------------
+
+const LOCKFILE_NAME = "analyze.lock";
+const LOCK_STALE_MS = 10 * 60 * 1000; // 10 minutes — stale lock threshold
+
+function getLockfilePath(baseDir: string): string {
+  return join(baseDir, LOCKFILE_NAME);
+}
+
+function acquireLock(baseDir: string): boolean {
+  const lockPath = getLockfilePath(baseDir);
+
+  if (existsSync(lockPath)) {
+    try {
+      const content = readFileSync(lockPath, "utf-8");
+      const lock = JSON.parse(content) as { pid: number; started_at: string };
+      const age = Date.now() - new Date(lock.started_at).getTime();
+
+      // Check if the owning process is still alive
+      try {
+        process.kill(lock.pid, 0); // signal 0 = existence check, no actual signal
+        if (age < LOCK_STALE_MS) {
+          return false; // Process alive and lock is fresh
+        }
+        // Process alive but lock is stale — treat as abandoned
+      } catch {
+        // Process is dead — lock is orphaned, safe to take over
+      }
+    } catch {
+      // Malformed lockfile — remove and proceed
+    }
+  }
+
+  writeFileSync(
+    lockPath,
+    JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }),
+    "utf-8"
+  );
+  return true;
+}
+
+function releaseLock(baseDir: string): void {
+  const lockPath = getLockfilePath(baseDir);
+  try {
+    if (existsSync(lockPath)) unlinkSync(lockPath);
+  } catch {
+    // Best effort — don't crash on cleanup
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Global timeout
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes total
+
+function startGlobalTimeout(timeoutMs: number): void {
+  setTimeout(() => {
+    console.error("[analyze] Global timeout reached. Exiting.");
+    process.exit(2);
+  }, timeoutMs).unref();
+}
+
+// ---------------------------------------------------------------------------
+// Per-project analysis
+// ---------------------------------------------------------------------------
+
+interface ProjectMeta {
+  last_analyzed_at?: string;
+  last_observation_line_count?: number;
+}
+
+function loadProjectsRegistry(baseDir: string): Record<string, ProjectEntry> {
+  const path = getProjectsRegistryPath(baseDir);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as Record<string, ProjectEntry>;
+  } catch {
+    return {};
+  }
+}
+
+function loadProjectMeta(projectId: string, baseDir: string): ProjectMeta {
+  const metaPath = join(getProjectDir(projectId, baseDir), "project.json");
+  if (!existsSync(metaPath)) return {};
+  try {
+    return JSON.parse(readFileSync(metaPath, "utf-8")) as ProjectMeta;
+  } catch {
+    return {};
+  }
+}
+
+function saveProjectMeta(projectId: string, meta: ProjectMeta, baseDir: string): void {
+  const metaPath = join(getProjectDir(projectId, baseDir), "project.json");
+  writeFileSync(metaPath, JSON.stringify(meta, null, 2), "utf-8");
+}
+
+function hasNewObservations(projectId: string, meta: ProjectMeta, baseDir: string): boolean {
+  const obsPath = getObservationsPath(projectId, baseDir);
+  if (!existsSync(obsPath)) return false;
+
+  const stat = statSync(obsPath);
+  if (meta.last_analyzed_at) {
+    const lastAnalyzed = new Date(meta.last_analyzed_at).getTime();
+    if (stat.mtimeMs <= lastAnalyzed) return false;
+  }
+
+  return true;
+}
+
+async function analyzeProject(
+  project: ProjectEntry,
+  config: ReturnType<typeof loadConfig>,
+  baseDir: string
+): Promise<boolean> {
+  const meta = loadProjectMeta(project.id, baseDir);
+
+  if (!hasNewObservations(project.id, meta, baseDir)) return false;
+
+  const obsPath = getObservationsPath(project.id, baseDir);
+  const sinceLineCount = meta.last_observation_line_count ?? 0;
+  const { lines: newObsLines, totalLineCount } = tailObservationsSince(obsPath, sinceLineCount);
+
+  if (newObsLines.length === 0) return false;
+
+  const obsCount = countObservations(project.id, baseDir);
+  if (obsCount < config.min_observations_to_analyze) return false;
+
+  console.log(
+    `[analyze] Processing ${project.name} (${project.id}): ${newObsLines.length} new observations (${obsCount} total)`
+  );
+
+  runDecayPass(project.id, baseDir);
+
+  const instinctsDir = join(getProjectDir(project.id, baseDir), "instincts", "personal");
+
+  const agentsMdProject = readAgentsMd(join(project.root, "AGENTS.md"));
+  const agentsMdGlobal = readAgentsMd(join(homedir(), ".pi", "agent", "AGENTS.md"));
+
+  let installedSkills: InstalledSkill[] = [];
+  try {
+    const { loadSkills } = await import("@mariozechner/pi-coding-agent");
+    const result = loadSkills({ cwd: project.root });
+    installedSkills = result.skills.map((s: { name: string; description: string }) => ({
+      name: s.name,
+      description: s.description,
+    }));
+  } catch {
+    // Skills loading is best-effort — continue without them
+  }
+
+  const userPrompt = buildAnalyzerUserPrompt(obsPath, instinctsDir, project, {
+    agentsMdProject,
+    agentsMdGlobal,
+    installedSkills,
+    observationLines: newObsLines,
+  });
+
+  const authStorage = AuthStorage.create();
+  const modelRegistry = new ModelRegistry(authStorage);
+  const modelId = (config.model || DEFAULT_CONFIG.model) as Parameters<typeof getModel>[1];
+  const model = getModel("anthropic", modelId);
+
+  const customTools = [
+    createInstinctListTool(project.id, baseDir),
+    createInstinctReadTool(project.id, baseDir),
+    createInstinctWriteTool(project.id, project.name, baseDir),
+    createInstinctDeleteTool(project.id, baseDir),
+  ];
+
+  const loader = new DefaultResourceLoader({
+    systemPromptOverride: () => buildAnalyzerSystemPrompt(),
+  });
+  await loader.reload();
+
+  const { session } = await createAgentSession({
+    model,
+    authStorage,
+    modelRegistry,
+    sessionManager: SessionManager.inMemory(),
+    customTools,
+    resourceLoader: loader,
+  });
+
+  try {
+    await session.prompt(userPrompt);
+  } finally {
+    session.dispose();
+  }
+
+  saveProjectMeta(
+    project.id,
+    { ...meta, last_analyzed_at: new Date().toISOString(), last_observation_line_count: totalLineCount },
+    baseDir
+  );
+  console.log(`[analyze] Completed ${project.name}`);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const baseDir = getBaseDir();
+
+  if (!acquireLock(baseDir)) {
+    console.log("[analyze] Another instance is already running. Exiting.");
+    process.exit(0);
+  }
+
+  startGlobalTimeout(DEFAULT_TIMEOUT_MS);
+
+  try {
+    const config = loadConfig();
+    const registry = loadProjectsRegistry(baseDir);
+    const projects = Object.values(registry);
+
+    if (projects.length === 0) {
+      console.log("[analyze] No projects registered. Use pi with the continuous-learning extension first.");
+      return;
+    }
+
+    let processed = 0;
+    for (const project of projects) {
+      try {
+        const didRun = await analyzeProject(project, config, baseDir);
+        if (didRun) processed++;
+      } catch (err) {
+        console.error(`[analyze] Error processing ${project.name}: ${String(err)}`);
+      }
+    }
+
+    console.log(`[analyze] Done. Processed ${processed}/${projects.length} project(s).`);
+  } finally {
+    releaseLock(baseDir);
+  }
+}
+
+main().catch((err) => {
+  releaseLock(getBaseDir());
+  console.error(`[analyze] Fatal error: ${String(err)}`);
+  process.exit(1);
+});