Guide · Open source

How to use Feynman: install, run research workflows and save sources

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Feynman is an open source, MIT-licensed command-line tool that runs an AI research agent. You give it a topic or a paper, and it searches academic sources and produces outputs such as literature reviews, critiques and drafts. This guide shows you how to install it, sign in to a model provider, run the main workflows and find the saved results and source list.

FeynmanCompanion-Inc/feynman · ★ 10.1k · MIT Install options & downloads

Quick start

1Install Feynman. Run the install script for your operating system, or install with npm if you have Node.js 22.22 or newer.
2Sign in to a model provider. Run feynman setup and follow the prompts to connect a model provider account.
3Run a literature review. Start with feynman lit followed by a topic in quotes.
4Open the outputs folder. Find your results in outputs/ and drafts in papers/.
5Check the provenance file. Read the provenance file listing the sources used and what was verified before you rely on any citation.
6Decide on telemetry. Set FEYNMAN_TELEMETRY=off if you do not want anonymous usage data sent.

Install Feynman with npm or the install script

On macOS or Linux, the README gives a one-line install script. On Windows, it gives a PowerShell command. If you prefer npm, you need Node.js 22.22 or newer.

macOS / Linux: run the install script from feynman.is
Windows: run the PowerShell install command from feynman.is
npm route: requires Node.js 22.22 or newer

npm install -g @companion-ai/feynman

Feynman needs a model provider account. After installing, run the setup command and follow the sign-in steps. The setup guide in the docs covers local models and editors such as Zed.

feynman setup

Run your first research query

You can pass a topic directly to feynman, or use a named subcommand such as lit for a literature review or deepresearch for a planned investigation. Plain quoted text works as a general query.

feynman "topic" runs a general query
feynman lit "topic" runs a literature review
feynman deepresearch "topic" runs a planned investigation with parallel researchers and citation checks

feynman "what do we know about scaling laws"
feynman lit "RLHF alternatives"
feynman deepresearch "mechanistic interpretability"

Choose the right workflow for your task

Feynman has workflows for different research jobs. Use the slash-command names inside the tool, as listed in the README.

/lit <topic or lab>: literature review covering consensus, disagreements and open questions
/review <paper or draft>: critique with severity levels and a revision plan
/audit <paper>: compares paper claims with its public code
/replicate <paper>: replication plan that 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 against a benchmark
/summarize <source>: summary of a paper, repository or PDF

Find your saved results and provenance file

Feynman saves results to an outputs folder, and drafts go to a papers folder. The /lit, /deepresearch and /recipe workflows also write a provenance file that lists the sources used and what was verified. Check this file before relying on any citation.

Results: outputs/
Drafts: papers/
Provenance file: written by /lit, /deepresearch and /recipe

Turn off telemetry if you do not want usage data sent

Telemetry is on by default. Feynman sends anonymous usage data to PostHog, including commands, workflows, tools, models, token counts, and errors with messages and stack traces. The README states it never sends prompts, model output, paper content, or tool arguments. Set the environment variable to turn it off.

FEYNMAN_TELEMETRY=off

What people use it for

A student starting a literature review on an unfamiliar topic with /lit
A researcher getting a first pass at related work and open questions
Checking a paper's claims against its public code with /audit
Summarizing a local PDF or paper with /summarize
Building a source comparison matrix with /compare

Frequently asked questions

Is Feynman free to use?

Feynman is released under the MIT licence, as stated in the README. The README also mentions free API keys for OpenAlex and Semantic Scholar that avoid shared rate limits. You still need an account with a model provider for feynman setup.

What do I need to install Feynman?

For the npm route, you need Node.js 22.22 or newer. You also need a model provider account to complete feynman setup. The install script for macOS, Linux and Windows is listed in the README.

How do I install Feynman?

Run the install script from feynman.is on macOS or Linux, or the PowerShell command on Windows. You can also run npm install -g @companion-ai/feynman with Node.js 22.22 or newer, then run feynman setup.

Are the citations from Feynman accurate?

The README describes verification steps but does not promise correctness. Check the provenance file and the original papers before using any citation. Treat the output as a first pass.

Does Feynman send my data anywhere?

Feynman sends anonymous usage data to PostHog by default, including commands, errors and token counts. The README says it does not send prompts, model output, paper content or tool arguments. Set FEYNMAN_TELEMETRY=off to disable it.

How does Feynman compare to Elicit, Semantic Scholar or Perplexity?

Feynman is a command-line agent that saves source-linked outputs and a provenance file. Elicit, Semantic Scholar and Perplexity are listed as comparable projects in the directory. Pick based on whether you want a terminal workflow with saved files or a hosted research interface.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Feynman suits people comfortable with terminal tools who want saved, source-linked research notes and a first pass at related work. It is a poor fit if you need a graphical app, guaranteed-accurate citations without checking, or no telemetry by default.

Install options & downloads