Projects
Open, create, and manage projects with onboarding wizards and package manager detection.
Projects
Projects in Codemux represent git repositories. Each project groups its workspaces in the sidebar and shares configuration like setup scripts and run commands.
Opening an Existing Project
- Click Add repository in the sidebar
- Select Open project
- Pick a folder from the file dialog
- Codemux checks if it's a git repo — if not, it offers to initialize one
- The project appears in the sidebar and the onboarding wizard opens
Recent projects appear in the project picker dropdown for quick access.
Creating a New Project
- Click Add repository in the sidebar
- Select New project
- Choose one of two options:
Empty Repository
- Select a parent directory and enter a name
- Codemux creates the directory, initializes a git repo, and opens the onboarding wizard
Clone from URL
- Enter a git URL (HTTPS or SSH)
- Repository name is auto-derived from the URL (editable)
- Codemux clones the repo and opens the onboarding wizard
Project Onboarding Wizard
When you open or create a project, a two-step wizard helps you set up your first workspace.
Step 1: Task and Branch
- Task description — Describe what you're working on (e.g., "Fix the login page CSS")
- Branch name — Auto-generated from your task via AI, or edit manually
- Base branch — Defaults to main/master, changeable in advanced options
- Existing worktrees — If the project has worktrees from outside Codemux, a banner lets you import them all with one click
Step 2: Setup Scripts
Codemux scans your project and auto-detects setup commands based on files it finds:
| Detected File | Setup Command | Enabled by Default |
|---|---|---|
bun.lock | bun install | Yes |
pnpm-lock.yaml | pnpm install | Yes |
yarn.lock | yarn install | Yes |
package-lock.json | npm ci | Yes |
package.json (no lockfile) | npm install | Yes |
Cargo.toml | cargo build | Yes |
go.mod | go mod download | Yes |
poetry.lock | poetry install | Yes |
uv.lock | uv sync | Yes |
requirements.txt | pip install -r requirements.txt | Yes |
Gemfile | bundle install | Yes |
composer.json | composer install | Yes |
.env.example / .env.sample / .env.template | cp .env.* .env | Yes |
.gitmodules | git submodule update --init --recursive | Yes |
docker-compose.yml / compose.yml | docker compose up -d | No |
You can toggle individual commands on/off, or switch to custom mode to write your own commands (one per line). Teardown commands (run when the workspace closes) are configurable in an optional collapsible section.
The wizard also lets you select which agent to auto-launch in the new workspace.
What Happens After the Wizard
- Codemux creates a git worktree for your branch
- Setup scripts run in the background
- The selected agent launches with your task description as its initial prompt
- You're ready to work
Closing a Project
Right-click a project header in the sidebar and select Close Project.
A confirmation dialog shows:
- The project name and number of workspaces
- Warning: "This will close N workspace(s) and kill all active terminals"
- Reassurance: "Your files and git history will remain on disk"
Closing a project removes all its workspaces from the sidebar but does not delete any files from disk. Worktree directories are kept intact.
Project Context Menu
Right-click a project header in the sidebar for these options:
| Action | Description |
|---|---|
| Open in File Manager | Opens the project directory in your system file manager |
| Copy Path | Copies the full project path to the clipboard |
| Set Image / Change Image | Set a custom avatar image for the project (see Project Avatars) |
| Change Color | Pick a color for the project's sidebar avatar (12 colors + default) |
| Close Project | Close all workspaces and remove from sidebar |
Project Sidebar Display
Each project in the sidebar shows:
- A project avatar — the first letter of the project name by default, color-coded or replaced with a custom image if you've set one
- The project name
- A workspace count in parentheses
- A collapse toggle to show/hide workspaces
- A new workspace button (
+) to create a workspace in that project
Collapsing the Sidebar
Press Ctrl+B (or the title-bar toggle) to collapse the whole left sidebar to a narrow icon rail instead of hiding it. In the rail, each project shows as a single avatar with an aggregate status indicator — a corner dot or badge that reflects, by priority, whether any of its agents needs input, has unread notifications, is working, or is ready for review. Hovering a project avatar opens a flyout that lists that project's workspaces with live per-workspace status, notification counts, branch, and a + New workspace action, and clicking a row switches to it — so agent activity stays fully visible and operable while the sidebar is collapsed.
Duplicate Project Names
When two projects share the same folder name — for example a local copy and the same
repo on a remote host, or two sibling directories — Codemux disambiguates their
sidebar labels automatically. The local copy keeps its clean name; each remote copy is
tagged with its host ( · <host>). When the host can't tell them apart, the label
grows its trailing path segments until every label is unique. The same disambiguation
applies in the project picker and the automations project dropdown.
Project Avatars
Right-click a project header and choose Set image… to replace the letter avatar. The input accepts three shapes:
- Image URL — a direct link to an image (PNG, JPEG, SVG, GIF, WebP, ICO, AVIF, BMP) renders as-is
- Data URL — a pasted
data:URL renders directly - Website or domain — anything else that looks like a website (
github.com,https://codemux.org) resolves to that site's favicon, so you can brand a project with its product or repo icon without hunting for an image file
If a site changes its favicon, re-save the image and the avatar refreshes — favicon lookups are cache-busted on every save, while direct image URLs are always used exactly as pasted. If the image fails to load, the avatar falls back to the letter.
Avatar image and color are stored per device.