Feynman

feynman is a research-first CLI built on @mariozechner/pi-coding-agent.

It keeps the useful parts of a coding agent:

• file access
• shell execution
• persistent sessions
• custom extensions

But it biases the runtime toward general research work:

• literature review
• source discovery and paper lookup
• source comparison
• research memo writing
• paper and report drafting
• session recall and durable research memory
• recurring and deferred research jobs
• replication planning when relevant

The primary paper backend is @companion-ai/alpha-hub and your alphaXiv account. The rest of the workflow is augmented through a curated .pi/settings.json package stack.

Install

npm install -g @companion-ai/feynman

Then authenticate alphaXiv and start the CLI:

feynman setup
feynman

For local development:

cd /Users/advaitpaliwal/Companion/Code/feynman
npm install
cp .env.example .env
npm run start

Feynman uses Pi under the hood, but the user-facing entrypoint is feynman, not pi. When you run feynman, it launches the real Pi interactive TUI with Feynman's research extensions, prompt templates, package stack, memory snapshot, and branded defaults preloaded.

Most users should not need slash commands. The intended default is:

• ask naturally
• let Feynman route into the right workflow
• use slash commands only as explicit shortcuts or overrides

Commands

Inside the REPL:

• /help shows local commands
• /init bootstraps AGENTS.md and notes/session-logs/
• /alpha-login signs in to alphaXiv
• /alpha-status checks alphaXiv auth
• /new starts a new persisted session
• /exit quits
• /deepresearch <topic> runs a thorough source-heavy investigation workflow
• /lit <topic> expands the literature-review prompt template
• /review <artifact> simulates a peer review for an AI research artifact
• /audit <item> expands the paper/code audit prompt template
• /replicate <paper or claim> expands the replication prompt template
• /draft <topic> expands the paper-style writing prompt template
• /compare <topic> expands the source comparison prompt template
• /autoresearch <idea> expands the autonomous experiment loop
• /watch <topic> schedules or prepares a recurring research watch
• /log writes a durable session log to notes/
• /jobs inspects active background work

Package-powered workflows inside the REPL:

• /agents opens the subagent and chain manager
• /run and /parallel delegate work to subagents when you want explicit decomposition
• /ps opens the background process panel
• /schedule-prompt manages recurring and deferred jobs
• /search opens indexed session search
• /preview previews generated artifacts in the terminal, browser, or PDF

Outside the REPL:

• feynman setup runs the guided setup for model auth, alpha login, Pi web access, and preview deps
• feynman model login <provider> logs into a Pi OAuth model provider from the outer Feynman CLI
• feynman --alpha-login signs in to alphaXiv
• feynman --alpha-status checks alphaXiv auth
• feynman --doctor checks models, auth, preview dependencies, and branded settings
• feynman --setup-preview installs pandoc automatically on macOS/Homebrew systems when preview support is missing

Web Search Routing

Feynman v1 keeps web access simple: it uses the bundled pi-web-access package directly instead of maintaining a second Feynman-owned provider layer.

The Pi web stack underneath supports three runtime routes:

• auto — prefer Perplexity when configured, otherwise fall back to Gemini
• perplexity — force Perplexity Sonar
• gemini — force Gemini

By default, the expected path is zero-config Gemini Browser via a signed-in Chromium profile. Advanced users can edit ~/.pi/web-search.json directly if they want Gemini API keys, Perplexity keys, or a different route.

Useful commands:

• feynman search status — show the active Pi web-access route and config path

Custom Tools

The starter extension adds:

• alpha_search for alphaXiv-backed paper discovery
• alpha_get_paper for fetching paper reports or raw text
• alpha_ask_paper for targeted paper Q&A
• alpha_annotate_paper for persistent local notes
• alpha_list_annotations for recall across sessions
• alpha_read_code for reading a paper repository
• session_search for recovering prior Feynman work from stored transcripts
• preview_file for browser/PDF review of generated artifacts

Feynman also ships bundled research subagents in .pi/agents/:

• researcher for evidence gathering
• reviewer for peer-review style criticism
• writer for polished memo and draft writing
• citation for inline citations and source verification

Feynman uses @companion-ai/alpha-hub directly in-process rather than shelling out to the CLI.

Curated Pi Stack

Feynman loads a lean research stack from .pi/settings.json:

• pi-subagents for parallel literature gathering and decomposition
• pi-btw for fast side-thread /btw conversations without interrupting the main run
• pi-docparser for PDFs, Office docs, spreadsheets, and images
• pi-web-access for broader web, GitHub, PDF, and media access
• pi-markdown-preview for polished Markdown and LaTeX-heavy research writeups
• @walterra/pi-charts for charts and quantitative visualizations
• pi-generative-ui for interactive HTML-style widgets
• pi-mermaid for diagrams in the TUI
• @aliou/pi-processes for long-running experiments and log tails
• pi-zotero for citation-library workflows
• @kaiserlich-dev/pi-session-search for indexed session recall and summarize/resume UI
• pi-schedule-prompt for recurring and deferred research jobs
• @samfp/pi-memory for automatic preference/correction memory across sessions

The default expectation is source-grounded outputs with explicit Sources sections containing direct URLs and durable artifacts written to outputs/, notes/, experiments/, or papers/.

Layout

feynman/
├── .pi/agents/   # Bundled research subagents and chains
├── extensions/   # Custom research tools
├── papers/       # Polished paper-style drafts and writeups
├── prompts/      # Slash-style prompt templates
└── src/          # Branded launcher around the embedded Pi TUI