--- title: Ask Omniscio — in-app help agent --- # Ask Omniscio — in-app help agent ## What it is Ask Omniscio is a sidebar virtual project that hosts normal Claude CLI sessions pre-seeded with the Omniscio LLM library and a live view of your Omniscio state. Each chat is a friendly tutor — longer explanations, no programmer jargon — that answers "how do I X?" / "what is X?" questions about the app and can configure it for you. Multiple parallel chats are supported and each is independent (no cross-chat memory in v1). The feature is on by default; turn it off in Settings → Features if you don't want the sidebar entry. ## Where to find it ### How to use it 1. **Find it in the sidebar.** Ask Omniscio is on by default. On a **fresh install** it is pinned as its own standalone row at the very top of the sidebar, right next to Claude (2026-08-19) — the flagship helper, always one click away, no longer nested inside the AI Tools group. To turn it off, open Settings → **Features** → flip off **Enable Ask Omniscio (in-app help agent)**. Toggling off is non-destructive — chats and history stay on disk; the sidebar simply hides them. Toggle back on and they reappear intact. You can drag Ask Omniscio anywhere in the sidebar; the pinned-next-to-Claude placement is just the fresh-install default (existing installs keep wherever it already sat, e.g. the top of the Omniscio built-ins divider). 2. **Start a chat — click the Ask Omniscio entry.** Clicking the sidebar entry drops you straight into a session. If a previous chat is waiting on you (a question, an error, or a stalled run), you land on it. Otherwise you land in a fresh blank chat with the textarea focused — start typing immediately. The "+" button on the project row still works for explicitly creating a new chat alongside an existing one. Chats run as normal Omniscio sessions: status flow, inbox row, snooze / archive / pause / Send Later, notifications — all unchanged. 3. **Ask anything — or ask to be shown.** "What's the difference between Snooze and Pause?", "What sessions need my attention right now?", "Schedule a cron pinging my main inbox every Monday at 9am." The agent reads the LLM library, queries your live state, and either explains or drafts the change for your approval. You can also ask **"where is X?"**, **"walk me through X"**, or **"show me around"** — instead of just naming the menu path, the agent lights up the real buttons on your screen and can step you through a multi-stop guided tour with Previous / Next (see _What the agent can do_ → **Points at the UI**). 4. **Approve mutations in the inbox.** When you ask the agent to change a setting, schedule a cron job, build a recipe, or wire an automation, the agent says "I've drafted X — look in your inbox for the approval row." Open the row and approve or reject it. Keybinding changes are the one exception — they apply immediately because they're personal preferences, not scheduled command execution; the agent will flag this clearly when it does one. 5. **Open multiple chats.** Each chat is a fresh session. Use one for "what is this feature" questions, a different one for "configure this for me" tasks, a third while the first two are still running. They don't share memory. ## How it behaves ### The model it runs on (yours first, ours as the safety net) Ask Omniscio runs on **your own Claude model first** — the same model behind your other sessions — so it answers as well as any other agent you run. If you have **no Claude credentials of your own**, it falls back to a **built-in, company-paid model** (**Claude Haiku**, which also reads screenshots and PDFs) so the help agent still works. That is the "never breaks" guarantee: you get a working helper whether or not you can run one yourself. > **Changed 2026-08-06.** Ask Omniscio used to prefer the built-in company model for everyone, to protect your Claude usage. That made it noticeably weaker for people already paying for a strong model, so the order was flipped: your model first, ours as the safety net. **Trialing a faster text model (opt-in).** A cheaper, faster model (DeepSeek V4 Flash) can handle _typed_ questions on the same company-paid, monitored path; screenshots and PDFs always stay on Claude, and if DeepSeek is ever unavailable a typed question falls back to Claude too. It ships **off by default** (`askAmcUseLuna`) while we confirm it works well, and — like the company-model switch — its toggle is developer-only for now. **Turning the fallback off.** The setting `askAmcUseCompanyModel` (on by default) now controls only the **fallback**: off = never spend company credit, so a user with no Claude credentials of their own gets the standard "sign in" prompt instead of the built-in model. It does not affect you if you already have your own credentials — you were never on the company model to begin with. Its Settings → Features toggle is **developer-only** (hidden in production builds). **Spending guardrails.** The per-session spending cap applies **only** to the company-paid fallback, because that is our money — on your own credentials Ask Omniscio spends like any other session you run. **No file writing, ever.** Ask Omniscio can't create or edit files on **any** path — your model or the built-in one. It's a help agent, not a builder: it reads, searches, browses the web, and takes the usual approval-gated actions. (This used to be tied to the built-in model only; it is now unconditional, so switching credentials can never quietly hand the help agent write access to your disk.) ### What the agent knows - **The LLM library.** The full `docs/llm-library/` tree (this file plus its siblings) is bundled into the chat's working directory on every spawn. The agent reads `INDEX.md` first and pulls specific pages on demand. If your question isn't covered, the agent says "not in library" before answering from general knowledge. - **A feature-recommendation catalog.** The bundled library includes a generated `feature-recommendations.md` — **released** features grouped by user goal (built off the Feature Roadmap), each with a one-line pitch. So when you ask what to use, the agent recommends real, available features and never points you at something that hasn't shipped. - **Your live state.** A new `GET /state` endpoint on the local CLI control server (`127.0.0.1:19519`) returns sessions, projects, accounts, integrations, settings, and inbox metadata in a single document. The agent curls it with the auto-delivered bearer token (same token the `omniscio-control` skill uses) for any "right now" / "current" / "what is pending" question. Read budget is 60 reads/min per token, separate from the global mutation rate-limit. - **Your past sessions (by content).** When you ask it to _find_ a past session ("which session was about X?", "find where I set up Y"), it searches across all your sessions' messages — by keyword and by meaning — using the live-database search endpoints, so it always sees your current sessions (never a stale copy) and hands you a clickable link to the best match. - **Project context.** The CLI's standard tool set (Read, Edit, Write, Grep, Glob, Bash) is available, so the agent can open files outside its working directory when relevant to your question. ### What the agent can do - **Read-only by default.** Explanations come from the library plus `/state`. The only on-screen effect it can produce without an approval is the UI spotlight (next bullet) — a dismissible highlight, never a data change. - **Recommends features by goal.** Ask "what should I use for X?" or "recommend a feature" and the agent matches your goal against the released-only recommendation catalog and suggests a few that fit — grounded in what's actually shipped, so it won't pitch an unreleased feature. - **Points at the UI — and gives guided tours.** When you ask "where is X?", "how do I get to X?", or "walk me through X" / "show me around", the agent doesn't just describe the menu path — it draws an on-screen spotlight + tooltip on the actual control. For anything that takes more than one step it builds a **guided multi-step tour** you click through with Previous / Next at your own pace, and it'll offer one proactively when you're learning a workflow. (Under the hood it reads the pointable elements from the CLI server's `GET /ui/snapshot` and calls `POST /ui/highlight`.) The overlay is purely cosmetic: it changes nothing in your data and clears when you dismiss it or finish the steps. When a tour points at a specific setting, it opens the Settings page that holds that setting first — even if you last left Settings on a different page. If you haven't allowed agents to move your screen, Ask Omniscio shows a **Go there** button instead of jumping; click it to land on the setting. - **Approval-gated mutations.** Cron jobs, automation rules, recipes, and settings changes route through the existing `omniscio-control` CLI surface — they land as `pending` rows in your inbox and do not fire until you approve them. This is the same flow external AI tools (ChatGPT, Claude.ai with the skill installed) use today. - **Immediate keybinding edits.** Keybinding mutations are not approval-gated — they apply to live sessions immediately via the `SETTINGS_CHANGED` push. The agent flags this in plain language so you know which kind of change just happened. - **No process spawns on its own initiative — a standing instruction, not a hard block.** The agent is told never to call `/project/.../new` unprompted (that would spawn a real Claude process and cost money), and its session runs with `Write` and `Edit` disallowed. That rule is enforced by the agent's instructions, not by code: **Settings → CLI Control → "Require approval for AI session spawn"** (`requireApprovalForAiSessionSpawn`) ships **off**, and with it off the spawn router launches directly — the only unconditioned backstop is the outstanding-spawn backlog cap. Turn that setting on to route every AI-initiated spawn through an inbox approval row first. - **Hands off real build work — on your explicit ask.** Ask Omniscio is the in-app _helper_: it has no access to the Omniscio source code and can't write files, so it won't try to build or change code itself (and it won't go hunting for a "repo" it doesn't have). When you ask it to actually build, fix, or change something — or say "spawn a session to do X" — it hands off: it spawns a **separate dev session in your own Omniscio project** (which has the code and the full dev pipeline) to do the work. Because that spends money, it only spawns when you clearly ask, and offers first when the request is ambiguous. ### Question log (owner review) Every time a help conversation starts, Omniscio records the opening question to a small local table, `ask_amc_questions`, so the owner can review what people get stuck on (a signal for what's confusing). It captures the question text, which surface asked it (`ask_amc` here, or `ask_page` for [Ask about this page](ask-about-this-page.md)), a link to the session (open it to read the answer), an attachment flag, and a timestamp. One row per conversation — its opening question; follow-up turns aren't logged separately. - **Local table + anonymized cloud view.** The full row (with the session link) stays in the local SQLite DB — there is no LOCAL in-app viewer; it's read back by querying the DB / `listAskAmcQuestions()` ([queries-ask-amc-questions.ts](/src/main/db/queries-ask-amc-questions.ts)). A telemetry-gated fleet tail also ships an **anonymized, scrubbed, length-capped** copy of the question (no session link, keyed only on a random install id) to the owner's cloud, where the admin console's **"Search & Questions"** tab shows what people ask across all installs. It rides the same Error-Reporting (`telemetryEnabled`) consent as every other fleet event and auto-deletes after 180 days. - **Bare question, not screen context.** "Ask about this page" logs only the question you typed, never the captured on-screen context (which rides in the model prompt, not the log). - **Fail-safe.** Logging is best-effort: if it ever errors, the help agent still answers (the Ask Omniscio "never breaks" guarantee). Captured at the `createSessionWithPrompt` chokepoint in [session-create.ts](/src/main/services/session/session-create.ts). Full invariants: `.claude/memory/contracts/ask-amc-questions-log-contract.md`. ### No Plain Speak overlay An Ask Omniscio chat shows the answer, not a plain-speak card restating it. The helper answers questions; a second copy of that answer behind a ⇄ toggle is noise, so the project carries the per-session overlay opt-out — stamped at session birth, exactly as Session Search does, and read at every spawn. Same rule, same single home: `OVERLAY_SUPPRESSED_VIRTUAL_PROJECT_PATHS` in [/src/shared/virtual-project-ids.ts](/src/shared/virtual-project-ids.ts). See [session-search.md](session-search.md) for the mechanism. This is about the transcript overlay only — the on-screen **spotlight and guided tours** described above are a different feature and are unaffected. ### Privacy model - **Settings whitelist redaction.** The `/state` endpoint exposes settings through a closed whitelist; any AppSettings field not on the list is dropped. A test asserts that adding a new field forces a deliberate whitelist opt-in, so secrets cannot leak by default. - **Inbox is metadata-only.** `/state` returns sender, channel, timestamp, status, and a 100-character preview — never the full message body. Ask Omniscio does **not** browse your message content on its own — the one time it reads inside your sessions is when you **explicitly ask it to find a past session**, which it answers with the live-database session search (returning a short matching snippet + a link), never unprompted. - **Bearer token is private.** The agent reads the token from `~/.amc/cli-token` to authenticate against the local server but is instructed never to echo it back in chat output. - **No MemPalace cross-pollination.** Even when you have MemPalace turned on globally, it is NOT attached to Ask Omniscio sessions in v1, so help-agent chats can't accidentally read or write your project memories. - **Where your questions go.** Normally Ask Omniscio uses your own Claude credentials, so questions go to your own account/provider — exactly like every other session you run. If you have no credentials of your own and it falls back to the built-in company model, your questions (and any attached screenshot/PDF) are processed by Anthropic's Claude Haiku — the same provider that already serves every other Omniscio session, so no third-party vendor is involved. Everything else above (whitelist redaction, metadata-only inbox) still applies either way. ### v1 limitations - **No cross-chat memory.** Each Ask Omniscio chat starts blank. If you want a fact remembered between chats today, you'd file it via MemPalace from a regular session. - **No starter prompts.** The sidebar entry is on by default, but no auto-introduction or seeded chat. You decide when to start one. - **No SSH-remote spawn.** Ask Omniscio sessions always run locally; the spawn never forwards to an SSH-remote host. ### How it works The toggle `askAmcEnabled` lives in [/src/shared/types.ts](/src/shared/types.ts) with the matching Zod field in [/src/shared/ipc-schemas.ts](/src/shared/ipc-schemas.ts) (`updateSettingsSchema`); `DEFAULT_SETTINGS.askAmcEnabled` is `true`. The sidebar entry uses sentinel virtual project ID `__ask_amc__` from [/src/shared/virtual-project-ids.ts](/src/shared/virtual-project-ids.ts), resolved to `/ask-amc/` by [/src/main/services/claude-project.ts](/src/main/services/claude-project.ts). The project row is created by `ensureAskAmcProject()` from two call sites: at app startup in [/src/main/index.ts](/src/main/index.ts) when the flag is on (covers fresh installs and configs that pre-date the field), and from the settings-update handler on a toggle-on transition (covers users who turned it off and back on). The seeder is idempotent — second and later calls are no-ops on an already-active row, and undelete a soft-deleted one. The row is auto-assigned to the Omniscio built-ins divider with `insertAtTopOfDivider: true` (claims `MIN(display_order) - 1`); and on a genuinely-new row `ensureAskAmcProject` also pins it (`isPinned: true`) so the sidebar's pinned section renders Ask Omniscio standalone, immediately after Claude — that default SLOT is written into the stored order once, by `backfillAskAmcPlacementOnce()` (`askOmniscioPlacementBackfilled` one-shot), which runs at startup right after `backfillAskAmcPinOnce()`. The pinned section renders `display_order` verbatim, so the row is an ordinary draggable row: moving it in the pinned list sticks, and nothing re-places it afterwards. Existing installs that were seeded with the old append-at-bottom behavior are backfilled by migration v110, which finds the Ask Omniscio row inside the Omniscio divider and rewrites its `display_order` to `MIN - 1`. The migration is scoped to the Omniscio divider, so a row the user dragged out is left alone, soft-deleted rows are skipped, and the no-divider case (user cleared the Omniscio group) is a no-op. A renderer-side selector in [/src/renderer/src/stores/project-visibility.ts](/src/renderer/src/stores/project-visibility.ts) filters `__ask_amc__` out of the visible-projects list when `!settings.askAmcEnabled`, subscribed to `SETTINGS_CHANGED` push so flag flips take effect without a reload. The `/state` endpoint is implemented in [/src/main/services/cli/cli-server.ts](/src/main/services/cli/cli-server.ts) backed by a unified-inbox composer in [/src/main/services/state-redaction.ts](/src/main/services/state-redaction.ts) that calls the seven per-source backend queries (sessions, SMS, Telegram, digest, cron approvals, automation approvals, recipe approvals) and merges by timestamp. Spawn integration lives in [/src/main/process/process-manager.ts](/src/main/process/process-manager.ts): when the session's project resolves to the `__ask_amc__` sentinel, a process-level mutex serializes the spawn, [/src/main/services/ask/ask-amc-bootstrap.ts](/src/main/services/ask/ask-amc-bootstrap.ts) atomically refreshes the workdir (write to `/ask-amc.bootstrap-tmp/` then rename) from `resources/llm-library/` and `resources/ask-amc-claude.md`, MemPalace MCP is force-disabled, and `--append-system-prompt` carries a 5-line shim that tells the agent to fail loudly if the workdir CLAUDE.md was not auto-loaded. If bootstrap throws, the spawn aborts and surfaces a user-facing toast — no silent agent-without-context. Full design rationale: [Ask Omniscio design doc](../plans/2026-04-26-ask-amc-helper-design.md). **Company-model routing.** `askAmcUseCompanyModel` (default `true`, [/src/shared/types/settings/agent-tools-settings.ts](/src/shared/types/settings/agent-tools-settings.ts)) gates a pure decision function `resolveAskAmcModelPlan()` ([/src/main/services/ask/ask-amc-model-plan.ts](/src/main/services/ask/ask-amc-model-plan.ts)) that the spawn path ([/src/main/process/spawn-cluster-manager.ts](/src/main/process/spawn-cluster-manager.ts)) consults before injecting credentials. **The user's own credentials come FIRST:** the spawn passes `userHasOwnCredentials`, derived from the session's auth pathway (`resolveSpawnAuthMode()` — `passthrough` needs nothing injected, `apiKeyOnly` counts when the isolated slot holds a key, `managed` counts when the pool has an account); when true the plan returns `user-credentials-first` and the spawn credentials exactly like any other native session. Only when it is false does the plan route to the company Claude Haiku key (`MODEL_HAIKU_LATEST`, from `getAskAmcFallbackApiKey()` in [/src/main/services/default-credentials.ts](/src/main/services/default-credentials.ts)), overriding `--model` and appending the per-session `--max-budget-usd` cap; with no company key or the setting off it falls through to the Layer-5 fallback (so never-breaks holds). `Write,Edit` are added to `--disallowedTools` on **every** path, company or not — the restriction describes the agent, not the funding source (Bash stays — Ask Omniscio needs it to reach the local control server). Full invariants: `.claude/memory/contracts/ask-amc-contract.md` → "Company cheap model (the FALLBACK — the user's own credentials come FIRST)". **Disabling the baked-key spend (operator kill switch).** Setting `AMC_DISABLE_ASK_AMC_FALLBACK=1` in the environment stops AMC from ever spending on the bundled Anthropic key at runtime — no new build needed. The company-model routing, the automation-helper company key, and the Layer-5 bulletproof fallback all read one getter (`getAskAmcFallbackApiKey()` in [/src/main/services/default-credentials.ts](/src/main/services/default-credentials.ts)), so the one flag neutralizes all of them: each degrades to the user's own credentials, or the standard refuse-spawn toast when the user has none. It exists so a leaked or abused baked key can be shut off instantly. ## Related - [cli-control.md](cli-control.md) — the same local HTTP server the agent uses for `/state` - [cli-pending-actions.md](cli-pending-actions.md) — how approval-gated mutations land in your inbox - [create-cron-job-with-ai.md](create-cron-job-with-ai.md) — sister flow for external AIs using the `omniscio-control` skill - [mempalace-memory.md](mempalace-memory.md) — opt-in cross-session memory (separate feature, not attached here)