pi-code

Warning

This project is in a very early stage of development. Expect rough edges, breaking changes, and incomplete features. Use at your own risk and please report any issues you encounter — contributions and feedback are welcome!

A desktop coding assistant powered by pi. Built with Electron, React, and TypeScript.

pi-code wraps the pi coding agent in a native desktop app with a full-featured UI — chat conversations, file browsing, git integration, an embedded terminal, plan mode, and more. Think of it as a GUI shell for pi that lets you interact with AI coding agents without leaving your editor-like environment.

Features

• AI Chat — Conversational coding sessions powered by the pi coding agent SDK
• Multi-session — Run multiple independent conversations across different projects
• File Browser — Browse and view project files alongside your conversation
• Git Integration — View diffs, stage changes, and commit directly from the app
• Embedded Terminal — Full terminal access via xterm.js without leaving the app
• Plan Mode — Toggle between implementation and planning modes for more deliberate workflows
• API Key & OAuth Management — Configure API keys or sign in with OAuth (Anthropic, OpenAI Codex, GitHub Copilot, Google) directly from Settings
• Model Selection — Switch between available AI models and thinking levels on the fly
• Web Fetch — Fetch and reference live documentation from URLs during conversations
• Skills — Load specialized skills for domain-specific tasks (shadcn, animations, design, etc.)
• Browser Preview — Embedded browser view for previewing web apps
• Cross-platform — Runs on macOS, Windows, and Linux

Tech Stack

Layer	Technologies
Shell	Electron · electron-vite
Frontend	React 19 · TanStack Router · Tailwind CSS 4
UI Components	shadcn/ui · Radix UI · cmdk
Code & Terminal	Monaco Editor · Shiki · xterm.js
AI Agent	@mariozechner/pi-coding-agent · Vercel AI SDK
Animations	Motion

Prerequisites

• Node.js >= 20
• npm >= 10
• API keys or OAuth login for at least one supported AI provider — configure these in the app's Settings page, or set environment variables (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY)

Getting Started

Install dependencies

npm install

Run in development

npm run dev

This starts the Electron app in dev mode with hot-reload for the renderer process.

Build for production

# macOS
npm run build:mac

# Windows
npm run build:win

# Linux
npm run build:linux

Built artifacts are output to the dist/ directory.

macOS notarization

This project is configured to notarize macOS builds automatically when Apple credentials are present in the environment.

Recommended setup uses an App Store Connect API key:

export APPLE_API_KEY=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
export APPLE_API_KEY_ID=XXXXXXXXXX
export APPLE_API_ISSUER=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Alternative Apple ID setup:

export APPLE_ID=you@example.com
export APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
export APPLE_TEAM_ID=XXXXXXXXXX

You'll also need a valid Developer ID Application certificate installed in your macOS keychain.

Then build as usual:

npm run build:mac

If the required Apple environment variables are set, electron-builder will sign and notarize the app during the macOS build.

Project Structure

src/
├── main/                  # Electron main process
│   ├── index.ts           # App entry point, window creation, IPC registration
│   ├── ipc/               # IPC handlers (auth, sessions, terminal, git, files, browser)
│   └── services/          # Core services
│       ├── auth.ts         # API key and OAuth credential management
│       ├── pi-runner.ts   # Agent session lifecycle and streaming
│       ├── session-manager.ts  # Session persistence
│       ├── git.ts         # Git operations
│       ├── terminal.ts    # PTY terminal management
│       ├── browser.ts     # Embedded browser management
│       ├── projects.ts    # Project discovery and management
│       ├── extensions/    # Pi extensions (plan-mode, load-skill)
│       └── tools/         # Custom tools (webfetch)
├── preload/               # Electron preload scripts (context bridge)
├── renderer/              # React frontend
│   └── src/
│       ├── components/
│       │   ├── ai-elements/   # Chat UI components (messages, prompt input, etc.)
│       │   ├── shell/         # App shell (sidebar, file browser, git, terminal, etc.)
│       │   └── ui/            # Base UI components (shadcn)
│       ├── lib/           # Client-side utilities and state
│       ├── hooks/         # React hooks
│       └── routes/        # TanStack Router file-based routes
├── shared/                # Types and utilities shared between main and renderer
└── components/            # Shared component source (shimmer, etc.)

Scripts

Command	Description
npm run dev	Start the app in development mode
npm run build	Typecheck and build all processes
npm run build:mac	Build distributable for macOS
npm run build:win	Build distributable for Windows
npm run build:linux	Build distributable for Linux
npm run typecheck	Run TypeScript type checking
npm run lint	Run ESLint
npm run format	Format code with Prettier

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a branch for your feature or fix: git checkout -b my-feature
3. Install dependencies: npm install
4. Run the app: npm run dev
5. Make your changes — the renderer hot-reloads, but main process changes require a restart
6. Typecheck: npm run typecheck
7. Lint: npm run lint
8. Submit a pull request

Development Notes

• Main process (src/main/) runs in Node.js and manages agent sessions, git, terminal PTYs, and IPC communication with the renderer.
• Renderer process (src/renderer/) is a React SPA bundled with Vite. It communicates with the main process exclusively through the preload bridge.
• Shared types live in src/shared/ and are imported by both processes.
• The app embeds the pi coding agent SDK — agent sessions, model selection, streaming, and tool execution all happen in the main process and are streamed to the renderer over IPC.
• Hot-reload works for the renderer. For main process changes, restart the dev server.

Acknowledgements

This project was heavily inspired by Cursor Glass. Huge thanks to the Cursor team for pioneering the desktop AI coding assistant experience.

License

MIT