Feynman CLI
Feynman — a terminal AI agent for scientific research: literature reviews, source checks, paper critique and comparing a paper with its code
- 10,011 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent writes files to `outputs/` and `papers/` and reaches about ten scientific databases and the web, while `/replicate` and `/autoresearch` run code once you pick an environment
- The installer runs through curl and bash, and the keys for the model provider, Modal and RunPod are read from the environment
- Telemetry is sent by default and includes error messages with stacks, although prompts and model output are not part of it
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/feynmanDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent writes files to `outputs/` and `papers/` and reaches about ten scientific databases and the web, while `/replicate` and `/autoresearch` run code once you pick an environment
- The installer runs through curl and bash, and the keys for the model provider, Modal and RunPod are read from the environment
- Telemetry is sent by default and includes error messages with stacks, although prompts and model output are not part of it
This is third-party code. Review the repository files before installing.
What it does
Feynman is a terminal agent that researches a question or a paper and saves the result in the project folder. It runs on the open-source Pi agent and installs as an npm package. After `feynman setup` you sign in to a model provider's account, then run a command with a topic, for example `feynman lit "RLHF alternatives"`. In interactive mode the same workflows are available as slash commands. There are ten commands: `/deepresearch` keeps a plan and checks citations, `/lit` assembles a literature review with consensus and disputed points, `/review` critiques a paper by severity, `/audit` compares a paper's claims with its public code, `/replicate` plans a replication, `/recipe` picks model training recipes, `/compare` builds a source comparison matrix, `/draft` writes a paper-style draft, `/autoresearch` runs a bounded experiment loop and `/summarize` condenses a source. Search covers alphaXiv, Semantic Scholar, OpenAlex, arXiv, PubMed, Europe PMC, bioRxiv, medRxiv, Crossref, the web and Hugging Face, and the agent reads local PDFs and documents itself. Four agents take part: a researcher, a source verifier, a reviewer and a writer. For a narrow question `/deepresearch` searches on its own in 3–10 calls, and for a broad topic it brings in two to six researchers. The verifier then opens every link, and the reviewer marks findings FATAL, MAJOR or MINOR. The finished report lands in `outputs/` or `papers/`, with a provenance file beside it: which sources were used, which were dropped and how verification ended.
Who it is for. For graduate students, researchers and engineers who learn a new topic from papers, review other people's work and check whether a repository's code matches what its paper claims.
Good fit when
- You need a literature review on a topic or a lab: where authors agree, where they dispute and which questions stay open
- Before submitting to a journal you want a review of a draft with severity levels and a revision plan
- You need to check whether a paper's public code does what the paper claims: `/audit` looks for mismatches, omissions and reproduction risks
- You want a reference report where every claim has a citation and a file next to it lists the accepted and rejected sources
- A paper has to be replicated: `/replicate` writes a plan and runs it only after you pick an execution environment
Not a fit when
- You need a skill inside Claude Code: Feynman runs as a separate agent, and the skills-only bundle in the repository is built for Codex and OpenCode
- The machine has no Node.js 22.22 or newer and you cannot install it: the npm package refuses to install
- You only need one MCP server for reading arXiv inside your own agent: arxiv-mcp-server covers that
- You need business or market research: the built-in database search targets scientific papers, preprints and their code
Example request
Do a literature review of RLHF alternatives from the last two years, mark where authors disagree and save a report with citationsLimitations
- MIT license. A model is required: Feynman does not include one, and you supply the key or provider sign-in yourself. The `OPENALEX_API_KEY` and `SEMANTIC_SCHOLAR_API_KEY` keys are free, but without them the shared search limits are lower, and `NCBI_API_KEY` raises the PubMed request limit from 3 to 10 per second.
- PostHog telemetry is on by default: commands, workflows, tools, models, token counts and errors with their message and stack, with the home folder shown as `~`. Prompts, model output, paper content and tool arguments are not sent. `FEYNMAN_TELEMETRY=off` turns it off.
- `/replicate` and `/autoresearch` execute code. The agent asks for the environment (local, virtual environment, Docker, Modal or RunPod) before running, and Modal and RunPod need their own accounts and keys. The experiment loop is limited to 20 iterations by default.
- The skills bundle from `scripts/install/install-skills.sh` installs sixteen skills and the command texts. The skills themselves are short: they invoke Feynman workflows and do not replace the agent.
- The repository holds evaluation results for literature reviews from September 23 and 24, 2026 for several models. These are the author's measurements, not a guarantee of quality on your topic, and each conclusion is worth rechecking against the links.
How to disable. Remove the package with `npm uninstall -g @companion-ai/feynman`. If you installed the agent with the script, the uninstall steps are in the installation guide on the project site. The skills bundle sits in a `skills/feynman` folder inside `$CODEX_HOME`, `.agents/skills` or `.opencode/skills`, and you remove it by deleting that folder. Reports stay in your project's `outputs/` and `papers/` folders.
FAQ
How do I install Feynman and where do I start?
On macOS and Linux run `curl -fsSL https://feynman.is/install | bash`, on Windows `irm https://feynman.is/install.ps1 | iex`, or install the package with `npm install -g @companion-ai/feynman` on Node.js 22.22 or newer. Then `feynman setup` connects a model provider. A good first run is `feynman "what do we know about scaling laws"`.
How is `/deepresearch` different from `/lit`?
`/deepresearch` keeps a plan, splits questions among researchers, checks links and saves a report with a provenance file. `/lit` assembles a literature review for a topic or a lab and highlights consensus, disagreements and open questions. Both commands write the sources file, and so does `/recipe`.
How does Feynman check that the links in a report are real?
The verifier agent opens every link and checks that the page supports the exact figure or conclusion it is attached to. It removes unsupported claims or turns them into a to-do note. If verification does not finish, the report gets the status BLOCKED or PASS WITH NOTES and a list of missing checks.
Can I install only the Feynman skills for Codex or OpenCode?
Yes, `scripts/install/install-skills.sh` downloads a release archive and copies the skills with the command texts. The `--codex` flag puts them in `$CODEX_HOME/skills/feynman`, `--repo` in the project's `.agents/skills/feynman`, `--opencode` in `.opencode/skills/feynman`. The script first deletes the target folder and recreates it.
Which sources does Feynman read besides the web?
It searches scientific databases: alphaXiv, Semantic Scholar, OpenAlex, arXiv, PubMed, Europe PMC, bioRxiv, medRxiv and Crossref, plus Hugging Face. It also reads local PDFs and documents from the project folder. You can add free OpenAlex and Semantic Scholar keys so you do not share the common limits.
What does `/replicate` do and when does it run code?
The command pulls the method, datasets, metrics and compute details from the paper and its linked code, and marks what it could not check as `unverified`. It then writes a replication plan and asks where to run it. Nothing runs until you answer.
Discussion
No questions or reviews yet.
Related
CLI toolsAn autonomous research assistant: from idea and plan through experiments and analysis to a paper, relying only on real results
ARIS
ARIS (Auto-Research-In-Sleep)
A skill set for autonomous machine learning research: literature review, idea discovery, experiments and paper writing with review by a separate model
A skill set that runs a research repository from its README within bounds and keeps verifiable evidence, without rewriting the original README
Awesome Autoresearch
awesome-autoresearch
A collection of autonomous self-improvement loops and research agents that set hypotheses and test them themselves
A multi-agent harness that verifies results by artifacts: stop hooks, an independent judge and an event log for Claude Code, Codex, Cursor and more
A team of AI agents from one request: it plans the task, writes code in parallel branches, tests, reviews and opens a pull request
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Feynman (this entry) | yes | 10,011 | ||
| GPT Researcher | no | 30,228 | researches from any sources and installs as a Python package or Docker, while Feynman targets scientific databases and paper checks | |
| arxiv-mcp-server | no | not required | 3,228 | a local MCP server for arXiv only inside your own agent, does not run as an agent of its own |
| Deep Research | no | 1,198 | a Claude Code skill with Markdown, HTML and PDF reports, does not install an agent of its own |
README in short
The repository holds the agent's TypeScript source, four agent definitions, ten workflow texts, sixteen skills and an extension that searches scientific databases. There are tests, build and package checks with a size limit, npm publication provenance checks and a folder of evaluations: questions and run results for several models. Installer scripts for macOS, Linux and Windows are included, and the documentation lives on the project site.