Skip to content

Getting started

Working with Pi

NativePi is a window onto Pi, not a replacement for it. Knowing which of the two owns what makes the rest of the app predictable.

Who owns what

Pi owns the agent loop, providers, models, authentication, tools, prompts, skills, extensions, queues, compaction, and sessions. NativePi calls Pi and renders the result. It has no agent loop, makes no model requests of its own, and adds no tools.

A pinned Pi build is bundled with each release and started in RPC mode. NativePi keeps at most one Pi process per project, and different projects can run at the same time.

Sessions and credentials

Conversations are Pi session files. They live in Pi's normal storage and remain fully interchangeable with the Pi command line. There is no second conversation store.

~/.pi/agent
├── sessions/      # conversations, shared with the pi CLI
├── packages/      # installed Pi packages
├── settings.json  # agent configuration
└── auth.json      # provider auth, never held by NativePi

Conversations open directly from session files without waiting for a Pi process to start, so resuming is immediate. Credentials are never written to NativePi's renderer storage or its state file.

What you can do to a session

Create, resume, rename, clone, fork, delete, import, export to HTML, inspect the session tree and statistics, and compact. These workflows use Pi's session formats and APIs; NativePi performs the small desktop-side file operations where Pi has no direct command.

What NativePi stores

This is the complete list:

  • Pinned projects
  • The last project and chat you had open
  • Unsent text drafts
  • Favorite models
  • Pane sizes
  • Its own appearance and notification preferences

No conversations, no credentials, no telemetry. Nothing leaves your machine.

Settings

Agent configuration belongs to Pi. NativePi reads and writes it through Pi's own settings manager at user scope, so a change you make in the Settings screen is a change the Pi command line sees immediately. NativePi never writes Pi's configuration format itself, and it exposes only the settings that mean something in a desktop window.

Project-scope overrides remain the command line's business. NativePi does not edit them.

Git

The context pane shows Git status and working-tree diffs beside the transcript. From the composer you can switch or create a branch, and from the project menu you can add a worktree, which is then added as a NativePi project of its own.

Pi packages and extensions

Normal Pi extensions run inside Pi, unchanged. NativePi can install, update, remove, and reload Pi packages at user or project scope, and it shows load errors rather than swallowing them.

Pi's own slash commands, prompt templates, and skills are offered by name in the composer and run through Pi, including while a turn is already in flight. An extension that wants to draw its own desktop UI uses the graphical extension API.

Terminals

Each project can open integrated terminals in a resizable split. They stay alive while hidden and while another project is in front. If closing the window would stop an agent turn or a terminal, NativePi names what it would stop before quitting.

Browser access

NativePi can open an access-token-protected HTTP and WebSocket server on your local network, presenting the same projects, chats, changes, and terminals in a browser while the desktop app stays open. It runs until you stop it or NativePi exits.