paseo/public-docs/workspaces.md

title, description, nav, order, category

title	description	nav	order	category
Workspaces	Understand how Paseo groups working directories, agents, terminals, and browsers into workspaces.	Workspaces	10	Workspaces

Workspaces

Paseo is organized around workspaces, not chats.

A workspace is the place where a task happens. It has a working directory and can contain multiple sessions running at the same time. In the app, each session opens as a tab.

Projects contain workspaces

The sidebar starts with projects. A project can be a git repository, a GitHub project, or any directory on a machine running the Paseo daemon.

Inside each project are workspaces. For example:

my-app
├── main
├── fix-login-flow
└── redesign-settings

Each workspace is a separate place to work. You can keep one for your main checkout, create another for a feature, or open a GitHub PR as another workspace.

Workspaces contain sessions

Agents run inside a workspace as sessions. A workspace can have one agent session, several agent sessions, terminals, browsers, and diffs open at the same time.

That matters because real development rarely fits into one long chat. You might ask one agent to implement a feature, open a terminal to run a service, start another agent to review the diff, and keep the browser open next to both. Those belong together because they are all part of the same task.

In Paseo, the workspace is the stable container. The sessions are what you run inside it.

Choose the runtime

Every workspace has a runtime:

• Local uses an existing directory, such as your main checkout. Use it when sessions should share the files already on disk.
• Worktree creates or opens a managed git worktree. Use it when a task needs its own directory and branch.
• Docker materializes the project's committed Git content in a container-owned workspace. Use it when files, tools, and providers should run in the configured image instead of the host environment.

The workspace is the product concept; the runtime chooses where its files and commands live. More than one workspace can refer to the same managed worktree, and Paseo removes that worktree after its last workspace is archived.

Creating a workspace

You can create a workspace in the app or from the CLI:

paseo workspace create --isolation local --path ~/dev/my-app --title main
paseo workspace create --isolation worktree --path ~/dev/my-app --base origin/main

You can also create a workspace without starting an agent right away. The workspace is still there with its working directory ready; you can open terminals, run services, or browse files, then start an agent later.

Either way, once the workspace exists you can add more sessions to it. Open a terminal alongside an agent, start a second agent to review changes, or open a browser tab to check a local service. Every session lives as a tab inside the same workspace.

Creating an agent and creating a workspace are separate actions. Pass a workspace ID when you want an agent in a specific existing workspace. A bare paseo run from a human shell creates a new local workspace; when one agent runs it, Paseo recognizes the caller and creates a subagent in the caller's workspace.

Worktrees

Every workspace in Paseo is backed by a working directory. When that directory is a git worktree, you get a separate branch and isolated environment for each task.

If you want the details on configuring setup hooks, scripts, and services, continue to Git worktrees.