01 — Install and first launch
Install and first launch
Perch is a single portable executable for Windows 10/11 x64. Download it, put it anywhere, and run it. There is no installer.
- Requires the WebView2 Runtime, ConPTY, and Job Objects.
- The build is unsigned, so Windows SmartScreen may ask you to confirm.
- The hook receiver unpacks to %LOCALAPPDATA%\Perch\bin; logs live at %APPDATA%\Perch\perch.log.
02 — Workspaces and Projects
Workspaces and Projects
A Project is a folder. Every new agent runs inside a real Project, and its terminal is the product surface.
- Workspaces opens first. The rail order is Workspaces / Overview / Settings.
- Add Project and New Agent are separate steps: choose or create the folder, then choose the agent.
- The old synthetic default area is no longer a target for new agents; its data remains on disk for the upcoming Chat mode.
- Closing a pane stops the run but keeps the record; reconnect by the original paneId later.
03 — First-run setup
First-run setup
The setup guide does not open at launch. It appears only when you try to add an agent and no installed, launchable agent is available.
- Install or select an agent.
- Connect the built-in gateway and a model.
- Finish closes the guide. It does not switch pages or launch an agent.
- If an agent is already available, New Agent opens the normal picker.
04 — Gateway and models
Built-in gateway and models
Perch includes a local gateway and applies models per pane. Gateway and provider configuration live in Perch's own directory, apart from your other agent configuration.
- The gateway runs locally. Provider keys, routing, usage, and plugins live in the embedded gateway console.
- Different panes can use different models without rewriting global agent configuration.
- If a profile cannot be applied, launch stops with a readable error instead of falling back silently.
- The gateway engine is provided by magpie; the console keeps its attribution and wording.
05 — Files
Read-only file rail
The right rail is a read-only view of the files around the active agent.
- Touched is a flat work list: filename plus its Project-relative parent path.
- All is a Project tree that opens at the root; expansion is remembered per Project for the session.
- Paths are shown relative to the Project. The full path is reserved for copy and reveal actions.
- Clicking a file opens an inline preview and never writes to disk.
06 — Data and privacy
Data and privacy
Perch has no account system and no telemetry of its own.
- %APPDATA%\Perch: settings, seat records, hook events, and logs.
- %LOCALAPPDATA%\Perch: the gateway engine, provider keys, and agent config sandboxes.
- Agent CLIs and magpie have their own network behavior and policies.
07 — Troubleshooting
Troubleshooting
Start with the log, then check these common cases.
- WebView2 is missing: install it from the prompt, or run winget install Microsoft.EdgeWebView2Runtime.
- SmartScreen blocks the app: choose More info → Run anyway; the beta is unsigned.
- An agent is missing: finish its install, then return to New Agent.
- Gateway or models are unavailable: open Overview → Gateway and check the connection and providers.
- For a report, attach %APPDATA%\Perch\perch.log; it does not contain provider keys.