Logs & Debugging (where to find logs, export for support)
Where Omniscio's diagnostic output actually lives — the authoritative rotating log files and their archive, a separate bootstrap log for the earliest startup moments, and how far back the archive realistically reaches. Covers reading them, exporting a bundle for support, and the automatic crash reporting.
On this page
What it is
Omniscio writes four kinds of diagnostic output, each in a different place. You usually only need the first one:
Log files on disk — the authoritative record.
main.log(current) plus at least eighteen rotated backups (main.log.1→main.log.18), each capped at 10 MB — the ring grows past that, up to 144 backups, to protect a 24-hour minimum of history under a 1.44 GB archive ceiling. Backups older than 30 days are auto-deleted on startup. A separatebootstrap.logcaptures the earliest startup moments with rawfswrites, so you still get a trace even if electron-log itself fails to initialize.How far back the archive actually reaches depends on how busy the app is, because the ring is primarily a file count (18), with a 24-hour time floor that can grow it up to 144 files on a busy machine. Every launch measures the real span and writes it to the log —
[log-retention] archive holds NNh of history— and warns when it drops below 72 hours, the point where an incident reported a few days later would have no log left. If you see that warning and you need a longer window, raiseMAX_BACKUPSinsrc/main/services/logging/log-file-safety.ts.If you instead see a single
main.old.logsitting beside amain.logthat starts only minutes ago, the ring was not what rotated it. That file name belongs to electron-log's own default archiver, which renames the live log onto ONE backlog file — overwriting the previous one — and it takes a single line from any process that loads the library without our policy. The window then holds minutes instead of hours. The app switches that rotation off at the transport, and every process that loads the library outside the app is meant to isolate its own log file; where a foreign writer still got through, the evidence that would name it is gone with the run, so treat amain.old.logas a bug report, not as normal rotation. Measured 2026-10-29: an overnight app-restart investigation lost its evidence exactly this way.Debug Log Viewer — a live in-app console that shows a rolling window of the most recent ~2000 log lines from both the main and renderer processes, with filtering, level pills, time-period buttons, and one-click copy.
Crash dumps — native minidump files (
.dmp/.txt/.json) written automatically when the GPU or renderer process crashes at a level regular JavaScript logs can't capture (segfaults, access violations). They live in their own folder.Extra renderer diagnostics — optional verbose
[scroll:*],[session:select],[session:nav],[mobile-perf]lines that can be switched on via alocalStorageflag when you're deep-debugging a UI bug.
Where to find it
The log files are in your account's own folder inside the Omniscio data folder — on Windows under %APPDATA%\omniscio\profiles\<your account>\logs\. The account part of that path is different on every install, so the reliable way to reach it is Settings → Diagnostics → Log Files, whose Open Logs Folder button opens the exact folder for the account you are signed in to. The in-app way to reach them, and to produce a bundle to send on, is Settings → Diagnostics, which also exposes the export-for-support action.
A second folder, %APPDATA%\omniscio\logs\, holds the app's own liveness tapes (heartbeat.log and its snapshots), not your session log. **If you find a main.log there that stops on an older date, it is a leftover from an older version of the app** — the live one is the one under profiles\<your account>\logs\.
How it behaves
How to use it
The easy path (for support): Settings → Diagnostics
- Open Settings → Diagnostics. You'll see up to four cards: Log Level, Log Files, Crash Dumps (only if crashes have occurred), and Actions.
- Open Logs Folder reveals
main.login Explorer so you can open it in any text editor. - Export diagnostic bundle — the one-click artifact to send support. It gathers the recent
logs, the startup and heartbeat traces, a list of crash dumps, version and build information,
and your settings with every secret stripped, into a single ZIP in your Downloads
folder. It also carries a
manifest.jsonrecording, for each place it tried to read, whether it was read, absent, or unreadable — so support can tell "nothing was logged" from "the file was locked at export time". Two more artifacts answer the questions a ZIP of logs cannot:database-health.jsonrecords which database file was in use, its schema version, whether a migration left its failure marker, and which backups a restore could draw from; and thecloudblock ofapp-info.jsonnames every cloud machine your sessions ran on. That is what lets a silent database rebuild or a cloud box that has already been released be established after the fact. If you are reporting a problem and are not sure what to attach, this is the one to send. To send it, attach the ZIP to a bug report from the toolbar Feedback button (see Report conversations) or email it to support@omniscio.com with the exact message you saw and roughly when it happened. - Export Logs zips every log file into a dated archive (
omniscio-logs-YYYY-MM-DD.zip) at a location you pick. Alongside your account's own files it carries the app's machine-level heartbeat tapes in amachine/folder. It is the logs-only option: useful when support asks for just the log files, or when you want the archive somewhere other than Downloads. Crash dumps are deliberately NOT in it — and not in the diagnostic bundle either: that bundle lists them by name, size and date, never their contents. A dump can embed a memory snapshot, absolute paths and prompt fragments, and it cannot be scrubbed like the text artifacts, so it stays on the device unless support explicitly asks for one; then attach it by hand from Open Crash Dumps Folder. - Log Level switches between Error / Warning / Info (recommended default) / Verbose / Debug, plus Quiet (developer). Bump it up to Verbose or Debug before reproducing a bug, then switch back so files don't fill up. Quiet is for a machine that runs the app as a daily driver and runs agents on it: it keeps everything at Info and above plus every line the performance readouts parse, and drops the routine per-request chatter that can otherwise write about a gigabyte a day. Anything you would still need for a bug report survives it. A few lines are written at every level, even Error: a Log Level change, and a Git or Claude Code update starting (
updating in the background) and finishing (update finished (exit …)), an update that could not start, and the next launch's note on an update the app closed in the middle of — so a log sent for support can always show whether an update ran and whether it completed. - Open Crash Dumps Folder (only shown when at least one dump exists) takes you to the minidumps. This button is the ONLY way to get one — they are not in the Export Logs ZIP (see above).
If a crash dump is sitting there, what to do
A dump in that folder means a native process crashed hard enough that ordinary logs could not capture it — a segfault, an out-of-memory kill, or heap corruption in the GPU or renderer process. You do not have to act: the app reports the crash on its own (see "Automatic crash reporting" below), and the report is already on its way by the time you see the file. Three things are worth knowing:
- Do not delete it before support asks. The dump is the only evidence of that particular crash, and it is not re-created.
- Do not attach a dump to a report unless support asks for one. It is a raw memory snapshot, so unlike the rest of the diagnostic bundle it can contain message text and other content. If support asks, open Open Crash Dumps Folder and attach that one file by hand.
- A dump from another program is not a problem to solve. On macOS, a program an agent session launches inherits Omniscio's crash handler, so its crash lands in this folder. Omniscio recognises those and never reports or lists them as its own.
If something shows a Reference ID, quote it
When a part of the app hits a display error, the card that replaces it says so in plain words ("This part of the app hit a display error. Your work is saved. Try again, or restart the app if the problem persists.") and prints a short Reference ID — selectable text, so you can copy it. That id is the handle connecting the card you are looking at to the crash record support can read. Include it in your bug report: without it, a report about a card that only existed for a moment cannot be tied to its record.
If you think a provider is down
Omniscio has no in-app provider status page. What it does show is the specific state it hit — a rate-limit banner with the absolute reset time, an account row that needs re-login, or an error toast naming the failure — and those are the things to check first in Settings → Accounts. When the error repeats across sessions and accounts at the same moment, confirm it is not local by checking Anthropic's own status page at status.anthropic.com. Repeated across one account only is an account state, not an outage.
Reporting a wrong or missing agent reply: attach the conversation transcript
Logs tell you what the app DID. For "the agent's answer is missing / wrong / cut off", the evidence you actually need is what the agent wrote — and the screen is exactly what you cannot trust in that situation.
So the feedback dialog (the bug icon in the header) offers a tick-box, "Include this
conversation's transcript", whenever you have a conversation open. Ticking it attaches the open
conversation as a .md file, which then shows up as a normal removable attachment chip so you can
see what you are sending before you send it.
It is off unless you tick it, and the choice does not carry over to your next report. A transcript is the most sensitive thing this app holds, so it never rides along unasked — and when it does, it is scrubbed exactly like the message before it leaves your computer: pasted keys, tokens, file paths and contact details are masked.
Why it is the right evidence: the transcript is built from the stored message text and does NOT
pass through the display logic that folds tool activity and collapses the region before an agent's
final-answer marker. It therefore shows what the agent wrote even when the screen hid part of it —
the one artifact that can settle a "your reply is not there" report. (Same builder as Export
Conversation in the session menu and the GET /session/:id/export CLI route, so all three produce
an identical file. Exporting conversation content is privacy-adjacent and is always recorded in the
audit log, this path included.)
Too big to attach (more than about 6 MB, or more than the room the report's other attachments leave) is reported as such rather than silently trimmed — a truncated transcript is worse than none, because it reads as the whole conversation. Use Export Conversation and send the file separately in that case.
Which code is actually running: Settings -> Diagnostics -> Running build
The version number tells you which RELEASE you have. It cannot tell you which COMMIT is running, and on a development install those two drift apart constantly - the app keeps running whatever was compiled the last time it started, while the checkout moves on beneath it. A fix can be merged, be sitting right there in the source, and still not be in the app you are using.
Settings -> Diagnostics -> Running build answers that directly. It shows three things:
| Row | What it means |
|---|---|
| Branch | The branch this bundle was built from |
| Commit | The short commit id - the exact code you are running |
| Built | When that build was made |
Each row reads Unknown when the build carries no git identity (a release tarball, a checkout
with no .git, a build made outside the normal path). Unknown is a real answer, not a failure:
it means the app genuinely cannot tell you, and it is deliberately never rendered as blank or as
anything you could mistake for being up to date.
The same three values ride along in every bug report's diagnostics, so a report can be answered without asking the reporter to go and look. That is the point: before this, establishing which code produced a report meant reading a log file or querying the database.
When to reach for it: any time behaviour looks like an older version of the app - a fix that is definitely merged but is not showing up, an instruction or prompt that reads like it predates a change, a setting that behaves the way it used to. Compare the commit here against what you expect; if it is behind, the app needs a rebuild and restart, not a bug report.
Where the version number lives
Settings -> Diagnostics -> Health -> App version shows the running release on every layout, phone included, with a Copy button - the surface to point a support reply at.
On desktop the same number also sits in the sessions sidebar footer. Click it to copy the version, or hover it for the build identity (branch, short commit and build time) in one line. That footer does not exist on mobile, and it is hidden while a panel (Boards, Voiceprint Studio, My API Keys, Agent Messages, a plugin sidebar) owns the second pane, which is why the Diagnostics card is the one to quote when you cannot see it.
The live view: Debug Logs toolbar button
- Click Debug Logs (terminal icon) in the toolbar. If it's not pinned, open the toolbar overflow (⋯) and either pin it or launch it from there each time.
- The viewer shows both main-process and renderer-process lines as they happen — useful for watching a bug reproduce in real time. Time buttons (30s / 1m / 5m / 15m / All) filter the window, level pills (error/warn/info/verbose/debug) toggle visibility, and the Dedup button collapses consecutive identical lines into a single row with a count.
- Copy puts the currently visible entries on the clipboard. Clear wipes the viewer only — the file on disk is untouched.
- Close with Esc or the × button.
The nuclear option: extra scroll/session logs
The renderer has three logging modes for scroll and selection events, toggled in the DevTools console:
localStorage.setItem('mc:log:scroll', 'verbose') // every call
localStorage.setItem('mc:log:scroll', 'dedup') // default — dedups per session+tag, suppresses hidden containers
localStorage.setItem('mc:log:scroll', 'silent') // off
Reload the app after setting. Only useful when debugging scroll-positioning or session-navigation issues.
Where the files actually live
- Log folder:
%APPDATA%\omniscio\profiles\<your account>\logs\on Windows (the folder named after your account differs per sign-in, so read the path from the **Log Files** card in Settings → **Diagnostics**, which always shows the resolved one; the equivalent is theuserDatafolder on macOS/Linux). The app's machine-level heartbeat tapes sit one level up, in%APPDATA%\omniscio\logs\. - Crash dumps: Electron's default
crashDumpspath (a sibling of the log folder inside the sameuserDatadirectory). - E2E isolation: when
AMC_INSTANCE_ID=e2eis set, everything lives underomniscio-e2einstead — letsnpm run test:e2e:prodrun alongside a live dev session with zero shared state.
Automatic crash reporting (auto-send-every-crash)
Separately from the on-disk logs above, Omniscio automatically sends a crash report whenever the app dies — by email (to support@omniscio.com via Resend) and to Sentry. You don't have to export anything or file a bug; a crash reaches the developer on its own. This is deliberately broad about what counts as a "crash":
- Live JavaScript errors — an unhandled exception or promise rejection while the app is running.
- Hard native crashes: segfaults, out-of-memory kills, or heap corruption that bypass all JavaScript error handling. Sentry receives a short text report naming the process that crashed, never the memory dump itself, which stays on this computer because it can hold passwords and message text; the email channel gets a short note pointing at the local dump file (the binary itself can be megabytes, so it isn't emailed).
- Silent deaths — the app is force-killed (Task Manager, OS, power loss) and never gets to run another line of code. Nothing can email at the moment of death, so Omniscio detects these on the next launch (see "heartbeat sentinel" below) and reports them retroactively.
- Startup failures — a crash while the app is still loading its own code, before any of the safety nets above exist. Omniscio writes a tiny "starting up" marker as the very first thing it does; if that marker is still there at the next launch, the previous startup died early, and the failure is reported then.
- A blank window at startup — the window opens but never shows the app (a display or data-loading failure). The main app process notices the window never became usable — even though the blank window itself can't report anything — and sends the report.
Also, if your machine is offline when a crash happens, the report can't leave right then; Omniscio saves it and sends it automatically the next time the app starts with a working connection (still capped at the daily limit below).
Always on, with no telemetry opt-in
Crash reporting and usage telemetry are separate pipelines, and neither has a setting that turns it off. Usage telemetry — anonymized feature counts, uptime, scrubbed error signals, app version and platform — is always on, as the Settings → Diagnostics → Health card states and the privacy policy declares. Anonymized crash capture is always on for the same reason: a silently-dropped crash is worse than a noisy one.
The one switch in this area is Auto-Email Crash Reports (Settings → Diagnostics → Health, on by default). It gates only the detailed crash email and its log excerpt, plus the crash entry in the fleet digest — turning it off does not stop the always-on crash capture.
Watching crash volume: the crash-free-session-rate
The reports above tell you that a crash happened; to answer how often — the number the public-beta "watch crash volume" step and the 1.0 release bar ("crash rate below X% of sessions") are judged against — read the crash-free-session-rate in Sentry Release Health. Omniscio's Sentry SDK counts one "session" per app run and marks it healthy or crashed, so Sentry computes crash-free-session-rate for you — no separate dashboard to build, nothing to divide by hand. To read it: open the Sentry project → Releases (or Release Health), filter to environment production and the release omniscio@<version> you're evaluating; the crash-free-sessions % is the crash-rate bar. Filtering to production matters — dev runs report under development and shouldn't count toward the release bar.
This is on automatically (it rides the same always-on Sentry init as crash capture) and is content-blind: a session carries only a healthy/crashed status and the release/environment tags — no message, stack, or IP. Automated test/sandbox launches don't pollute it because they suppress Sentry entirely (AMC_DISABLE_TELEMETRY / AMC_INSTANCE_ID). For repo-access readers: it's the SDK's default mainProcessSessionIntegration, kept on (and locked by a guard test) in sentry-init.ts; the invariant + the measurement caveats are I28 in the crash-reporting contract.
Privacy
Before any crash report leaves the machine, Omniscio scrubs it. Secrets and paths are stripped — Anthropic API keys, Bearer/JWT tokens, OAuth access/refresh fields, and your Windows/Unix home-directory path — and so is contact PII: email addresses, phone numbers, and non-loopback IP addresses are masked ([EMAIL_REDACTED], [PHONE_REDACTED], [IP_REDACTED]). The scrub runs over the error message, stack trace, and every attached log/crash file. It is deliberately targeted at those shapes so it never mangles stack traces, file paths, or error fingerprints. Your OS username is no longer included. (Your machine's hostname is intentionally kept, so reports can be told apart across machines.)
The local log follows the same rule for its own reason. A request URL Omniscio writes into main.log keeps only its path and its parameter names — every query value is replaced with <redacted> — so a search you ran over the CLI never puts the words you searched for into the log, while the line stays useful for debugging. The same rule now runs a second time on the way out: when you export a log bundle or a diagnostic report, the CLI's own log lines pass through the scrubber, which blanks every query value on them. That closes the gap for lines already on disk from before the write-time rule existed — they were written in the clear, and without it they would have shipped in the clear.
For the Node diagnostic report specifically — a native-crash artifact that bundles your entire process environment — Omniscio goes further than the pattern scrub: it removes the whole environment-variables block before sending, wholesale and name-independent, so even an oddly-named custom key can't slip past the matcher. And if that report is itself corrupted or truncated (so the block can't be cleanly removed), it's withheld entirely rather than sent through the weaker pattern scrub — the crash is still reported, just without the unparseable attachment.
How to turn it off
Settings gives you one switch — the crash email — and nothing that stops capture itself. In order of bluntness:
- Settings toggle — Auto-Email Crash Reports under Settings → Diagnostics → Health. Turning it off stops the crash emails and their log excerpt entirely (default is on); the anonymized crash capture still runs.
- Crash hard kill-switch env var — launch with
AMC_DISABLE_CRASH_AUTOSEND=1. This wins over the setting and additionally prevents the Sentry SDK from loading at all. It exists for automated test suites and incident-response windows that deliberately crash the app and must not spam reports. - Master telemetry kill-switch env var — launch with
AMC_DISABLE_TELEMETRY=1. This is the broadest off switch: one flag silences the ENTIRE phone-home stack — crash auto-send AND Sentry (main + renderer) AND the fleet-telemetry / weekly-digest / error-tail pipeline — by forcing every telemetry-gated check off. It is theisTelemetrySuppressed()master gate that bothgetCrashAutoSendEnabled()andgetTelemetryEnabled()compose, so it wins over the two switches above. The E2E / cloud / CI launch fixtures set it so test boots never report; a real user MAY set it to opt out of everything at once. (A non-emptyAMC_INSTANCE_ID— sandbox / e2e / throwaway instances — triggers the same suppression.)
There is also a built-in daily cap (15 crash emails per calendar day) that survives restarts, so an app stuck in a crash-restart loop can't flood the inbox. A matching guard protects the Sentry side: each distinct error is capped to a set number of events per rolling day (on top of a coarser per-minute limit), so one looping error can't quietly drain the shared monthly Sentry event quota and blind crash monitoring for everyone — the first several of every distinct error still send, so a genuinely new bug always gets through.
The heartbeat sentinel (how silent deaths are caught)
While running, Omniscio rewrites a tiny heartbeat-sentinel.json file in the logs folder every 5 seconds and deletes it on a clean shutdown. If that file is still present at the next launch, the previous run must have died without shutting down cleanly — a silent death. A boot-time sweep (sweepCrashEvidence) finds the leftover sentinel (plus any native crash dumps and Node diagnostic reports), forwards each as a crash report, and marks them so they're never re-sent. One exception — a crash dump that isn't ours. On macOS a program an agent session launches inherits Omniscio's crash handler, so its dump lands in Omniscio's crash folder; the sweep reads each dump's own list of loaded modules and, only when that list positively names no module of ours, recognises it as that other program's crash and never reports, lists or attaches it. A dump it cannot read stays reported, so a parse problem never hides a real crash. The sentinel carries the prior process's PID, uptime, the last operation it was performing, and a short tail of health ticks — enough to answer "was it healthy right before it vanished, and what was it doing?" It also records the launcher that started the app (its PID, name, and start time); on the next launch the sweep compares that against the new process's launcher, so a silent death of an otherwise-healthy app now also says who killed it — the same launcher respawning the app (the signature of a dev-server / electron-vite hot-reload restart) versus a different or absent one (an external kill). That verdict is included in the crash report. The report also says whether the app was still killing something when it died: Omniscio records every process tree-kill it dispatches, and clears the record once that kill finishes, so a record still on disk at the next launch means a kill was in flight when the process vanished. When the target was the app's own process ID — or the process that launched it — the report names it as a self-kill, because a Windows tree-kill carries /T and takes the target's whole subtree down with it, the app included. When nothing was in flight the report says so as evidence only, never as proof that nothing outside ended the process.
How it works (for repo-access readers)
The send path is reportCrash() in telemetry-reporter.ts, gated by getCrashAutoSendEnabled() in accessors-settings.ts (env check first, then the crashAutoSendEnabled setting defaulting on). Sentry init is sentry-init.ts. The boot sweep is crash-evidence-sweeper.ts; the sentinel is written by main-heartbeat.ts. The ledger behind the self-kill verdict is process-terminations-ledger.mjs, written from the single tree-kill dispatch point in child-kill.ts. The exhaustive invariants (the telemetry asymmetry, the sentinel-ownership race fix, idempotency, the boot wiring order) live in the feature contract: crash-reporting-contract.md.
Related
- notifications-and-silence.md — error notifications (what reaches you), not the log record (what the app writes for later)
- session-stuck-in-needs-you.md — if one specific session is misbehaving, its needs-you state usually explains more than the log file
- diagnostics-developer-experience.md — the whole area this page opens: how the app records what it is doing, how you read those records, and how to export a support bundle with the diagnostics already attached
Last verified 2026-11-09