@companion-ai/feynman 0.5.0 → 0.5.2

package/.feynman/agents/researcher.md

@@ -5,6 +5,7 @@ thinking: high
 tools: read, write, edit, bash, grep, find, ls, web_search, fetch_content, get_search_content, feynman_science_database_search, hf_dataset_info, hf_repo_files, hf_repo_read_file
 output: research.md
 defaultProgress: true
+async: true
 ---
 
 You are Feynman's evidence-gathering subagent.

package/.feynman/agents/verifier.md

@@ -5,6 +5,7 @@ thinking: medium
 tools: read, bash, grep, find, ls, write, edit, web_search, fetch_content, get_search_content, feynman_science_database_search
 output: cited.md
 defaultProgress: true
+async: true
 ---
 
 You are Feynman's verifier agent.

package/AGENTS.md

@@ -84,7 +84,7 @@ Never use generic names like `research.md`, `draft.md`, `brief.md`, or `summary.
 
 ## Workspace changelog
 
-- `CHANGELOG.md` is a lab notebook, not release notes.
+- `CHANGELOG.md` is a local, untracked lab notebook (ignored by git), not release notes. Release notes live in `RELEASES.md`.
 - Read `CHANGELOG.md` before resuming substantial work when it exists.
 - Append concise entries after meaningful progress, failed approaches, major verification results, or new blockers.
 - Each entry should identify the active slug or objective and end with the next recommended step.

package/README.md

@@ -188,7 +188,7 @@ Four bundled research agents, invoked by workflow prompts when decomposition hel
 - **[Hugging Face Hub](https://huggingface.co/docs/hub/api)** — dataset metadata, split/schema inspection, and small file reads from model, dataset, and Space repos
 - **Web research** — multi-provider search, explicit proxy routing, bounded GitHub issue/PR documents, raw or question-grounded page retrieval, direct images, external fetched-content caching, stored-page passage lookup, and auditable source text; tools, commands, images, PDFs, and browser cookies remain independently gated
 - **Session search** — indexed recall across prior research sessions
-- **Observability** — opt-out PostHog analytics, logs, and traces for Feynman's own CLI commands
+- **Observability** — opt-out PostHog usage metadata for CLI commands, research workflows, tools, and model calls (see [Telemetry](#telemetry))
 - **Research execution options** — Docker, plus Modal or RunPod when their CLIs are installed, for explicitly chosen replication, benchmark, or dataset-heavy experiment runs; not service deployment or generic cloud administration
 
 ---
@@ -199,6 +199,12 @@ Built on [Pi](https://github.com/badlogic/pi-mono) for the agent runtime, [alpha
 
 ---
 
+### Telemetry
+
+Feynman sends anonymous usage telemetry to PostHog by default and prints a one-time notice on first run. It sends commands, workflow names and outcomes, tool names, model and provider names, token counts, latency, and error flags under a random install ID. It never sends prompts, model output, paper content, file paths, or tool arguments. Set `FEYNMAN_TELEMETRY=off` (or `DO_NOT_TRACK=1`) to disable it; `feynman status` shows the current setting. The full event list is in the [configuration docs](https://feynman.is/docs/getting-started/configuration#telemetry).
+
+---
+
 ### Star History
 
 <a href="https://www.star-history.com/?repos=Companion-Inc%2Ffeynman&type=date&legend=top-left">

package/RELEASES.md

@@ -6,6 +6,22 @@ GitHub release notes are generated from the matching `## vX.Y.Z` section in this
 
 ## Unreleased
 
+## v0.5.2 - 2026-09-23
+
+### Faster, cheaper research runs
+
+- OpenAlex exact searches (`openalex_search_works`, citations, references, authors, venues) now return at most the tool's `limit` (default 5, max 20) instead of 50-100 full records; an explicit `max_records` is capped at 50. In live `/lit` runs these results were 100-240 KB per call and drove most of the multi-million-token usage.
+- The `researcher` and `verifier` subagents run in the background by default, where they get Feynman's web and literature tools. Foreground launches of these agents failed and had to be retried.
+- `alpha_ask_paper` now states it takes arXiv and alphaXiv papers only, and points DOI-only papers to `fetch_content` or Europe PMC full text.
+
+## v0.5.1 - 2026-09-23
+
+### Telemetry
+
+- **Research runs are now visible in telemetry, without content.** The research extension inside Pi sends `feynman_session_started`, `feynman_workflow_started` and `feynman_workflow_completed` (workflow name such as `deepresearch` or `chat`, status, tool and subagent call counts, whether anything under `outputs/` or `papers/` was written, duration), `feynman_tool_used` (tool name and error flag), and one PostHog LLM analytics `$ai_generation` event per model response (model, provider, token counts, latency, HTTP status, stop reason; the trace ID is the Pi session ID). Prompts, model output, paper content, file paths, and tool arguments are never sent.
+- **First-run notice.** The first interactive run prints a one-time notice on stderr (never in scripts or CI) saying telemetry is on, what it collects, and how to turn it off with `FEYNMAN_TELEMETRY=off`. `feynman status` shows whether telemetry is on.
+- Telemetry stays on by default and follows the existing opt-outs: `FEYNMAN_TELEMETRY=off` or `DO_NOT_TRACK=1` disables the CLI and the Pi runtime events alike.
+
 ## v0.5.0 - 2026-09-23
 
 ### Stock Pi runtime

package/dist/cli.js

@@ -29,7 +29,7 @@ import { fetchLatestFeynmanVersion, getFeynmanUpgradeLines, isNewerVersion } fro
 import { runDoctor, runStatus } from "./setup/doctor.js";
 import { setupPreviewDependencies } from "./setup/preview.js";
 import { runSetup } from "./setup/setup.js";
-import { captureTelemetryEvent, emitTelemetryLog, getCliTelemetryMetadata, initializePostHogTelemetry, shutdownPostHogTelemetry, startTelemetrySpan, telemetryErrorProperties, } from "./telemetry/posthog.js";
+import { captureTelemetryEvent, emitTelemetryLog, getCliTelemetryMetadata, initializePostHogTelemetry, shutdownPostHogTelemetry, startTelemetrySpan, telemetryErrorProperties, telemetryFirstRunNotice, } from "./telemetry/posthog.js";
 import { ASH, printAsciiHeader, printInfo, printPanel, printSection, RESET, SAGE } from "./ui/terminal.js";
 import { createModelRuntime } from "./model/registry.js";
 import { cliCommandSections, formatCliWorkflowUsage, legacyFlags, readPromptSpecs, topLevelCommandNames, } from "../metadata/commands.mjs";
@@ -386,6 +386,9 @@ export async function main() {
     const appRoot = resolve(here, "..");
     const feynmanVersion = loadPackageVersion(appRoot).version;
     initializePostHogTelemetry({ appVersion: feynmanVersion, serviceName: "feynman-cli" });
+    const telemetryNotice = telemetryFirstRunNotice();
+    if (telemetryNotice)
+        process.stderr.write(`${telemetryNotice}\n`);
     const commandTelemetry = getCliTelemetryMetadata(process.argv.slice(2), { knownCommands: getTelemetryCommandNames(appRoot) });
     const commandStartedAt = Date.now();
     const commandSpan = startTelemetrySpan("feynman.cli.command", commandTelemetry);

package/dist/pi/launch.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { constants } from "node:os";
 import { buildPiArgs, buildPiEnv, ensureFeynmanCommandShim, ensureFeynmanWorkspaceScaffold, resolvePiCliPath, } from "./runtime.js";
 import { resolveAllExecutables } from "../system/executables.js";
+import { telemetryFirstRunNotice } from "../telemetry/posthog.js";
 export function exitCodeFromSignal(signal) {
     const signalNumber = constants.signals[signal];
     return typeof signalNumber === "number" ? 128 + signalNumber : 1;
@@ -31,6 +32,10 @@ export async function runPi(options, args, env, stdin = "inherit") {
 export async function launchPiChat(options) {
     if (process.stdout.isTTY && options.mode !== "rpc") {
         process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+        // Clearing the screen erased the first-run notice printed at startup.
+        const telemetryNotice = telemetryFirstRunNotice();
+        if (telemetryNotice)
+            process.stderr.write(`${telemetryNotice}\n`);
     }
     if (options.preLaunchNotice) {
         process.stdout.write(`${options.preLaunchNotice}\n`);

package/dist/pi/runtime.js

@@ -2,6 +2,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { createRequire } from "node:module";
 import { delimiter, dirname, resolve } from "node:path";
 import { BROWSER_FALLBACK_PATHS, MERMAID_FALLBACK_PATHS, PANDOC_FALLBACK_PATHS, resolveExecutable, } from "../system/executables.js";
+import { getPostHogChildEnv } from "../telemetry/posthog.js";
 // Pi packages shipped as Feynman dependencies and loaded from their install
 // paths through settings.json `packages` (Pi's documented local-path source).
 export const BUNDLED_PI_PACKAGES = ["pi-subagents", "pi-web-access", "pi-docparser", "pi-btw"];
@@ -132,5 +133,6 @@ export function buildPiEnv(options, executables) {
         PI_SKIP_VERSION_CHECK: process.env.PI_SKIP_VERSION_CHECK ?? "1",
         MERMAID_CLI_PATH: mermaidPath,
         PUPPETEER_EXECUTABLE_PATH: browserPath,
+        ...getPostHogChildEnv(),
     };
 }

package/dist/setup/doctor.js

@@ -6,6 +6,7 @@ import { formatPiWebAccessDoctorLines, getPiWebAccessStatus } from "../pi/web-ac
 import { BROWSER_FALLBACK_PATHS, PANDOC_FALLBACK_PATHS, resolveExecutable } from "../system/executables.js";
 import { readJson } from "../pi/settings.js";
 import { validatePiInstallation } from "../pi/runtime.js";
+import { isTelemetryDisabled } from "../telemetry/posthog.js";
 import { printInfo, printPanel, printSection } from "../ui/terminal.js";
 import { getCurrentModelSpec } from "../model/commands.js";
 import { buildModelStatusSnapshotFromRecords, getAvailableModelRecords, getSupportedModelRecords } from "../model/catalog.js";
@@ -79,6 +80,7 @@ export async function runStatus(options) {
     printInfo(`Web access: pi-web-access (${snapshot.webRouteLabel})`);
     printInfo(`Service tier: ${getConfiguredServiceTier(options.settingsPath) ?? "not set"}`);
     printInfo(`Preview: ${snapshot.previewConfigured ? "configured" : "not configured"}`);
+    printInfo(`Telemetry: ${isTelemetryDisabled() ? "off" : "on (anonymous usage metadata; set FEYNMAN_TELEMETRY=off to disable)"}`);
     printSection("Paths");
     printInfo(`Sessions: ${snapshot.sessionDir}`);
     printSection("Runtime");

package/dist/telemetry/posthog.js

@@ -19,6 +19,11 @@ export const DEFAULT_POSTHOG_PROJECT_TOKEN = "phc_owCZbr7c4mchCuVN5JXA6uBByjbT2k
 const TELEMETRY_STATE_FILE = "telemetry.json";
 const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "no", "off", "disabled"]);
 const TELEMETRY_KEY_PATTERN = /^[A-Za-z0-9_$./-]+$/;
+export const TELEMETRY_NOTICE = [
+    "Attention: Feynman collects anonymous usage telemetry: commands, workflows, tool names, models, token counts, and errors.",
+    "It never sends prompts, paper content, file paths, or tool arguments.",
+    "To opt out, set FEYNMAN_TELEMETRY=off. Learn more: https://www.feynman.is/docs/getting-started/configuration#telemetry",
+].join("\n");
 let posthogClient;
 let tracerProvider;
 let loggerProvider;
@@ -26,6 +31,7 @@ let activeConfig;
 let telemetryInitialized = false;
 let telemetryStartWarningPrinted = false;
 let telemetryTransportFailed = false;
+let telemetryNoticeThisProcess;
 export function createTelemetryTransportCircuitBreaker(onTransportFailure) {
     let circuitOpen = false;
     return {
@@ -125,7 +131,7 @@ function disableTelemetryAfterTransportFailure(error) {
         process.stderr.write(`[feynman] Telemetry disabled for this session after a transport failure (${error instanceof Error ? error.message : "unknown error"}).\n`);
     }
 }
-function isTelemetryDisabled(env = process.env) {
+export function isTelemetryDisabled(env = process.env) {
     const setting = env.FEYNMAN_TELEMETRY ?? env.FEYNMAN_POSTHOG_TELEMETRY;
     return (setting !== undefined && TELEMETRY_DISABLED_VALUES.has(setting.trim().toLowerCase())) || env.DO_NOT_TRACK === "1";
 }
@@ -156,6 +162,42 @@ function getAnonymousDistinctId(home = getFeynmanHome()) {
     writeFileSync(statePath, JSON.stringify({ ...state, anonymousId }, null, 2) + "\n", "utf8");
     return anonymousId;
 }
+/**
+ * Returns the first-run telemetry notice once per Feynman home, and again for
+ * the rest of this process so a launch that clears the screen can reprint it.
+ * Only interactive terminals get it: scripts and CI (where Windows PowerShell
+ * treats any stderr as an error) never see it, and it stays pending for the
+ * first interactive run.
+ */
+export function telemetryFirstRunNotice(home = getFeynmanHome(), interactive = process.stderr.isTTY === true) {
+    if (telemetryNoticeThisProcess || !activeConfig)
+        return telemetryNoticeThisProcess;
+    if (!interactive)
+        return undefined;
+    const statePath = resolve(getFeynmanStateDir(home), TELEMETRY_STATE_FILE);
+    const state = readTelemetryState(statePath);
+    if (state.noticeShown)
+        return undefined;
+    try {
+        mkdirSync(dirname(statePath), { recursive: true });
+        writeFileSync(statePath, JSON.stringify({ ...state, noticeShown: true }, null, 2) + "\n", "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    telemetryNoticeThisProcess = TELEMETRY_NOTICE;
+    return telemetryNoticeThisProcess;
+}
+/** Env the Pi child needs for the research extension to send under the same install id. */
+export function getPostHogChildEnv() {
+    if (!activeConfig)
+        return {};
+    return {
+        FEYNMAN_POSTHOG_KEY: activeConfig.projectToken,
+        FEYNMAN_POSTHOG_HOST: activeConfig.host,
+        FEYNMAN_TELEMETRY_DISTINCT_ID: activeConfig.distinctId,
+    };
+}
 export function resolvePostHogTelemetryConfig(options = {}) {
     const env = options.env ?? process.env;
     if (isTelemetryDisabled(env))
@@ -441,6 +483,7 @@ export async function shutdownPostHogTelemetry() {
     activeConfig = undefined;
     telemetryInitialized = false;
     telemetryTransportFailed = false;
+    telemetryNoticeThisProcess = undefined;
     await Promise.allSettled([
         client?.shutdown(3000),
         traces?.shutdown(),

package/extensions/research-tools/alpha.ts

@@ -86,7 +86,7 @@ export function registerAlphaTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "alpha_ask_paper",
 		label: "Alpha Ask Paper",
-		description: "Ask a targeted question about a paper. Uses AI to analyze the PDF and answer.",
+		description: "Ask a targeted question about an arXiv or alphaXiv paper. Uses AI to analyze the PDF and answer. DOI-only papers are not supported; read those with fetch_content on the open-access PDF or Europe PMC full text.",
 		parameters: Type.Object({
 			paper: Type.String({ description: "arXiv ID, arXiv URL, or alphaXiv URL." }),
 			question: Type.String({ description: "Question about the paper." }),

package/extensions/research-tools/science-database-openalex-exact.ts

@@ -1,4 +1,4 @@
-const MAX_EXACT_RECORDS = 500;
+const MAX_EXACT_RECORDS = 50;
 const REQUEST_TIMEOUT_MS = 25_000;
 const OPENALEX_BASE = "https://api.openalex.org";
 const OPEN_ABSTRACT_LICENSES = new Set(["cc-by", "cc-by-sa", "cc0", "public-domain"]);
@@ -461,9 +461,9 @@ async function fetchWorkById(workId: string): Promise<{
 	};
 }
 
-async function exactWorkSearch(query: string, commandQuery: string): Promise<Record<string, unknown>> {
+async function exactWorkSearch(query: string, commandQuery: string, defaultLimit?: number): Promise<Record<string, unknown>> {
 	const parsed = parseKeyValueQuery(commandQuery);
-	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), 50);
+	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), defaultLimit ?? 50);
 	const url = endpointPath("/works");
 	if (parsed.text) url.searchParams.set("search", parsed.text);
 	const filters: string[] = [];
@@ -518,12 +518,12 @@ async function exactGetWork(query: string, workId: string): Promise<Record<strin
 	}, "openalex_get_work", query, resolved.endpoints, resolved.credentialStatus);
 }
 
-async function exactCitations(query: string, commandQuery: string): Promise<Record<string, unknown>> {
+async function exactCitations(query: string, commandQuery: string, defaultLimit?: number): Promise<Record<string, unknown>> {
 	const parsed = parseKeyValueQuery(commandQuery);
 	const workInput = parsed.text;
 	if (!workInput) throw new Error("openalex_citations requires an OpenAlex work id or DOI.");
 	const resolved = await fetchWorkById(workInput);
-	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), 50);
+	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), defaultLimit ?? 50);
 	const url = endpointPath("/works");
 	url.searchParams.set("filter", `cites:${resolved.workId}`);
 	const sort = exactSearchSort(parsed.flags.sort ?? "cited_by_count", false);
@@ -545,11 +545,11 @@ async function exactCitations(query: string, commandQuery: string): Promise<Reco
 	}, "openalex_citations", query, [...resolved.endpoints, result.endpoint], result.credentialStatus);
 }
 
-async function exactReferences(query: string, commandQuery: string): Promise<Record<string, unknown>> {
+async function exactReferences(query: string, commandQuery: string, defaultLimit?: number): Promise<Record<string, unknown>> {
 	const parsed = parseKeyValueQuery(commandQuery);
 	if (!parsed.text) throw new Error("openalex_references requires an OpenAlex work id or DOI.");
 	const resolved = await fetchWorkById(parsed.text);
-	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), 100);
+	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), defaultLimit ?? 100);
 	const referenceIds = arrayValue(resolved.payload.referenced_works).map(shortOpenAlexId).filter((id): id is string => Boolean(id));
 	const selected = referenceIds.slice(0, maxRecords);
 	const endpoints = [...resolved.endpoints];
@@ -581,10 +581,10 @@ async function exactReferences(query: string, commandQuery: string): Promise<Rec
 	}, "openalex_references", query, endpoints, credentialStatus);
 }
 
-async function exactSearchAuthors(query: string, commandQuery: string): Promise<Record<string, unknown>> {
+async function exactSearchAuthors(query: string, commandQuery: string, defaultLimit?: number): Promise<Record<string, unknown>> {
 	const parsed = parseKeyValueQuery(commandQuery);
 	if (!parsed.text) throw new Error("openalex_search_authors requires a name query.");
-	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), 25);
+	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), defaultLimit ?? 25);
 	const url = endpointPath("/authors");
 	url.searchParams.set("search", parsed.text);
 	url.searchParams.set("per-page", String(Math.min(maxRecords, 200)));
@@ -625,7 +625,7 @@ async function exactGetAuthor(query: string, commandQuery: string): Promise<Reco
 	}, "openalex_get_author", query, [result.endpoint, works.endpoint], works.credentialStatus);
 }
 
-async function exactVenueInfo(query: string, commandQuery: string): Promise<Record<string, unknown>> {
+async function exactVenueInfo(query: string, commandQuery: string, defaultLimit?: number): Promise<Record<string, unknown>> {
 	const parsed = parseKeyValueQuery(commandQuery);
 	const venue = parsed.text;
 	if (!venue) throw new Error("openalex_venue_info requires a source id, ISSN, or venue name.");
@@ -640,7 +640,7 @@ async function exactVenueInfo(query: string, commandQuery: string): Promise<Reco
 			records: [row],
 		}, "openalex_venue_info", query, [result.endpoint], result.credentialStatus);
 	}
-	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), 10);
+	const maxRecords = safeExactLimit(numberValue(parsed.flags.max_records), defaultLimit ?? 10);
 	const url = endpointPath("/sources");
 	url.searchParams.set("search", venue);
 	url.searchParams.set("per-page", String(Math.min(maxRecords, 200)));
@@ -657,15 +657,15 @@ async function exactVenueInfo(query: string, commandQuery: string): Promise<Reco
 	}, "openalex_venue_info", query, [result.endpoint], result.credentialStatus);
 }
 
-export async function searchExactOpenAlex(query: string): Promise<Record<string, unknown> | undefined> {
+export async function searchExactOpenAlex(query: string, defaultLimit?: number): Promise<Record<string, unknown> | undefined> {
 	const command = exactCommand(query);
 	if (!command) return undefined;
-	if (command.name === "openalex_search_works") return exactWorkSearch(query, command.rest);
+	if (command.name === "openalex_search_works") return exactWorkSearch(query, command.rest, defaultLimit);
 	if (command.name === "openalex_get_work") return exactGetWork(query, command.rest);
-	if (command.name === "openalex_citations") return exactCitations(query, command.rest);
-	if (command.name === "openalex_references") return exactReferences(query, command.rest);
-	if (command.name === "openalex_search_authors") return exactSearchAuthors(query, command.rest);
+	if (command.name === "openalex_citations") return exactCitations(query, command.rest, defaultLimit);
+	if (command.name === "openalex_references") return exactReferences(query, command.rest, defaultLimit);
+	if (command.name === "openalex_search_authors") return exactSearchAuthors(query, command.rest, defaultLimit);
 	if (command.name === "openalex_get_author") return exactGetAuthor(query, command.rest);
-	if (command.name === "openalex_venue_info") return exactVenueInfo(query, command.rest);
+	if (command.name === "openalex_venue_info") return exactVenueInfo(query, command.rest, defaultLimit);
 	return undefined;
 }

package/extensions/research-tools/science-database-openalex.ts

@@ -354,7 +354,7 @@ async function resolveDoiWork(doiWorkId: string): Promise<{
 export async function searchOpenAlex(params: SearchParams): Promise<Record<string, unknown>> {
 	const query = cleanQuery(params.query);
 	const limit = safeLimit(params.limit);
-	const exact = await searchExactOpenAlex(query);
+	const exact = await searchExactOpenAlex(query, limit);
 	if (exact) return exact;
 	if (/^rate-limit$/i.test(query)) {
 		if (!openAlexApiKey()) {

package/extensions/research-tools/telemetry.ts

@@ -0,0 +1,263 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PostHog, type PostHogOptions } from "posthog-node";
+
+import { readPromptSpecs } from "../../metadata/commands.mjs";
+import { APP_ROOT, FEYNMAN_VERSION } from "./shared.js";
+
+// Same opt-out contract as src/telemetry/posthog.ts. The CLI passes the
+// project token, host, and anonymous install id to the Pi child only when its
+// own telemetry is on, so a Pi run outside the CLI sends nothing.
+const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "no", "off", "disabled"]);
+const FLUSH_TIMEOUT_MS = 2000;
+const OUTPUT_DIRS = ["outputs", "papers"];
+const OUTPUT_SCAN_LIMIT = 5000;
+const SHARED_STATE_KEY = Symbol.for("feynman.research-telemetry");
+
+type TelemetryValue = string | number | boolean | undefined;
+export type ResearchTelemetryClient = Pick<PostHog, "capture" | "flush" | "shutdown">;
+export type ResearchTelemetryConfig = { projectToken: string; host: string; distinctId: string };
+
+// pi-subagents runs foreground children as in-process sessions that load this
+// extension again with fresh module state, so the owner of the top-level
+// session and the client live on globalThis.
+export type ResearchTelemetrySharedState = {
+	client?: ResearchTelemetryClient;
+	primary?: object;
+	primarySessionId?: string;
+};
+
+type WorkflowRun = {
+	workflow: string;
+	startedAt: number;
+	toolCalls: number;
+	subagentCalls: number;
+	stopReason?: string;
+};
+
+export function resolveResearchTelemetryConfig(env: NodeJS.ProcessEnv = process.env): ResearchTelemetryConfig | undefined {
+	const setting = env.FEYNMAN_TELEMETRY ?? env.FEYNMAN_POSTHOG_TELEMETRY;
+	if ((setting !== undefined && TELEMETRY_DISABLED_VALUES.has(setting.trim().toLowerCase())) || env.DO_NOT_TRACK === "1") {
+		return undefined;
+	}
+	const projectToken = env.FEYNMAN_POSTHOG_KEY?.trim();
+	const host = env.FEYNMAN_POSTHOG_HOST?.trim().replace(/\/+$/, "");
+	const distinctId = env.FEYNMAN_TELEMETRY_DISTINCT_ID?.trim();
+	return projectToken && host && distinctId ? { projectToken, host, distinctId } : undefined;
+}
+
+function createPostHogClient(config: ResearchTelemetryConfig): ResearchTelemetryClient {
+	// One attempt per send; the first failure drops the rest of this process's
+	// sends silently, matching the CLI's circuit breaker.
+	let transportFailed = false;
+	const fetchOnce: NonNullable<PostHogOptions["fetch"]> = async (url, options) => {
+		if (!transportFailed) {
+			try {
+				const response = await fetch(url, options as RequestInit);
+				if (response.status >= 200 && response.status < 400) return response;
+			} catch {}
+			transportFailed = true;
+		}
+		return new Response(null, { status: 204 });
+	};
+	const client = new PostHog(config.projectToken, {
+		host: config.host,
+		flushAt: 1,
+		flushInterval: 0,
+		isServer: false,
+		disableGeoip: true,
+		fetchRetryCount: 0,
+		fetch: fetchOnce,
+	});
+	client.on("error", () => {});
+	return client;
+}
+
+export function workflowName(text: string, workflows: ReadonlySet<string>): string {
+	const name = /^\/([A-Za-z0-9_-]+)(?:\s|$)/.exec(text.trimStart())?.[1];
+	return name && workflows.has(name) ? name : "chat";
+}
+
+export function wroteResearchOutput(cwd: string, since: number): boolean {
+	let scanned = 0;
+	for (const dir of OUTPUT_DIRS) {
+		let entries: string[];
+		try {
+			entries = readdirSync(join(cwd, dir), { recursive: true, encoding: "utf8" });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (++scanned > OUTPUT_SCAN_LIMIT) return false;
+			try {
+				const stats = statSync(join(cwd, dir, entry));
+				if (stats.isFile() && stats.mtimeMs >= since) return true;
+			} catch {}
+		}
+	}
+	return false;
+}
+
+function stopStatus(stopReason: string | undefined): "completed" | "error" | "aborted" {
+	return stopReason === "error" || stopReason === "aborted" ? stopReason : "completed";
+}
+
+function readWorkflowNames(): Set<string> {
+	try {
+		return new Set(readPromptSpecs(APP_ROOT).map((spec) => spec.name));
+	} catch {
+		return new Set();
+	}
+}
+
+export function registerResearchTelemetry(
+	pi: ExtensionAPI,
+	options: {
+		env?: NodeJS.ProcessEnv;
+		createClient?: (config: ResearchTelemetryConfig) => ResearchTelemetryClient;
+		shared?: ResearchTelemetrySharedState;
+		now?: () => number;
+	} = {},
+): void {
+	const env = options.env ?? process.env;
+	const config = resolveResearchTelemetryConfig(env);
+	if (!config) return;
+	const now = options.now ?? Date.now;
+	const globalSlot = globalThis as { [SHARED_STATE_KEY]?: ResearchTelemetrySharedState };
+	const shared = options.shared ?? (globalSlot[SHARED_STATE_KEY] ??= {});
+	const workflows = readWorkflowNames();
+	const owner = {};
+	const baseProperties = {
+		app_version: FEYNMAN_VERSION,
+		node_version: process.versions.node,
+		platform: process.platform,
+		arch: process.arch,
+		telemetry_source: "feynman",
+		$process_person_profile: false,
+	};
+
+	let primary = false;
+	let traceId: string | undefined;
+	let pendingWorkflow: string | undefined;
+	let run: WorkflowRun | undefined;
+	let requestStartedAt: number | undefined;
+	let httpStatus: number | undefined;
+
+	const capture = (event: string, properties: Record<string, TelemetryValue>) => {
+		try {
+			shared.client ??= (options.createClient ?? createPostHogClient)(config);
+			shared.client.capture({ distinctId: config.distinctId, event, properties: { ...baseProperties, ...properties } });
+		} catch {}
+	};
+
+	const finishRun = (cwd: string, status: "completed" | "error" | "aborted") => {
+		if (!run) return;
+		const finished = run;
+		run = undefined;
+		capture("feynman_workflow_completed", {
+			workflow: finished.workflow,
+			status,
+			tool_calls: finished.toolCalls,
+			subagent_calls: finished.subagentCalls,
+			output_written: wroteResearchOutput(cwd, finished.startedAt),
+			duration_ms: now() - finished.startedAt,
+		});
+	};
+
+	pi.on("session_start", (event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		primary = env.PI_SUBAGENT_CHILD !== "1" && shared.primary === undefined;
+		if (primary) {
+			shared.primary = owner;
+			shared.primarySessionId = sessionId;
+		}
+		traceId = primary ? sessionId : (shared.primarySessionId ?? env.PI_SUBAGENT_PARENT_SESSION ?? sessionId);
+		if (!primary) return;
+		capture("feynman_session_started", {
+			reason: event.reason,
+			mode: ctx.mode,
+			model_provider: ctx.model?.provider,
+			model: ctx.model?.id,
+		});
+	});
+
+	pi.on("input", (event) => {
+		if (primary && !event.streamingBehavior) pendingWorkflow = workflowName(event.text, workflows);
+	});
+
+	pi.on("agent_start", () => {
+		if (!primary || run) return;
+		run = { workflow: pendingWorkflow ?? "chat", startedAt: now(), toolCalls: 0, subagentCalls: 0 };
+		pendingWorkflow = undefined;
+		capture("feynman_workflow_started", { workflow: run.workflow });
+	});
+
+	pi.on("tool_execution_end", (event) => {
+		capture("feynman_tool_used", { tool: event.toolName, is_error: event.isError, subagent: !primary });
+		if (!run) return;
+		run.toolCalls += 1;
+		if (event.toolName === "subagent") run.subagentCalls += 1;
+	});
+
+	pi.on("before_provider_request", () => {
+		requestStartedAt = now();
+	});
+
+	pi.on("after_provider_response", (event) => {
+		httpStatus = event.status;
+	});
+
+	pi.on("message_end", (event) => {
+		const message = event.message;
+		if (message.role !== "assistant") return;
+		// PostHog LLM analytics schema, metadata only: no $ai_input or $ai_output_choices.
+		capture("$ai_generation", {
+			$ai_trace_id: traceId,
+			$ai_model: message.model,
+			$ai_provider: message.provider,
+			$ai_input_tokens: message.usage.input,
+			$ai_output_tokens: message.usage.output,
+			$ai_cache_read_input_tokens: message.usage.cacheRead,
+			$ai_cache_creation_input_tokens: message.usage.cacheWrite,
+			// Pi reports input tokens with cache reads and writes already subtracted.
+			$ai_cache_reporting_exclusive: true,
+			$ai_latency: requestStartedAt === undefined ? undefined : (now() - requestStartedAt) / 1000,
+			$ai_http_status: httpStatus,
+			$ai_is_error: message.stopReason === "error",
+			$ai_stop_reason: message.stopReason,
+			subagent: !primary,
+		});
+		requestStartedAt = undefined;
+		httpStatus = undefined;
+		if (run) run.stopReason = message.stopReason;
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		finishRun(ctx.cwd, stopStatus(run?.stopReason));
+	});
+
+	pi.on("session_shutdown", async (event, ctx) => {
+		finishRun(ctx.cwd, "aborted");
+		if (shared.primary === owner) {
+			shared.primary = undefined;
+			shared.primarySessionId = undefined;
+		}
+		const client = shared.client;
+		if (!client) return;
+		const quitting = primary && event.reason === "quit";
+		if (quitting) shared.client = undefined;
+		let timer: NodeJS.Timeout | undefined;
+		const timeout = new Promise<void>((resolve) => {
+			timer = setTimeout(resolve, FLUSH_TIMEOUT_MS);
+			timer.unref?.();
+		});
+		try {
+			await Promise.race([quitting ? client.shutdown(FLUSH_TIMEOUT_MS) : client.flush(), timeout]);
+		} catch {
+		} finally {
+			clearTimeout(timer);
+		}
+	});
+}

package/extensions/research-tools.ts

@@ -9,6 +9,7 @@ import { registerHuggingFaceTools } from "./research-tools/huggingface.js";
 import { registerInitCommand, registerOutputsCommand } from "./research-tools/project.js";
 import { registerServiceTierControls } from "./research-tools/service-tier.js";
 import { registerScienceDatabaseTools } from "./research-tools/science-databases.js";
+import { registerResearchTelemetry } from "./research-tools/telemetry.js";
 
 export default function researchTools(pi: ExtensionAPI): void {
 	const cache: { agentSummaryPromise?: Promise<{ agents: string[]; chains: string[] }> } = {};
@@ -27,4 +28,5 @@ export default function researchTools(pi: ExtensionAPI): void {
 	registerOutputsCommand(pi);
 	registerServiceTierControls(pi);
 	registerScienceDatabaseTools(pi);
+	registerResearchTelemetry(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",