Omniscio won't start, or says Claude Code is missing — the first-run fixes

What it is

This page collects the three startup failures a new user meets most: Claude Code not being installed yet, a database held open by another copy of the app (or a startup upgrade that failed), and a pile of running sessions using more memory than the machine comfortably has. It is written so you can follow it yourself, and so an Omniscio session can follow it for you — and it says plainly which of these must never be answered by deleting your database.

Where to find it

The problems show up at launch: the setup screen on the first run, an error dialog instead of the app window, or a machine that drags once several sessions are running. The settings the fixes use are inside the app — Settings → System for the Claude Code binary path, Settings → Sessions for the message history limit, and the Backup area of Settings for the automatic backups a failed upgrade can be restored from.

How it behaves

The app says Claude Code isn't installed

Omniscio runs your sessions on Claude Code, a separate tool made by Anthropic. A brand-new computer does not have it yet, so this is expected on the very first launch — nothing is broken.

1. Let the setup screen install it. The first-run setup offers to install Claude Code. Accept that offer and wait for it to finish. This is the easiest path and needs no terminal.

2. If the install did not happen, install it yourself with one command:

   npm install -g @anthropic-ai/claude-code
   

   That needs Node.js on the machine. If npm is not recognised, install Node.js first (the LTS installer from nodejs.org), then run the command again.

3. If it is installed but still not found, tell Omniscio exactly where it is: open Settings → System and set Claude Code Binary Path. Common locations are:

   • Windows: %APPDATA%\npm\claude.cmd
   • macOS: /usr/local/bin/claude or ~/.npm-global/bin/claude
   • Linux: /usr/bin/claude or ~/.local/bin/claude

4. Restart Omniscio after installing or changing the path. The app reads your system PATH when it launches, so a restart is what makes a new install visible.

If you use a Node version manager (nvm, fnm), make sure the version that has Claude Code is the active one before you restart Omniscio.

It won't start and mentions "database is locked" or a failed migration

Stop before deleting anything. These two messages look like "the app won't start", but they are not corruption, and deleting the database or its -wal/-shm files destroys data that can be recovered.

"Database is locked" / busy

Almost always another program is holding the file open:

1. Check for a second copy of Omniscio (an older install, or one still shutting down) and quit it.
2. Close any SQLite browser, backup tool or file-inspection tool that has the database open.
3. Relaunch Omniscio — do not delete the database or the WAL files.

A startup migration failed

A migration is a startup upgrade of the database. If one throws, Omniscio stops rather than carry on with a half-upgraded database:

1. Restore the automatic backup taken just before that upgrade — Omniscio keeps per-migration backups, and the Backup area of Settings lists them.
2. If you cannot find one, email support@omniscio.com before deleting anything. Omniscio also keeps an automatic backup snapshot every 6 hours by default, so a recent copy almost always exists.

Only the genuine corruption case (a database integrity failure, with no usable backup) is answered by starting fresh — and even then, restore the newest automatic backup first if one exists.

The app is using a lot of memory

Omniscio itself is one process; each running session starts its own Claude Code process, and each of those can use a few hundred megabytes. A big pile of active sessions is the usual reason memory climbs.

1. Finish or archive sessions you are not using. Archived sessions leave memory.
2. Lower the message history Omniscio loads per session: Settings → Sessions → Message history limit (default 200). Turning it down shrinks the message cache; "Show all messages" still loads a long conversation on demand.
3. Restart Omniscio. That clears the in-memory caches and reloads only what is active.
4. If the whole machine freezes right after many sessions start at once (a crash recovery or a bulk restart), the machine is out of memory and swap is thrashing. Wait for the burst to settle or restart the computer, then open fewer sessions at a time.

For a deeper, step-by-step memory guide, see Computer feels slow? A step-by-step fix-it guide.

Still stuck

Email support@omniscio.com. Include:

• the reference number shown in the error message, if there is one;
• what you were doing when it happened (first launch, after an update, after a restart);
• the exact words on screen.

That is enough to find the matching entry in the main log and tell you what happened.

Related

• First-time setup — the guided first run, including the Claude Code install.
• Windows installer — what the installer does and what it needs.
• Computer feels slow? A step-by-step fix-it guide — the deeper memory and load guide this page points at.
• Fresh install — starting point — starting over cleanly without losing what can be kept.