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
• skills
• 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, skills, prompts, 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
• /lit <topic> expands the literature-review prompt template
• /related <topic> builds the related-work and justification view
• /review <artifact> simulates a peer review for an AI research artifact
• /ablate <artifact> designs the minimum convincing ablation set
• /rebuttal <artifact> drafts a rebuttal and revision matrix
• /replicate <paper or claim> expands the replication prompt template
• /reading <topic> expands the reading-list prompt template
• /memo <topic> expands the general research memo prompt template
• /deepresearch <topic> runs a thorough source-heavy investigation workflow
• /autoresearch <idea> expands the end-to-end idea-to-paper prompt template
• /compare <topic> expands the source comparison prompt template
• /audit <item> expands the paper/code audit prompt template
• /draft <topic> expands the paper-style writing prompt template
• /log writes a durable session log to notes/
• /watch <topic> schedules or prepares a recurring research watch
• /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 full guided setup for model auth, alpha login, Pi web, 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 now treats web search as a small provider subsystem instead of a one-off prompt. The current 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

Feynman exposes those through four user-facing choices in feynman setup web, but defaults to Pi web through Gemini Browser when nothing explicit is configured:

• Auto
• Perplexity API
• Gemini API
• Gemini Browser

Gemini Browser is still the same Pi web-access path under the hood: it forces the Gemini route and expects a signed-in Chromium profile rather than an API key.

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
• verifier for claim and source checking
• reviewer for peer-review style criticism
• writer for polished memo and draft writing
• review chain for gather → verify → peer review
• auto chain for plan → gather → verify → draft

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-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
├── skills/       # Research workflows
└── src/          # Branded launcher around the embedded Pi TUI