Omniscio

Session Search (sidebar virtual project)

Session Search is a permanent sidebar entry: a chat with Claude where you describe a past session in plain English and Claude does the searching, then replies with clickable links straight into the session it found. Claude's first call is GET /search/sessions, which answers in ranked, deduped SESSIONS rather than message rows — fusing the title, the worktree branch, the dev-pipeline plan title, the crew, the opening message and the transcript, plus a local embedding index of the same metadata. Ctrl+K remains the separate, instant keyword palette.

On this page

What it is

Session Search lets you find past Omniscio sessions by describing what you're looking for in plain English — "that Stripe refund thing from last week", "the session where I debugged auth", "help me find the script I was writing for invoices". It ships as a permanent Session Search entry in the sidebar (the __search__ virtual project): a chat with Claude where you ask in plain English and Claude does the legwork — calling the local search endpoints, verifying candidates, and replying with real omniscio://session/<id> deep links you can click to jump straight into a session.

The sidebar surface is backed by one ranked search over session titles, plan titles and transcripts (see "Session-level search" below). When smart search is switched on (Settings → Sessions → AI-Powered Search), a local embedding index of titles and opening messages adds meaning-based matches on top; when it is off, nothing touches the embedding engine.

The Ctrl+K palette no longer has a separate "Semantic" tab. That UI was removed in the 2026-04-26 search redesign. Semantic ranking now blends silently into the regular Ctrl+K results per existing eligibility — there's no mode toggle, no AI badge, and no "Top N matches" wording. See semantic-search.md for the silent-blend behaviour. If you want a Claude-driven, conversational search experience, use the sidebar Session Search project documented below.

Where to find it

How to use it

  1. Find it in the sidebar. A project named Session Search sits in the sidebar list alongside your real projects (seeded on first launch, idempotent — it survives deletion attempts).

  2. Click Session Search. Clicking the sidebar entry drops you straight into a session with the reply textarea focused — no "+ New Search" click needed. If a previous search chat is waiting on you (a question or error), you land on it; otherwise you land in a fresh blank with the textarea focused, ready to type your next query. Behind the scenes Omniscio spawns the Claude CLI with a system prompt that tells Claude how to query the local search endpoints. Blank-session reuse on the backend keeps repeated clicks from spamming new rows — the last empty chat is recycled.

    Ctrl+T / N also work while Session Search is active — same as in any other session-hosting project — so you can spin up a fresh search chat without leaving the keyboard. (See keyboard-shortcuts.md for the full list.)

  3. Ask in plain English. Type something like "what was that session where I was debugging the Gmail OAuth flow?" and send. Claude will call /search/sessions once with the topic words of your request (it leaves out words like "session" or "yesterday") and answer from the ranked rows — each shows the session's opening request and which of your words it matched. It takes one more differently-worded search only when the first turns up nothing on the topic, so a question costs one call, or two at the most; when the words are not enough it answers with the closest matches and one question about the detail that would settle it rather than hunting. Every call it makes is around ten seconds of your wait, which is why it spends so few. It replies with a short synthesized answer plus a list of clickable session links in the format - [<session name>](omniscio://session/<id>) — <one-line reason>.

  4. Click a result. The omniscio://session/<id> links render as real buttons in the chat — clicking one opens the session in-app without a page reload (see deep-links.md).

  5. Ask follow-ups. Since it's a normal Claude session, you can say "show me the last three in that series" or "only the ones in the Gmail project" and Claude keeps searching.

Use the sidebar Session Search project when… Use Ctrl+K (global search) when…
You only remember the gist and want a synthesized natural-language answer with reasoning. You remember an exact phrase, error string, or file name.
You want Claude to verify candidates by reading recent messages before recommending one. You want to filter by channel (SMS, Slack, Telegram, RSS, webhook) — sidebar search is session-only.
You want to ask follow-ups in the same conversation ("now narrow to Gmail project"). You want raw results back instantly — no LLM round-trip.
The query is fuzzy enough that keyword search wouldn't match. You need phrase quoting ("refund flow"), exclusion (-word), or OR syntax.

The Ctrl+K palette shows an Ask AI button (the sparkle icon) — desktop in the modal header, mobile in the Filters row. Clicking it opens a small popover (it no longer launches directly), pre-filled with whatever you'd already typed, where you tweak what to search for. Submitting spawns a Session Search chat in the background that auto-runs your query — you are not pulled out of what you were doing. A toast confirms "Searching in the background…" with an Open button that jumps you into the chat; the chat also appears in the sidebar with its normal status, so you can switch in when it's ready. The chat bubble shows only your question — the scope instructions ride hidden in the sent prompt (via the displayText override).

The search is scoped to the tab you're on. On Conversations it searches your sessions/messages and folds in your active filters (project, channel, dates, tags). On Notes it searches your KMS vault (/kms/search, /kms/semantic-search). On Settings it answers from your settings catalog, injected as context (there is no settings search endpoint). The All tab searches conversations + notes. Meetings / Voice / Recordings / Helpdesk currently fall back to searching conversations + notes — dedicated per-surface AI search for those is a planned follow-up.

Submit stays disabled until the box is non-empty; a launch failure shows an error toast and keeps the popover open to retry. The button hides itself if the Session Search project hasn't been seeded yet (very first launch) or outside the desktop app. Behaviour is locked by search-ask-ai-contract.md.

How it behaves

Dependencies and failure modes

Session Search depends on Omniscio's local HTTP server at 127.0.0.1:19519 — the same localhost-only server documented in cli-control.md. The server exposes four read-only endpoints the feature relies on:

  • GET /search/sessions?q=<query>&limit=<n> — the ranked, one-row-per-session search Claude starts with (see below).
  • GET /sessions?startedAfter=<ts>&excludeSessionId=<id> — the list of sessions in a time window, for "what did I work on yesterday?" requests.
  • GET /session/<id>/history?tier=final+user — the prompts and answers of one session, used only when two candidates are close.
  • GET /search/fts and GET /search/semantic — keyword and meaning search over messages, still served for other callers.

All four endpoints require Authorization: Bearer <token> where the token is read from ~/.amc/cli-token (%USERPROFILE%\.amc\cli-token on Windows). Missing or invalid token returns 401 { ok: false, error: "unauthorized", code: "AUTH_REQUIRED" }. The bundled search-sessions skill that Omniscio writes into each Session Search workdir's CLAUDE.md reads the token file and adds the header for in-Omniscio sessions automatically; external CLI users (Claude Code outside Omniscio, curl, scripts) must add the header explicitly. Auth is gated on these endpoints because they expose private session content — FTS hits, semantic neighbours, full transcripts — that localhost-only binding alone does not protect from other processes on the host.

All responses are { ok: true, ... } or { ok: false, error: "...", code: "<ERROR_CODE>" }. Every failure body carries a machine code alongside the human error string — the error strings are frozen, and code is the discriminator to branch on, so a client never has to match on prose or special-case which branch it hit (AUTH_REQUIRED on 401, RATE_LIMITED on 429, VALIDATION_FAILED on 400, NOT_FOUND on a gated 404, REQUEST_TIMEOUT / SERVICE_UNAVAILABLE on 503, INTERNAL on a 500).

When GET /search/fts cannot finish (2026-09-25). The full-text route runs on its own short-lived database host rather than the shared one, so a common-word search can no longer stall or recycle the worker every other read depends on. If that host cannot complete the search, the route answers 503 { ok: false, error: "<plain reason>", code: "REQUEST_TIMEOUT" | "SERVICE_UNAVAILABLE" } instead of hanging. The distinction matters to a caller: an empty results array ALWAYS means the search ran and matched nothing, never "we gave up".

When the search host cannot start at all (2026-10-25). Both GET /search/fts and GET /search/sessions run their transcript read on that same short-lived host. If no host can be started — a busy machine, a slow disk, or the AMC_DISABLE_SEARCH_OFFTHREAD escape hatch — the answer is 503 { ok: false, error: "The search could not run right now. Please try again.", code: "SERVICE_UNAVAILABLE" }, and the retry is the remedy. This is a deliberate "skip, retry later" rather than a fault: it is never answered 500 and never reported to the crash channel. A caller should treat it as capacity, not as a broken server.

When the server is unreachable. Inside a sidebar Session Search chat, Claude itself runs into the refused connection and tells the user "Omniscio does not appear to be running" in its reply. The feature fails soft; it does not crash the session. The inline Ctrl+K semantic blend (see semantic-search.md) goes through a main-process IPC proxy with a 5-second timeout — on failure it silently falls back to pure keyword results without any user-visible alert, since semantic and keyword hits no longer have separate UI surfaces.

Port override caveat. The bundled search-sessions SKILL.md (which Omniscio copies into the session's workdir as CLAUDE.md) hardcodes 127.0.0.1:19519. If you run Omniscio with the AMC_CLI_PORT=<n> override, the sidebar Session Search chat will not find the server. Fix planned; acceptable Phase-1 limitation.

One call instead of many: the sessions digest

GET /sessions/digest answers the question Session Search takes several round-trips to reach — what is every agent doing right now, and what did it last say to me? — in a single call. Where a caller would otherwise list sessions and then fetch each one's messages, the digest returns, per session: its status, the original ask, the last real user message, and the last N agent messages.

GET /sessions/digest?repo=<folder path or project name>&statuses=needs_you,running&prose=3

Every parameter is optional: repo (one repo; omitted means every project) or projectId (exact, wins over repo), statuses (default needs_you,running), prose — how many agent messages per session, 1–20, default 3 — maxChars (per-message clip, 1–5000, default 600), sessionLimit (1–500, default 200), and format=text|json (default text).

Prefer the digest when you want the state of a whole board; use Session Search when you are hunting for one specific conversation. The digest is scoped by repo and status, not by relevance — it has no query, so it cannot find the session where something was discussed, only report what each session is doing now.

The token tier decides the content. The global ~/.amc/cli-token reads everything (scope: "full"): opening asks, the user's replies, agent prose and — under ?include=alerts — the inbox. A scoped $AMC_CLI_TOKEN (an agent's own per-session token) reads scope: "metadata": facts about sessions — name, status, timings, spend, turns, branch and its lifecycle token, crew, spawn provenance — with every message field empty and the inbox never fetched. That is deliberately MORE than a /sessions row carries (which has no spend, turns, crew or branch lifecycle) and deliberately nothing anyone wrote. The reply lists what it withheld in withheld, so an empty transcript is never mistaken for 'this agent said nothing'.

One call for an inbox overseer. Triaging "what is waiting, who started it, and what did it last say" used to mean a call per session plus a call per transcript. Three opt-in parameters fold the whole picture into the same request: include=crew,branch,alerts (all takes every one), fullText=1 to drop the per-message clip, and changedSince=<ISO> to see only what moved since your last pass — the mark is echoed back so a five-minute sweep can page forward. Alongside the fields above, each session then also reports who really wrote its opening request (user / peer / system, so a person's own chats separate from a spawned worker fleet), its Plain Speak overlay parsed into sections and carried beside the final message rather than instead of it, any lettered question it asked, the app's own attention bucket (where an interrupted turn is distinguishable from a delivered one), and how long it has been running next to its cost and turns. As with everything else here, a caller that asks for none of it gets exactly what it got before.

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" GET "sessions/digest?repo=<folder path>&statuses=needs_you,error,stalled&include=all&fullText=1&format=json"

Relationship to the search-sessions skill (external/CLI users)

There is a user-level skill at ~/.claude/skills/search-sessions/ that documents the exact same endpoints and search strategy for Claude Code sessions running outside Omniscio. If you're using the Claude CLI directly (not through Omniscio) and the skill is active, you can say "find my Omniscio session about X" and that external Claude will curl the same 127.0.0.1:19519/search/semantic endpoint. The skill is the single source of truth. In-app Session Search sessions load the SAME skill body — Omniscio reads .claude/skills/search-sessions/SKILL.md at spawn time (or, in packaged builds, from resources/bundled-skills/search-sessions/SKILL.md), strips the YAML frontmatter, and writes it to ~/Claude/search-sessions/CLAUDE.md so the Claude CLI auto-loads it on startup. One file, both surfaces — no drift risk, no second copy to keep in sync.

Relationship to inline semantic search in Ctrl+K

Omniscio has a separately documented feature called Semantic Search (Settings → Sessions → AI-Powered Search) — that feature silently augments keyword Ctrl+K results by blending a few vector-similarity hits at the top of the response. As of the 2026-04-26 redesign there is no UI distinction between keyword and semantic hits in Ctrl+K (no AI badge, no Local/Semantic toggle, no "Top N matches"); semantic ranking just runs invisibly under the hood when the eligibility criteria match (clean query, Most Relevant sort, first page, no source/date filters).

The sidebar Session Search project documented above is a different surface entirely:

  • It's a chat with Claude, not a results palette — Claude verifies candidates and synthesizes a natural-language answer.
  • It calls the same local HTTP server (/search/sessions, /sessions, /session/<id>/history) the CLI exposes, through the spawned CLI agent, not via IPC.
  • It returns conversational replies with deep links, not score-ranked rows.

Both features use the same underlying embedding pipeline, so either surface finds the same sessions — they just present differently.

Self-exclude — why the search agent never finds itself

The search agent is itself running in an Omniscio session, so without protection its own session would be the strongest match for any query (the user's request to the search agent is the most relevant document for any query the user just typed). Omniscio prevents that deterministically:

  1. Spawn-time env injection. When Omniscio spawns the Claude CLI for a search session (or any other session), process-manager.ts:spawnLocalStreamJson sets spawnEnv.AMC_SESSION_ID = session.sessionId. The env var rides in the child process environment alongside CLAUDE_CODE_OAUTH_TOKEN and Omniscio's other per-spawn stamps.
  2. Ambient strip. getStrippedExact() in clean-spawn-env.ts includes AMC_SESSION_ID, so a leftover shell-profile copy from a prior debug run cannot masquerade as a legitimate spawn-injected value (same canonical strip-and-reinject pattern as ANTHROPIC_API_KEY).
  3. The search route leaves the asker out. The search-sessions skill calls GET /search/sessions through the helper, which sends X-AMC-Source-Session-Id; the route drops that session from every leg. Its one GET /sessions time-window call passes excludeSessionId=$AMC_SESSION_ID itself, because that list never excludes the caller by default.
  4. The other search routes still filter on request. handleSearchFts and handleSearchSemantic in cli-server-search.ts drop any result whose sessionId matches an excludeSessionId param before responding (after the timeframe filter, with total recomputed for FTS).

When the env var isn't set (external Claude Code outside Omniscio), the skill falls back to two heuristics — drop sessions started in the last 10 minutes, drop sessions whose first message is a near-paraphrase of the user's query. The heuristics are best-effort and can mis-fire when the user legitimately wants to find an old session whose prompt resembled their current one; the env-var path has no such ambiguity. Full invariants and safe-change checklist: session-search-contract.md.

No Plain Speak overlay on a search answer

A Session Search reply is the result list, so it does not get the Plain Speak overlay. A plain-speak card would restate the answer already on screen and hide it behind a ⇄ toggle — noise on a chat whose whole output is "here are the sessions, with links".

The switch is the ordinary per-session overlay opt-out, stamped at session birth for anything created in the __search__ virtual project (and, for the same reason, in __ask_amc__ — see ask-amc.md — and in the Chief of Staff chat, see simple-mode.md). Stamping the row means it holds for every later spawn of that session, not only the first turn, and it also drops the "you forgot your card" nudge and the spoken-narration fragment.

The rule has one home — OVERLAY_SUPPRESSED_VIRTUAL_PROJECT_PATHS in virtual-project-ids.ts — and is applied by both session-minting paths (session-create.ts for Claude, the gated non-Claude leaf in ipc/session/launch.ts). Chats created before this shipped keep the cards already stored in their transcripts: stored message content is never rewritten.

Session-level search — GET /search/sessions

The search agent's FIRST call. It answers in sessions, not message rows: one row per session, deduped and ranked server-side, so a caller never pages a day of sessions or probes each candidate with a second call.

Each row carries the session's status, startedAt, lastActiveAt, messageCount, ownerMessageCount (messages the person actually wrote, from sessions.message_count_human), branch, firstMessage (the opening request, 200 characters), matchedTerms (which of the query's words it matched), the matchSources that found it (name, branch, task, crew, semantic, transcript) and a score. A row has no snippet.

It fuses the signals that actually identify a session, all through existing queries:

  • metadata — the title, the session's worktree branch, the dev-pipeline plan title, the crew name and the id. These carry the words a person remembers ("nighty-tidy-findings-review-deck- linear", "Nighty Tidy findings review deck") that a generated title never contains.
  • transcript — each query word looked up newest-first: the newest 1,000 messages that contain it, in both the live and the archived store, giving up to 100 sessions per word. It never scores every match, which is what made a common word take minutes on a cold disk.
  • meaning — the session's embedding, only while smart search is switched on. With it off the route never touches the embedding engine.

Words every request uses ("session", "Omniscio", "find", "yesterday" and similar) are left out before the eight-word limit, and a query made only of them answers with a notice asking for a topic word. Titles are ranked by how many of the query's words they hold before the 300-row cut, and read from their own index. The score counts how much of the query a session's title and transcript cover, with rare words worth more, plus a boost when the query names the session's project and for messages the person typed — and a session nobody typed in (a reviewer, a lander, a worker) ranks lower. Measured on 35 real past searches: the right session reached the top 3 in 13 of 35, up from 2.

The route excludes the calling session by default (the opposite of GET /sessions, which is a census — see the self-exclude section below).

The index stays current

session-index-scheduler runs a bounded index pass every minute while smart search is on, so a session created after launch is embedded within a tick instead of waiting for the next restart. The embedded document is the title + plan title + branch + crew + project + the opening message (capped at 400 characters, because MiniLM reads ~512 tokens and an untruncated message would push the branch out of the window).

A session is re-examined when it has no embedding, or when it has been ACTIVE since it was last checked (session_embeddings.checked_at). That second arm matters because the branch and the plan title are written minutes after the session starts — the first embedding cannot hold them. A pass stamps checked_at even when the document is unchanged, so the candidate set cannot stall, and content_hash is what decides whether to re-embed. source_text still stores only the session name; the hash is a sha256 digest, so no new private content is stored at rest.

The guard. GET /status carries searchIndex (newestEmbeddedAt, newestSessionAt, lagSeconds, stalledSeconds, stale, counts), and /search/semantic repeats it beside the results. It measures the INDEXER, not the clock: a pass counts as progress when it had no failures or actually wrote a vector, and the index is stale when no usable pass has completed for two hours, or when nothing has ever been embedded on an install that has sessions. The health check runs on its own cadence rather than after the pass, so even a pass that never returns ages the clock. While smart search is on, one deduped inbox card is raised — and cleared again once a usable pass lands. When smart search is off because the ONNX crash breaker turned it off, the existing circuit-breaker card is raised instead.

A wedged pass cannot stop the indexer. The pass runs behind a single-flight latch, and a pass contains awaits with no deadline of their own — a model load waiting on the network, an engine init, a background read — so one pass that never returned used to be the last one for the life of the process, while the card went on saying it retried every minute. Each pass now carries a five-minute deadline: past it the latch is released and, while smart search is still on, the embedding host is re-armed when the model is not ready (a healthy model is left alone), so the next tick is a real retry and indexing resumes by itself once the engine recovers — no restart, and no trip to the settings switch. The abandoned pass keeps its own generation, so its late completion can never clear a newer pass's latch and it stops at its next candidate; when it does land it still updates the health clock. Five minutes is far longer than a normal pass, whose 25 embeds take milliseconds each; a pass in which every embed hit its own 60-second deadline is exactly the wedged engine the deadline exists for, and abandoning it costs only work the next pass redoes. What this cannot fix is a model download that black-holes inside its own HTTP fetch: that load is coalesced, not aborted, so the engine stays unavailable until the connection settles or the app restarts, however often the indexer retries.

Writing nothing is normal on a busy install: a running session re-marks itself active every few seconds while its embedded text stays the same, so the "sessions still to check" figure never reaches zero and no vector is written for hours — neither figure says anything about health. Silent staleness was the whole failure this guard exists for; a false alarm on a working index is the other side of the same coin.

Archive & retention

Search sessions archive just like any other session — on desktop you middle-click the row (no X button is shown on desktop), on mobile you tap the X button (mobile-only) to remove it from the default sidebar list. Archived search sessions then appear in a collapsed Archived (N) row at the bottom of the Session Search project's sidebar. Clicking the row expands it so you can reopen a past search, and clicking again collapses it. The count updates live as you archive or reopen sessions.

Unlike regular projects — where archive history is kept indefinitely — archived search sessions are retained for 30 days only. After that, an automatic background task soft-deletes (is_deleted = 1) any search session whose status = 'archived' and whose status_changed_at timestamp (the moment of the last status transition, which the archive flow updates) is older than 30 days. This keeps the Archived drawer from growing unbounded for a feature that generates throwaway one-shot chats. Regular project archives are unaffected by this pruner — only rows belonging to the __search__ virtual project are eligible.

Pruned rows remain physically present in the SQLite file (soft-deletes leave the row on disk; SQLite is not configured to auto-vacuum), but they are never exposed to the renderer because every sidebar and list query already filters AND is_deleted = 0. If a user ever needs manual recovery of a pruned search session within that file-retention window, the underlying row can still be found by querying the database directly; there is no in-app undo after pruning. The two layers of "delete" here are: status = 'archived' (reversible, visible in the Archived drawer, 30-day window) and is_deleted = 1 (invisible to the UI, set by the background pruner).

The pruner logic lives in archive.ts (pruneOldArchivedSearchSessions) and is scheduled alongside the other periodic DB maintenance tasks in the main process.

  • global-search.md — the Ctrl+K palette (FTS5 keyword search blended silently with semantic ranking, filters, deep-links)
  • semantic-search.md — the inline semantic augmentation of keyword results inside Ctrl+K (different surface, same embedding model)
  • cli-control.md — the 127.0.0.1:19519 HTTP server that hosts the /search/sessions, /search/semantic, /search/fts, and /session/<id> endpoints
  • deep-links.md — the omniscio://session/<id> URLs Claude renders in its replies
  • default-claude-project.md — the sibling ~/Claude default project that hosts search-sessions/ as a subdirectory

Last verified 2026-10-02