Your code and app in one window

Tab "Files" in a detailed view of the task (Session · Diff · Graph · Terminal · Files · Git) shows a working copy of the task and the application launched from it next to the agent chat. The idea: see what the agent wrote, correct the line, see the result in the preview and point at the page element to explain to the agent, “this needs to be corrected,” without leaving Pulse and without opening five windows.

This is not a replacement for an external editor: the built-in editor is simple (no highlighting or auto-completion). For serious editing, there is an “Open on line N” button - it opens the same file on the same line in VS Code, Cursor or Windsurf.

Scope: whose working copy

Each tab operation is performed in clearly signed working copy. Signature in the tab header: “Working copy: task · …/task-12” or “Working copy: “Tester” session · …/task-12-tester.” Rule:

  • if selected in the task isolated session (with its own folder and branch, like the members of the swarm), the tab works with its folder;
  • otherwise - with the task folder.

The session of someone else's task is rejected by the main process (“Session does not belong to the task”). All paths are relative and inside the folder: .., absolute paths and symbolic links leading outwards are rejected before any read or write.

File list and search

The list is taken from git ls-files --cached --others --exclude-standard: ignored files (node_modules, dist, assemblies) are not shown. If the folder is not a repository - traversal of the directory without hidden folders and node_modules/dist/out. Search by path: case-insensitive substring, then fuzzy match (letters in order). No more than 5000 records; the line at the bottom says "N of M shown".

Editor and file version control

The file opens with content fingerprint (sha1 as in git hash-object). Saving (button or ⌘S / Ctrl+S) sends the text along with the fingerprint that the editor saw:

  • the fingerprint matches the one on the disk - the file is written atomically (temporary file + rename), rights are preserved;
  • didn't match — an agent or external editor changed the file after opening: the recording is not performed, the editor shows a red bar “The file... has been changed since opening” with two actions: “Reread” (your edits are lost) or “Overwrite with your version” (an explicit human decision: a record with the current fingerprint);
  • folder busy with the agent's progress (rent a working copy, see docs/modules/tasks/README.md) — saving is rejected with the message “Agent progress is being made in the working folder”; repeat after completing the turn.

While the file is open, the editor checks the fingerprint against the disk every 4 seconds. Without unsaved edits, he silently picks up the new version; with edits - shows the yellow bar “The file has been modified externally, and you have unsaved edits” and does not overwrite your text.

Limitations: binary files cannot be edited (only “Open in external editor”); files larger than 1 MB are shown as a fragment and read-only.

Open in external editor on line

The "Open on line N" button uses the editor's CLI (code --goto file:string, the same cursor, windsurf). If the command is not in PATH (typical on macOS without shell command installed), the file is opened by the application without going to line. The editor's choice is memorable.

Preview: Working Copy Application

The right panel launches the development command (by default npm run dev, is remembered for the task) in working copy this tab and displays the application in an inline frame.

How it works:

  1. Pulse allocates a free port (or one you specify) and passes it to the command via a variable PORT; each working copy has its own process and its own port, so two sessions of the same task do not interfere with each other.
  2. The address is taken from the command output (lines like Local: http://localhost:5173); if the command does not print it, Pulse waits for the port to open.
  3. Between the frame and the application is local proxy Pulse on 127.0.0.1: it skips requests and WebSocket (hot reload works), and adds a small element selection script to the HTML pages. The frame does not have privileged access to the application - it is a regular page.
  4. The status shows the status (starting · running · stopped · not started), pid, port, working copy and address; "output" expands the tail of stdout/stderr.

Stop - the “Stop” button (SIGTERM is sent to the process, after a pause SIGKILL). Deleting a task and exiting Pulse stops it from running. Preview does not restart itself after restarting Pulse: launch is a human action.

Select element → context for agent

“Select element” puts the preview into selection mode: hovering highlights the element, clicking fixes it. The card below shows the selector, text, and layout. “To session composer” adds a block to the draft of the selected session:

Preview page element (http://127.0.0.1:5173/; working copy .../task-12):
- selector: main > button.cta
- text: “Buy”
- the source in the code is not defined - find it using the selector and text
```html
<button class="cta">Buy</button>

A person sends it - the tab itself does not send anything to the agent. Linking to source
(`- source: src/App.tsx:42`) appears only when the application itself flags
elements (`data-source`, attributes of React/Vue dev plugins); otherwise it is honestly written that
the source is not determined, but not invented.

The preview page is someone else's code (the application and its dependencies), so the Pulse window
receives a message about the selected element only while the selection mode is enabled, only from
your iframe and only with the origin of your proxy; margins are trimmed to reasonable limits.
Residual risk: in selection mode, the page script can theoretically replace
card contents - the text in the card is taken from the page, look at it before
"Into the session composer" and before sending.

## Layouts

Switch in the header: **Files** · **Files + Preview** · **Preview**. Choice
memorable. On a narrow window, the panels are placed one below the other.

## What's where in the code

| Layer | File |
|---|---|
| Working copy files: paths, list, read, write with version | `src/main/files/workspaceFiles.ts` |
| Application launch, port, address, proxy, stop | `src/main/preview/devServer.ts`, `proxy.ts`, `picker.ts` |
| IPC: `pulse:files-list/file-read/file-write/open-editor-at/preview-*` | `src/main/ipc.ts` |
| Files tab, editor, preview, element card | `src/renderer/src/components/files/FilesView.tsx` |
| Draft session (adding context) | `src/renderer/src/store.drafts.ts` |