1# Pi
2
3T3 Code can use your existing Pi coding agent installation while keeping Pi's models, auth,
4extensions, skills, context files, and native session history.
5
6## Set Up Pi
7
8Install [Pi](https://pi.dev) on the machine running the T3 Code server. Pi requires Node.js
9 22.19 or newer; its platform installers can install Node if needed. T3 Code supports Pi
10 0.80.5 or newer.
11Run `pi` in a terminal, then `/login` to connect your model provider or configure its API key.
12Open T3 Code Settings, enable Pi, and refresh the provider.
13
14For an npm installation, use:
15
17npm install -g --ignore-scripts @earendil-works/pi-coding-agent
19
20If `pi` is not on the server's `PATH`, set Pi's binary path to the executable. Provider environment
21variables and launch arguments are also available for installations that need a custom agent
22directory, endpoint, or model configuration. `--provider` must be paired with `--model`. T3 Code
23rejects launch arguments that change Pi's execution mode or select a session because T3 owns those
24parts of the process lifecycle.
25
26On a remote or headless server, connect to that machine over SSH and run `pi`, then `/login`.
27Open the authorization URL on your own computer. If the callback cannot reach the server,
28paste the final redirect URL or authorization code back into Pi when prompted. You can also
29set your model provider's API-key environment variable in the Pi instance's settings; mark
30secret values as sensitive.
31
32Update installer-managed Pi with `pi update`. If another package manager owns the installation,
33update it through that manager instead. For example, a Nix profile installation uses
34`nix profile upgrade pi`.
35
36## What Carries Over
37
38T3 Code discovers the models reported by Pi and exposes their supported thinking levels. The
39thinking picker marks the discovered active model's configured level as its default without
40overriding it. Other models keep their Pi defaults when no level is selected. A model that lists
41`serviceTiers` (for example `[{ "id": "priority", "name": "Fast" }]`) in its Pi definition gets
42a speed picker with Standard plus those tiers. A chosen tier is sent as the request's
43`service_tier`; Standard sends none and leaves the endpoint's default. Threads
44use Pi's native session files for resume, rollback, and forks within the same Pi instance. Forks
45preserve the native conversation through the selected turn in the destination workspace.
46Switching providers uses portable conversation context. Extension
47dialogs appear in the T3 Code composer, and the thread details context window follows Pi's own usage
48reporting while a response streams and after it settles.
49
50Pi skills appear in the composer's `$` menu. This includes user skills and project skills that Pi
51loads for the current workspace; selecting one uses Pi's native skill expansion.
52
53Pi loads its normal user extensions, and project extensions once the folder is trusted in Pi.
54Blocking `select`, `confirm`, `input`, and `editor` dialogs work in T3 Code. Notifications appear in
55the work log. Extensions can publish status text near the composer. Terminal titles and generic
56widgets do not have a T3 Code equivalent.
57
58## Permission Modes
59
60T3 Code applies the composer permission mode through Pi's blocking tool hook:
61
62**Supervised** asks before commands, file changes, and extension tools. Read-only tools continue.
63**Auto-accept edits** allows Pi's edit and write tools, but asks before commands and extension
64 tools.
65**Full access** allows tools without T3 Code approval prompts.
66
67The **Auto** option is not shown for Pi because Pi does not expose an AI approval reviewer.
68Threads that already stored Auto before Pi support was added behave and display as Supervised.
69
70Changing the mode restarts the Pi provider session and resumes the same native conversation. The
71policy covers Pi tool calls; it is not an operating-system sandbox, and code that a trusted Pi
72extension runs outside a tool call remains governed by Pi's own extension trust model.
73
74T3 Code's `delegate_task` tool creates durable child threads in the shared subagent UI. If the user
75installs Pi's example `subagent` extension, T3 Code also shows its task progress and results in that
76UI. Pi runs those children without a session, so they cannot be opened or resumed as T3 Code
77threads.
78
79## Troubleshooting
80
81If Pi is unavailable, confirm that the configured binary runs on the server machine, then refresh
82 the provider in Settings.
83If no models appear, open Pi directly and confirm its authentication and model configuration.
84If discovery cannot complete, T3 Code keeps Pi available with the `Pi default` model. Start a
85 thread to let the interactive Pi session handle any startup prompt.
86If Pi skips project settings, extensions, skills, prompts, MCP servers, or system prompt files
87 because the folder is not trusted, the thread shows a notice on the first turn of the Pi session.
88 Run the configured Pi binary in that folder on the server machine, using the same provider
89 environment, including `PI_CODING_AGENT_DIR` if set. Trust the folder or its parent with `/trust`,
90 then start a new thread using that same worktree. Launch arguments with `--no-approve` keep
91 project files off without the notice.
92To see context usage on web and desktop, turn on **Context window** in **Settings → Appearance →
93 Thread details**. It appears once Pi reports usage for the thread. Some model providers only
94 report usage when a response completes, so it can wait for the first reply.