Feynman CLI: an AI research agent for literature review, paper ranking and replication checks

The reading backlog problem Feynman targets

Feynman is built for the stage of research that sits between "I have forty candidate papers" and "I know which three to read first." The README frames it as a research-first CLI agent built on Pi and alphaXiv, and the command list backs that framing: `feynman lit` produces a literature review with consensus, disagreements and open questions, `feynman rank` decides what to read first using citation, method, reproducibility and provenance evidence, and `feynman audit` compares a paper's claims against its public codebase. Those are three distinct jobs that normally get done by hand in a reference manager plus a browser with too many tabs.

The intended user is someone who already reads papers and wants a faster first pass, not someone looking for a chatbot that summarizes abstracts. The `--expand-citations`, `--full-text-top` and `--critique-top` flags on `feynman rank` show the design assumption: the user sets how much evidence to gather, and the tool escalates from citation metadata to full text to critique. That is a deliberate cost and latency dial, and it is the most interesting design decision in the command surface.

The scope is narrower than "AI research agent" suggests. There is no team workspace, no shared library, and no hosted multi-user mode described. `feynman serve` opens a local workbench, and `--no-auth` opens it at a plain localhost URL for trusted local testing. The trust boundary is your machine.

How the agent is put together: Pi runtime, skills tree, local workbench

The package metadata describes Feynman as a CLI agent built on Pi and alphaXiv, and the bundled dependencies confirm it: `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` are listed as bundle dependencies alongside `@advaitpaliwal/alpha-hub`. Feynman is therefore a layer on top of an existing agent runtime rather than a from-scratch loop.

The repository layout shows two front ends sharing one core. `src/` holds the CLI logic, `workbench-web/` is a Vite-built web app with `workbench.vite.config.ts` at the root, and `website/` is the public site. `skills/` and `prompts/` are shipped as data, which is why there is a separate skills-only installer that copies those trees without the terminal. `skills-lock.json` pins the skill set.

Observability is wired in rather than bolted on. The bundled pi-otel extension sends `gen_ai.*` spans to PostHog AI Observability, and `.env.example` sets `PI_OTEL_CAPTURE_CONTENT=metadata_only`, meaning prompt and tool payload content is excluded from those spans by default. Telemetry itself is on by default (`FEYNMAN_TELEMETRY=1`) and points at a PostHog project with ID 479027; setting `FEYNMAN_TELEMETRY=off` disables it. That default-on choice is worth knowing about before you point the tool at unpublished drafts or private corpora.

Model access is provider-agnostic. `.env.example` lists keys for OpenAI, Anthropic, Gemini, OpenRouter, ZAI, Kimi, MiniMax, Mistral, Groq, xAI, Cerebras, Hugging Face, OpenCode, an AI gateway and Azure OpenAI, plus RunPod and Modal credentials for compute. Local models are supported through the setup flow, with defaults documented for LM Studio at `http://localhost:1234/v1` and LiteLLM Proxy at `http://localhost:4000/v1`.

Installing Feynman and running a first literature review

The README gives two installation paths. The standalone installer fetches the latest tagged release, downloads a native bundle with its own pinned Node.js runtime, and verifies the release SHA-256 before replacing an existing installation. On macOS or Linux that is a single command.

curl -fsSL https://feynman.is/install | bash

The README notes that to pin a version you pass it explicitly, for example `curl -fsSL https://feynman.is/install | bash -s -- 0.2.35`. Pinning matters here because the project is on a fast v0.3.x release cadence and the installer otherwise tracks the latest tag.

The npm alternative uses your own Node.js runtime instead of the bundled one. The package declares `"node": ">=22.22.0 <26"` in its engines field, so check your version before choosing this route.

npm install -g @advaitpaliwal/feynman

If you installed the older scoped package, the README gives a one-time migration: `npm uninstall -g @companion-ai/feynman` followed by `npm install -g @advaitpaliwal/feynman`. The command name stays `feynman`.

With the binary on your PATH, the first useful run is a literature review. The README's example takes a topic and returns consensus, disagreements and open questions.

feynman lit "RLHF alternatives"

According to the README, when the input names a research group the command switches into a lab/PI corpus mode. If you want a ranked reading list instead of a narrative review, `feynman rank "mechanistic interpretability sparse autoencoders"` scores candidates on citation, method, reproducibility and provenance evidence, and you can widen the evidence base with `--expand-citations 2` to add cited and citing papers to the local citation graph before scoring graph prestige.

One CLI detail the README calls out is worth internalizing early: a prompt starting with a dash is parsed as an option unless you separate it. `feynman -- "- summarize the strongest evidence first"` preserves it, and `feynman --prompt="- summarize the strongest evidence first"` runs it once and exits.

Self-hosted workbench, local models and the headless login gap

`feynman serve` opens the standalone science workbench: projects, Pi chat, Feynman Bio Tools, notebooks, compute, artifact previews, provenance, settings, skills and onboarding context. `feynman serve --no-auth` opens the same workbench at a plain localhost URL for trusted local testing. The README does not describe a remote or multi-user deployment mode, so treat this as a single-user local surface.

Local model support is documented per provider rather than as one generic setting. For LM Studio, run `feynman setup`, choose `LM Studio`, and keep the default `http://localhost:1234/v1` unless you changed the server port. For LiteLLM, choose `LiteLLM Proxy` and keep the default `http://localhost:4000/v1`. For Ollama or vLLM, choose `Custom provider (baseUrl + API key)`, use `openai-completions`, and point it at the local `/v1` endpoint. The `openai-completions` value is a protocol selector, not a model name, and getting it wrong is an easy mistake.

Hosted providers authenticate through `feynman model login <provider>`. OpenRouter login opens an OAuth page and listens for a local callback, which fails over SSH or in another headless environment; the README's workaround is to paste the browser's final redirect URL or authorization code into Feynman's prompt, or to set `OPENROUTER_API_KEY` before launch to use API-key authentication without OAuth. GitHub Copilot sign-in retries model discovery once when GitHub rate-limits the request. There is no documented general-purpose headless login flow beyond these per-provider notes, which is a real friction point for CI or remote boxes.

Compute credentials are separate from model credentials. `RUNPOD_API_KEY`, `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` appear in `.env.example`, and the README describes `feynman replicate` as planning replication checks and running them only after an explicit environment choice. That gate is the right default, but it also means replication is not a one-command operation.

Upgrade paths, telemetry defaults and where Feynman gets in the way

The upgrade story has a trap in it. Rerunning the installer upgrades the standalone app, but `feynman update` only refreshes installed Pi packages inside Feynman's environment; it does not replace the standalone runtime bundle itself. If you assume `feynman update` keeps the whole tool current, you will drift. For npm installs the equivalent is `npm install -g @advaitpaliwal/feynman@latest`.

Uninstalling is documented as a manual cleanup: remove the launcher and runtime bundle, then optionally remove `~/.feynman` to delete settings, workbench app state, sessions and installed package state. If you also want to clear alphaXiv login state, remove `~/.ahub`. The README points to the installation guide for platform-specific paths rather than listing them, so on an unfamiliar platform you are reading the docs before you can fully remove the tool.

Telemetry is the other default worth a decision. `FEYNMAN_TELEMETRY=1` and a PostHog project ID ship in `.env.example`, with `PI_OTEL_CAPTURE_CONTENT=metadata_only` limiting what the Pi/plugin spans carry. Metadata-only is a meaningful mitigation, but if your institution treats any outbound span as a disclosure, set `FEYNMAN_TELEMETRY=off` before first launch rather than after.

Where Feynman is the wrong tool: it is not a reference manager, it does not replace reading, and the README makes no claim about correctness of synthesis. `feynman audit` compares paper claims against a public codebase, so a paper with no public code is out of scope for that command. `feynman paper` resolves "legal full-text access candidates" and fetches source-specific text when available, which is an explicit acknowledgement that full text is frequently unavailable. If your workflow depends on publisher PDFs behind an institutional proxy, expect that path to be partial.

Feynman versus the skills-only install and generic coding agents

The clearest alternative is Feynman's own skills-only installer. `curl -fsSL https://feynman.is/install-skills | bash` installs the skill library into `~/.codex/skills/feynman` for Codex, and the same script takes `--codex`, `--repo` and `--opencode` targets, installing into `.agents/skills/feynman` or `.opencode/skills/feynman` under the current repository. Those 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.

That is a genuine architectural fork, not a packaging detail. Taking the skills route means your existing agent host owns the loop, the model choice and the approval UX, and Feynman contributes research methodology as prompt and skill data. Taking the full install means Feynman owns the loop and adds the workbench, the citation graph, the alphaXiv integration and the provenance views. If you already have a coding agent you trust, the skills route is the smaller commitment and avoids a second runtime on disk.

The other alternative is a general-purpose coding agent with web search pointed at papers. The difference is in the evidence model. Feynman's `rank` command builds a local citation graph and scores graph prestige, and its `--full-text-top` and `--critique-top` flags add section-aware full-text evidence and rubric answers before rescoring. A generic agent will happily summarize an abstract and stop. Whether Feynman's extra evidence layers are worth the runtime cost is something you have to measure on your own corpus; the README does not publish accuracy figures, and this review has not run any.

Licence, maintenance and what the release cadence implies

Feynman is MIT-licensed, with the licence file at the repository root and the `license` field set to MIT in package.json. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and licence text are preserved. That is a general description of the licence, not legal advice for your situation; if you are embedding Feynman in a product, have your own counsel read the actual LICENSE file.

The maintenance signal is straightforward. The repository is not archived, and the last push was on 2026-09-06. Recent tags run v0.3.45, v0.3.46 and v0.3.48, all in August and early September 2026, and package.json on main reads version 0.3.49. That is a tight release cadence on a 0.x line, which usually means interfaces can still move.

Budget for that. The CLI flags documented here are the surface you will script against, and a 0.x project has no compatibility promise. The standalone installer's version pinning exists precisely because tracking the latest tag is the default, so pin a known-good tag in any automation and upgrade deliberately. The npm route makes this easier to control since you choose the version you install. Also budget for the runtime: the standalone bundle carries its own pinned Node.js runtime, so you are adding a Node distribution to the machine, not just a binary.

Editorial conclusion

Adopt Feynman if your work is reading-heavy and you want a terminal tool that produces cited briefs, ranked reading lists and replication plans, and you are comfortable with a fast-moving v0.3.x release line. Do not adopt it if you need a stable long-term interface, a hosted multi-tenant service, or a tool that replaces human judgement on what to read. Before committing, verify two things on your own machine: that the standalone installer's SHA-256 verification and pinned Node runtime work behind your proxy, and that the provider you intend to use is reachable through `feynman model login` or the relevant API key in .env.example.

Frequently asked questions

Official sources

1. Companion-Inc/feynman on GitHub
2. License: MIT
3. Project website
4. README
5. Releases