Skip to main content
A Code project groups workspaces for the same repository. It holds the repository’s paths, default branch, scripts, Git-writing instructions, and linked issue resources. For groups of Work and Chat conversations, see Collections.

​
Add a project

Click Add Project or press ⌘N in Code. Import a local folder, clone a Git URL, or initialize a new repository. Mains finds or creates the project during import. Repositories with the same normalized remote origin share a project. A repository without an origin is identified by its local root path.

​
Project settings

Open the project’s settings to edit: Each workspace can have its own PR base. Creating a branch from the current branch updates that workspace’s base; the project’s default branch remains the integration branch.

​
Lifecycle scripts

The Setup script runs after workspace creation. The Archive script runs when you archive the workspace. They execute in the workspace directory in the background. For example, a setup script can install the repository’s dependencies:
Mains does not wait for setup to finish before showing the workspace. Check that required dependencies are ready before starting a task. Restoring an archived workspace does not rerun setup. If an archive script removed files, restore them yourself before using the workspace.

​
Commit and PR instructions

The Git actions panel uses project instructions when generating a commit message or PR draft. Project instructions take precedence over the corresponding defaults in Settings → Git. These instructions guide generated text. Commits and PRs are submitted through the panel, or through the shell when you explicitly ask an agent to use Git. Link resources from a connection, such as a GitHub repository or Linear team. Their synced issues then appear in the project’s task context. Linking a resource does not grant another service access to your repository. It selects which imported issues belong with the project.

​
Sync across devices

With Bridge, a project’s workspaces and chats appear on your other devices as read-only copies. Another device’s workspace appears under its local project when both share the same normalized remote origin. Turn off a project’s sync in Bridge → Project sync to keep its new chats and changes on this device. Folder paths, Git state, and terminals never sync. See Work across devices.