---
title: Add a project
---

# Add a project

## What it is

A **project** in Omniscio is a folder on your computer that you'd like to run Claude Code sessions inside. Adding one creates a row in the projects sidebar (the left-hand strip with the colored bars and icons) so you can launch sessions, organize them in groups, and track work per codebase. The "+" icon at the top of the projects sidebar opens the **Add Project** dialog, which lets you either point at an existing folder on disk, create a brand-new folder under your default projects directory, or clone a GitHub repo. Real projects are filesystem folders — distinct from the built-in **virtual** projects (Skills, Recipes, Cron Jobs, Gmail, SMS, etc.) that ship with Omniscio and don't have a real path on disk. The sole exception is the auto-created **Claude** project at `~/Claude` which acts like a real project but is special-cased on first launch.

## Where to find it

### How to use it

1. **Open the Add Project dialog.** In the projects sidebar header (top-left of the app), click the **+** icon. A small popover shows two options — **Add Project** (folder icon) and **New Group** (list icon). Choose **Add Project**. You can also open the dialog from a divider's right-click menu (or its **MoreVertical** `…` icon) by picking **Add Project** — that path pre-selects the divider in the Group dropdown (step 4) so the new project lands inside that group without an extra click. If your project list is completely empty, the empty-state card in the middle of the sidebar shows a big **Add Project** button instead, which opens the same dialog.
2. **Pick a tab.** The dialog has three modes across the top:
   - **Quick Create** — type a name, Omniscio creates a new empty folder under your **default projects folder** (set in Settings → System → Default Projects Folder). The dialog shows a live preview like `Creates: C:\Projects\my-new-app`. Disabled until a default folder is configured — the dialog inlines a "Choose Default Projects Folder" button to set one without leaving the modal.
   - **Browse Existing** — type or paste a folder path, or click the folder icon to open the native folder picker. The project name auto-fills from the folder's basename (e.g. `C:\code\my-app` → `my-app`); type into the Project Name field to override and Omniscio remembers that you took control. The display name is for the sidebar label only — it does not rename your folder on disk.
   - **GitHub** — clone a GitHub repo into your default projects folder and immediately add it as a project. Also gated on having a default folder set. If your GitHub account isn't connected yet, the tab shows a **Connect GitHub** button that runs a one-time browser sign-in (the same device-flow as Settings → GitHub Notifications) right inside the dialog — you don't need to run `gh auth login` in a terminal. A clone is tracked as a background job: while it runs the tab shows that it is still cloning and offers **Cancel**, and if you close the dialog you can reopen Add Project → GitHub to see the still-running clone instead of losing the state.
     - **Which GitHub account.** The tab shows **Signed in to GitHub as _name_**. Omniscio browses with the GitHub CLI (`gh`), and `gh` only ever uses its *active* account — so if you are signed in to more than one account, the tab shows a **GitHub account** dropdown instead: pick the account whose repositories you want and Omniscio switches `gh` to it (the same as `gh auth switch`) and reloads the lists.
     - **Owner dropdown.** Lists your organizations **and** every other owner of a repository you can reach — including organizations where you are only an outside collaborator, which used to be missing entirely. Picking an owner shows its repositories, including private ones you were invited to. Up to 1000 repositories load per owner (the list used to stop at 100).
     - **Missing an organization?** Some organizations block third-party apps or require single sign-on; their repositories are hidden from `gh` until an org owner approves the GitHub CLI app, or until you authorize single sign-on for it on github.com. The tab says so under the owner dropdown. You can always paste a repository URL instead.
3. **Pick a color (optional).** The field is labeled **Optional Color** and shows a single compact chip instead of the full palette — click the chip to open a small menu. There, choose a preset swatch, click **Auto** for the next unused preset, **Custom** for a hex picker, or **None** to skip color entirely; the chip then shows your choice and the menu closes. The color shows up as a thin vertical bar on the left edge of the sidebar row, and the **Auto** button skips colors already in use by other projects so two adjacent rows aren't the same. A note under the field reminds you that if your folder has its own icon it'll be auto-detected (step 6), so a color is genuinely optional.
4. **Pick a group (optional).** The **Group** dropdown lists every existing divider — pick one to drop the new project into that group, leave it on **None** to land ungrouped at the top of the list, or pick **+ Create new group…** to type a new divider name without leaving the dialog. Dividers are sidebar group headers (collapsible labels that visually separate clusters of projects). When you opened the dialog from a divider's right-click menu, that divider is already selected here — you can submit straight through; otherwise the dropdown defaults to the active project's divider (or **None** if no project is selected or the active project is ungrouped).
5. **Submit.** Click **Create Project** (Quick Create) or **Add Project** (Browse). On success: a toast confirms `Project "<name>" created`, the dialog closes, the project lands in the sidebar, Omniscio selects it, and a session auto-spawns inside it so you can start working immediately. If the folder doesn't exist (Browse mode) or already has a project pointing at it, the dialog shows an inline error and stays open.
6. **Omniscio auto-detects an icon in the background.** Right after the project is created, Omniscio looks at the folder's contents for a logo file (`favicon.ico`, `public/icon.svg`, `apple-touch-icon.png`, and ~101 other common locations) and silently sets it as the project's icon if one is found. This is gated by **Settings → Appearance → Auto-Detect Project Icons** (default on). You can override the icon any time via the project's right-click menu — **Detect Icon**, **Choose or Replace Icon…**, or **Remove Icon**. There's no upload size cap; Omniscio just stores the absolute path to whatever image you point at.

Project names cannot contain `< > : " | ? * \ /` — those are filesystem-unsafe characters and the dialog rejects them with an inline error in Quick Create. Names are capped at 100 characters, and display gets truncated past ~20–30 characters in the sidebar.

## How it behaves

### How it works

The dialog component is [AddProjectDialog.tsx](../../src/renderer/src/features/projects/AddProjectDialog.tsx), opened from [ProjectsSidebar.tsx](../../src/renderer/src/features/dashboard/ProjectsSidebar.tsx) via two paths: the sidebar header's **+** menu calls `onAddProject()` with no argument, and the divider header's right-click / **MoreVertical** menu in [DividerHeader.tsx](../../src/renderer/src/features/dashboard/DividerHeader.tsx) calls `onAddProject(divider.id)`. Both paths land in `Dashboard.tsx`'s `openAddProject(initialDividerId?)` helper, which stashes the divider id in state and flips the dialog open. The dialog accepts an `initialDividerId?: string | null` prop — when non-null it preselects that divider in the Group dropdown; when null (the default) the dropdown falls back to the active project's `dividerId`, then to **None**. The dialog calls `addProject()` on the project store ([project-store.ts](../../src/renderer/src/stores/project-store.ts)), which invokes the `PROJECT_CREATE` IPC channel handled in [project-handlers.ts](../../src/main/ipc/project-handlers.ts). The handler validates against `createProjectSchema` from [ipc-schemas.ts](../../src/shared/ipc-schemas.ts), then either `mkdirSync`s the new folder (Quick Create) or `existsSync`-checks a user-supplied path (Browse). It rejects duplicates if any active project already has the same `folderPath`. The actual row insert lives in `createProject()` in [queries-projects.ts](../../src/main/db/queries-projects/projects.ts) — it generates a UUID, writes a row with `is_deleted = 0`, and either appends to the end of the chosen divider (`MAX(display_order) + 1`) or inserts at the top of the ungrouped list (bumps every existing row's `display_order` by 1 and writes the new row at 0). The handler then emits both `PROJECTS_CHANGED` and `DIVIDERS_CHANGED` push events so the renderer's stores re-sync.

The GitHub tab uses [GitHubCloneTab.tsx](../../src/renderer/src/features/projects/GitHubCloneTab.tsx). It starts clones through `PROJECT_IMPORT_GITHUB_START`, polls `PROJECT_IMPORT_GITHUB_JOBS`, and can stop a running clone through `PROJECT_IMPORT_GITHUB_CANCEL`. The tracked job state lives in [import-github-service.ts](../../src/main/services/project/import-github-service.ts), so a dismissed dialog can reattach to the latest running clone for the default projects folder. The legacy blocking `PROJECT_IMPORT_GITHUB` channel and `POST /project/import-github` CLI route still call the same service as a compatibility/headless path, but the desktop UI no longer waits on one opaque IPC call before it can explain what is happening.

The repo browser's data comes from [github-auth-handlers.ts](../../src/main/ipc/github-auth-handlers.ts): `gh:auth-status` reports the **active** account and every signed-in account (parsed per account block by [gh-status-parse.ts](../../src/main/services/github-auth/gh-status-parse.ts) — the first account `gh` prints is not necessarily the one it uses); `gh:list-orgs` merges member organizations with the owners of every repository reachable as owner, collaborator or organization member, paging through both with `gh api --paginate` ([gh-repo-owners.ts](../../src/main/services/github-auth/gh-repo-owners.ts)); `gh:list-repos` merges an owner's `gh repo list` with the reachable repositories under that owner, up to `GITHUB_REPO_LIST_LIMIT` (1000); and `gh:auth-switch` runs `gh auth switch` for a validated login, clears the cached `GH_TOKEN`, and returns the fresh status.

Background icon detection is done by `detectProjectIcon()` in [project-icon-service.ts](../../src/main/services/project-icon-service.ts), which is fired via `setImmediate()` so the dialog can close instantly — the function does ~104 `existsSync()` probes which antivirus can intercept and turn into 10–30 seconds of main-thread blocking. When a hit is found, the row's `iconPath` column is updated and another `PROJECTS_CHANGED` event refreshes the sidebar icon. Auto-launch of the first session uses `launchSession()` on the session store, gated by `autoLaunchInFlight` to prevent double-spawns. Color presets are defined in `PROJECT_COLORS` in [src/shared/utils.ts](../../src/shared/utils.ts), and the `Auto` button calls `generateUniqueColor()` from the same file — preset cycling first, then golden-angle HSL spacing past 10 used colors. In the Add Hub and Edit Hub dialogs the palette is collapsed behind a single **Optional Color** chip via [ColorPickerMenu.tsx](../../src/renderer/src/components/ui/ColorPickerMenu.tsx), which opens the unchanged [ColorPicker.tsx](../../src/renderer/src/components/ui/ColorPicker.tsx) in a shared `AnchoredPopover` (the other surfaces still render it inline). The native folder picker is the standard Electron `dialog.showOpenDialog({ properties: ['openDirectory'] })` exposed via `IPC.DIALOG_OPEN_FOLDER`.

## Related

- [default-claude-project.md](default-claude-project.md) — the auto-created `~/Claude` project that's added on first launch and acts as your general-purpose chat workspace
- [project-folder-missing.md](project-folder-missing.md) — what happens if a project's folder disappears after you add it (moved, renamed, unmounted drive)
- [projects-sidebar.md](projects-sidebar.md) — the default "Omniscio" group that holds the built-in virtual projects new real projects land below
- [reorder-projects.md](reorder-projects.md) — drag, group, and pin projects after they're added