Repository navigation
Pi mode
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.
-
Install pi:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
-
Give pi access to a model. Start
pionce 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.
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.
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, thenpion your PATH. On Windows it looks forpi.cmd,pi.exeorpi. -
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.
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 |
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.
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.
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,editandbash. -
Skills. pi loads skills from
~/.pi/agent/skills,~/.agents/skills, pi packages, and theskillslist in its settings.~/.agents/skillsis the same folder Dive reads, so one copy of a skill can serve both. Type/skill:nameto load one. -
Extensions and packages. pi loads extensions from
~/.pi/agent/extensionsand 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, andAGENTS.mdorCLAUDE.mdfrom 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.
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.
For developers and agents:
-
routes/pi.jsstarts onepi --mode rpcprocess 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/streamstreams a turn./api/pi/eventsis 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.jsand sent to pi as the RPC commandsget_available_models,set_model,set_thinking_level,compactandget_session_stats. -
diveSkillsis false for Pi inassets/js/00-modes.js, andrequireNonPiMode()keeps Dive's tool, skill and MCP routes away from it.
| 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 |
These pages describe Dive 5.0.8. Source code: DuckTapeKiller/dive. Spotted a mistake? Open an issue.
Get started
Tools and skills
Build your own
Share and stay safe
How Dive works
Help