IDE guide
The IDE that ships the app.
Piye IDE is a desktop editor with an agent that can operate the whole workbench: the editor, terminal, Git, tests, debugger, simulators, deploy, and operations. It opens the same project a founder builds in Builder, so the hand-off is just opening the folder.
Start
Piye IDE
Piye is built on Electron, React, and Monaco, and Piye owns every line of its interface. It is not a VS Code fork and does not try to look like one. What you get on day one, with no extensions: TypeScript and JavaScript language services, a real terminal, Git, search, debugging, testing, a ports view, Docker status, simulators, deploy, and an agent that can use all of it.
AI native
Built in beats extension
Speed is a feature
Start
How Piye is different
If you come from Cursor, Zed, or VS Code, the editor will feel familiar within minutes. The difference is everything around the editor.
| What feels familiar | What Piye adds | |
|---|---|---|
| Editing | Monaco, tabs, splits, palette, multi-cursor | Tab ghost text and ⌘K on the live buffer, with next-edit hints |
| Agent | Chat with your codebase, file edits with diffs | Four modes with hard limits, and piye_action to operate the IDE itself |
| Team | Git, branches, pull requests | A no-code Builder on the same folder for the non-technical side |
| Mobile | Run Expo or React Native from a terminal | iOS Simulator and Android emulator side by side, inside Piye |
| Shipping | Deploy from CLIs and CI | Deploy panel for web hosts and app stores, with env sync by key name |
| Production | Dashboards in other tabs | Operations: live probes of hosts, CI, stores, and Stripe in one panel |
| Tools | MCP via JSON config | One-click MCP Connect with browser OAuth, no JSON editing |
| Privacy | Bring your own key | BYOK, Piye Cloud, and Privacy Mode with local Ollama |
What Piye is not
Start
Workbench tour
Explorer
app
page.tsx
layout.tsx
components
lib
.piye
package.json
Tab to accept
Terminal · zsh
❯ pnpm dev
✓ Ready on localhost:3000
Panels can be resized, collapsed, and popped out into their own windows. View, Reset Workbench Layout brings everything back.
Start
Open a project
- 01
Open a folder
File, Open Folder. Add more with Add Folder to Workspace. - 02
Or clone
Pick a repository from your GitHub on the Welcome screen. - 03
Or switch from Builder
Open the project name menu in Builder and choose Developer. Same folder, now in the IDE.
Tip
.piye/. Commit the parts you want to share (rules, launch configs, tasks) and ignore the rest. See The .piye folder.Edit
Editor
- Monaco with language services for TypeScript, JavaScript, HTML, CSS, JSON, and Markdown.
- Tabs, editor groups, and ⌘\ to split right. Join All Editor Groups to merge back.
- Breadcrumbs and an outline of symbols for the current file.
- Format on save, auto save, word wrap, minimap, and font settings under Settings, Editor.
- A Simple Browser for quick looks at docs or a local URL.
Edit
Tab and Cmd+K
Tab: ghost text
⌘K: inline edit
Note
Edit
Search and replace
⌘⇧F searches the whole project with ripgrep and respects your ignore files. ⌘⇧H replaces across files with a preview. In the agent, identifier search and "search by meaning" are available as tools.
Edit
Diffs and merge conflicts
- Compare with Saved and Compare with Clipboard from the File menu.
- Resolve Merge Conflicts opens a dedicated view for conflicted files.
- Agent file cards open as diffs before you accept them.
Agent
Agent panel
Open it with ⌘⇧A, or pop it out into its own window. Pick a mode and a model, attach files or images, and talk to your project. The agent sees what you see, so you never paste the file you are looking at: say "this" or "here" and it quotes your visible range.
Agent
Agent modes
Ask
Answers and explains, read-only.
Can: Read files and live buffers, search, git hunks, diagnostics, terminal, tests, web search, fetch pages, inspect localhost.
Cannot: Create, edit, delete, run shell, or operate the IDE.
Architect
Plan only.
Can: Read everything Ask can, and produce a plan.
Cannot: Edit, run shell, or operate the IDE. Switch to Build to implement.
Build
Implement.
Can: File cards for create and edit, approved one-shot commands, piye_action to run Expo, Next, tests, deploy, git, and the debugger. MCP tools.
Cannot: Delete without your approval.
Debug
Reproduce and fix.
Can: Diagnose, make surgical edits, short commands, piye_action.
Cannot: Create files, refactor, or start long-lived servers with shell.
The agent operates the IDE
piye_action instead of telling you which button to press: start Expo or Next, boot a simulator, run tests, Deploy Now, stage a hunk, commit, reveal a line. After a patch it runs the failing test and only says done when tests and problems are clear.Agent
Review and Auto
| Setting | Creates and edits | Deletes | Commands |
|---|---|---|---|
| Review | Wait for Accept on each file card | Always wait | You approve each one |
| Auto | Written as proposed | Always wait | You approve each one |
Accepting a card applies the edit to the open tab and writes disk, so the tab is clean afterwards. Closed files are written to disk directly.
Agent
What the agent sees
Each turn starts with a live snapshot of the workbench. No copy and paste needed.
| Context | What is in it |
|---|---|
| Editor | Open tabs, dirty flags, focused file, cursor, visible range, unsaved buffers. |
| Terminal | Last 200 lines per session (up to 16k characters), Piye and Classic sessions. |
| Git | Branch, dirty files, last commits, and the actual working-tree hunks. |
| Problems and tests | Diagnostics, discovered tests, pass and fail, failing file and line. |
| Debug | Session status, paused location, call stack, breakpoints, console tail. |
| Ports | Listening ports, process names, local URLs. Avoids starting a second dev server. |
| Deploy and operations | Host, link, production URL, env names (never values), build log, live probes. |
| Project rules | .piye/rules.md, AGENTS.md, and .piye/rules/*.md. |
Secrets stay secret
.env.Agent
Checkpoints and undo
At the start of every turn Piye records a checkpoint: your dirty buffers and the Git HEAD. Undo on a turn restores those buffers and reverts the file cards you accepted in it.
Agent
Project rules
Put conventions the agent should follow in .piye/rules.md, AGENTS.md, or several files under .piye/rules/. They are injected into every turn, capped so they never crowd out your code.
# House rules
- TypeScript strict. No any.
- Server components by default; "use client" only for interaction.
- Tailwind for styling. No inline styles.
- Every API route validates input with zod.
- Run pnpm test before saying done.Run
Terminal
Piye sessions
Classic sessions
- ⌘` toggles the panel, ⌘⇧` opens a new terminal. Split Terminal sits next to it.
- ⌘⇧T pops the terminal into its own window.
- Commands the agent runs with approval use a separate process and do not appear in your terminal. IDE actions like starting Expo write into the terminal you already have.
Run
Git and source control
Branches
Hunks
Agent aware
Run
Testing
The Testing panel discovers tests in your project and runs them from the panel or the editor gutter. The agent uses the same commands, so "fix the failing test" means it can run it, patch, and run it again.
Run
Run and Debug
Run and Debug speaks the Debug Adapter Protocol. Configurations live in .piye/launch.json. Set breakpoints in the gutter, step through code, and read variables, the call stack, and the debug console.
{
"configurations": [
{
"name": "Next.js: server",
"type": "node",
"request": "launch",
"runtimeExecutable": "pnpm",
"runtimeArgs": ["dev"],
"cwd": "${workspaceFolder}"
}
]
}Run
Problems and tasks
- Problems collects diagnostics from language services. Click one to jump to the file and range.
- Tasks run your package scripts and anything in
.piye/tasks.json. ⌘⇧B runs the build task. - Output shows logs from tasks, extensions, and Piye itself.
Run
Ports
Ports lists every listening TCP port on your machine with the process name and a local URL to open. The agent checks it before suggesting npm run dev, so you do not end up with two servers fighting over port 3000.
Ship
Apps, devices, stores
The Apps view has four tabs: Project, Devices, Stores, and Setup. Piye detects each app from its package.json, including nested apps/, packages/, and mobile/ folders in a monorepo.
| Detected | From | Run means |
|---|---|---|
| Mobile Expo | expo or expo-router | Boot the real iOS Simulator or Android emulator. Start Expo runs Metro with a QR code. |
| Mobile Native | React Native, Capacitor | Run on simulators and emulators. |
| Desktop Electron | electron, Electron Forge, electron-vite, Tauri | Open a native window, not a phone. |
| Website Web | next or vite without a native runtime | Open the URL in your browser. |
{ "runtime": "expo" }Pin the stack with .piye/app.json to skip detection. Stores connects App Store Connect, Google Play, and EAS so you can submit builds without leaving Piye.
Note
Ship
Deploy
Deploy shows the selected host, sign-in state, the linked project, production URL, environment variable names with sync status, Docker engine status, and the build log. Deploy Now ships it.
EU sovereign hosting
Env by name
Docker: Engine offline
Ship
Operations
Operations (⌘⇧O) is your production radar. It probes the services your project actually uses and streams what changed: failed deploys, CI runs, store reviews, Stripe events, new CVEs.
| Probe status | Means |
|---|---|
| ok | The query succeeded. It does not mean everything is fine in production. |
| auth | Piye needs you to sign in to that service. |
| error | The query failed. Retry or check the service. |
| blind | Piye cannot see that service yet. |
The header's Watching N is the number of live adapters being probed (Railway, Vercel, Hostinger, GitHub, Expo and EAS, Stripe, the stores). Operations also helps set up SEO, analytics, consent, and edge configuration by writing the code into your project.
Extend
MCP integrations
Press Connect on a marketplace card. Piye writes the launcher into its own MCP config and runs the sign-in. No API key forms, no JSON editing.
| Service | How it connects |
|---|---|
| Notion, Linear, Stripe, Vercel, Hostinger | Browser OAuth window. Connected when it finishes. |
| GitHub | Uses gh auth login or GITHUB_TOKEN. |
| Postgres | Needs DATABASE_URL in the environment Piye was launched from. |
| Figma | Enable desktop MCP in Figma Dev Mode, then Connect. |
| Slack | Needs your Slack app client id and secret, with Piye's local redirect URL. |
| Framer | Paste the URL from the Unframer plugin into the card. |
Note
ready on a card means its tools are live for the next Build turn; failed shows the reason, and Retry reinstalls.Extend
Extensions and OXP
OXP
VS Code extensions
Extend
Models and keys
Piye Cloud
Your keys
Local
The status bar shows the active model and route. Change the default in Settings, AI, or per conversation in the Agent panel.
Reference
The .piye folder
| Path | What it holds |
|---|---|
rules.md | Rules for the agent. Also rules/*.md. |
app.json | Pinned runtime for the Apps view. |
launch.json | Run and Debug configurations. |
tasks.json | Extra tasks beside your package scripts. |
keybindings.json | Your keyboard overrides. |
mcp.json | Optional project-scoped MCP servers. Connect writes the user config, not this. |
blueprint.json | The Builder Blueprint map. |
memory/ | Comm-Link and Builder memory, notes, build timings. |
outbox/ | Emails your app sent in development. |
brief/ | The original brief and logo. |
Reference
Keyboard shortcuts
Shown for macOS. On Windows and Linux, ⌘ is Ctrl. Open the full list with ⌘⇧/ and override any of them in .piye/keybindings.json.
Reference
Pop-out windows
View, Open in New Window pops out the Agent, Operations, or Terminal. Each keeps working on the same project, so you can put the agent on one screen and the code on another.
Reference
Editions and roadmap
| Edition | Includes | For |
|---|---|---|
| Lite | Core editor, JS and TS, Git, AI | Pure editing |
| Web Default | Lite plus Tailwind, Prettier, ESLint, web languages, dev server, HTTP client | Web developers |
| Pro | Web plus Python, Jupyter, Docker, debug, database tools | Full stack, data, AI |
On the way
- Jupyter notebooks with real kernels from your own Python environments.
- Built-in Tailwind IntelliSense, Prettier, and ESLint without extensions.
- Inline blame, file history, and conflict resolution in Git.
- An agent task queue for running several agents in parallel.
- The OXP registry with signed packages.