How to Use Pi Coding Agent 1.0: Install, Connect a Model, and Run Your First Task

Name

Soren Atelier

Updated on 10/4/2026

The short answer: install Pi, open a project folder, sign in, and give it a task.

curl -fsSL https://pi.dev/install.sh | sh
cd /path/to/project
pi

Inside Pi, type /login and pick a provider: a Claude, ChatGPT, or GitHub Copilot subscription, an API key, or a local model. Then describe the task in plain words. On Windows, use powershell -c "irm https://pi.dev/install.ps1 | iex" instead of the first line.

Pi is a minimal, open-source (MIT) coding agent for the terminal, made by Earendil Works. Version 1.0 shipped on October 1, 2026, with 1.0.2 out by October 4. The repo has over 112,000 GitHub stars, and the 1.0 launch post reached 1,678 points on Hacker News. The project says it has hundreds of thousands of weekly users.

Read this before you start: Pi does not ask for permission before it runs a command or edits a file. It runs with your user account's full permissions. That is the biggest difference from Claude Code and Codex, and it changes how you should set it up. The safety section below explains what to do about it.

What was tested: on October 4, 2026, we installed Pi 1.0.2 from npm on macOS (Apple M4 Max, Node.js 22.20). We connected it to a local qwen3-vl:8b model through Ollama. We ran a real file-writing task, a read-only run, an AGENTS.md check, and a session export. We did not test the /login subscription flows, the interactive full-screen TUI, MCP servers, codemode, or third-party packages. Those parts come from the official docs bundled with 1.0.2 and from the Pi 1.0 announcement (opens in a new tab).

What Pi is, and who it is for

Pi calls itself "a minimal, extensible agent harness that you can make your own." In practice it has two layers:

• A coding agent CLI (pi) with seven built-in tools: read, bash, edit, write, plus grep, find, and ls, which are off by default.
• A toolkit underneath it: a multi-provider LLM library (pi-ai), an agent runtime, a terminal UI library, and a TypeScript SDK. Other projects build on these. OpenClaw is the best-known example.

Pi leaves out a lot on purpose. It has no built-in sub-agents and no plan mode. Its answer is "ask Pi to build what you want, or install a package that does it your way." If you want a polished, batteries-included product, Claude Code, Codex, or OpenCode fit better. Pi suits people who want one small, readable agent loop that works with almost any model and that they can extend themselves.

Step 1: Install Pi

Pick one of four install paths:

We used npm with --ignore-scripts. It added 121 packages in 26 seconds:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

pi --version printed 1.0.2.

Install traps:

• Old Node.js. Pi needs Node 22.19 or newer. On Node 20, use the installer script, which brings its own Node, or upgrade Node first.
• Old tutorials. Many pre-1.0 guides point to badlogic/pi-mono and the @mariozechner/... npm scope. The current repo is earendil-works/pi (opens in a new tab) and the package is @earendil-works/pi-coding-agent.
• Windows shell. Native Windows Pi runs its bash tool through Git Bash. If !printf 'Bash is working\n' fails inside Pi, install Git for Windows or set shellPath in ~/.pi/agent/settings.json.

Step 2: Connect a model

Pi only works once it can reach a model. You have three options.

Option A: a subscription or API key through /login

Start pi in a project folder and type:

/login

In Pi 1.0.2, the /login provider list includes Anthropic (Claude Pro/Max), OpenAI (ChatGPT Plus/Pro), GitHub Copilot, xAI, Kimi Code, and Meta, plus API-key logins for many more. Credentials go to ~/.pi/agent/auth.json. Keep that file private and never commit it. Use /model to switch models afterwards, or press Ctrl+P to cycle through the models you listed with --models.

We did not test the subscription logins. Check your provider's terms before using a consumer subscription in a third-party tool.

Option B: an environment variable

This is the CI-friendly path. Pi reads the usual variable names:

export ANTHROPIC_API_KEY=sk-ant-...
pi --model sonnet "Explain how this repo is structured"

Other names follow the same pattern: OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, and many more. pi --help prints the full list. Use pi auth check --provider <name> to confirm a provider is ready without starting a session.

Option C: a local model through Ollama (tested)

Pi has built-in support for the llama.cpp router (the /llama command). For Ollama, LM Studio, vLLM, or any OpenAI-compatible server, you add the server to ~/.pi/agent/models.json yourself. This is the exact file we used:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "qwen3-vl:8b" }
      ]
    }
  }
}

The apiKey value is a dummy that Ollama ignores, but Pi needs a value there to treat the model as available. Check that Pi sees the model:

pi --list-models qwen

It printed ollama qwen3-vl:8b 128K .... Pi lists the context window as 128K, even though Ollama reports 262K for this model. Pi uses its own default unless you set a limit in models.json.

Step 3: Run your first task

In interactive mode, type the task and use @ to pick files. To script Pi or to test a model, use print mode (-p): Pi runs the task and exits.

Our test project held a six-row sales.csv. We asked:

pi --model ollama/qwen3-vl:8b -p "Read sales.csv. Write a Python script growth.py that uses only the standard library csv module to print each region's month-over-month sales change in percent. Then run it with python3 and show the output."

The session log showed what happened:

1. Turn 1: Pi called read on sales.csv.
2. Turn 2: It called write to create growth.py, then bash to run it. The 8B model had put literal \n escape sequences into the file, so Python raised a SyntaxError.
3. Turn 3: Pi read the error, rewrote the file correctly, and ran it again.
4. Turn 4: It reported the result:

north: 2026-07 to 2026-08 → 12.50%
south: 2026-07 to 2026-08 → -11.11%
east: 2026-07 to 2026-08 → 58.33%

All three numbers are correct. The run took 6 minutes 54 seconds on a laptop GPU, and most of that was one long "thinking" turn (about 12,000 output tokens). A hosted frontier model finishes the same task in seconds. The local run proves the setup works offline at zero API cost. It does not show local 8B models are good enough for daily coding.

Pi never asked before writing the file or running python3. That is the default behavior, not a bug.

Safety defaults you should change on day one

Pi's security doc (opens in a new tab) says plainly that Pi "does not ask for approval before every tool call." It also says watching the transcript is not a security boundary. Three habits make up for that.

1. Use a read-only tool set for review work. --tools is an allowlist, so this run can read but cannot write or execute:

pi --tools read,grep,find,ls -p "Review the code in src/ and list risky functions"

We tested this. When we asked Pi to create a file, it replied that none of its tools could write files. It finished in 11.5 seconds and left the folder unchanged.

2. Put unattended or untrusted work in a sandbox. The docs describe three patterns: the Gondolin extension (Pi's tools run inside a local Linux micro-VM), plain Docker, and NVIDIA OpenShell. Use one before you point Pi at a repo you did not write, or before you leave it running alone.

3. Treat packages and project folders as code. Pi packages can contain extensions that run code. A project's .pi/settings.json only loads after you grant project trust. Read a third-party package's source before pi install, and decline trust for folders you just cloned.

Instructions, sessions, and cost

• AGENTS.md and CLAUDE.md. Pi loads both from the agent directory, the working folder, and parent folders. This does not require project trust. We tested it with a one-line AGENTS.md rule, and the model followed it. AGENTS.override.md replaces the file in the same folder. If you already keep an AGENTS.md for other agents, Pi reuses it. Our AGENTS.md guide for Claude Code, Codex, and OpenCode explains how to write one file for all of them.
• Sessions are saved automatically. Run pi --continue to resume the latest session for a folder, or /resume to pick one. Sessions are JSONL files under ~/.pi/agent/sessions/.
• Export a session. pi --export <session.jsonl> out.html produced a 390 KB standalone HTML transcript in our test, which is useful for code review or bug reports.
• Watch cost. The footer shows running token usage and cost. /session shows them for the current session. Pi 1.0 also added cache warming for Anthropic models, which reduces repeat-prompt cost on long sessions.

Going further: MCP, codemode, and packages

These features come from the official docs. We did not test them.

MCP servers. Add a server from the shell, check it, then start Pi:

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list

To copy servers from Claude Code, Claude Desktop, or Cursor, you can paste their mcpServers entries into Pi's mcp.json almost as-is. Entries from Codex TOML or OpenCode local/remote blocks need converting first.

Codemode. New in 1.0. The model writes a JavaScript script that calls Pi's tools, MCP tools, and non-LLM models (classifiers such as Jev-style decision models, or image models) inside a QuickJS sandbox. Only the script's output goes back to the model. Turn it on in ~/.pi/agent/settings.json:

{
  "defaultTools": ["+codemode"]
}

Packages. Extensions, skills, prompt templates, and themes ship as npm or git packages:

pi install npm:@example/pi-tools@1.0.0
pi -e npm:@example/pi-tools

The first line installs a package permanently. The second loads it for one run without changing your settings, which is the safer way to try something. Sub-agents and plan mode exist only as community packages.

Troubleshooting

Where Pi fits in a data workflow

Pi works well on scripts and repos. Notebooks are harder: .ipynb files are JSON, so a repo-style agent edits cell source as text and never sees the live kernel state, such as which DataFrames are loaded or what the last cell printed. If most of your work happens in Jupyter, a notebook-native agent like RunCell (opens in a new tab) runs cells and reads their outputs directly, which suits that workflow better. A common split: Pi for the repo, a notebook agent for exploration.

FAQ

Related Guides

• Oh My OpenCode and OpenCode: Install, Setup, and Fixes
• How to Use Codex
• Claude Code Reads AGENTS.md: Share One File with Codex, OpenCode, and Cursor
• How to Use DeepSeek Harness
• NemoClaw vs OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot
• Best AI Coding Tools in 2026