Projects

Projects in Codemux usually represent git repositories, but any folder can be opened as a project — git is not required. Each project groups its workspaces in the sidebar and shares configuration like setup scripts and run commands.

Opening an Existing Project

1. Click Add repository in the sidebar
2. Select Open project
3. Pick a folder from the file dialog
4. Codemux opens the folder as a project whether or not it's a git repo — non-git folders open in plain-folder mode (see Non-Git Projects)
5. The project appears in the sidebar's project filter once it has a workspace and the onboarding wizard opens

Recent projects appear in the project picker dropdown for quick access.

Non-Git Projects

Git is never required to open a folder. Codemux will not refuse a folder, and it will never run git init on your files unless you explicitly ask it to.

• Any folder opens. The folder picker, the sidebar +, chat drafts, and onboarding all accept non-git folders silently — there's no "this is not a git repository, initialize one?" prompt that blocks you.
• Plain-folder mode. A non-git workspace uses the folder itself as its root. Git-dependent features degrade with honest messaging instead of failing silently: the chat pane's status row and the Changes panel show a "Not a git repository" label with an Initialize Git button where the branch details would normally appear, and worktree controls are hidden (there's no repository to branch from).
• Opt-in "Initialize Git". Clicking Initialize Git runs a plain git init only — it never stages or commits your files, so nothing is added to version control and no secrets are captured. The git UI lights up immediately once the repo exists. (Creating a brand-new empty project is different — that path does make an initial commit, because a starting commit is what you want there.)

Creating a New Project

1. Click Add repository in the sidebar
2. Select New project
3. 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:

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

1. Codemux creates a git worktree for your branch
2. Setup scripts run in the background
3. The selected agent launches with your task description as its initial prompt
4. You're ready to work

Closing a Project

Not currently available. Closing or archiving a whole project at once was a project-header action in the old sidebar tree. The sidebar is now a flat workspace inbox with no project rows, so that action has no entry point. Archive or close workspaces individually from a card's right-click menu instead.

Project Avatars

Projects show a letter avatar (or a custom image/color) on inbox cards, in the collapsed rail, and in the project-filter dropdown.

To customize one, right-click any workspace of that project — an active card, a settled row, or a snoozed row — and open the Project "<name>" submenu. From there you can:

• Set an image — a direct image URL, a data URL, or a website/domain whose favicon Codemux fetches.
• Pick a color — a 12-color palette.
• Clear — back to the letter avatar.

The change applies to the whole project and repaints every surface of it immediately. Avatars are device-local and do not sync across devices, there is no local file picker, and a project with no workspace in the inbox has no right-click surface to reach.

The Sidebar

The expanded sidebar is a flat workspace inbox — one card per active workspace, not a per-project tree. Projects appear in two places:

• The project-filter dropdown at the top of the inbox ("All projects", or a specific repo). Each row shows that project's active-workspace count. Filtering applies to both the active cards and the Settled section.
• The Add repository (+) button pinned beside that dropdown, with Open project and New project actions.

A project appears in the dropdown once it has at least one workspace.

There are no project rows, no per-project collapse toggles, no per-project + button, and no workspace-count-in-parentheses labels.

Collapsing the Sidebar

Press Ctrl+B (or the title-bar toggle) to collapse the sidebar to a 52px icon rail. The rail shows one avatar per active workspace — not one per project — each with its own status dot (red pulsing = needs input, amber = working, green = ready for review). Hovering opens the same hover details card you get in the expanded inbox; clicking selects that workspace without expanding the sidebar. Parked workspaces — settled and snoozed — do not appear in the rail, with one exception: the workspace you currently have open always keeps its avatar, whichever shelf it's parked on, since the selection fill is the rail's only "you are here" marker. The project filter does not apply in the rail.

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.