The Problem
Researchers and engineers need a repeatable way to gather, synthesize, and verify scientific information without manually juggling web searches, paper PDFs, and code audits. The current process is error‑prone, time‑consuming, and hard to automate across projects.
What This Does
feynman is a command‑line AI research agent built on the Pi runtime. The core CLI lives in src/cli.ts and is exported from src/index.ts. It dispatches four built‑in agents—researcher, reviewer, writer, and verifier—that coordinate tasks such as literature search (extensions/research-tools/alpha.ts), code‑base auditing (prompts/audit.md), and multi‑agent synthesis (prompts/deepresearch.md).
The repository ships a curated set of skills (e.g., skills/alpha-research/SKILL.md, skills/docker/SKILL.md) that are synced to ~/.feynman/agent/skills/ on first run (src/bootstrap/sync.ts). Documentation for each workflow is generated from the website/ Astro site, with source Markdown in website/src/content/docs/.
How To Use It
Clone and prepare the development environment git clone https://github.com/getcompanion-ai/feynman.git cd feynman nvm use || nvm install # Node ≥20.18.1 as required by .env.example pnpm install # npm lockfile present; pnpm works because scripts use pnpm Optional – install the pre‑built bundle (production use) curl -fsSL https://feynman.is/install | bash Run the CLI pnpm start -- <command> # entry point src/cli.ts Example from README feynman "what do we know about scaling laws"
Configuration – A template environment file is provided at .env.example. Keys for external services (AlphaXiv, Gemini/Perplexity) must be added before invoking commands that require them (e.g., deepresearch, web-search). The runtime loads settings from src/pi/settings.ts and src/config/paths.ts.
Running a workflow – Use the slash‑style shortcuts documented in website/src/content/docs/workflows/.md. For example:
feynman deepresearch "mechanistic interpretability"
The command triggers the researcher and reviewer agents, then synthesizes a citation‑rich brief.
Real‑World Use
A data‑science team can embed a nightly literature‑review step in their CI pipeline:
.github/workflows/lit-review.yml name: Nightly Literature Review on: schedule: [cron: '0 2 '] jobs: review: runs-on: ubuntu-latest steps: uses: actions/checkout@v3 run: curl -fsSL https://feynman.is/install | bash run: feynman lit "large language model interpretability" uses: actions/upload-artifact@v3 with: name: review-output path: ~/.feynman/outputs/.md
The generated markdown can be archived or posted to a documentation site automatically.
Code Health & Issues
Low – Missing API key handling – External services are required but no fallback or validation appears in src/pi/web-access.ts; missing keys will cause runtime failures. Medium – Limited test coverage – 7 test files exist (tests/.test.ts), but core agent orchestration (src/pi/launch.ts) lacks direct unit tests. Low – No root‑level lint config – Only the website folder contains eslint.config.js; the main TypeScript code relies on default tsconfig rules, which may miss style inconsistencies. Low – No Dockerfile – Although a Docker skill is provided (skills/docker/SKILL.md), the repo does not ship a container definition for the CLI itself, requiring users to build their own if needed. Low – License present – LICENSE is MIT, satisfying legal requirements. Low – CI present – GitHub Actions workflow (.github/workflows/publish.yml) runs on push; however, it only publishes, not test, indicating a missing test‑run step in CI.
Overall, the codebase compiles cleanly, uses TypeScript typings (metadata/commands.d.mts), and includes documentation generated from source Markdown, indicating reasonable maintenance discipline.
The Bottom Line
feynman delivers a usable, extensible CLI for AI‑assisted research, with clear documentation and a modular skill system. It is well‑suited for teams that can provide required API keys and are comfortable with a Node.js environment. The primary gaps are sparse test coverage of core orchestration and the absence of built‑in containerization, which may require additional effort for production hardening.