Workspaces

Each workspace is an isolated coding context with its own terminal tabs, pane layout, git branch, and browser state. Workspaces appear in the sidebar and persist across restarts.

Creating Workspaces

Click the + button in the sidebar or use the project onboarding wizard to create a new workspace. Codemux uses a prompt-first flow — you describe what you want to do, and Codemux sets up the workspace around that.

Prompt-First Creation

The workspace creation dialog centers on a prompt textarea ("What do you want to do?"). From this single dialog you can:

1. Describe your task — Type what you're working on (e.g., "Add dark mode support")
2. Auto-generated branch name — Codemux generates a branch name from your prompt using AI (see below)
3. Pick a device — A compact pill at the left of the bottom bar selects where the workspace runs. Defaults to Local Device; a submenu lists any SSH hosts you've registered in Settings → Hosts
4. Pick an agent — Select which AI agent to launch (Claude Code, Codex, OpenCode, Gemini, Antigravity, Copilot, Cursor Agent, Amp, Grok, Droid, Mastracode, Pi, or a custom preset)
5. Pick a model — A model pill next to the agent picker lets you choose the model, reasoning effort, and (for Claude) context window before launch, instead of starting with the default and restarting. Appears only for agents Codemux has model data for — Claude, Codex, OpenCode, Gemini. See Model Selection below
6. Choose a project and base branch — The project picker shows active and recent projects
7. Attach files or link a PR — Optional context for the agent

The prompt becomes the agent's initial task when the workspace opens. Press Ctrl+Enter to create.

New branches start from a freshly fetched origin/<base> tip — Codemux runs a quick scoped fetch (capped at 10 seconds, never prompts for credentials) before branching, and falls back to your local base branch when offline or in a local-only repo.

Model Selection

The model pill next to the agent picker lets you choose the model, reasoning effort, and context window before the agent launches — no need to start with the default, stop the agent, switch models, and resend your prompt.

• When it shows — Only for agents Codemux has model data for: any preset whose command launches claude, codex, opencode, or gemini. Custom presets that launch one of these CLIs light it up automatically; everything else hides the pill.
• Model — Lists are live wherever possible: OpenCode harvests its connected providers, Codex reads model/list, Claude pulls its supported models from the CLI (with an ANTHROPIC_API_KEY REST fallback and a maintained list), and Gemini uses GEMINI_API_KEY (falling back to a maintained list). Long rosters get search + favorites + provider grouping; short ones show a flat list.
• Reasoning — Shown for CLIs with a reasoning flag (Claude --effort, Codex -c model_reasoning_effort). The available levels come from the selected model, so Sonnet and Opus show different choices. OpenCode and Gemini have no reasoning flag, so the row is hidden.
• Context window — Claude only. Pick 200K or 1M for models that support the larger window.
• Default — Leaving the pill on "Default" emits no flags, so the launch is identical to before this feature existed. Your last pick per agent family is remembered and restored next time.

AI Branch Name Generation

When you type a task description, Codemux auto-generates a git branch name:

• AI-generated — Uses Claude CLI to generate a short 2-4 word hyphenated branch name from your prompt (e.g., "add-dark-mode")
• Random fallback — If AI is unavailable, generates a random adjective-noun pair (e.g., "swift-reef", "bold-gate")
• Custom override — You can always edit the branch name manually
• Deconfliction — Names are sanitized and checked against existing branches. Conflicts get a -2, -3 suffix

Other Creation Methods

You can also create workspaces by:

• From branch — Select an existing branch from the dropdown; creates a git worktree. The branch picker is a derivative-branch picker with icons, recency-based sorting, and a Worktree tab for browsing existing worktrees.
• From PR — Link a pull request from the + menu to set the branch automatically.

Attaching Context To The Prompt

The prompt input on the workspace-creation dialog accepts:

• File picker — click the paperclip / attach button to attach files from your workspace
• GitHub issue / PR linking — searchable picker shows your repo's open issues and PRs (with state-colored icons); the linked item's context is injected into the agent prompt. Linking an issue auto-fills a deterministic branch name, so if that issue (or the typed branch) already has a workspace, the dialog tells you up front and offers to Open it instead of silently switching to the existing one and dropping the message you just typed
• Clipboard paste — paste images directly into the prompt textarea with Ctrl+V. Useful for screenshots from grim, the Windows Snipping Tool, or anything else that puts an image on your clipboard

Each workspace gets its own terminal tabs and pane layouts.

Checkout Default Branch

Every primary workspace (the one rooted at the original checkout, not a worktree) has a Checkout default branch action in its sidebar context menu. One-click way to switch back to main (or whatever your configured default base branch is) without dropping to a terminal.

Empty Workspace State

When a workspace has no panes open, it shows a centered logo with clickable quick-action buttons:

• Open Terminal — also bound globally to Ctrl+T
• Open Browser
• Open in Editor
• Search Files — also bound globally to Ctrl+Shift+P

A "Delete workspace" option is also available at the bottom. For the full list of global key bindings, see Keyboard Shortcuts.

Layout Presets

When creating a workspace, choose a layout preset:

Agent Presets

The preset bar at the top of each workspace lets you launch AI agents with one click. Twelve coding-agent CLIs ship as pinned builtins:

• Claude Code — claude --dangerously-skip-permissions
• Codex — codex --dangerously-bypass-approvals-and-sandbox
• OpenCode — opencode
• Gemini — gemini --yolo
• Antigravity — agy --dangerously-skip-permissions
• Copilot — copilot --allow-all
• Cursor Agent — cursor-agent --yolo
• Amp — amp --dangerously-allow-all
• Grok — grok --always-approve
• Droid — droid (autonomy injected via a runtime --settings file)
• Mastracode — mastracode
• Pi — pi

Each agent preset launches in its CLI's skip-permissions / auto-approve mode so you don't have to confirm individual tool calls. You can create custom presets with your own commands, icons, and launch modes (split pane or new tab). The agent picker in the workspace creation dialog also uses these presets. See Terminal → Preset Bar for the full flag rationale per agent.

Open In External Editor

The IDE launcher in the title bar (and the Open in editor entry in the sidebar context menu) opens the current workspace in your preferred external editor. Codemux probes for 19 editors on launch via which so PATHEXT, .cmd shims, and JetBrains Toolbox shims all resolve without special casing:

Only families with at least one installed editor render in the launcher — no empty headers. On Windows, fallback paths cover per-user installs that don't always land on PATH (Windsurf, Trae, Lapce).

Workspace Sections

Organize workspaces into named sections in the sidebar. Drag workspaces between sections to reorder. Sections can be color-coded and collapsed.

Removing Workspaces

Click the X on a workspace row or right-click and select "Close Worktree" to open the remove dialog.

The dialog offers two options:

• Hide — Removes the workspace from the sidebar but keeps the worktree files on disk. Available for all workspace types.
• Delete — Permanently removes the worktree directory and optionally deletes the local branch. Only available for worktree workspaces.

A checkbox lets you toggle "Also delete local branch" (enabled by default for worktree workspaces).

Unpushed Commit Warnings

If the workspace has uncommitted changes or unpushed commits, a warning banner appears in the remove dialog before you confirm. This prevents accidental data loss.

Primary vs. Worktree Workspaces

• Primary workspaces (the main checkout) can only be hidden, not deleted
• Worktree workspaces support both hide and delete

Context Menu

Right-click a workspace in the sidebar to:

• Rename the workspace
• Open in external editor
• Move to a different section
• Close the workspace

Workspace Context Bar

A slim, read-only status strip runs along the bottom of the work surface and always reflects the active workspace. Left to right it shows:

• the git branch, and whether the workspace is a repo root or a worktree
• ahead / behind counts against the upstream
• the diff size — added / removed lines and the number of changed files
• a clickable PR chip, colored by state (open / merged / closed / draft), that opens the pull request on GitHub
• a clickable issue chip that opens the linked issue's detail
• a device label — This device, or the host name for a workspace running on a remote SSH host

It's purely informational — no commit or push actions live here — and it hides itself when there's nothing to report (for example a home-directory workspace with no branch, PR, or linked issue). The sidebar stays glanceable while the context bar carries the full labeled detail for whatever workspace you're looking at.

Setup & Teardown Scripts

Configure commands that run automatically when workspaces open or close. Two configuration methods:

File-based (.codemux/config.json)

Add a .codemux/config.json to your project root:

{
  "setup": ["npm install", "npm run build"],
  "teardown": ["docker compose down"],
  "run": "npm run dev"
}

• setup — Runs when the workspace opens
• teardown — Runs when the workspace closes
• run — The dev command for the Run button (Ctrl+Shift+G)

Database-based (Settings)

Configure scripts in Settings > Projects. Database settings apply when no .codemux/config.json exists. File config takes precedence.

Docker Compose Support

Scripts automatically receive these environment variables:

• COMPOSE_PROJECT_NAME — Derived from the git root directory name, so Docker Compose uses consistent project names across worktrees
• CODEMUX_ROOT_PATH — Full path to the git root
• CODEMUX_WORKSPACE_PATH — Full path to the workspace directory

Setup Banner

When a project has worktree workspaces but no setup scripts configured, a banner appears in the sidebar suggesting you configure automation. Dismiss it per-project or click "Configure" to open Settings.

Project Detection

Codemux detects the project root for each workspace by walking up from the workspace directory to find the git root. This works correctly for worktree workspaces — the project root is the main repository, not the worktree directory.

Merging Without PRs

For solo developers or personal projects where code review isn't needed, Codemux supports merging feature branches directly into main from the Changes panel. The "Merge into [base]" button uses a temporary resolver branch so main is never modified until the merge is verified clean — same safety guarantees as the AI conflict resolver. See Merge Resolver for details.

Keyboard Shortcuts

See Also

• Workspaces Overview — account-wide view across every device with push/pull/adopt actions.
• Settings → Hosts — register an SSH host before pushing a workspace to it.