feynman

The open source AI research agent.

Installation

macOS / Linux:

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

Windows (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):

npm install -g @companion-ai/feynman

If you installed the interim @advaitpaliwal/feynman package, migrate once:

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: "agent_servers": { "Feynman": { "command": "npx", "args": ["-y", "pi-acp"], "env": { "PI_ACP_PI_COMMAND": "feynman" } } }. See the installation guide for uninstalling and the setup guide 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:

macOS / Linux:

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

Windows (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:

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

& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope Codex     # or -Scope Repo, -Scope OpenCode

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.

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

Skills & Tools

• alphaXiv — 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) and optionally SEMANTIC_SCHOLAR_API_KEY (request one) to use your own rate limits
• Hugging Face Hub — 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; Exa works without a key, and feynman search set configures Perplexity, Exa, or Gemini
• Documents — local PDF and office-document parsing through pi-docparser
• Compute — Docker, plus Modal or RunPod when their CLIs are installed, for replication and experiment runs you explicitly approve

How it works

Feynman runs on stock Pi (@earendil-works/pi-coding-agent). Its prompts, skills, agents, and research tools load as a Pi package alongside the bundled pi-subagents, pi-web-access, pi-docparser, and pi-btw packages. Paper search and analysis use alphaXiv. 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 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.

Star History

The bundled Pi packages are pinned and update with Feynman, not through feynman update. See the package stack and release notes.

Contributing

See CONTRIBUTING.md for the full contributor guide.

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 · Release Notes · MIT License