Skip to content

Working in a workspace

A workspace's pages: its repositories, the shared box, and the agent session (Claude Code, Codex or OpenCode) everyone on the workspace shares.

Where
Workspaces → any workspaceIn the app (sign-in required), opens in a new tab.
Reading time
4 min read

How it works

A workspace runs in a box: a container with every repo cloned and checked out on the workspace's own branch, the same box for everyone in the organization. Two people opening the workspace are in one box and one terminal session, not two copies. The work in it is read on the Changes page (the diff on the branch) and shipped from Git.

The Terminal page is that session, and only the organization's owners can open it. It has two views, switched in its header (Terminal / Conversation):

  • Terminal is the live TTY. You type into the same session the agent (Claude Code, Codex or OpenCode) is working in.
  • Conversation is the same session parsed into messages, easier to read back, and what the mobile app shows, since a phone cannot host an interactive TTY.

The Overview page holds the requirements and the repository list. Requirements & plan is the description you wrote, kept in sync with REQUIREMENTS.md in the box and shown as formatted text, with its attached files and links under it (Attach files or links adds one).

Stopping is safe and reversible. The container's volume and every file on it survive; opening the workspace starts it again exactly where it was. DevBench also stops boxes on its own: a workspace that is not in the board's active column has no reason to hold memory, so it is stopped once it has been quiet for a while, unless Keep this box running is set on it. Every automatic stop is written to the workspace's Activity page, so "why did my box stop?" has an answer.

A workspace's pages (Overview, Terminal for owners, Chat, Changes, Tasks, Git, Previews, Docs, then under More ▾: Media, Watcher logs, Work locally, Activity, Workspace settings, Screen) are the row under its tab. A doc opened inside the workspace (from its Docs page, its chat, a task) joins that row as a tab of its own after Docs. One shows at a time; Side by side ▾ at the end of the open workspaces' row puts other workspaces beside it, each a column with its own pages, to follow several agents at once: their tabs form a coloured group, as a browser groups tabs, with an address of its own, and each column has its own box, agent and branch icons beside its name. Dragging a tab onto another groups the two, onto a group's label adds it to the group, and past the last tab takes it out, as in Chrome. A click on the group's label or any of its tabs opens the group side by side; Alt click collapses it; its ▾ (or a right-click) names it, recolours it or ungroups it. The box icon's menu pops the agent's terminal out into a browser tab of its own (owners too).

Steps

Following along? Tick each number off as you go.

  1. Open a workspace from the board.

  2. Read Requirements & plan on the Overview page, and attach a screenshot or a spec with Attach files or links.

  3. Open Changes to read the diff on the workspace's branch, and Git to push it and open a merge request.

    Everyone in the organization sees the same box.

  4. As an organization owner, open the workspace's Terminal page to talk to its agent: Terminal in the workspace's pages.

    Switch between Terminal and Conversation in its header; ⋯ → Pop out gives it a whole browser tab.

  5. If the agent seems stuck on a menu or a screen, press ⋯ → Check this box in the Terminal page's bar.

    DevBench says whether it is ready for a message and frees it where it can; see Box health.

  6. Add repositories from the Overview page as the work grows.

    They are cloned onto the same branch as the rest.

  7. Press Stop in the workspace's Settings → Box page when you are done, or just leave it.

    DevBench stops it for you once the workspace leaves the active column and has been quiet.

Worth knowing

  • The agent's session is shared. Typing into the terminal interrupts whatever the agent is doing there, which is often what you want, but it is not a private shell.

  • A stopped box has no live terminal until it is started again: Start in the workspace's Settings → Box page.

  • Moving from the old workspace page? See Moving from the old layout for where each piece went.

Read next

Getting startedWorkspace chatThe conversation that lives with the workspace, where agents post, where the team replies, and where @agent puts the workspace's agent to work.Code and shippingChanges and GitWhat is different since the workspace was checked out, whether it has reached the provider, and what the agent is allowed to push.Getting startedThe workspace boardEvery workspace as a card, in the column that says what is happening to it, with card, calendar and per-person views.Running the organizationBox health with JevChecks whether a box's agent is ready for a message and, if you allow it, presses the key that frees one stuck on a menu or a one-time screen.
Report a problem