Omniscio

CLI Feedback Submission (file bugs / feature requests from external AI)

How to file a bug, feature request, feedback or question from an outside AI: the in-app Send Feedback button and the local HTTP route that mirrors it, what each response code means, how diagnostics get collected, and the rules an agent should follow so a report is actually useful to the developer reading it.

On this page

What it is

Omniscio has a bug-icon toolbar button ("Send Feedback") that opens a small dialog where you pick a category — Bug, Feature, Feedback, or Question — type a description, optionally drop in screenshots, and send. Signed in, the dialog asks for no email at all: it shows "We'll reply to your account email" — the address Omniscio fills in from the account you are signed in with, so a report always carries an address the developer can reply to — with a Use a different email button that brings back the box for a different reply-to (a typed address always wins). Signed out, the optional email box shows as before. Hitting "Send Bug Report" / "Send Feature Request" / etc. runs the payload through the shared report-delivery chain (report-delivery.ts), which sends to Resend (an email to the Omniscio developer) and/or Firestore (the developer's bug-report database) according to the bugReportTransport setting (default both). Both stop when the user turns off Email bug reports & feedback: nothing leaves the computer, and the report is kept locally and re-sent automatically once the switch is back on (or once the failing leg recovers) — no resend needed from you. A send always ends in an answer: the awaited delivery leg carries a deadline sized from that leg's own allowance, so a send that is merely slow is never cut short, but a leg that never settles stops holding the Send and the report falls into that same saved-locally outbox instead of leaving you watching a spinner. The device diagnostics a report carries are collected under their own deadline too — on a computer where reading them stalls, the report is sent without them rather than not at all. Device / version diagnostics (app version, Electron version, OS, arch, Node version, current active-session count, status breakdown, recent error log lines, a recent-crashes summary from the last 48h — crash-signature log lines + crash-evidence files, scrubbed and bounded, shown only when the app has actually crashed, see recent-crashes-contract.md, process uptime) are auto-collected and attached so the report is actionable without follow-up. The report counts as delivered if any leg succeeds — email or Firestore alone; only if every leg fails is it kept in the <userData>/bug-reports/ outbox, so it is never silently lost, and the hourly outbox drain retries it later automatically. The log files ride the email leg alone — the database copy carries how many there were, never the bytes — so a report whose email leg failed has just that one leg queued for retry, from a saved copy that keeps the report's own log files. That matters because the log directory rotates on its own: a retry that re-read the directory would send a later window of logs than the one you were looking at. The Help Desk ticket records what the report said it carried, so a ticket whose logs never arrived says so instead of looking complete, and a report finally given up on raises an inbox card naming how many log files went with it.

That same flow is now reachable over the 127.0.0.1:19519 localhost HTTP control server — POST /feedback — so an external AI agent (Claude Code in another project, ChatGPT with the omniscio-control skill, a curl script, the in-app sandboxed Claude session) holding the Omniscio bearer token can file a bug report on the user's behalf without piping the form through the renderer.

Where to find it

The way in is a bug icon in the app's toolbar — the Send Feedback button — which opens a small dialog where you choose a category, write the description, and optionally attach screenshots. There is no sidebar entry and no settings page for this; the button is the whole surface. The rest of this page describes how to reach the same flow without touching the interface at all, which is only useful if you are an AI agent or writing a script.

How it behaves

Sending feedback is a single one-shot action: pick a category, write the description, attach anything useful, and press send. Nothing is saved as a draft and nothing is queued for later on your end — the report goes out on the spot. If every leg rejects it, Omniscio keeps it in a local outbox rather than silently losing it, and an hourly background drain retries it automatically — you do not need to send it again. Because the destination is the developer's inbox rather than your own data, the send is not put behind an approval prompt the way a destructive action would be.

The two neighbours most worth knowing are where Omniscio's own logs live, which is usually the first thing to consult before filing anything, and the startup trace you can paste into a slow-startup report. Both are named in the list below. The page also sits within the wider CLI surface, so if what you want is to drive Omniscio over HTTP generally rather than just file a report, start from CLI control.

Boundary with bug-report-intake

This page covers the outbound "send a bug to the Omniscio developer" path — exposed at POST /feedback, dispatched via the shared report-delivery chain (email, Firestore), no per-project routing.

The inbound "tester emails a bug to MY project's intake address" path (subject [BUG: <slug>] <title>, parsed and routed to the matching project's Claude session) is a separate feature documented at bug-report-intake.md. The two share no code and do not interact.

See also

  • logs-and-debugging.md — where Omniscio's local logs live; useful to consult before filing a bug
  • startup-trace.md — the self-contained startup.log you can paste into the bug body for slow-startup reports
  • cli-server-gating.md — full CLI endpoint gating reference
  • cli-server-feedback.test.ts — 43 cases across /feedback and /feedback/bug-report covering auth gating, validation, happy path, diagnostics auto-attach + caller-supplied preservation, delivery outcomes (200 delivered / 202 kept-and-queued / 502 genuinely lost), the kept-202's sending-off-vs-will-retry error text, X-Client-Request-Id replay (delivered AND kept), concurrent-duplicate coalescing, and rate-limit
  • cli-feedback-routes.test.ts — the body cap (a >1 MB attachment is accepted; over the cap still 413s), and the video route's promises: the link reaches the delivered message, a refused publish files nothing, a screenshot is refused, the share token comes back even when a later step throws, a retry never publishes twice, and an agent token is both admitted and confined
  • feedback-video-attachment-contract.md — the binding contract for the video route

Last verified 2026-09-28