The Problem

Developers and researchers need a repeatable, source‑grounded way to turn a natural‑language query into a structured research artefact (literature review, audit, replication plan, etc.). Manual searching, note‑taking and synthesis are fragmented and error‑prone, especially when the output must stay linked to original papers or code.

What This Does

feynman is a CLI‑driven AI research agent built on the Pi runtime. The core commands live under src/ (src/cli.ts, src/index.ts) and invoke a set of reusable Pi skills stored in .feynman/ and the skills/ directory. The web front‑end in website/ renders generated artefacts, while extensions/research-tools/ provides command‑specific helpers (e.g., header.ts, project.ts).

Key entry points:

  • src/cli.ts – parses sub‑commands (deepresearch, lit, audit, …) and dispatches to handlers such as handleAlphaCommand and handleModelCommand.
  • src/index.ts – exports a run function used by the bundled binary bin/feynman.js.

The CLI ultimately calls UI helpers in src/ui/terminal.ts (printing, colour handling) and model‑resolution logic in src/model/commands.ts and src/model/catalog.ts. All network or filesystem interactions are confined to the “setup/doctor”, “pi/web‑access”, and “system/executables” modules.

How It Is Wired

Execution starts at src/cli.ts:278 (main). main reaches 87 functions, the largest blast‑radius hub is src/cli (instability 0.92, imports 12 other modules). From main the flow is:

  1. Command parsing → calls a handler (handleAlphaCommand, handleModelCommand, handleSearchCommand, etc.).
  2. Handlers invoke model resolution (src/model/commands.ts → resolveAvailableModelSpec, selectOAuthProvider).
  3. UI output is funneled through src/ui/terminal.ts (printInfo, paint, rgb). printInfo is the most‑referenced function (12 callers).
  4. For web or repo access, src/pi/web-access.ts provides loadPiWebAccessConfig and formatRouteLabel.
  5. System binaries are located by src/system/executables.ts: resolveExecutable, called from four places.

The internal call graph shows 250 intra‑repo edges; no circular dependencies were detected. High‑instability modules (src/setup/setup, src/model/commands) import many utilities but are only imported by one other module, so changes there cascade widely. Low‑instability hubs (src/pi/web-access, src/system/executables) are pure providers with no outgoing imports.

How To Use It

# Clone the repo (use the exact URL)
git clone https://github.com/moses-y/feynman
cd feynman

# Install dependencies (npm works; the repo also supports pnpm)
npm ci

# Optional: copy example env (currently unused but present)
cp .env.example .env

# Run the CLI directly
node bin/feynman.js deepresearch "mechanistic interpretability"
# or via the TypeScript entry point
npx ts-node src/cli.ts lit "RLHF alternatives"

The binary reads skill definitions from ~/.feynman/agent/skills/ on first run; the install‑skills scripts referenced in the README are wrappers around the same logic.

Real‑World Use

A data‑science team wants a quick brief on recent RLHF literature. They run:

feynman lit "RLHF alternatives"

The CLI resolves the model (src/model/commands.ts), queries AlphaXiv via the Pi skill, formats the result with src/ui/terminal.ts, and writes a markdown artefact into outputs/. The artefact contains citations linked back to the original papers, ready for internal review.

Code Health & Issues

  • MEDIUM – Enable Dependabot or Renovate – no automated dependency updates (.github/dependabot.yml missing).
  • MEDIUM – Add dependency‑vulnerability scan to CI – no scan step in .github/workflows.
  • MEDIUM – Set persist-credentials: false on checkout – token persists in CI steps (publish.yml).
  • MEDIUM – Review install lifecycle script – preinstall script present; could run untrusted code.
  • LOW – Add timeout-minutes to workflow jobs – jobs may run up to six hours.
  • LOW – Add repository convention files – missing .editorconfig, .gitattributes, formatter config.

Tests exist (tests/), CI runs via GitHub Actions, a LICENSE is present, and the lockfile is committed. No secrets were detected.

The Bottom Line

feynman delivers a functional, modular CLI for AI‑augmented research with a clear separation of concerns (command parsing, model handling, UI output). The codebase is healthy overall but suffers from duplicated logic, deep nesting in a few extension files, and lacks automated dependency hygiene. It is suitable for teams that need an extensible research automation layer and are comfortable managing the identified maintenance gaps.