Add a project
Adding a folder as a project in Omniscio: the Add Project dialog's Quick Create, Browse Existing and GitHub tabs, picking a color and a side-nav folder, the background icon detection, the name rules, and the IPC and GitHub plumbing that sits behind the dialog.
On this page
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 + on the Projects heading of the side nav (or Add Project in the Workspace header's ⋮ menu) 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
- Open the Add Project dialog. Click the + at the end of the Projects heading in the side nav. Or open the ⋮ menu in the Workspace header (top of the side nav) and choose Add Project — that menu is also the way to reach it from the keyboard. Both open the same dialog. The + is greyed out, and so is the menu entry, once you have reached your plan's project limit. On a phone, a folder's long-press menu has an Add entry that pre-selects the folder in the Group dropdown (step 4) so the new project lands inside that folder 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.
- 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. Two switches sit under the name: Set up git with a README and a first commit (on by default) makes the new folder a git repository with aREADME.mdand an "Initial commit" before the first session starts, and Publish it to GitHub as a private repository (off by default) also creates a private GitHub repository for it and pushes. See publish-repository.md. - 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 likemy-appis 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 loginin 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. While it runs the tab shows what git is actually doing — connecting, counting, downloading, resolving, writing files — with a percentage when git gives one. A big repository is never stopped for taking long, only when git goes quiet for two minutes. If an SSH address fails because SSH cannot connect or sign in, the clone retries once over HTTPS to the same host and says so. A clone never opens a password or SSH prompt. A failed or cancelled clone removes the folder it created (a folder that already existed is never touched), and a clone that finishes while the dialog is closed still becomes a project, once.- Which GitHub account. The tab shows Signed in to GitHub as name. Omniscio browses with the GitHub CLI (
gh), andghonly 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 switchesghto it (the same asgh 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
ghuntil 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.
- Which GitHub account. The tab shows Signed in to GitHub as name. Omniscio browses with the GitHub CLI (
- 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
- 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.
- Pick a group (optional). The Group dropdown lists every existing side-nav folder — pick one to drop the new project into it, leave it on None to land as a loose item at the end of the middle zone, or pick + Create new group… to type a new folder name without leaving the dialog. When you opened the dialog from a folder's menu, that folder is already selected here — you can submit straight through; otherwise the dropdown defaults to the active project's folder (or None if no project is selected or the active project is not in a folder).
- 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. - 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 src/renderer/src/features/projects/AddProjectDialog.tsx, opened from src/renderer/src/features/dashboard/ProjectsSidebar.tsx via two paths: the Projects heading's + and the Workspace menu's Add Project call onAddProject() with no argument, and on a phone the folder sheet's Add in src/renderer/src/features/dashboard/side-nav/MobileSideNavActionSheet.tsx calls onAddProject(dividerId) for that folder. 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 (src/renderer/src/stores/project-store.ts), which invokes the PROJECT_CREATE IPC channel handled in src/main/ipc/project-handlers.ts. The handler validates against createProjectSchema from src/shared/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() (src/main/services/project/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 src/main/db/queries-projects/projects.ts — it generates a UUID, writes a row with is_deleted = 0, and with appendToEnd places it one past every live project and folder (nextSidebarEndOrder), so it lands at the bottom of the middle zone, inside the chosen folder if one was given, without shifting any other row. The handler then emits both PROJECTS_CHANGED and DIVIDERS_CHANGED push events so the renderer's stores re-sync.
The GitHub tab uses 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 src/main/services/project/import-github-service.ts, so a dismissed dialog can reattach to the latest running clone for the default projects folder. All four clone channels refuse a web or phone caller inside the handler as well as at the bridge. A finished clone is registered in main by registerClonedProject, which runs the same project-creation body as PROJECT_CREATE; the dialog only shows the toast and starts the first session. The mechanism is in project-clone-map.md. 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 src/main/ipc/github-auth-handlers.ts: gh:auth-status reports the active account and every signed-in account (parsed per account block by 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 (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 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, 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 Project and Edit Project dialogs the palette is collapsed behind a single Optional Color chip via src/renderer/src/components/ui/ColorPickerMenu.tsx, which opens the unchanged 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 — the auto-created
~/Claudeproject 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 three-zone side nav and its folders, where new projects appear
- reorder-projects.md — drag, group, and pin projects after they're added
Last verified 2026-10-23