# How Does Feynman Launch the Pi Child Process? Runtime Deep Dive

> Discover how Feynman launches the Pi child process. Learn about environment validation, path resolution, and process spawning in this runtime deep dive.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: deep-dive
- Published: 2026-09-08

---

**Feynman launches the Pi AI framework as a child process through the `launchPiChat` function in [`src/pi/launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.ts), which validates the Node.js environment, resolves binary paths, and spawns a Node.js process with inherited stdio.**

Feynman is an open-source research agent framework that orchestrates AI workflows by wrapping the Pi framework in a controlled runtime. When users initiate a chat session, the system bootstraps the Pi environment within a separate Node.js process to ensure isolation and proper resource management. According to the advaitpaliwal/feynman source code, this orchestration happens through a carefully sequenced pipeline in [`src/pi/launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.ts) that verifies compatibility before handing control to the Pi CLI.

## From CLI to launchPiChat: The Entry Point

The execution flow begins at [`bin/feynman.js`](https://github.com/advaitpaliwal/feynman/blob/main/bin/feynman.js), the CLI entry point that parses user commands such as `feynman chat` or `feynman chat --mode rpc`. After constructing a **`PiRuntimeOptions`** configuration object from CLI arguments and defaults, the CLI invokes `launchPiChat(options)` to initiate the child process lifecycle.

## Step-by-Step Process Execution in launchPiChat

Located in [`src/pi/launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.ts), the `launchPiChat` function implements a seven-stage pipeline to prepare and spawn the Pi environment.

### Environment Validation and Node Version Checks

Before spawning, the system verifies the current Node.js version against supported runtimes (lines 24-26). It also patches the embedded Pi `node_modules` directory to ensure compatibility with the host environment. This validation prevents runtime errors from version mismatches before the child process starts.

### Resolving Pi Binary Paths and Dependencies

Using the **`resolvePiPaths`** helper, the function discovers critical file locations: the Pi CLI executable, the main module entry point, the wrapper script, and any required polyfills (lines 27-36). If any required files are missing—including the Pi CLI, main module, or polyfills—the system throws descriptive errors immediately (lines 37-54), failing fast rather than launching an incomplete process.

### Console Preparation and Interactive Mode

When running in an interactive terminal (TTY) and not in RPC mode, Feynman clears the screen to provide a clean chat interface (lines 56-58). This ensures that previous terminal output does not clutter the Pi chat UI, creating a focused user experience for research interactions.

### Building Command Line Arguments and Loaders

The function constructs the Node.js execution context dynamically:

- If a development-time polyfill is available, it appends the TSX loader and source polyfill via `--import` flags.
- Otherwise, it imports the built-in polyfill.
- The wrapper script—either the compiled version or the source version with TSX loader—is combined with the Pi main module and arguments generated by **`buildPiArgs`** (lines 64-68).

This approach allows Feynman to support both production builds and development environments without separate configuration files.

### Spawning the Child Process with spawn

The actual child process creation occurs using Node.js's **`spawn`** function (lines 72-76). Feynman configures the process to inherit the parent's stdio streams (`stdin`, `stdout`, `stderr`), ensuring that Pi's interactive output displays directly in the terminal. The environment variables are constructed via **`buildPiEnv`**, which merges user configuration, discovered executable paths, and necessary system adjustments.

### Handling Process Termination and Exit Codes

After spawning, `launchPiChat` awaits the child's exit (lines 78-90). If the process terminates due to a signal, Feynman logs the event and converts the signal to a conventional exit code using the formula `128 + signalNumber`. For normal exits, the child's exit code propagates directly to the parent, maintaining standard Unix exit code conventions.

## Programmatic Usage and CLI Examples

You can trigger the Pi child process programmatically or via the command line:

```typescript
// Programmatically start a Pi chat session
import { launchPiChat } from "./src/pi/launch.js";
import { readConfig } from "./src/config.js";

async function startChat() {
  const opts = await readConfig();   // builds PiRuntimeOptions from CLI args / defaults
  await launchPiChat(opts);          // spawns the Pi child process
}

startChat().catch(err => console.error(err));

```

```bash

# Using the Feynman CLI (most common approach)

node bin/feynman.js chat          # launches Pi in interactive chat mode

node bin/feynman.js chat --mode rpc   # launches Pi in RPC mode (no screen clearing)

```

## Key Source Files and Their Roles

- **[`src/pi/launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.ts)**: Contains the core `launchPiChat` function that orchestrates the entire child process lifecycle.
- **[`src/pi/runtime.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/runtime.js)**: Provides helper functions `buildPiArgs` for command-line construction and `buildPiEnv` for environment variable management.
- **[`bin/feynman.js`](https://github.com/advaitpaliwal/feynman/blob/main/bin/feynman.js)**: The CLI entry point that parses user input and invokes the launch sequence.
- **[`src/system/node-version.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/system/node-version.js)**: Validates Node.js version compatibility before launching Pi.
- **[`src/system/executables.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/system/executables.js)**: Detects external executables required in the Pi environment path.

## Summary

- Feynman launches Pi through the **`launchPiChat`** function in [`src/pi/launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.ts), called by the CLI entry point at [`bin/feynman.js`](https://github.com/advaitpaliwal/feynman/blob/main/bin/feynman.js).
- The launch sequence includes Node.js version validation, binary path resolution, file verification, console preparation, and dynamic argument construction.
- The child process spawns via Node.js **`spawn`** with inherited stdio, ensuring seamless interactive output.
- Exit codes follow Unix conventions, with signal terminations converted to **`128 + signalNumber`**.
- The system supports both production and development environments through TSX loader detection and polyfill management.

## Frequently Asked Questions

### What function is responsible for launching the Pi process in Feynman?

The **`launchPiChat`** function in [`src/pi/launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.ts) handles the complete lifecycle of spawning the Pi child process, from environment validation to process termination handling as implemented in the advaitpaliwal/feynman repository.

### How does Feynman handle missing Pi executables or dependencies?

Before spawning, the code verifies that the Pi CLI, main module, and required polyfills exist (lines 37-54 in [`launch.ts`](https://github.com/advaitpaliwal/feynman/blob/main/launch.ts)). If any critical file is missing, it throws an immediate error with a descriptive message, preventing incomplete launches.

### Can I launch the Pi child process programmatically instead of using the CLI?

Yes. Import `launchPiChat` from [`src/pi/launch.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/launch.js) and pass a `PiRuntimeOptions` object constructed via **`readConfig()`** or manually. This allows integration into custom Node.js applications without invoking [`bin/feynman.js`](https://github.com/advaitpaliwal/feynman/blob/main/bin/feynman.js).

### How does Feynman manage environment variables for the Pi process?

The **`buildPiEnv`** function located in [`src/pi/runtime.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/pi/runtime.js) merges user configuration, discovered executable paths from [`src/system/executables.js`](https://github.com/advaitpaliwal/feynman/blob/main/src/system/executables.js), and system adjustments into a single environment object passed to the `spawn` call.