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. A typed path must be a full path (C:\code\my-app, /Users/you/my-app) — a bare name like my-app is refused with an inline hint, because it would otherwise resolve against wherever Omniscio itself is running. 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 a typed Browse path is not a full path, or the folder already has a project pointing at it, the dialog shows an inline error and stays open. A full Browse path whose folder does not exist yet is created for you.
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, opened from 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 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), which invokes the PROJECT_CREATE IPC channel handled in project-handlers.ts. The handler validates against createProjectSchema from ipc-schemas.ts, then either mkdirSyncs the new folder (Quick Create) or takes a user-supplied path (Browse), creating it if it is missing. A Browse path that is not absolute on this host is refused by relativeFolderPathError() (hub-folder-path.ts) before any filesystem call — the same check guards PROJECT_UPDATE, the CLI's POST /project/create, and both relocate doors (inside relocateProject()) — because a relative one resolves against the app's working directory (/ on a packaged Mac, where the mkdir fails with ENOENT). It rejects duplicates if any active project already has the same folderPath. The actual row insert lives in createProject() in queries-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. 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, 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: gh:auth-status reports the active account and every signed-in account (parsed per account block by 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); 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, 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, 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, which opens the unchanged 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 — the auto-created ~/Claude project that's added on first launch and acts as your general-purpose chat workspace
• project-folder-missing.md — what happens if a project's folder disappears after you add it (moved, renamed, unmounted drive)
• projects-sidebar.md — the default "Omniscio" group that holds the built-in virtual projects new real projects land below
• reorder-projects.md — drag, group, and pin projects after they're added