PerchAI
Using Perch

Workspace

The Perch workspace on Desktop and CLI is a scoped folder with a real file browser, an editor with diffs, a live terminal, artifacts, and a browser. Here is what each part does.

When you work in Perch on Desktop or the CLI, you are not working in a chat box that happens to accept file uploads. You are working inside a scoped workspace: a folder Perch can read and write, a file browser and editor, a real terminal, artifacts for long-form output, a browser it can drive, and a trail of sources behind its claims.

This page covers what each part is. For the tools Perch uses inside the workspace, see the agent harness.

Folder scope is the boundary

Perch works from the folder you choose, and that choice is a permission boundary rather than a convenience. Filesystem access is validated per call against approved roots, so Perch cannot wander outside the folder you pointed it at. There is no whole-disk indexing.

Keep the relevant material together, and leave out what you do not want in scope. Changing the folder changes what Perch can see, read, and edit.

The file browser and editor

The desktop app gives you the workspace as a real interface, not just as something the model talks about. It lives in the side panel, which switches between Files, Terminal, and Browser:

  • File browser. Navigate the folder tree Perch has access to.
  • File viewer with syntax highlighting. Open any file and read it with proper language coloring, the same tokenizer the chat transcript uses for code blocks.
  • Inline editing. Edit a file directly in the panel and save it, or revert your changes, without leaving Perch or switching to another editor.
  • Diff view. See what changed as a line by line diff, which is also how proposed changes from background agents are presented for review.

If Perch changes files you did not want changed, /rewind lists the messages whose file changes can be undone and /undo restores the latest. See Slash commands.

The terminal

The desktop app runs a real terminal pane, not a simulated one. Commands Perch runs appear there, and you can drive it yourself in the same session. Long-running commands can be handed off to the background, where Perch can check on them, wait for them, or stop them while continuing to work on something else.

Artifacts

Long-form output becomes an artifact rather than being buried in chat scrollback: documents, code, pages, tables, charts, and images. It is the right home for work that is meant to leave Perch as a file.

In the desktop app, an artifact opens in the side panel from its card in the chat, and the Artifacts library collects outputs across chats so you can find them later. The CLI has no panel, so documents, code, and tables print under the step that made them, and a page is saved as a file with a link you open in your browser. See Artifacts for previews, revisions, downloads, and share links.

The browser

In the desktop app, Perch can operate web tools you are already signed into, using the browser session you control rather than asking every app for its own OAuth grant. It drives the page from the accessibility tree and screenshots together, which is also how you can point it at a local dev server and have it look at what it just built.

The CLI has a browser too, without a window. It starts a headless Chrome, Edge, or Chromium the first time a task needs one, in a temporary profile that is not signed in to anything. That is enough to look at a local dev server or a public page. Work inside apps you are signed in to belongs in the desktop app.

See the agent browser for what it can do and how to take the wheel yourself.

The source trace

Claims point back to the material Perch read. In writing work, unsupported claims are marked before they reach a final draft. See citation verification.

What differs by surface

The workspace is not identical everywhere, and the differences are worth knowing before you pick a surface.

DesktopCLIPerch AI Web
Folder access, read and writeYesYesNo
File browser, editor, diff viewYesTerminal UINo
TerminalYesIt is the terminalNo
Folder index and retrievalYesNoNo
BrowserYes, in the side panelYes, headlessNo
ArtifactsSide panel and libraryPrinted in the terminalYes

The CLI is a full terminal UI rather than a stripped-down client, and it does the same file and command work as Desktop. What it does not carry is the folder index, the side panel, and a browser signed in to your accounts. Perch AI Web is the light front door: upload, ask, and get an answer with its sources, with no local folder.

Perch Terminal also opens in a browser on Pro and Ultra, at chat.perchai.app/agents/desktop. There it runs cloud agents in a private cloud workspace, or sends messages to your own computer with remote control. Your local folders open only in the desktop app.