Workspaces and machines

A project tells Mework which directories a task may work in: on this computer, in WSL, or on machines you reach over SSH. Set up projects and machines, then work in them with the Files, Review and Terminal panes.

Projects and workspaces

A project is a named group of 1 to 16 workspaces; a workspace is one directory on one machine. The model's file, search and shell tools use a task's workspaces as their security boundary.

A workspace has no name of its own: the app shows it by its absolute path everywhere — the workspace chip, the workspace menus for terminals, previews and files, preview and Review tabs, and the sections of Conversation settings — shortened in the middle when space is short.

Create a project

1. In the sidebar, click New project beside Projects.
2. Under Workspaces, open the row's machine chip, pick This machine, a WSL distribution or an SSH machine, then click Choose a directory…. Add workspace adds another row, on any machine.
3. Optionally enter a Display name (by default, the first workspace's folder name), then click Create project.

Edit, reorder or delete

• Edit: the project's ⋯ menu → Edit project…. Rename the project or add and remove workspaces 2 to 16. The first workspace identifies the project and stays fixed unless its machine has been deleted.
• Default preset: ⋯ → Default conversation preset sets the preset the project's + button uses; choose it again to clear it.
• Reorder: drag projects, or tasks within a project.
• Delete: click the trash icon, then confirm. This removes the project and all its tasks from Mework for good; the files in its directories are never touched.

Workspace numbers

A task's workspaces are numbered from 1: the project's in order, then the task's attached workspaces. The model names a workspace by its number, and a path always resolves inside the workspace named. The workspace chip above the message box only chooses which workspace the branch chip, Git status and new terminals use.

Each workspace has its own .mework folder: a task can use the skills, MCP servers and hooks of all its workspaces, and each workspace keeps its own project memory.

The temporary project

A task you send without choosing a project goes to Temporary project and gets its own empty folder inside Mework's data folder.

Note Deleting a temporary task deletes its folder, with everything the model wrote in it.

Machines

A workspace can be on This machine (the computer running Mework), a WSL distribution (Windows only), or an SSH machine you add. A workspace on WSL or an SSH machine works like a local one, with its own skills, MCP servers and hooks read and run on that machine. A machine's gear (Settings for {name}) in the machine menus opens its shells and, for SSH, its connection.

Add an SSH machine

1. Open the project dialog (New project, or ⋯ → Edit project…).
2. In a workspace row, open the machine chip → SSH → Add SSH machine….
3. Fill in the fields and click Save. Mework connects right away to look for its shells, so this is usually where it first asks you to accept the host key or enter a password.

Mework uses this computer's OpenSSH with your ~/.ssh/config, keys and ssh-agent; signing in with a key or ssh-agent needs no prompt. When a connection needs your input, Mework asks in the app. The first time it meets a machine's host key, it shows the key's fingerprint for you to accept, and adds an accepted key to ~/.ssh/known_hosts; a host key that has changed since you accepted it is always refused. If the machine asks for a password or key passphrase, Mework asks you for it when it connects and keeps it in memory until Mework quits; it stores no password or key on disk. The machine needs /bin/sh (Unix) or Windows PowerShell 5.1 (Windows), and git for the Git features.

To delete a machine, click Delete in its settings. Every workspace on it, a project's first workspace included, shows Deleted machine and stops working until you choose a machine and directory for it again in Edit project…, or attach it again. Those workspaces' environment variables and sandbox settings are deleted too.

The Mework agent

The first time Mework uses an SSH machine, it installs a small helper, mework-remote, under ~/.mework/remote/ there and keeps one connection to it open. With it, terminals and dev servers survive network drops, and the Files pane, previews, the sandbox and the Review pane work on that machine. Quitting Mework closes the connection and leaves nothing running.

If the agent can't run, for example on a noexec home folder, the model's tools, terminals and Git status still work there, but the Files pane, previews, the sandbox and the Review pane don't. Set MEWORK_REMOTE_ROOT in the machine's login environment to install the agent elsewhere, or MEWORK_REMOTE_AGENT=off in Mework's own environment to never use it.

Shells

Mework looks for these shells on each machine, in this order, and offers the matching shell tools (bash, zsh, sh, powershell):

After installing a shell, click Probe shells again in the machine's settings. On WSL and SSH machines, Agent shell sets the shell the model's file tools and language servers run in.

Attached workspaces

To give one task another directory without changing its project, click Attach a workspace above the message box, pick a machine and choose the directory. It becomes the task's next numbered workspace. Its chip's gear opens its environment variables; × removes it.

A task takes up to 32. Attached workspaces get terminals and the Files pane, but no Git status or Review page. Forks, auto-compact continuations and Branch from this message keep the task's attached workspaces; forks and continuations also share its worktrees.

Environment variables

Each workspace has its own environment variables and sandbox, used by every task in that directory. Open them with the gear beside a workspace in the workspace chip's menu. Write one KEY=value per line:

API_KEY=value
HTTP_PROXY=http://127.0.0.1:7890

Changes apply as you type; an invalid line is flagged and the last valid version is kept. The variables reach every command run in the workspace, on any machine: the model's shell commands, hook commands, the MCP servers of a WSL or SSH workspace, and your terminals. Variables named like secrets never reach the sandbox, and terminals are never sandboxed. A task on a worktree uses the settings of the directory it came from.

Worktrees

Tick worktree beside the branch chip before the first message, and the task runs on its own Git checkout instead of the project's shared directory.

On the first message, Mework creates <repo>/.mework/worktrees/conversations/<id> on a new branch mework/conv/<id> from the workspace's current HEAD. The task's model, terminals and Review page use the worktree.

Note A worktree starts from the last commit. Uncommitted and untracked files are not in it.

• The workspace must be the root of a Git repository, with git on its machine.
• The box applies to the workspace selected in the workspace chip; each workspace can have its own worktree.
• Workflow steps with worktree isolation get worktrees the same way, on whichever machine the repository is.

Deleting the task, or its project, releases its worktree: one with no uncommitted changes or new commits is removed with its branch; one that holds work stays on disk, and Mework says so. A worktree shared with a fork or continuation stays until the last task using it is deleted.

Without a worktree, the branch chip's Switch branch checks out a branch in the shared directory, for every task of the project.

Files

The Files pane is your own file manager for this computer, WSL and every SSH machine you added; the model can't use it. Open it with More options (⋮) → Files in the top bar, or click a file path in the timeline.

Type a location in the address bar: a local path, devbox:/srv/app or user@host:~/notes for an SSH machine, or \\wsl.localhost\Ubuntu\home\dev for WSL. Right-click a row to open, rename, delete or copy its path. Deleting on this computer moves the item to the Trash (Recycle Bin on Windows); on another machine it is deleted for good.

The viewer is read-only. It shows a text file's first 1 MiB, and images, PDFs and audio up to 8 MB.

Changes and review

Git status

When the selected workspace is the root of a Git repository, a Git status chip sits above the message box. Its card shows lines added and removed, commits ahead and behind, and the repository's next step: conflicts to resolve, an operation to continue, changes to commit, or commits to push or pull. Each row opens the Review pane. Mework has no commit, push or pull buttons: ask the agent, or use a terminal.

The Review pane

Click Review in the top bar. Review scope shows all changes, only staged or only unstaged ones, and on a worktree All changes on the branch, commits included. A file's ⋮ menu stages, unstages or discards it.

Edited N files

After each turn, an Edited N files card lists the files changed with write and edit; click a row to open it. Changes made by shell commands are not listed.

Terminals

Terminal in the top bar opens New terminal, with the shells of the selected workspace's machine (zsh and bash on macOS). A terminal starts in the workspace's directory, or the task's worktree.

• Closing the pane only hides it; a tab's × ends its shell.
• On an SSH machine, a terminal survives a dropped connection for up to 2 hours.
• On this computer, a command you enter while Mework is changing Git state or a worktree in that folder is not run, and the terminal says so; run it again afterwards.
• Up to 64 terminals run at once. The model can wait on a command in your terminal with task_wait.