Projects — the folders you work in

What it is

A project is a folder. Adding one registers a folder you already have, or creates a new empty one for you — Omniscio stores a reference to it and never moves or copies your files. Removing the project does not touch the folder either.

Sessions live inside a project. Every session you start belongs to exactly one project, and that pairing is what hands the agent its working folder, the project's own default engine, its notes, and the project documents it is allowed to read.

Some sidebar rows are not folders. Omniscio's built-in tools — Session Search, Recipes, Cron Jobs, Skills, Stats and the rest — appear as projects so you can open them from the same rail, but they are virtual: they have no folder on disk. They ship nested inside a collapsible Omniscio group, and Settings is one of them.

One project is made for you. On a fresh install Omniscio creates a Claude project in your home directory (~/Claude) so there is somewhere to chat with no codebase attached. It behaves like any other project, and deleting it sticks — it is not re-created on the next launch.

Where to find it

• The projects sidebar is the left rail: your projects as vertical bars with their live sessions beside them as coloured status dots, a pill badge on any project whose sessions need you, pinned projects in a fixed section above the scrollable list, and collapsible dividers grouping related projects.
• Add one with the + icon in the sidebar header — it offers Add Project and, in the same popover, New Group for a new divider. A divider's own menu can add a project straight into that group.
• Work on one by right-clicking its row: the context menu carries edit, notes, files, appearance, pin, recipes, delete and the permanent erase.
• Quick Create's destination folder is the one project setting that lives outside the project: Settings → System → Default Projects Folder.

How it behaves

Adding and removing

• Adding has three routes in one dialog — create a new folder, point at an existing one, or paste a GitHub repository URL to clone and add in a step. A folder you already track is recognised instead of being added twice, and the display name starts from the folder's name without renaming anything on disk. See Add a project.
• Remove Project takes the project out of the sidebar and stops its sessions, but it is a soft removal with an Undo toast for a few seconds afterwards, and your folder on disk is never touched. Permanently Erase sits directly below it in the same menu and additionally purges everything Omniscio had stored for that project — messages, search rows, archives, attachments — with no Undo. Neither one deletes the folder itself. See Delete a project.
• A folder that goes missing is not silent: the next session in that project fails immediately with a red banner naming the exact path and a Recreate Folder button, instead of retrying forever. See Project folder missing (recreate or relink).

Making a project recognisable

• Each project carries a display name, a colour, and an icon. The icon starts as a guess — a background cascade reads the folder's favicons, manifests, package files and app icons — and you can replace it with an image, an emoji or a built-in glyph, or ask for it to be detected again.
• A short plain-English line can be set for hubs, so a row says what the project is rather than just naming it. See Hub Descriptions.
• See Edit a project for everything changeable after the fact, including moving the project to a different folder.

Arranging the sidebar

• Drag rows to reorder them, create dividers as named collapsible section headers, and drag a project from one divider into another; pinned projects sit above everything and scroll separately. See Reorder projects.
• The rail itself collapses to an edge gutter and can be filtered down to only the projects with something happening, or sorted by how much you use them. See The sidebar (hubs and sessions), Show only active projects (funnel filter) and Sort projects by usage.

The extras a project carries

• Notes — a markdown scratchpad per project, opened from its menu. See Project Notes (markdown scratchpad per project).
• A default engine and a deploy profile — a project can set the provider its new sessions start on, and the instructions describing how that project ships. See Switching between AI providers and Deploy Profiles.
• Spend — a project's sessions roll up into its own cost, token and session-count view. See Codebase Stats (project health dashboard).
• Documents the agent may read — context files handed to the agent for this project, and the auto-injected kind. See Auto Context — auto-inject files like Claude.ai Projects and Project docs selection.
• Bug intake — a project can be given an email address that turns incoming bug reports into sessions, behind a safety screen. See Bug intake safety screen.
• Its own window — a project can be popped out of the main window into a window of its own. See Pop out a project or integration window.

Related

• Add a project — the Add Project dialog's three tabs, name rules and icon detection
• Edit a project — everything about a project you can change after it exists
• Delete a project — removal with Undo, and the permanent erase beside it
• Reorder projects — dragging, dividers, pinning and collapsing
• The sidebar (hubs and sessions) — the rail these rows live on
• Project Notes (markdown scratchpad per project) — the per-project scratchpad
• Project folder missing (recreate or relink) — when the folder itself is gone
• Pop out a project or integration window — a project in its own desktop window
• Default Claude Project (chat without software context) — the project Omniscio makes for you
• Settings — Virtual Project Entry — Settings as one of the built-in virtual projects