Skip to content

Pi mode

DuckTapeKiller edited this page Sep 13, 2026 · 2 revisions

Pi mode puts Dive in front of pi, the coding agent. pi does the work: it reads and edits files, runs commands, and uses its own tools, skills and extensions. Dive runs pi in the background, shows its replies and activity, and asks you whenever pi needs an answer or a permission.

Before you start

  1. Install pi:

    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  2. Give pi access to a model. Start pi once in a terminal and run /login, then choose a subscription provider or store an API key. pi saves the key in ~/.pi/agent/auth.json. pi's quickstart guide lists the providers.

1. Open Pi mode

Pi mode is switched on from the start. Click the π icon in the top-left mode switcher. If it's missing, open Settings, go to the MODES tab and tick it under ENABLED MODES.

2. Check that Dive found pi

Open Settings. On the MAIN tab, PI EXECUTION holds pi's settings:

  • PI COMMAND PATH (OPTIONAL). Leave it empty and Dive looks for pi at /opt/homebrew/bin/pi, then /usr/local/bin/pi, then pi on your PATH. On Windows it looks for pi.cmd, pi.exe or pi.
  • PI WORKING DIRECTORY. The folder pi works in: where it clones, builds and edits files, and what relative paths start from. It defaults to your Dive data folder, ~/dive. Set it to the project you want pi to work on.

The summary under these settings shows the command Dive resolved, the working directory, whether pi's sandbox is on globally and for the project, and the configured and active server port. Press SAVE PI SETTINGS after a change.

3. Pick a model and a thinking level

pi starts only when a conversation needs it, so the lists fill in after your first message. Then the MODEL dropdown in the side panel lists pi's models, and the PI section below it sets the thinking level. You can also type these commands in the message box:

Command What it does
/models Lists pi's models
/model <name> Switches to a model
/think <level> Sets the thinking level: off, minimal, low, medium or high
/compact Compacts the session
/stats Shows session statistics
/help Lists these commands

4. Give pi a task

Type a request, for example:

List the files in this folder and summarise what the project does.

Dive starts a pi process for the conversation and streams pi's reply, with its tool activity, into the chat.

5. Answer pi's questions

When pi needs a decision, such as a permission, a choice from a list or some text, Dive opens a dialog with pi's options. If you close it, the PERMISSION button in the top bar opens it again.

If you don't answer in time, Dive applies TIMEOUT DEFAULT ACTION and shows a countdown in the dialog. By default it denies the request after 45 seconds. Set PERMISSION DECISION TIMEOUT to 0 to make Dive wait for you.

These two settings also decide what happens to unanswered permission prompts for Dive's own tools in the other modes. If you set TIMEOUT DEFAULT ACTION to Allow, an unanswered request is allowed there too.

Tools, skills and extensions in Pi mode

Dive's TOOLS and SKILLS tabs don't apply in Pi mode and are hidden. Everything comes from pi:

  • Tools. By default pi gives the model read, write, edit and bash.
  • Skills. pi loads skills from ~/.pi/agent/skills, ~/.agents/skills, pi packages, and the skills list in its settings. ~/.agents/skills is the same folder Dive reads, so one copy of a skill can serve both. Type /skill:name to load one.
  • Extensions and packages. pi loads extensions from ~/.pi/agent/extensions and from the packages in ~/.pi/agent/settings.json. Sharing with pi and Claude Code explains how to keep one copy of a repository that has both a skill and an extension.
  • Context files. pi reads ~/.pi/agent/AGENTS.md, and AGENTS.md or CLAUDE.md from the working directory and its parent folders.
  • MCP. pi has no MCP support, and Dive doesn't pass its MCP servers to pi.

The DATABASE switch in the side panel still works: with it on, Dive tells pi to answer only from your library's passages. A /db request that can't reach the library ends with an error instead of an answer that isn't grounded in it.

Settings for Pi mode

On the MAIN tab, in Pi mode:

Setting What it does Default
PI COMMAND PATH (OPTIONAL) A specific pi binary Empty: auto-detect
PI WORKING DIRECTORY The folder pi works in ~/dive
SERVER PORT Dive's own port, used by the whole app. Applies after a relaunch 8080
PI TIMEOUT (MS) The longest Dive waits for a pi request before stopping it 300,000 (5 minutes)
TRACE BUFFER CHARS Characters kept in the execution trace 12,000
PERMISSION POLICY Normal or Strict. Strict forces Deny on timeout and caps the timeout at 30 seconds Normal
TIMEOUT DEFAULT ACTION Deny or Allow, applied when a prompt times out Deny
PERMISSION DECISION TIMEOUT (MS, 0 = DISABLED) How long a prompt waits before the default action 45,000
EXPAND THINKING PANEL BY DEFAULT Opens reasoning expanded instead of collapsed Off
DIVE DATA FOLDER OPEN FOLDER and COPY PATH for the data folder

Pi mode also has its own colour palette, font and font size. The settings are saved in ~/dive/pi-settings.json.

How it works

For developers and agents:

  • routes/pi.js starts one pi --mode rpc process per conversation, adds --extension routes/pi-rpc-ui-compat.js, and exchanges JSONL with it over stdin and stdout. The extension lets pi's permission screen work over RPC, which is how its questions reach Dive's dialog. RPC records over 4 MB are rejected.
  • /api/pi/stream streams a turn. /api/pi/events is a Server-Sent Events channel that lets a window reattach to a run after a reload or a mode switch, replaying up to 256 events or 4 MB per conversation.
  • The commands in step 3 are handled in assets/js/06-pi.js and sent to pi as the RPC commands get_available_models, set_model, set_thinking_level, compact and get_session_stats.
  • diveSkills is false for Pi in assets/js/00-modes.js, and requireNonPiMode() keeps Dive's tool, skill and MCP routes away from it.

Troubleshooting

Symptom What to do
Dive can't start pi Check that pi runs in a terminal. Set PI COMMAND PATH if it's installed somewhere Dive doesn't look, then check the resolved command in the summary
The model list stays empty Send a first message: pi only starts when a conversation needs it. Make sure pi has a model through /login
pi works in the wrong folder Change PI WORKING DIRECTORY and press SAVE PI SETTINGS
Requests get denied without you answering That is the timeout default action. Raise PERMISSION DECISION TIMEOUT, set it to 0, or check PERMISSION POLICY
Long tasks stop after five minutes Raise PI TIMEOUT

Read next

Clone this wiki locally