@companion-ai/feynman 0.5.8 → 0.5.10

package/README.md

@@ -10,176 +10,70 @@
   <a href="https://deepwiki.com/Companion-Inc/feynman"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
 </p>
 
----
+## Install
 
-### Installation
-
-**macOS / Linux:**
+macOS / Linux:
 
 ```bash
 curl -fsSL https://feynman.is/install | bash
 ```
 
-**Windows (PowerShell):**
+Windows (PowerShell):
 
 ```powershell
 irm https://feynman.is/install.ps1 | iex
 ```
 
-The one-line installer fetches the latest tagged release as a standalone bundle with its own Node.js runtime and verifies its SHA-256 before installing. To pin a version, pass it explicitly, for example `curl -fsSL https://feynman.is/install | bash -s -- 0.5.3`. Rerun the installer to upgrade; `feynman update` only updates optional Pi packages you installed.
-
-**npm alternative** (uses your local Node.js `>=22.22.0`):
-
-```bash
-npm install -g @companion-ai/feynman
-```
-
-If you installed the interim `@advaitpaliwal/feynman` package, migrate once:
-
-```bash
-npm uninstall -g @advaitpaliwal/feynman
-npm install -g @companion-ai/feynman
-```
-
-Then run `feynman setup` to sign in to a model provider. To use Feynman in an ACP editor such as Zed, run it through [pi-acp](https://github.com/svkozak/pi-acp): `"agent_servers": { "Feynman": { "command": "npx", "args": ["-y", "pi-acp"], "env": { "PI_ACP_PI_COMMAND": "feynman" } } }`. See the [installation guide](https://feynman.is/docs/getting-started/installation) for uninstalling and the [setup guide](https://feynman.is/docs/getting-started/setup) for local models (LM Studio, LiteLLM, Ollama, vLLM) and Amazon Bedrock.
-
-### Skills Only
-
-If you want just the research skills without the full terminal app:
+Or with npm and Node.js 22.22 or newer: `npm install -g @companion-ai/feynman`.
 
-**macOS / Linux:**
+Then sign in to a model provider:
 
 ```bash
-curl -fsSL https://feynman.is/install-skills | bash
+feynman setup
 ```
 
-**Windows (PowerShell):**
+The [installation guide](https://feynman.is/docs/getting-started/installation) covers pinned versions, uninstalling, and the skills-only bundle for Codex and OpenCode. The [setup guide](https://feynman.is/docs/getting-started/setup) covers local models and editors such as Zed.
 
-```powershell
-irm https://feynman.is/install-skills.ps1 | iex
-```
-
-That installs the skill library into `~/.codex/skills/feynman` for Codex. For other targets, pass a scope:
+## Use
 
 ```bash
-curl -fsSL https://feynman.is/install-skills | bash -s -- --codex     # ~/.codex/skills/feynman (default)
-curl -fsSL https://feynman.is/install-skills | bash -s -- --repo      # .agents/skills/feynman in the current repo
-curl -fsSL https://feynman.is/install-skills | bash -s -- --opencode  # .opencode/skills/feynman in the current repo
-```
-
-```powershell
-& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope Codex     # or -Scope Repo, -Scope OpenCode
+feynman "what do we know about scaling laws"
+feynman lit "RLHF alternatives"
+feynman deepresearch "mechanistic interpretability"
 ```
 
-These installers download the bundled `skills/` and `prompts/` trees plus the repo guidance files referenced by those skills. They do not install the Feynman terminal, bundled Node runtime, auth storage, or Pi packages.
-
----
-
-### What you type → what happens
-
-```
-$ feynman "what do we know about scaling laws"
-→ Searches papers and the web, answers with cited sources
-
-$ feynman deepresearch "mechanistic interpretability"
-→ Plan-first investigation with parallel researchers, synthesis, and citation verification
-
-$ feynman lit "RLHF alternatives"
-→ Literature review with consensus, disagreements, open questions, and lab/PI corpus mode when the input names a research group
-
-$ feynman audit 2401.12345
-→ Compares paper claims against the public codebase
-
-$ feynman replicate "chain-of-thought improves math"
-→ Plans replication checks and runs them only after an explicit environment choice
-
-$ feynman recipe "fine-tune a small model for math reasoning"
-→ Finds ranked, implementable ML training recipes from papers, datasets, docs, and code
-```
-
----
-
-### Workflows
-
-Ask naturally or use slash commands as shortcuts.
-
-| Command | What it does |
+| Workflow | What it does |
 | --- | --- |
-| `/deepresearch <topic>` | Source-heavy multi-agent investigation |
-| `/lit <topic-or-lab>` | Literature review from paper search and primary sources; lab/PI inputs map publication trajectories and originality-ranked papers |
-| `/review <artifact>` | Research review with severity and revision plan |
-| `/audit <item>` | Paper vs. codebase mismatch audit |
-| `/replicate <paper>` | Plan replication checks; execute only after choosing an environment |
-| `/recipe <task-or-paper>` | Ranked ML training recipes with dataset, method, code, and verification status |
+| `/deepresearch <topic>` | Planned investigation with parallel researchers and citation checks |
+| `/lit <topic or lab>` | Literature review: consensus, disagreements, open questions |
+| `/review <paper or draft>` | Critique with severity levels and a revision plan |
+| `/audit <paper>` | Paper claims compared with its public code |
+| `/replicate <paper>` | Replication plan; runs only after you choose an environment |
+| `/recipe <task>` | Ranked ML training recipes with datasets and code |
 | `/compare <topic>` | Source comparison matrix |
 | `/draft <topic>` | Paper-style draft from research findings |
-| `/autoresearch <idea>` | Bounded experiment loop with benchmark evidence |
-| `/summarize <source>` | Summarize a paper, report, repo, or PDF without loading it raw into context |
-| `/btw <question>` | Side conversation while the main research agent is busy, with optional handoff back into the main thread |
-| `/outputs` | Browse all research artifacts |
-
----
-
-### Agents
-
-Four bundled research agents, invoked by workflow prompts when decomposition helps.
-
-- **Researcher** — gather evidence across papers, web, repos, docs
-- **Reviewer** — internal research critique with severity-graded feedback
-- **Writer** — structured drafts from research notes
-- **Verifier** — inline citations, source URL verification, dead link cleanup
+| `/autoresearch <idea>` | Bounded experiment loop against a benchmark |
+| `/summarize <source>` | Summary of a paper, repository, or PDF |
 
----
+Results are saved to `outputs/` (drafts to `papers/`). `/lit`, `/deepresearch`, and `/recipe` also write a provenance file listing the sources used and what was verified.
 
-### Skills & Tools
+## Sources
 
-- **[alphaXiv](https://www.alphaxiv.org/)** — paper search, Q&A, code reading, and annotations (via Feynman's `alpha` tools and `feynman alpha` command)
-- **Literature databases** — read-only Semantic Scholar, OpenAlex, arXiv ID lookup, PubMed, Europe PMC full text, bioRxiv/medRxiv, and Crossref, with stable identifiers. Set the free `OPENALEX_API_KEY` ([create one](https://openalex.org/settings/api)) and optionally `SEMANTIC_SCHOLAR_API_KEY` ([request one](https://www.semanticscholar.org/product/api#api-key-form)) to use your own rate limits
-- **[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** — search, page fetching, and PDF extraction through [pi-web-access](https://github.com/nicobailon/pi-web-access); Exa works without a key, and `feynman search set` configures Perplexity, Exa, or Gemini
-- **Documents** — local PDF and office-document parsing through [pi-docparser](https://github.com/maxedapps/pi-docparser)
-- **Compute** — Docker, plus Modal or RunPod when their CLIs are installed, for replication and experiment runs you explicitly approve
+Feynman searches alphaXiv, Semantic Scholar, OpenAlex, arXiv, PubMed, Europe PMC, bioRxiv, medRxiv, Crossref, the web, and Hugging Face, and reads local PDFs and documents. Free `OPENALEX_API_KEY` and `SEMANTIC_SCHOLAR_API_KEY` keys avoid the shared rate limits. It runs on stock [Pi](https://github.com/earendil-works/pi) with four research agents: researcher, verifier, reviewer, and writer.
 
----
+## Telemetry
 
-### How it works
+Feynman sends anonymous usage data to PostHog: commands, workflows, tools, models, token counts, and errors with their messages and stack traces (your home folder shown as `~`). It never sends prompts, model output, paper content, or tool arguments. Turn it off with `FEYNMAN_TELEMETRY=off`. [What is sent](https://feynman.is/docs/getting-started/configuration#telemetry)
 
-Feynman runs on stock [Pi](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`). Its prompts, skills, agents, and research tools load as a Pi [package](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) alongside the bundled `pi-subagents`, `pi-web-access`, `pi-docparser`, and `pi-btw` packages. Paper search and analysis use [alphaXiv](https://www.alphaxiv.org/). Research claims link to papers, docs, or repos with direct URLs.
-
----
-
-### 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 messages with stack traces (home folder shown as `~`) under a random install ID. It never sends prompts, model output, paper content, 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">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Companion-Inc/feynman&type=date&theme=dark&legend=top-left" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Companion-Inc/feynman&type=date&legend=top-left" />
-    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Companion-Inc/feynman&type=date&legend=top-left" />
-  </picture>
-</a>
-
----
-
-The bundled Pi packages are pinned and update with Feynman, not through `feynman update`. See the [package stack](https://feynman.is/docs/reference/package-stack) and [release notes](https://feynman.is/docs/reference/releases).
-
-### Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
+## Contributing
 
 ```bash
 git clone https://github.com/Companion-Inc/feynman.git
 cd feynman
-nvm use || nvm install
 npm install
 npm test
-npm run typecheck
-npm run build
 ```
 
-[Docs](https://feynman.is/docs) · [Release Notes](RELEASES.md) · [MIT License](LICENSE)
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+[Docs](https://feynman.is/docs) · [Release notes](RELEASES.md) · [MIT License](LICENSE)

package/RELEASES.md

@@ -6,6 +6,18 @@ GitHub release notes are generated from the matching `## vX.Y.Z` section in this
 
 ## Unreleased
 
+## v0.5.10 - 2026-09-27
+
+- **Semantic Scholar understands the documented query syntax.** A `semantic:` prefix and `year_from=`/`year_to=` flags, which the model reuses from the OpenAlex examples, were sent to Semantic Scholar as search text and returned unrelated papers or nothing. They now become Semantic Scholar's own year filter.
+- **The startup header lists only Feynman's workflows.** It also listed prompt commands that pi-subagents ships, such as `/parallel-review` and `/review-loop`.
+- **Cleaner README and landing page** with a current screenshot, and a shorter configuration page.
+
+## v0.5.9 - 2026-09-27
+
+- **Subagents keep their search tools in the foreground.** A `researcher` or `verifier` launched in the foreground failed at once because foreground children never load the parent's extensions, so `web_search`, `fetch_content`, and `feynman_science_database_search` were missing. Feynman now points pi-subagents' `defaultSubagentOnlyExtensions` setting at its research tools and pi-web-access, so every child has them, in the foreground or background.
+- **No alphaXiv account, no alphaXiv search tools.** Without an account, every `alpha_search`, `alpha_get_paper`, `alpha_ask_paper`, and `alpha_read_code` call failed, and research runs retried them. They are now registered only when you are signed in; otherwise papers come from Semantic Scholar, OpenAlex, and the other literature databases. Start a new session after `feynman alpha login`.
+- The Windows install docs now say Feynman needs Bash from Git for Windows for shell commands.
+
 ## v0.5.8 - 2026-09-26
 
 - `FEYNMAN_HOME=~` or `~/path` now means your home folder. Unexpanded `~` (common in `.env` files, Docker `ENV`, and Windows shells) created a literal `~` folder in the current directory.

package/dist/pi/settings.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { BUNDLED_PI_PACKAGES, getFeynmanPackageSources } from "./runtime.js";
+import { BUNDLED_PI_PACKAGES, getFeynmanPackageSources, resolvePackageRoot } from "./runtime.js";
 import { choosePreferredModelRecord, getAvailableModelRecords } from "../model/catalog.js";
 // Written by Feynman <= 0.4.0 next to a subagent extension path it managed.
 const LEGACY_RESEARCHER_EXTENSION_MARKER = "_feynmanResearchToolsExtension";
@@ -150,6 +150,17 @@ function removeLegacyResearcherExtension(settings) {
     else
         delete researcher.subagentOnlyExtensions;
 }
+// Foreground subagents run inside the parent process and never load its
+// extensions, so researcher and verifier lost web and paper search there.
+// pi-subagents loads these paths in every child session; they are rewritten on
+// each launch because the install path changes between versions.
+export function feynmanSubagentExtensions(appRoot) {
+    const webAccess = resolvePackageRoot(appRoot, "pi-web-access");
+    return [join(appRoot, "extensions", "research-tools.ts"), ...(webAccess ? [webAccess] : [])];
+}
+function isFeynmanSubagentExtension(path) {
+    return typeof path === "string" && (/[\\/]extensions[\\/]research-tools\.ts$/.test(path) || /[\\/]pi-web-access$/.test(path));
+}
 export async function ensureFeynmanSettings(settingsPath, bundledSettingsPath, appRoot, defaultThinkingLevel, authPath) {
     // Validate before model discovery or either settings write. Invalid custom
     // configuration must not silently turn into an empty/default configuration.
@@ -173,6 +184,12 @@ export async function ensureFeynmanSettings(settingsPath, bundledSettingsPath, a
     if (isRecord(settings.subagents) && settings.subagents.agentExcludeDirs === undefined) {
         settings.subagents.agentExcludeDirs = ["~/.agents"];
     }
+    if (isRecord(settings.subagents)) {
+        const current = settings.subagents.defaultSubagentOnlyExtensions;
+        if (current === undefined || (Array.isArray(current) && current.every(isFeynmanSubagentExtension))) {
+            settings.subagents.defaultSubagentOnlyExtensions = feynmanSubagentExtensions(appRoot);
+        }
+    }
     if (!settings.defaultProvider || !settings.defaultModel) {
         const preferredModel = choosePreferredModelRecord(await getAvailableModelRecords(authPath));
         if (preferredModel) {

package/extensions/research-tools/alpha.ts

@@ -4,6 +4,7 @@ import {
 	clearPaperAnnotation,
 	disconnect,
 	getPaper,
+	isLoggedIn,
 	listPaperAnnotations,
 	readPaperCode,
 	searchPapers,
@@ -41,14 +42,18 @@ const paperSectionsSchema = Type.Unsafe<string[]>({
 	}),
 });
 
-export function registerAlphaTools(pi: ExtensionAPI): void {
+export function registerAlphaTools(pi: ExtensionAPI, signedIn = isLoggedIn()): void {
 	// The alphaXiv MCP client keeps a connection open; close it so print and
 	// JSON runs can exit once the session ends.
 	pi.on("session_shutdown", async () => {
 		await disconnect();
 	});
+	// Search, paper, Q&A, and code tools need an alphaXiv account. Without one,
+	// every call failed, so leave them out and let the model use the other
+	// paper sources. Annotations are local and stay available.
+	const registerAccountTool: ExtensionAPI["registerTool"] = signedIn ? (tool) => pi.registerTool(tool) : () => {};
 
-	pi.registerTool({
+	registerAccountTool({
 		name: "alpha_search",
 		label: "Alpha Search",
 		description:
@@ -65,7 +70,7 @@ export function registerAlphaTools(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerTool({
+	registerAccountTool({
 		name: "alpha_get_paper",
 		label: "Alpha Get Paper",
 		description:
@@ -96,7 +101,7 @@ export function registerAlphaTools(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerTool({
+	registerAccountTool({
 		name: "alpha_ask_paper",
 		label: "Alpha Ask Paper",
 		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.",
@@ -140,7 +145,7 @@ export function registerAlphaTools(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerTool({
+	registerAccountTool({
 		name: "alpha_read_code",
 		label: "Alpha Read Code",
 		description: "Read files from a paper's GitHub repository. Use '/' for repo overview.",

package/extensions/research-tools/header.ts

@@ -6,6 +6,8 @@ import { resolve as resolvePath } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
+import { readPromptSpecs } from "../../metadata/commands.mjs";
+
 import {
 	APP_ROOT,
 	FEYNMAN_AGENT_LOGO,
@@ -161,9 +163,11 @@ function detectSystemResources(): SystemResources {
 
 type WorkflowInfo = { name: string; description: string };
 
-function getResearchWorkflows(pi: ExtensionAPI): WorkflowInfo[] {
+// Only Feynman's own workflows; other packages (pi-subagents) also ship prompt commands.
+export function getResearchWorkflows(pi: Pick<ExtensionAPI, "getCommands">, appRoot = APP_ROOT): WorkflowInfo[] {
+	const feynmanWorkflows = new Set(readPromptSpecs(appRoot).map((spec) => spec.name));
 	return pi.getCommands()
-		.filter((cmd) => cmd.source === "prompt")
+		.filter((cmd) => cmd.source === "prompt" && feynmanWorkflows.has(cmd.name))
 		.map((cmd) => ({ name: `/${cmd.name}`, description: cmd.description ?? "" }))
 		.sort((a, b) => a.name.localeCompare(b.name));
 }

package/extensions/research-tools/science-databases.ts

@@ -257,12 +257,31 @@ function truncateText(value: string | undefined, maxChars: number): string | und
 	return `${value.slice(0, maxChars).trimEnd()}…`;
 }
 
-function semanticScholarSearchUrl(query: string, limit: number, sort: string): URL {
+// The model reuses the OpenAlex syntax this tool documents (a `semantic:`
+// prefix, year_from=/year_to= flags). Sent as text, it returned junk or zero
+// results; map it to Semantic Scholar's own year filter instead.
+export function parseSemanticScholarQuery(raw: string): { query: string; year?: string } {
+	let from = "";
+	let to = "";
+	const query = raw
+		.replace(/^\s*semantic:\s*/i, "")
+		.replace(/\byear_(from|to)=(\d{4})\b/gi, (_match, kind: string, year: string) => {
+			if (kind.toLowerCase() === "from") from = year;
+			else to = year;
+			return " ";
+		})
+		.replace(/\s+/g, " ")
+		.trim();
+	return from || to ? { query, year: `${from}-${to}` } : { query };
+}
+
+function semanticScholarSearchUrl(query: string, limit: number, sort: string, year?: string): URL {
 	const relevance = sort === "relevance";
 	const url = new URL(`${SEMANTIC_SCHOLAR_BASE}/paper/search${relevance ? "" : "/bulk"}`);
 	url.search = new URLSearchParams({
 		query,
 		fields: SEMANTIC_SCHOLAR_FIELDS,
+		...(year ? { year } : {}),
 		...(relevance ? { limit: String(limit) } : { sort }),
 	}).toString();
 	return url;
@@ -271,10 +290,10 @@ function semanticScholarSearchUrl(query: string, limit: number, sort: string): U
 // Bulk search sorted by citation count surfaces seminal papers that relevance
 // ranking misses; it returns up to 1,000 rows, so only the top `limit` are kept.
 async function searchSemanticScholar(params: ScienceDatabaseSearchParams): Promise<Record<string, unknown>> {
-	const query = cleanQuery(params.query);
+	const { query, year } = parseSemanticScholarQuery(cleanQuery(params.query));
 	const limit = safeLimit(params.limit);
 	let sort = params.sort === "relevance" ? "relevance" : params.sort === "pub_date" ? "publicationDate:desc" : "citationCount:desc";
-	const endpoints = [semanticScholarSearchUrl(query, limit, sort)];
+	const endpoints = [semanticScholarSearchUrl(query, limit, sort, year)];
 	let note: string | undefined;
 	let payload: Record<string, unknown>;
 	try {
@@ -284,7 +303,7 @@ async function searchSemanticScholar(params: ScienceDatabaseSearchParams): Promi
 		const anonymous = !process.env.SEMANTIC_SCHOLAR_API_KEY?.trim();
 		if (sort !== "relevance" || !anonymous || !(error instanceof ScienceDatabaseRequestError) || error.status !== 429) throw error;
 		sort = "citationCount:desc";
-		endpoints.push(semanticScholarSearchUrl(query, limit, sort));
+		endpoints.push(semanticScholarSearchUrl(query, limit, sort, year));
 		note = `Relevance search was rate-limited (HTTP 429) on Semantic Scholar's shared anonymous pool, so these are citation-sorted bulk results. A free SEMANTIC_SCHOLAR_API_KEY avoids this: ${SEMANTIC_SCHOLAR_KEY_URL}`;
 		payload = recordValue(await fetchSemanticScholar(endpoints[1]!));
 	}
@@ -314,6 +333,7 @@ async function searchSemanticScholar(params: ScienceDatabaseSearchParams): Promi
 		schema: "feynman.scienceDatabaseSearch.v1",
 		source: "semanticscholar",
 		query,
+		...(year ? { year } : {}),
 		sort,
 		...(note ? { note } : {}),
 		totalCount: numberValue(payload.total) ?? results.length,

package/package.json

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