Pi Web is the native web interface of Pi Coding Agent. It does not transform Pi into another cloud agent. Instead, it reads existing Pi session files on the local machine and displays conversations, tool calls, context usage, model settings, skills, and project files in the browser.
Project address:
https://github.com/agegr/pi-web
The scenario for which it is suitable is clear: you are already using the Pi, but you don’t want to scroll through the history session in the terminal all the time, or you want to continue the same Agent task while looking at the project file.
Confirm before installation
On Windows, prepare:
- Node.js and npm;
- Pi Coding Agent that is already in normal use;
- PowerShell or Windows Terminal;
- A project directory managed by Git.
Check Node.js:
|
|
Pi Web reads by default:
|
|
If the Pi has not spawned any sessions, the web page can be launched, but the session list may be empty.
Run directly without installation
The easiest way is to use npx:
|
|
After the service is started, it will try to open the browser automatically. The default address is:
|
|
This method is suitable for first-time experience. There is no need to permanently install the command to the global npm directory.
Global installation
Frequently used can be executed:
|
|
If PowerShell prompts that pi-web cannot be found, check whether the npm global directory is in PATH:
|
|
After modifying PATH, you need to reopen the terminal.
Modify port and listening address
When used only on this machine by default, it is recommended to explicitly bind the loopback address:
|
|
Modify port:
|
|
Use in combination:
|
|
As a background service, you do not want to automatically open the browser:
|
|
Do not directly bind 0.0.0.0 and open the public network port just to access it from your mobile phone. Pi Web can read Agent sessions, project files, and model configurations, which may include source code, file paths, prompt words, and tool output.
Configure HTTP proxy
Pi Web reads standard proxy environment variables. Windows PowerShell example:
|
|
These variables only take effect within the current PowerShell session. NO_PROXY is very important, otherwise it may also be sent to the proxy when accessing the local service.
What to do if the Pi session cannot be found?
Pi Web reads JSONL sessions from ~/.pi/agent/sessions by default. If your Pi data directory is not in the default location, set:
|
|
First check if the directory actually exists:
|
|
Sessions are organized by project working directory. If the same repository has been opened from different drive letters, soft links or WSL paths, it may be recognized as different projects.
What can be managed in the web page?
Pi Web mainly provides these functions:
- Browse past Pi sessions by project;
- Continue, fork or create new branches from old messages;
- View Markdown, tool calls and contextual compression status;
- View project source code, documents, images, audio and PDF;
- Manage models, login information, API Key and model testing;
- Turn Skills on or off;
- Switch between Git Worktrees.
It reads and writes the local Pi configuration and session, not a separate copy of the cloud state. Before modifying model configuration or session branches, it is a good idea to back up the .pi directory.
What is the difference between Fork and intra-session branching?
Fork in Pi Web creates a new JSONL session file, suitable for trying another implementation route from a node while retaining the original session.
“Edit from here” creates a branch within the same session file. It’s more lightweight, but less intuitive to organize and migrate than standalone files.
If you want to compare two implementations or hand off to different Worktrees, Fork first; just to correct a prompt or go back to the previous step, use in-session branching.
Cooperate with Git Worktree
Worktree is suitable for allowing different Agent sessions to process different branches in independent working directories to avoid modifying the same file at the same time.
First create a Worktree in the main repository:
|
|
Pi Web’s sidebar can toggle recognized Worktrees and allow new sessions and file browsers to follow the corresponding directories.
After completion, first confirm that the branch content has been submitted, and then remove it:
|
|
Do not force deletion of Worktree when uncommitted modifications exist.
FAQ
The page opens but there is no history
Check that PI_CODING_AGENT_DIR, the default sessions directory, and the current Windows user are correct. Running it once as an administrator and once as an ordinary user may also produce two different sets of user directories.
Port is occupied
Change a port:
|
|
Or query occupied processes:
|
|
Model request failed
First confirm that the same model can be used in Pi CLI, and then check whether the Pi Web process inherits the proxy variables and API Key. If the web page can be opened, it only means that the local service is normal, but it does not mean that the model supplier is successfully connected.
The project file cannot be seen
The scope of the file preview is limited by the selected project directory and session working directory. Confirm that the session is indeed started from the target repository and do not enter the project through inconsistent drive letter mapping or soft links.
Security recommendations
Pi Web touches model configurations, agent sessions, and project files. suggestion:
- Default binding
127.0.0.1; - Do not map the port directly to the public network;
- Do not expose API Key, prompt words and private source code in screenshots;
- Back up the Pi session directory regularly;
- Check uncommitted modifications before switching or deleting Worktree;
- Confirm code and model data usage policies in company projects first.
Pi Web is more suitable for existing Pi users to improve session management. If you are just looking for an Agent that can write code, you should first run through the Pi CLI model, permissions, and basic workflow before installing the web interface.