Pi runs over its RPC mode
(pi --mode rpc: JSON lines on stdio), one Pi process per session. The
driver is packages/agent-host/src/drivers/pi/.
Nothing to install by hand: @earendil-works/pi-coding-agent is installed on
demand at the version and sha512 pnpm-lock.yaml pins, into <home>/agents/
— Install on the phone, or codedeck-bridge agents install pi. It is a
pure-JS package tree, like the DeepSeek Harness's. CODEDECK_PI_PATH names a
CLI of your own to use instead (its cli.js, run with the bridge's Node, or
an executable).
A session needs a model Pi can reach, any of:
- An account connected on the phone (the agent's page → AI providers →
Connect a provider): an API key for any of Pi's providers, or a sign-in to
a subscription where Pi has one (Claude Pro/Max, ChatGPT Plus/Pro through
OpenAI Codex, GitHub Copilot, xAI and others). Pi's own code stores it, in its home (below), exactly where its
/loginwould. The model picker then lists that provider's models. - A provider profile added on the phone (the agent's page → AI
providers): any OpenAI-compatible endpoint — a provider's own API or a
gateway in front of several (claude-code-router, LiteLLM). A session bound
to one runs on it, and its models are the ones the picker offers. A
profile's model list rarely says how large a model's context is or
whether it reasons, so each model borrows those facts from Pi's own
catalog: matched on the part of its id after the last
/(a gateway'sOpenCode Go/deepseek-v4.1-flashis Pi'sdeepseek-v4.1-flash), from the provider the route names when Pi has it, else the entry with the smallest context. That sets the context meter, when Pi compacts, the reasoning levels and the longest answer. A size the endpoint states wins; a model Pi does not know runs at 128k context without reasoning. - The bridge's environment: the keys Pi reads itself, such as
ANTHROPIC_API_KEYorOPENROUTER_API_KEY. The phone shows them as the machine's, which only the machine can change.
The list is Pi's own: every provider the installed Pi knows, with a key form where Pi takes a key and a sign-in where it has one. A key is checked by Pi only when a session uses it.
A sign-in gives a page to open on any device. Some providers then show a code to enter there and finish on their own; the others send the browser back to an address on the bridge's machine, which a phone cannot open: paste the address it fails to load, and Pi finishes the sign-in with it.
What else a login asks is on the form, in Pi's own words: Cloudflare's
account and gateway IDs beside the key, how to sign in to Anthropic or
OpenAI Codex (a page, or a code for another device), a GitHub Enterprise
domain (blank for github.com). Pi asks these as its login goes, so the
bridge finds them when the phone lists the providers, by running each
login with every way off the machine blocked (the network, listening,
other programs) and its placeholder answers kept in a scratch file deleted
afterwards. Where a login offers several ways and only one works without
the machine's own setup (Amazon Bedrock's bearer token, Google Vertex's API
key, rather than an AWS profile or a credentials file), the phone offers
that one. A way that needs the machine itself is not offered — run Pi's
own /login there for it.
Pi's settings, credentials, models and conversations live in the directory
the driver points PI_CODING_AGENT_DIR at: CODEDECK_PI_HOME, else a pi
directory beside the agent cache. Pi in a terminal shares all of it when
pointed there (PI_CODING_AGENT_DIR=<that directory>): accounts, MCP
servers and packages added either way are there for both. Conversations are files under its sessions/, which is what a session
resumes from after a restart and what deleting a conversation removes.
A profile's token never touches a file, nor Pi's environment: the profile
travels in an environment variable, the token on a pipe of its own (file
descriptor 3), which the CodeDeck extension reads once as Pi starts and
registers as the profile's key. Everything Pi starts — the model's shells,
background shells, sub-agents, MCP and language servers — inherits Pi's
environment, and on Linux any process of the same user can read a process's
starting environment back from /proc, so a token there would be the
model's to print. A sub-agent's Pi gets the token on its own pipe the same
way. An operator's own Pi executable that wraps Pi must hand file
descriptor 3 on to it; one that does not leaves the profile's requests
without a key (Pi's error says so, and the bridge log has the extension's
line naming the missing token).
Pi runs with --offline, version checks and telemetry off: it makes no
network request of its own beyond the model's. Its model catalog is therefore
the one its release shipped with, plus your own models.json.
Pi has no permission system of its own: it runs every tool call it decides
on. CodeDeck installs an extension into every session — the CodeDeck Pi
extension, <home>/codedeck/codedeck-pi.js, rewritten when the bridge's
version of it changes and loaded with -e — that holds each tool call until
the phone answers:
- Ask (the default): a card for every tool call, except Pi's read-only
tools (
read,grep,find,ls) and the extension's own tools that change nothing (below), which run without one. The card offers Allow, Allow<tool>for this session, and Deny; a denied call never runs, and Pi tells the model it was denied. A tool that another extension or an MCP server adds asks like any other. - Auto edit: Pi's own file tools (
edit,write) also run without a card; a command, a web fetch, and any tool an extension or an MCP server adds, still asks. - Plan: the session explores and changes nothing. Read-only tools and
read-only shell commands (
git status,git diff,cat,grep… without their writing options, no redirection) run; anything else is refused, and the model is told to present its plan instead. The plan arrives as a plan card: approve it to switch the session to Ask or Auto edit, or send it back with what to change. - YOLO: every tool call runs without a card.
What "for this session" allows is kept by the session only: Pi saves no rules, so the next session asks again.
Pi ships read, bash, edit and write on by default. A session also
turns on its ls, and its grep and find where ripgrep and fd are on the
machine (the container image has both; Pi runs offline, so it never
downloads them). The CodeDeck Pi extension adds what a session driven from a
phone needs, shown with the same cards as the other agents:
todo: the model's checklist, shown as the session's checklist.ask: up to four questions with options, shown as a question card.exit_plan: the plan card of Plan mode.task: a sub-agent — a second Pi with a fresh context — for one job, answering with its conclusion; several run in parallel.explorehas the read-only tools only, so it changes nothing and never asks;generalhas the session's tools, and each of its tool calls asks exactly as the session's own would, on a card that names the sub-agent. Its work shows under its call.bash_background,task_output,task_stop: a command that keeps running after its call (a dev server, a watcher), whose output the model reads later. Each is a background task the phone can stop; whatever still runs when the session's Pi exits is stopped with it.web_fetch: one web page read as text, asking first every time. It sends no cookies or credentials, follows at most five redirects and never into a local or private address the first URL did not name, reads text only, and tells the model the page is data, not instructions.memory: notes about the project that later sessions start with — one file per note and an index the system prompt carries, in Pi's home undercodedeck/memory/<project>/, never in the working tree. Each save shows on the phone as amemorycall; a note that looks like it holds a secret is refused.
The checklist, questions, sub-agents and background shells need no card of their own beyond what they start.
A file Pi changes with edit or write shows as a diff under its call:
an edit's lines are the patch Pi applied, with the lines around it; a write
shows the content it wrote.
After an edit or write succeeds, the project's language server checks
the file, and its errors and warnings are added to the tool's result — the
model reads a type error it just made before its next step, and the phone
shows it in the result like the rest. Only servers already on the machine
are used; nothing is installed:
| Files | Server | Found in |
|---|---|---|
| TypeScript, JavaScript | typescript-language-server for a TypeScript up to 6.x; TypeScript 7's own tsc --lsp |
the project's node_modules; typescript-language-server also on PATH |
| Python | basedpyright-langserver, else pyright-langserver |
the project's .venv/venv, its node_modules, then PATH |
| Rust | rust-analyzer (its own check, then cargo check's) |
PATH |
The project is the nearest directory above the file with a tsconfig.json,
jsconfig.json or package.json; a Cargo.toml; or a pyproject.toml,
setup.py, setup.cfg, pyrightconfig.json or requirements.txt. A
server starts with the first change in its project and stays for the
session (stopped after ten idle minutes, and with Pi). The first check
waits for it to load the project — about a second for TypeScript and
Python, ten or more for rust-analyzer, at most 30 s — and later ones take
under a second; a check never waits more than 10 s, and a list that came
in late is marked unfinished. A server that is missing or fails to start
is skipped for that project until the session ends: rustup's
rust-analyzer without the component installed
(rustup component add rust-analyzer) is one.
Reported: the changed file only, errors and warnings (not hints), at most
20. A server runs the project's own build tooling (cargo check runs
build scripts) with the bridge's environment, without a provider profile's
token. Set CODEDECK_PI_LSP=off in the bridge's environment to turn the
checks off.
Reasoning is Pi's thinking level: Off, Minimal, Low, Medium (Pi's default), High, Extra high, Max. A model without one of them runs at the nearest it has, as in Pi's own terminal UI.
A message sent while a turn runs is steered into that turn: Pi hands it to the model after the tool calls in flight, before its next request. Stop aborts the turn and answers any card still open as cancelled.
When a request fails and Pi retries it, the session shows one line per retry instead of an error; only an error Pi gives up on, or one it does not retry, is shown as an error.
Dialogs that your own Pi extensions open (select, confirm, input,
editor) reach the phone as question cards; their notifications show as a
status line in the session.
The MCP screen manages the mcpServers of mcp.json in Pi's home, the file
pi mcp add and /mcp edit. Stdio and streamable HTTP servers only: Pi
rejects the legacy SSE transport, and server names other than letters,
digits, _ and -. Switching one off keeps it with Pi's own
enabled: false. A Pi process connects its servers as its session starts:
a change applies to the sessions started after it, and a session's MCP
panel shows a server changed since as not loaded yet. Env and header values
are kept in the file, which is written readable by its owner only on Linux
and macOS.
The Plugins screen manages Pi's packages, through Pi's own pi install,
pi update and pi remove. A package bundles extensions, skills, prompt
templates and themes from npm (npm:<package>), git (git:github.com/… or
a URL) or a path, and is how Pi gains tools neither it nor CodeDeck ships.
A package runs code with the bridge's permissions: install only ones you
trust. An npm package needs npm on the machine (the container image has
it, a release archive does not); CODEDECK_NPM_REGISTRY is passed on to it.
Packages cannot be switched off, only removed; sessions started after a
change load it.
- No subscription usage to ask for (the context meter still works) and no saved permission rules.
- Diagnostics for three languages: TypeScript/JavaScript, Python and Rust (above). Another language's checks can come from a Pi package.
- Accounts need Pi's package: with
CODEDECK_PI_PATHnaming an executable rather than acli.js, they cannot be listed or changed.
Like the DeepSeek Harness it is a package tree in the agents volume. A host
without npm registry access installs it from a copied agents/ directory,
points CODEDECK_NPM_REGISTRY at a mirror, or points CODEDECK_PI_PATH at
its own.