Stage 0: Get the system running

Corresponding to Learning Path Stage 0 (Preparation · 0.5–1 day). This document is a supplementary explanation and does not replace the checklist items. Source code directory: $PI_SRC. Unless otherwise specified, run the following commands in PowerShell by first cd-ing into this directory. Verified local environment: Node v26.11.1, npm 11.20.0 (requires Node ≥ 22.19).

Why this step is needed

The later stages are all hands-on verification driven: running programs, observing event flows, modifying code, and watching behavior. Therefore, the goal of Stage 0 is only one thing:

Get the “source code version of Pi” fully running on your machine and establish three basic concepts.

Source version vs Installed version. If your machine has the pi global command, that is the packaged installed version; the learning zone uses pi-test.ps1 — running TypeScript source code directly via Node without building. The two might not be the same version; all experiments in this checklist follow the source version.
Why locked at v1.3.0. The learning zone is an independent git worktree, a detached HEAD fixed at v1.3.0 (commit 71023aec). The paths and behaviors in the checklist correspond to this version; the development line is still moving forward, compare with the main repo as needed. Do not switch branches or pull updates in the learning zone.
Two types of local artifacts. node_modules/ (dependencies) and packages/ai/src/providers/data/ (model data). Both are in.gitignore — if lost, they can be reinstalled/regenerated at any time, no need to worry.

Step 1 · Install dependencies: npm install –ignore-scripts

First check: node --version, requires ≥ v22.19.0 (repository’s engines requirement).

Execute:

npm install --ignore-scripts

What happened: Monorepo dependency installation — dependencies for 11 packages are installed uniformly at the root node_modules, and the packages are linked to each other. The first time requires downloading more content, a few minutes is normal.

Why --ignore-scripts is necessary: To prevent npm from running lifecycle scripts that come with dependencies (such as postinstall). This is the established convention of the repository and the official installation process (supply chain security); normal usage with Pi does not require any installation scripts for dependencies.

Expected result: node_modules/ appears in the root directory; git status remains clean (node_modules is gitignored).

If it fails:

Timeout/download failed → network or proxy problem. Retry after configuring a proxy or mirror source
Node version not supported → upgrade Node to 22.19
Do not forcibly install using admin privileges, a normal user directory is sufficient

Step 2 · Generate model data: npm run hydrate:model-data

This is the easiest step to get confused in stage 0, and also the most important to understand.

First, understand what ‘model data’ is and why it is not in git

Model data = directory information for each model: context window, price, capability tags, etc. (for example, ‘how long is a model’s context, cost per million tokens’).

The generator (packages/ai/scripts/generate-models.ts) is responsible for fetching and calculating this data from upstream directories (OpenRouter, Vercel AI Gateway, Radius, etc.);
The results are divided into two parts:
- Code skeleton: src/models.generated.ts and providers/*.models.ts — committed to git;
- Data files: src/providers/data/*.json — gitignored, not in git.
The code skeleton will import "./data/anthropic.json" directly reference the data files — so the newly cloned source tree must generate the data first before it can run.

Why not commit the data to git (this will be tested in self-check):

It is derived data: generated by the generator from upstream sources, not manually written code;
Upstream changes frequently: new models, price adjustments are common. Committing would only introduce noisy diffs and merge conflicts;
Regenerable: can be regenerated locally with a single command, or during build/release. The official npm package will include this data, so only ‘running from source’ requires generating it yourself.

Execution:

npm run hydrate:model-data

(The actual execution is generate-models.ts --strict --data-only under packages/ai).

What it does: According to the submitted provider list, fetch the upstream directory over the network → generate JSON for each provider in a temporary directory .manifest.json → after validation, atomically replace src/providers/data/ (if validation fails, it will roll back and not leave any half-finished products).

Expected result: Output Hydrated JSON model values under src/providers/data/; opening packages/ai/src/providers/data/ shows anthropic.json, openai.json… and .manifest.json.

Note:

This step requires a network; in --strict mode, fetch failures will immediately report an error and exit (usually due to network/proxy issues, just retry).
Do not confuse it with similar commands: hydrate:model-data only supplements data (used in the learning period); generate-models regenerates along with the code skeleton; npm run build is a full build — not needed during learning and should not be run casually (it will make the workspace no longer a ‘clean reference copy’).

Step 3 · Verify Version

Two commands, confirming two things:

git describe --tags        # Should output v1.3.0 —— Confirm the learning area hasn't gone off track
.\pi-test.ps1 --version    # Should output 1.3.0  —— Confirm that the source version can start

pi-test.ps1 is: a very thin wrapper. It runs packages/coding-agent/src/cli.ts directly with Node (without building first) and injects a source code parser so that imports within the package can match; command-line arguments are forwarded to pi as-is. It takes the source code from its own location, so the same source is used no matter which directory you run it from.

But remember one difference: Pi’s ‘working directory’ is the directory you are in when executing the command—which files the tool can access, which project a session belongs to, and where context files are found are all based on that. So before ‘asking it to summarize a repository,’ first cd into that repository.

If you get ‘script execution is disabled’ (PowerShell execution policy):

powershell -ExecutionPolicy Bypass -File .\pi-test.ps1 --version

Or only allow for the current session: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

A small tool: pi-test.ps1 --no-env will temporarily clear a batch of API key environment variables before startup (simulating a clean environment), useful when troubleshooting “where the credentials are actually coming from.”

Step 4 · Run a non-interactive task once (-p)

Execute (in the learning area directory):

.\pi-test.ps1 -p "Summarize the directory structure of this repository"

-p(–print): Non-interactive mode—send a message, wait for it to finish, output the final result, and exit directly. Suitable for quick verification and scripting (stage 7 will systematically cover print / JSON / RPC / SDK forms).

Prerequisite: You need model credentials. For the first time, first use /login in interaction mode (choose a provider to log in or enter the API key), or configure the corresponding environment variables (pi-test.ps1 lists a batch of *_API_KEY lists as clues). If there are no credentials, this step will directly prompt authentication requirements.

You’ll notice: it’s not a “empty summary”—it actually calls tools (listing directories, reading files, possibly multiple rounds) to give conclusions. This also previews the last two core concepts: the “loop” in phase 2 and the “tool call” in stage 4. To see the details of each step, switch to --mode json for a complete event stream (stage 1 expands).

Project Trust Tip:p The rint / JSON / RPC mode will not display the “Trust this project” interaction prompt; by default, it skips protected resources in the project; Add --approve when needed. In interaction mode, the opposite is the answer: it will ask you.

Step 5 · Enter interactive mode and have a real chat

Execution:

.\pi-test.ps1

You will see: full-screen TUI. There is an input box and status bar at the bottom; After sending a message, the response streams onscreen; Tool calls are displayed as separate blocks.

Here are a few things to do when you first join:

Enter /: The command menu pops up — an authority list of commands available for the current session
/login: Log in to the provider (must be done if no credentials are available)
/model: View/switch models
/hotkeys: View the currently active shortcuts

Several Key Buttons:

Esc: Stop the current turn (the “brake” while working)
Ctrl+C: Clear the input box for the first time, then press again to exit
Ctrl+D: Exits directly when the input field is empty; You can also /quit

Let’s talk about something real: For example, “Read the repository’s README and summarize it in three sentences.” Observe streaming output, toolblocks, and see if it actually reads the file.

Two Facts:

The learning area (PI repository itself) includes .pi/skills/ protected resources. For the first time, the interaction mode will pop up a project trust prompt—choose what to choose depending on whether you want to load them; /trust You can remember the decision. (What the trust mechanism protects and what does not protect, Stage 4 expands.))
Configuration and session default are written to ~/.pi/agent(Windows: C:\Users\<you>\.pi\agent); Session JSONL stored by working directory is under sessions/ — this is the ready-made material for Stage 3, which you can browse after chatting.

Step 6 · Read two sections of the README

Packages table: The README lists 7 packages that have been released externally (chord / telemetry / ai / durable / agent / coding-agent / tui); The warehouse actually has 11 packages. Now, let’s quickly glance at it and get familiar with the face; the self-check for “One Sentence Responsibility per Package” is in the next section.

Permissions & Containerization (Be sure to read and remember the conclusion):

Pi does not have a built-in permission sandbox—by default, it runs with the user/process privileges that activate it, and whatever you can access is what you can;
Use containerization when stronger boundaries are needed. The documentation provides three modes: Gondolin extension (pi and credentials remain on the host, built-in tools and! Command routing into the local Linux microVM), whole processes go to Docker, and whole processes go into the OpenShell policy sandbox.

Why read now: When Stage 4 discusses tool permissions and security models, there will be kickbacks; More importantly, before you let Pi work on your own project, you should first think carefully about its permission boundaries.

Self-Inspection for Customs Clearance (Compared to the Three Criteria of Stage 0)

(1) Both Patterns Worked Through

.\pi-test.ps1 --version Normal output 1.3.0
-p The task is truly completed and the result is given
Discussed interaction mode once

(2) Be able to name one sentence for each bag (recall first, then look at the answer)

Package	In short: Responsibility
agent	Universal Agent runtime: tool call loops and state management, decoupled from UI/specific models
ai	Unified Multi-Vendor LLM API: Streaming Event Normalization + Model Directory
coding-agent	Complete application: Assemble sessions, tools, patterns, and interfaces into a coding agent CLI
tui	Terminal UI library: Differential rendering
mcp	Standalone MCP client (external tool protocol)
codemode	Sandbox JS runtime: The only capability is to call the injected tool
chord	Plugin host runtime: hot overload, contract, copy state, JSON-RPC
durable	Persist dialogue/task/document runtime
env	Remote execution environment (SSH-deployed daemon + client)
telemetry	Common format for telemetry data: unified event and indicator structure, not tied to any particular vendor
evals	Evaluation Framework

“Vendor neutral” means not relying on a single monitoring vendor; “Typed schema” refers to which fields events and metrics are and what types they are, with a unified and checkable definition. Pi only provides a recording interface in this format; whether to connect to OpenTelemetry, Sentry, or its own logs is up to the application itself.

Dependence on directions and stratification (who is whose base) is left for the global map in Stage 1.

(3) Why doesn’t the model data enter git (Answer in three sentences)

Derived data: Generated by the generator fetched from upstream directories, not handwritten source code;
Frequent changes: Upstream updates frequently, but entering git only causes noise diffs and conflicts;
Renewable: Regenerated locally/during build, included in the release package; The repository only submits the generator and code skeleton.

Quick Quick Reference for Common Questions

Symptoms	Causes	Treatment
npm install timeout/failure	Network or proxy	Configure proxy/image source and then retry
hydrate reports fetch failure	Cannot detect upstream directory (–strict directly throws an error)	Check the network/proxy and retry
Runtime not found `./data/*.json`	Model data not generated	Return to step 2
“Script Prohibited”	PowerShell Execution Policy	`powershell -ExecutionPolicy Bypass -File .\pi-test.ps1 ...`
Prompt Requires authentication	No credentials	Interaction mode `/login` or configuration environment variable
Interaction mode asks “Do you trust”	Run in a directory containing `.pi/`	Select as needed; `/trust` Remember to decide
Want to check the source of your credentials	—	`pi-test.ps1 --no-env` Clear the environment variable to start

After finishing

Go back to Learning Path and check the box for Stage 0.
Next stop: Stage 1 · Global Map (detailed guide: Stage 1). Read packages/coding-agent/docs/how-pi-works.md with a specific question in mind: ‘What exactly happens to a message from arrival to being written to disk?’

Companion Learning Path Stage 0 writing · 2026-10-19 · Based on v1.3.0 (71023aec)