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. Open the project dropdown at the top of the sidebar
2. Choose Open existing project (or press Ctrl+O)
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

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

From the Empty Home

Before you have any workspace, the chat Home offers the ways in directly under the composer: Open project (Ctrl+O), Clone repository, and up to five recent projects. A recent project reopens without the folder picker; if its folder is gone, unreadable, or no longer a folder, Codemux refuses it with a toast that says why. Pressing New agent or Ctrl+N while that Home draft is already open focuses its composer.

In the classic (non-chat) flow, the full-screen Open Project page offers the same recent projects and a direct Clone repository button — and you can drop a folder from your file manager onto it to open it. Dropping a file instead of a folder is refused with a toast.

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 project menu, 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. Open the project dropdown at the top of the sidebar
2. Choose Create or clone project
3. Choose one of two options:

Empty Repository

• Select a parent directory and enter a name
• Codemux creates the directory and initializes a git repo

Clone from URL

• Enter a git URL (HTTPS or SSH)
• Repository name is auto-derived from the URL (editable)
• Codemux clones the repo

Project Onboarding Wizard

In the classic terminal-first flow, opening, creating, or cloning your first project opens a two-step wizard that sets up your first workspace. It appears only when you have no workspaces yet and haven't seen it before, and it is skipped entirely with Agent Chat and lazy workspace creation on (the default) — there, the project opens straight into a chat draft.

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
• Agent — Which agent to start in the new workspace, using the same picker as the New Workspace dialog
• Existing worktrees — If the project has worktrees from outside Codemux, a banner lets you import them all with one click. Import shows Importing n / total… progress, and a partial failure ends with a summary toast

A progress bar beside the step label tracks the two steps, and focus moves to the first control of each step. Pressing Enter advances only from the text inputs, so Enter inside the agent menu doesn't skip ahead.

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 step's button reads Create & start <agent>.

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

If the create fails, the wizard stays open with a dismissible inline error instead of closing — the project you just opened isn't lost. If the worktree was created but couldn't be opened, the wizard says so, and retrying reopens that workspace rather than failing with "branch already exists". If the branch already has a live workspace, Codemux switches to it and a toast says your task wasn't sent.

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.
• Open existing project and Create or clone project, pinned at the bottom of that dropdown.

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. Codemux remembers whether the sidebar was collapsed, so it reopens the same way next launch. 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. Alt+1..9 jump to rail avatars in on-screen order, and a pinned needs-you chip (also Ctrl+Shift+J) jumps to the workspace that has waited longest — see Jumping to a workspace.

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.