The Layer Beneath the Conversation
In Feynman, the key architectural question is not how to make a chat window sound like a researcher. It is how to place research-specific control around an existing agent runtime without losing the runtime’s flexibility or the research run’s traceability. Feynman answers by wrapping Pi: Feynman owns the research-facing entry point, prompts, extensions, workspace conventions, and safeguards, while Pi supplies the underlying session and model machinery. Understanding that boundary lets a reader trace a command into a real research session and see where consistency comes from—and where dependency complexity begins.
Why build on Pi?
A research agent needs capabilities that are not themselves a model response. It needs a session that can be resumed, tools that can reach different kinds of sources, prompts that define workflow behavior, a place to store outputs, and a way to select or constrain models. It also needs failure handling: missing runtime files, unavailable providers, malformed inputs, and unfinished work should stop or degrade visibly rather than disappear inside a paragraph.
Feynman could have attempted to implement all of that as one monolithic application. The repository instead treats Pi as the agent runtime and adds a research-oriented layer around it. This is a consequential choice. The benefit is leverage: Feynman can use Pi’s session model, provider and model plumbing, package loader, RPC path, and agent loop while concentrating its own code on research tools and workflows. The cost is hidden coupling. A change in the runtime’s package model, session format, extension interface, or provider behavior can affect Feynman even when Feynman’s research code has not changed.
The repository makes the relationship explicit rather than presenting Pi as an invisible implementation detail. Its documentation describes Feynman as built on Pi and says that runtime resources follow Pi’s documented package, extension, and skill models. The public package stack then adds curated research packages and a bundled research extension on top. This is composition, not replacement: Feynman’s identity is expressed through what it injects into the runtime and what it requires the runtime to preserve.
That approach also gives the research boundary a useful shape. A model provider can change without redefining what a research run is. A source tool can be added without rewriting the session engine. Conversely, the existence of a stable runtime does not automatically give a run evidentiary quality. The wrapper can arrange the conditions for a disciplined investigation; it cannot make a poor source authoritative or make a model follow a workflow perfectly.
From command to controlled session
The path from a user command to a Pi session is a sequence of ownership decisions. Feynman’s top-level process first establishes its own operating conditions. It checks the supported Node environment, loads a working-directory environment file when present, ensures its home area exists, and synchronizes bundled assets. It then parses the command line and resolves the working directory and session directory that will govern file operations and persistence.
That early stage matters because a research workflow is only reproducible relative to a defined place and state. The working directory determines where the research artifacts live. The session directory determines where conversational history and resumable sessions are kept. Feynman’s settings and authentication paths are resolved separately from those locations, allowing the runtime to find model and package configuration without treating the project’s output directory as a credential store.
Before launch, Feynman normalizes its settings against bundled defaults and reconciles managed core package installations. It resolves the selected model, thinking level, execution mode, and any initial prompt. A workflow command is converted into a workflow-shaped prompt rather than treated as an arbitrary shell subcommand: a command such as a deep-research invocation becomes an initial research instruction for the Pi session. In an interactive setting, Feynman can also decide whether setup is needed when no valid current model is configured.
The handoff to Pi is explicit. Feynman passes the session directory, its research extension, its prompt-template directory, and its system prompt. It may also pass a text, JSON, or RPC mode, a model specification, a session identifier, a thinking level, a request to continue a recent session, or a one-shot or initial prompt. The Pi process receives a complete launch context instead of having to discover Feynman’s conventions indirectly.
The launch path performs preflight before it starts the child process. It checks for the Pi command-line entry and main module. It checks for the Feynman wrapper and Promise polyfill, permitting a source-mode fallback only when the corresponding development assets are present. It resolves external executables used by the broader environment, prepares the standard research workspace folders, and creates a Feynman command shim so tools inside the child session can invoke the same CLI boundary.
The final handoff is an environment boundary. The child receives paths for the session directory, memory area, web-search configuration, Feynman executable, Pi executable, research package workspace, and agent configuration. It receives the selected browser, Mermaid, and document-rendering paths when available. It also receives Feynman’s telemetry routing decisions and package-manager prefix. The point is not to expose every variable to the reader; it is to understand that Feynman makes the runtime’s dependencies explicit and scoped before the research loop begins.
Notice what this arrangement prevents. The Pi child does not need to guess which prompt set, extension directory, package workspace, or session store belongs to the invocation. Nor does the parent process have to pretend that a successful child launch means research is complete. The handoff establishes a place and a set of resources; the workflow that runs inside that place must still gather evidence and produce the right artifacts. This is a clean separation of runtime readiness from research sufficiency. It also gives failures a location. A missing module is a launch failure, an unavailable source is an evidence failure, and an unperformed check is a verification gap. They may all surface during one conversation, but they should not receive the same diagnosis.
This sequence explains why Feynman’s research behavior is not reducible to the text that appears in the terminal. The visible answer is the last message in a process that has already selected a workspace, loaded prompts and extensions, chosen a runtime, and established a persistence boundary. If any of those preparations fail, the system has a chance to report the failure before a misleading research narrative is produced.
Ownership is an interface, not a slogan
The most useful way to divide responsibility is to ask what crosses the boundary. Feynman sends Pi a launch context: paths, prompts, extensions, system instructions, model controls, and session controls. Pi returns the behavior of the agent loop: it runs the session, loads the supplied resources, calls tools, and persists the conversation through its runtime mechanisms. Feynman’s research extension then gives that loop domain-specific capabilities, including AlphaXiv operations, Hugging Face inspection, discovery commands, model and service-tier controls, science-database connectors, and workbench context.
This division leaves Feynman with three kinds of ownership.
The first is research semantics. The workflow prompts determine what “deep research,” literature review, ranking, review, audit, recipe extraction, or replication means at the user-facing level. The second is research state around the runtime. Feynman defines artifact locations, run-oriented outputs, and later workbench records that connect sessions to files and checks. The third is research guardrails. Access plans, verification statuses, bounded evidence packets, privacy-oriented telemetry, and plugin validation constrain what the surrounding product treats as a completed result.
Pi remains essential because these semantics need somewhere to execute. But it should not be mistaken for the source of every Feynman guarantee. A Pi session can be running while a research claim remains unverified. A loaded extension can provide a search tool while the search result remains incomplete. A model can receive a workflow prompt while still producing a response that does not satisfy the workflow’s artifact contract. The composition works only when the boundary between “the runtime executed” and “the research result is supported” stays visible.
The plugin manifest reinforces that distinction. A plugin does not simply announce a collection of arbitrary features. It declares the research jobs it serves and attaches resources to bounded slots such as source adapters, access resolvers, entity extractors, rank scorers, experiment runners, artifact exporters, visualizers, subagents, or MCP servers. It may declare Pi resources and required environment variables as well. Validation rejects unsafe package names, absolute or escaping paths, unsupported research jobs, unknown slots, and malformed environment-variable names.
That is a useful perimeter because it makes an extension answer a prior question: which research job does this capability support? It does not make the plugin’s substantive behavior trustworthy. A path-safe experiment runner could still implement a flawed experiment. A valid source adapter could still return partial evidence. The validator governs shape, scope, and placement; it does not replace review of the logic inside the extension.
Reliability is a package-system problem
Once Feynman is understood as a wrapper, its reliability story becomes more concrete. The product is not one isolated executable with no moving parts. It is a coordinated runtime train: Pi, research packages, web access, subagents, document parsing, scientific viewers, telemetry, and Feynman-owned extensions. The package metadata pins important runtime versions, declares a supported Node range, and exposes build, test, typecheck, and architecture checks. The release documentation describes updates as a coordinated set and distinguishes updating installed Pi packages from upgrading the standalone Feynman runtime.
This discipline addresses a real failure mode. If a research workflow depends on the exact shape of a Pi extension hook, a session file, a document parser, or a web-access response, upgrading one package independently can produce a system that starts but no longer preserves the workflow’s assumptions. Coordinated versions reduce that class of drift. Preflight checks reduce another class: a missing Pi module, wrapper, polyfill, or rendering executable is detected as a launch problem rather than discovered halfway through a run.
The trade-off is maintenance burden. Users inherit a supported Node range, a managed package workspace, runtime patching, and an update model that is more involved than running a single script against whatever dependencies happen to be installed. Developers inherit the need to verify both Feynman’s parent CLI wiring and the actual Pi launch path. The repository’s own guidance calls for checking the Pi package version and matching runtime documentation before changing runtime integrations. That is sensible systems engineering, but it is not free simplicity.
The same trade-off appears in observability. Feynman can route telemetry for the parent CLI and the Pi child, but the child’s environment is deliberately constructed so that inherited package-manager and telemetry settings do not silently leak into the session. This improves control at the cost of another configuration surface to maintain. The wrapper is therefore both an integration layer and a policy boundary.
What this layer can—and cannot—guarantee
The wrapped architecture can guarantee some things locally when its checks are executed: that required launch assets are present, that the child receives the intended research resources, that workspace and session paths are selected deliberately, and that plugins conform to declared structural constraints. It can make a workflow’s intended prompts and artifacts available to the runtime. These are valuable preconditions for an inspectable research loop.
It cannot guarantee that a provider will return complete sources, that a model will obey every workflow instruction, or that a source-grounded synthesis is correct. It cannot infer scientific validity from the successful exit of a child process. Nor can package pinning eliminate all operational risk when external APIs, credentials, browser access, compute, or source repositories are part of the run.
That is why the next architectural question is about the workflow itself. Once Feynman has prepared a controlled runtime, it must decide how to move a question through planning, source acquisition, synthesis, and verification. The value of the Pi boundary is realized only if those stages leave evidence that a reader can follow rather than merely a session that happened to complete.