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. Choose a project and base branch — The project picker shows active and recent projects
6. 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.

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 — picker shows your repo's open issues and PRs; the linked item's context is injected into the agent prompt
• 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 quick action buttons:

A "Delete workspace" option is also available at the bottom.

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 --full-auto
• 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

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.