Omniscio

Delete a project

How to remove a project from the Omniscio sidebar: the ordinary removal that leaves your folder untouched on disk, and the separate permanent erase that purges the project's stored data at once — plainly irreversible, with no undo.

On this page

What it is

Deleting a project removes it from the projects sidebar and terminates any running sessions inside it. It's a soft delete — the row stays in the SQLite database with an is_deleted = 1 flag rather than being physically removed, so an immediate Undo restores it cleanly. Your folder on disk is never touched — only Omniscio's reference to it goes away. This makes "remove a project" a low-stakes operation: if you delete the wrong one you have ~8 seconds to click the Undo toast, and even after that a developer can hand-flip the flag back in SQLite. Deleted projects do not re-appear after restart, including the auto-created Claude project (~/Claude) — once removed, Omniscio respects the user's intent and doesn't resurrect it.

Where to find it

How to use it

  1. Right-click the project row. In the projects sidebar, right-click the project you want to remove. The portal menu opens and, below a separator in its destructive group, the first item is Remove Project (red trash-can icon) — Permanently Erase sits directly beneath it.

  2. Click Remove Project. A confirm dialog appears: "Are you sure you want to remove "<name>"? This will terminate N active session(s). Your files will not be deleted." The count covers running, waiting-on-you (needs_you), red-error, and idle sessions in the project. It is not everything Remove archives: a paused session is not counted, yet Remove still stops and archives it along with the rest. Archived and ended sessions are settled already and don't count. Click Remove (red destructive button) to proceed, or Cancel to back out.

  3. Middle-click goes elsewhere — it is not a delete shortcut. On desktop, middle-clicking the project row runs a different gesture: it clears what is waiting on you in that hub, archiving its needs_you items behind their own confirmation. The project itself is untouched, and Remove Project has no middle-click route — use the right-click menu (on mobile the overflow menu is the only path).

  4. If an agent will not stop, the delete is refused. Omniscio stops a project's agents before removing it, because removing a project out from under a live agent is how work gets lost. If any agent is still running a few seconds later, the delete stops there and nothing is changed — you get "Some agents did not stop, so nothing was changed. Stop them and try again." Stop those sessions by hand (see pause or stop a session) and click Remove again. Before this, only Claude's agents were stopped and the delete always went through, so an external engine's agent kept working against a project that no longer existed — with nothing on screen saying so.

  5. Use Undo within the toast window. A toast appears for ~8 seconds: "Project "<name>" removed" with an Undo button. Click it (or press the keyboard shortcut shown next to the button — by default the global Undo shortcut) to restore the project row. The sessions that were terminated stay terminated — undo only un-soft-deletes the project record.

  6. Out of luck after the toast? There is no "Recently deleted" UI yet. If you missed the Undo window, you can manually flip the row back — but close Omniscio first: a write to the database while the app is running can corrupt it. Then open the SQLite database at <userData>/mission-control.db (path varies by OS — see logs and debugging), run UPDATE projects SET is_deleted = 0 WHERE id = '<project-id>', and restart Omniscio to pick up the change.

    The project's sessions do not come back the same way. Remove Project archives them rather than soft-deleting them (see "How it works"): each live session gets status = 'archived' and archived_by = 'project-deleted', and its is_deleted stays 0 — so there is no soft-deleted flag to clear. If you also want them listed again, un-archive them explicitly with UPDATE sessions SET status = 'ended', archived_by = NULL WHERE project_id = '<project-id>' AND archived_by = 'project-deleted'. Two details matter: restore to a settled status only (ended, error, needs_you or paused) — a live one such as ready or running would leave a row claiming a process it does not have, which is why the app's own un-archive clamps anything else to ended; and keep the archived_by = 'project-deleted' filter so this cannot resurrect sessions you archived yourself. The row does not record the status it held before the cascade, so pick the settled one you want.

Note that deleting the Claude project (the auto-created ~/Claude workspace) works the same way — the only twist is that Omniscio won't re-create it on the next launch. The dedup check in the code intentionally includes soft-deleted rows so the user's deletion is respected. If you change your mind, add ~/Claude as a regular project via the + button.

How it behaves

Permanently erase (irreversible, no undo)

Directly below Remove Project in the same right-click menu is Permanently Erase (eraser icon). This is the heavier, one-way cousin of Remove, meant for a privacy/data-subject erasure request rather than everyday tidying:

  • Remove Project is a soft delete: the row is hidden (is_deleted = 1) but its conversation history, embeddings, search index, archive, and attachments all remain in the database until the aged retention purge. It has an ~8-second Undo.
  • On an app row (a row in the Apps section) the menu has no Remove item; Remove from side nav takes the app off the sidebar instead. Permanently Erase on an add-on app purges that app's sessions and stored data the same way but keeps the app installed and reachable, like a fresh start. Data the app keeps in its own storage (for example the books Books imported) is not touched.
  • Permanently Erase runs that soft-delete cascade AND then immediately purges the project's stored data — messages, embeddings, FTS search rows, cold-storage archive, and attachments — instead of waiting for the retention horizon. There is no Undo.

Clicking it opens a red danger confirm: "Permanently erase all of "<name>"'s data? This terminates its active sessions and cannot be undone. Your files on disk are not deleted." (There is no type-the-name step — the danger button is the guard.) Your files on disk are still never touched; only Omniscio's stored records go. The success toast reads "Erased all data for "<name>."" without a row count, because the purge is a global retention sweep and any number would over-state what belonged to this one project.

How it works

The right-click menu's Remove Project entry in ProjectListItem.tsx calls handleDeleteProject(), which uses useConfirmDialog() for the confirmation prompt. (The row's middle-click handler is a different gesture — it clears the hub's waiting items; see step 3 above.) On confirm, the renderer calls useProjectStore().removeProject(id), which invokes the PROJECT_DELETE IPC channel handled in project-handlers.ts. The handler delegates to deleteProjectService(id) in project-delete-service.ts, which runs the cascade: stop every non-terminal session on the engine that owns it, through the shared control seam in engine-agent-control.ts — an agent run by any engine is stopped, not only Claude's — and refuse the delete if an agent will not stop. It then calls queries.deleteProject(id), which in one transaction soft-deletes the project row, cascade-archives its live sessions, and hard-deletes the dependent rows (codebase_stats_cache, codebase_stats_ignores, recipe_schedules, cron_jobs, focus_mode_rules, tag_project_scopes, nighty_tidy_audit_schedules, nighty_tidy_runs, bug_intake_processed, orchestration_runs, team_time_project_links). The service then prunes orphan cron-group labels, removes any recipe schedules referencing the project (emitting RECIPE_SCHEDULES_CHANGED when it removed at least one), and emits PROJECTS_CHANGED — plus TAGS_CHANGED when a tag scope lost this project and sessions carried it.

The actual SQL is in deleteProject() in queries-projects.ts — a single transaction that soft-deletes the project row through the shared softDelete() helper (which stamps updated_at) and DELETEs the dependent rows listed above. Note recipe_schedules is a hard delete, not a soft delete — schedules don't survive project removal even if the project is later undeleted. The undo path in ProjectListItem.tsx registers a useUndoStore entry whose execute calls useProjectStore().undeleteProject(projectId), which invokes the PROJECT_UNDELETE channel — that one just runs UPDATE projects SET is_deleted = 0, updated_at = ? WHERE id = ? in queries-projects.ts and emits PROJECTS_CHANGED. Sessions are not auto-undeleted because they were also terminated and their is_deleted cascade is a separate concern.

Soft delete is a project-wide convention: every query in queries-projects.ts and every SELECT against the projects table includes AND is_deleted = 0, so deleted rows simply don't appear anywhere in the UI without being physically purged. The projectExistsByFolderPath() check in queries-projects.ts intentionally does not filter by is_deleted, which is what makes the Claude project's deletion stick — re-running ensureClaudeProject() on the next launch sees the deleted row and skips creation.

Permanently Erase wires the same way but with no undo: the menu item calls handleEraseProject() → useProjectStore().eraseProjectData(id) → the PROJECT_ERASE_NOW channel in project-handlers.ts → eraseProjectDataNow(id) in project-delete-service.ts, which runs deleteProjectService + markProjectSessionsForImmediateErase + an immediate purgeExpiredData. The channel is blocked on the mobile/web bridge and deliberately has no CLI route — an irreversible mass-erase stays a desktop-confirmed action.

  • project-folder-missing.md — different scenario: the folder is gone but the project row stays. Different banner, different fix
  • add-a-project.md — adding a project back if you missed the Undo window
  • edit-a-project.md — non-destructive changes to a project (rename, recolor, re-icon)
  • default-claude-project.md — the auto-created Claude project follows the same delete flow but does not re-create itself on next launch

Last verified 2026-10-14