Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getcompanion-ai/feynman/llms.txt

Use this file to discover all available pages before exploring further.

Feynman is a research-first CLI built on Pi and alphaXiv. Contributions are welcome across code, prompts, skills, docs, installers, and workflow behavior. This page covers what you need to know before opening a PR.

​
What goes where

PathContents
src/CLI entry point, Pi launch logic, model/search/setup commands, runtime utilities
prompts/Bundled research workflow templates (one .md file per workflow)
skills/Bundled Pi skills (reusable tool-level capabilities)
.feynman/agents/Bundled Pi subagent prompts: researcher, reviewer, writer, verifier
website/Documentation site source
scripts/Build and release scripts
outputs/, papers/, notes/Generated research artifacts — not source files
To change how bundled subagents behave, edit .feynman/agents/*.md. Do not duplicate subagent behavior in AGENTS.md — that file is the repo-level contract for workspace conventions, not per-agent instructions.

​
Before you open a PR

1

Start from latest main

Always branch from an up-to-date main. Do not base PRs on stale or unrelated branches.
2

Use the correct Node version

The repo requires Node.js 20.19.0 or newer. Use .nvmrc to stay aligned:
nvm use || nvm install
The .nvmrc, package.json engines, website/package.json engines, and the runtime version guard must all stay in sync. Do not bump one without checking the others.
3

Install dependencies

npm install
4

Run the required checks

All three must pass before asking for review:
npm test
npm run typecheck
npm run build
5

Validate the docs site if you changed it

cd website
npm install
npm run build
6

Keep the PR focused

Do not mix unrelated cleanup with the real change. Add or update tests when behavior changes. Update docs, prompts, or skills when the user-facing workflow changes.

​
Contribution rules

  • Bug fixes, docs fixes, installer fixes, and focused workflow improvements are good PRs.
  • Large feature changes should start with an issue or implementation discussion before code lands.
  • Avoid refactor-only PRs unless they unblock a real fix or are requested by a maintainer.
  • Do not silently change release behavior, installer behavior, or runtime defaults without documenting the reason in the PR.
  • Use American English in docs, comments, prompts, UI copy, and examples.

​
Prompt and skill changes

New research workflows live in prompts/*.md. New reusable tool-level capabilities live in skills/<name>/SKILL.md.
  • Keep skill files concise. Put detailed operational rules in the prompt or in focused reference files only when needed.
  • If a new workflow should be invokable from the CLI, include the correct frontmatter metadata so the command works through the normal prompt discovery path:
---
description: Short description of what the workflow does.
args: <arg>
section: Research Workflows
topLevelCli: true
---
The topLevelCli: true field makes the workflow available as both a slash command in the REPL and a top-level CLI command (feynman <name>).

​
Agent and artifact conventions

The AGENTS.md file is the repo-level contract for workspace conventions. It covers output locations, file naming, provenance requirements, and handoff rules between the lead agent and subagents. Key conventions from AGENTS.md:
  • Research outputs → outputs/
  • Paper-style drafts → papers/
  • Session logs → notes/
  • Long-running workflow plans → outputs/.plans/<slug>.md
  • The workspace lab notebook → CHANGELOG.md (updated for substantial multi-round work only)
File naming: Every workflow that produces artifacts derives a short slug from the topic (lowercase, hyphens, no filler words, ≤5 words). All files in a single run use that slug as a prefix. Never use generic names like research.md, draft.md, or summary.md. Provenance: Every output from /deepresearch and /lit must include a .provenance.md sidecar recording source accounting and verification status. Delegation: The lead agent plans, delegates to subagents, synthesizes, and delivers. Prefer file-based handoffs over passing large intermediate results back into parent context.

​
Release and versioning discipline

The curl installer and release docs point users at tagged releases, not arbitrary commits on main. When shipping user-visible fixes:
  • Do not leave main and the latest release advertising the same version string with different behavior.
  • When changing release-sensitive behavior, check the version story across:
    • .nvmrc
    • package.json
    • website/package.json
    • scripts/check-node-version.mjs
    • Install docs in README.md and the website installation page

​
AI-assisted contributions

AI-assisted PRs are accepted. The contributor is still responsible for the diff.
  • Understand the code you are submitting.
  • Run the local checks yourself instead of assuming generated code is correct.
  • Include enough context in the PR description for a reviewer to understand the change.
  • If an agent updated prompts or skills, verify the instructions match the actual repo behavior.

​
Review expectations

  • Explain what changed and why.
  • Call out tradeoffs, follow-up work, and anything intentionally not handled.
  • Include screenshots for UI changes.
  • Resolve review comments you addressed before requesting another review pass.

​
Good first areas

The install and upgrade paths cover a lot of Node version and environment surface area. Improving error messages, handling edge cases in the setup wizard, and making feynman doctor more actionable are consistently high-value contributions.
The prompts in prompts/ drive every research workflow. Improvements to planning quality, subagent delegation, verification discipline, citation accuracy, and output structure are welcome. Make sure any prompt change still produces valid outputs end-to-end.
feynman model login, feynman model list, and feynman setup are the primary UX for auth. Improving provider error messages, OAuth flow reliability, and model listing clarity helps users get unblocked faster.
The docs site source lives in website/. Improving accuracy, fixing outdated examples, adding usage context to thin reference pages, and clarifying setup steps are all valuable. Run cd website && npm run build to validate changes.
The /preview command and pandoc dependency path have rough edges on some platforms. Improving the feynman --setup-preview flow, pandoc version handling, and Markdown/LaTeX rendering consistency are practical contributions.
Release scripts, installer reliability, version string consistency, and npm packaging are all areas where incremental improvements compound over time.

Build docs developers (and LLMs) love

Get started for freeTalk to us