How Projects Are Created
You rarely create a project by hand. When you add a workspace — by cloning a URL, picking a local folder, or initializing a repo — Mains finds or creates its project automatically, deduplicated by the repository’s normalized remote origin:
So three workspaces cloned from the same GitHub repo land in one project and share its configuration. A project also tracks its
defaultBranch and the workspaces path — the directory its worktrees are created under.
Anatomy
Manage all of these under Settings → Projects.
Scripts
Projects can run a shell command at two points in a workspace’s lifecycle. Both run in the background (fire-and-forget) in the workspace’s root directory.
Because Setup runs on every new workspace of the project, it’s the right place for dependency installs and build steps you’d otherwise repeat by hand.
Commit & PR Instructions
Projects carry Commit Instructions and PR Template Instructions that shape how agents finish their work. These aren’t passive notes — they’re delivered to the agent through Mains’ built-in git tools:1
Agent calls CommitChanges or CreatePR
On the first call — before it has written a message or PR body — the tool returns the project’s instructions instead of acting.
2
Agent follows the rules, then calls again
Now with a message/body that conforms to your conventions (commit format, PR template, checklists).
Project-level commit and PR instructions override the global Git settings when present, so different repos can enforce different conventions.
Linked Resources & Issues
A project can be linked to connection resources — a GitHub repository, a Linear team, a Jira project, and so on (see Connections). Once linked, the issues from those resources surface against the project, so a workspace can pull in the right tickets as run context without searching every tracker. Add or remove links from the project’s Linked resources section in Settings.Managing Projects
Open Settings → Projects and pick a project from the sidebar to edit its icon, paths, default branch, scripts, instructions, and linked resources. The Danger Zone lets you remove a project or its underlying repository.Projects vs. Workspaces
See Workspaces for the per-task layer and Multi Session for running several workspaces of the same project in parallel.