Workbench

Chat is where you talk to your agent. The workbench is where you can see and touch what it's actually doing: the files it's editing, a shell to run commands in, and a browser to check its work in.

It lives in the panel to the right of chat, as a set of tabs: Files, Canvas, Browser, and Terminal. Open a chat and they're right there, no setup needed.

Quick Win: Open a File in 5 Seconds

1. Open a chat (any project you've added to DorkOS works).
2. Click the Files tab in the right panel.
3. Click any file in the tree.

It opens in the Canvas tab, in a viewer built for what it is: code gets an editor, images get zoom, PDFs get a reader. You just went from "where's that file" to reading it, in three clicks.

Files: Browse, Create, Rename, Move, Delete

The Files tab shows a tree rooted at your chat's working directory. If that directory is a git checkout, a small branch badge tells you which one, so you always know which workspace you're looking at.

• Browse: folders expand on click, loading their contents as you go (large projects stay fast because DorkOS only loads what's on screen).
• Create: the New File and New Folder buttons in the tab's toolbar add an entry inside the selected folder (or the root, if nothing's selected).
• Rename: right-click a file or folder (or long-press on touch) and choose Rename. The name field opens inline with the base name pre-selected, so typing replaces it and the extension survives untouched.
• Move: drag a file onto a folder to move it there.
• Delete: right-click and choose Delete.

Two more toolbar buttons round it out: an eye icon toggles hidden files (dotfiles) on and off, and a refresh button re-reads the tree from disk, in case something changed outside DorkOS.

If a create, rename, or delete fails (a name collision, a permission problem), a toast tells you why. Nothing silently disappears.

Viewers: The Right Tool for Every File

Click a file and DorkOS picks the viewer that fits it:

Code and markdown files open read-only by default. Click the pencil icon to start editing; it turns into a checkmark you click to stop and save. While you're editing, DorkOS holds back any agent update to that specific file, so your keystrokes and the agent's writes never collide. Every other open file keeps updating live.

When the agent does try to change what you're editing, a short notice appears above the document: "Your agent changed this while you were editing, so nothing here moved." Reload shows their version and ends your edit; Keep mine throws theirs away. Agents are told up front that this is how it works, so "I've updated that" from your agent is never a claim that it replaced what's on your screen.

If the file changed on disk while you had it open (say, the agent edited it too), DorkOS tells you before your save could clobber it, with a choice to reload the new version or overwrite it with yours.

Terminal: A Real Shell, Right There

Open the Terminal tab and you get an actual shell, running in your chat's working directory. No extra window, no cd-ing back to where you were.

• Multiple tabs: click the + to open another terminal; each gets its own numbered tab.
• Survives a refresh: close the browser tab or hit reload, and your terminals are still running when you come back. DorkOS reattaches to the same live shell instead of starting a fresh one.

Browser: Preview Without Leaving DorkOS

The Browser tab is a browser inside DorkOS, with the controls you expect: back, forward, reload, and an address bar you can type into. Type an address yourself, or let your agent send you a page.

• Local HTML files render right there, relative links and pictures included.
• Dev servers you're running — Vite, Next, anything on a localhost address — render too, from any device that reaches your DorkOS machine directly: your laptop, your phone, a tablet on the couch. Live reload keeps working. Through a tunnel, or an HTTPS proxy sitting in front of DorkOS, the tab can't reach the preview; it tells you so and offers the "Open in system browser" button in the toolbar, which is always there.
• External sites are framed too, when the site allows it. When a site refuses (many do, for security), DorkOS shows an "Open in system browser" button instead of a blank frame.
• When something goes wrong, the tab says so instead of showing a blank white page: nothing running on that port, a page taking too long, or a page that failed to load some of its own files.
• Each page keeps its own back/forward history, so switching between two open pages never mixes up where you were.

A page here isn't only something to look at. Ask your agent to try the signup form and it will: it can click buttons, fill in fields, scroll, and read the page back to see what happened — in the tab you're watching, on the page you're looking at. See "Agents can check their own work, and act on it".

Multi-Document Tabs

Canvas and Browser each hold more than one thing at a time, and each keeps its own set. Open three files and they line up as tabs across the top of Canvas, exactly like a code editor. Open three pages and they line up the same way across the top of Browser. Click a tab to switch, click its x to close it.

Each tab also remembers where you were. Switch to Browser and back, and the file you were reading is still the one on screen.

If you (or the agent) open something that's already open, DorkOS switches to that existing tab instead of opening a duplicate.

Your tabs live on your DorkOS machine, not in one browser. Open the same chat on your phone and the same things are open; close one there and it closes on your laptop too. Clearing your browser data doesn't cost you your tabs, and a second window on the same chat shows the same set rather than its own.

Reviewing Changes: See Exactly What the Agent Edited

When the agent edits a file, DorkOS opens a diff for it automatically — a view of just the lines that changed since the agent started, not the whole file. You read three changed lines instead of hunting through three hundred.

Every changed block (a "hunk") has two controls in the margin:

• Accept keeps the agent's change and settles the block out of your way.
• Reject undoes that one block on disk — the lines snap back to how they were before the agent touched them. Everything else the agent did stays.

Above the diff you can Reject all (undo every change to the file at once) or Mark reviewed (you're happy — later edits will diff from here). On a wide screen, a toggle switches between the stacked inline view and a side-by-side before/after. A second toggle compares against your last commit instead of the chat's starting point, if you'd rather see it that way.

If the file changes underneath you — say the agent edits it again while you're reviewing — you get a calm "this file changed" notice with a Refresh button, never a silent overwrite. A change that fails to write (a permissions problem, a dropped connection) tells you so too, so you can try again.

Sometimes DorkOS has no snapshot from when the agent started — for example, if the server restarted mid-chat. When that happens the header says so plainly and compares against your last commit instead. In that state, Reject all asks you to confirm first, because it would also undo edits you made yourself before the chat.

Changed images get their own comparison, in the style you may know from GitHub: 2-up shows before and after side by side, Swipe puts them in the same frame with a divider you drag, and Onion skin blends between them with a slider. Because an image changes as a whole, the review is whole-file: Restore previous puts the old image back on disk (it asks you to confirm first), and Mark reviewed keeps the new one. An image the agent just created has no previous version — the panel says so instead of pretending there's something to compare.

You can turn the automatic open off with workbench.autoOpenDiff in your config file — the agent can still bring up a diff on purpose.

Agents Can Drive the Workbench for You

An agent isn't limited to describing what it did in text. It can act directly on the workbench you're looking at:

• Open a file it just edited, so you're looking at exactly what changed. It lands in the Canvas tab.
• Open a terminal, if it wants you to see (or run) something in a live shell.
• Open a page it wants you to check, like a dev server it just started. It lands in the Browser tab, so a page it sends never takes over the file you were reading.
• Use that page, once it's open: click a button or a link, type into a field, press a key, scroll to something further down, and wait for the page to catch up before looking again.

It can also read what's already there. Ask "what have we got open?" and the agent gets the real list — every tab, what it is, what it's called, and which one is at the front — and it can read one back, like the chart it drew for you last turn. Before, it could only guess from whatever your window last mentioned.

This only reaches into the chat you're actively viewing. An agent running unattended in the background can't reach into a workbench you have open elsewhere.

Using a page works on a preview DorkOS is serving for you — a local HTML file, or a dev server on your machine. A page loaded straight from the internet is shown, not driven, and your agent is told so in a sentence instead of trying and waiting.

With the same chat open in two windows, an agent acts in the one that most recently brought a preview to the front, and only that one. The other window sees nothing. Your agent can also name a specific tab when it has several open.

In a room, the canvas belongs to everyone

Open a room and the same two tabs are there, showing the room's own set instead of your private one. When an agent in that room opens a document or a page, it lands on the room's canvas, and every member sees the same thing at the same time — still there after a reload, and gone for everyone when somebody closes it.

Nobody is interrupted by it. The room's log gets one quiet line per turn saying what that agent opened, the tab grows a small dot so you can find it when you're ready, and the tab you're on doesn't move. An agent that actually wants you to look now @mentions you, like anyone else would.

Agents Can Check Their Own Work, and Act on It

Once an agent has a preview open in the Browser tab, it isn't flying blind: it can read the same signals you'd check yourself. It can read the console for errors and warnings, check for network requests that failed (a missing asset, a broken API call), and take a screenshot to see exactly how the page rendered. That lets it catch a mistake and fix it before telling you it's done, instead of you having to open dev tools and relay the error back.

It can also use the page. Ask it to "sign up as test@example.com and tell me what happens" and it reads the page to see what's on it, types the address into the email field, clicks Create account, waits for the page to settle, and tells you what it saw — including the 500 in the console, if there was one. It never pastes the page's HTML at you, and it doesn't guess: when several things on the page match what it asked for, it says so and asks which one rather than picking one.

It can also record what it did. Ask for a recording and it starts one, redoes the steps, and stops — and you get back one line saying how many frames it kept, how long it covers, and where the file is. The file is a small animated picture: one frame per action, a slideshow of the steps rather than a video of them. It saves into the agent's own working directory, under .dork/.temp/recordings/, so you can open it and watch the form fail for yourself. The agent gets the last frame back as a picture, and it can put the file itself into a room so other people — and other agents — can open it.

A recording keeps at most 60 frames. Past that it stops filming, and everything else keeps working.

Both halves work on local previews DorkOS renders directly: a local HTML file or a localhost dev server. External sites, and pages with a strict security policy, aren't instrumented — they're shown, not driven.

In the permission mode DorkOS ships with, your agent does this without stopping to ask. If you've set a mode that asks first, you'll see a card the first time it clicks something, the same as for any other action.

Everything it does happens inside the preview frame, on the page you are looking at, and it cannot reach DorkOS itself. What that frame is depends on what you opened: a local file DorkOS serves has no sign-in and no address of its own, so there is nothing there to act as. A dev server preview is your dev server — so your agent acts on it exactly as you would by clicking in it, including anything that page is already signed in to. Point it at a page you would be happy to click around in yourself.

Your agents can do all of this out of the box, whichever runtime they run on — with one difference: an agent reaching in from outside the DorkOS app cannot ask you about anything first, so applying a Shape is refused there and it tells you to do that one in the app yourself.

For the Curious

Three settings live under workbench in your config file:

• workbench.defaultViewers: an object mapping a file extension to the viewer that should open it (for example, forcing .csv files into the plain code editor instead of the table view). Empty by default, which means every file type above uses its standard viewer.
• workbench.terminalGraceTtlMinutes: how long a terminal's shell stays alive after every browser tab pointed at it disconnects, so a refresh can reattach instead of losing the shell. Defaults to 10 minutes.
• workbench.autoOpenDiff: whether a diff opens automatically when the agent edits a file. On by default; set it to false to keep the canvas on whatever you last had open.

None of these are something most people ever need to touch.

Next Steps