Skip to content

Using NativePi

Sessions and storage

Pi session files are the conversation source of truth. NativePi keeps only the desktop state that Pi does not own.

Pi data

~/.pi/agent
├── sessions/      # conversations shared with the Pi CLI
├── npm/           # npm-sourced packages installed by Pi
├── git/           # git-sourced packages installed by Pi
├── settings.json  # agent configuration and package declarations
├── mcp.json       # optional MCP server configuration
└── auth.json      # provider credentials managed by Pi

NativePi opens and updates conversations through Pi's session formats and APIs. You can resume the same session from the Pi command line, and a session created in the command line appears in NativePi's project history.

These are the default locations. Pi honors PI_CODING_AGENT_DIRfor a custom agent directory and PI_CODING_AGENT_SESSION_DIRfor session storage. Check Settings → System for the agent directory this app uses. Local packages remain at their original paths.

Session actions

NativePi can create, resume, rename, clone, fork, delete, import, and export sessions. It also presents Pi's session tree, statistics, and compaction workflows. Forks and clones remain ordinary Pi sessions, not NativePi-specific copies.

Right-click a chat for its actions, including View chat branches…, Export to HTML, and Delete chat…. Choose Import an existing chat from the project actions menu, or drop a Pi session file into the window.

NativePi data

NativePi persists only interface state:

  • Pinned projects and chats
  • Focus and Finished organization
  • The last open project and chat
  • Unsent text drafts
  • Favorite models
  • Pane sizes
  • Custom color schemes and source-control preferences
  • Appearance, notification, and keyboard-shortcut preferences
  • The selected Stable or Nightly release channel

It does not put conversations or credentials in that state file and does not send NativePi-owned desktop telemetry. Pi's optional analytics remain a Pi setting.

The desktop state file is state.json in Electron's per-user app data directory. Removing that file resets NativePi's interface state; it does not delete Pi sessions or credentials.

The release-channel preference is stored separately in update-channel.json in the same app data directory.

External changes

Because NativePi and the CLI share files, do not actively write to the same session from two processes. NativePi detects external changes where continuing could overwrite newer data and fails conservatively instead of silently replacing them.

Related guides