System Instructions (Auto Context sub-group)

Renamed 2026-05-27; mobile unified 2026-06-03. This surface used to be a standalone Claude Files sidebar section. As part of the Auto Context redesign it was folded in as the first sub-group of the unified Auto Context panel — same probe, same rows, same peek-on-click — alongside the Always-inject and On-demand context sub-groups. Both desktop and mobile now render it from inside that one Auto Context panel (ProjectDocsSection); the separate mobile ImportantFilesSection — which only ever showed these four rows, never the Always-inject / On-demand groups — was removed when mobile was unified onto the shared panel. The user-facing label everywhere is now System Instructions; "Claude Files" survives only as a historical synonym.

What it is

A sub-group inside the Dashboard's right-hand Auto Context (N) sidebar panel that gives you one-click access to the four AI-context files that shape every Claude Code session in this project: the project's own CLAUDE.md and MEMORY.md, plus the global ~/.claude/CLAUDE.md and ~/.claude/memory/MEMORY.md. These are the files Claude reads on every turn — the project file holds repo-specific rules, the global file holds your cross-project preferences — and editing them is the single most direct way to change how AI sessions behave in this project. The sub-group exists so you don't have to dig through Explorer to find them, and so they live next to the auto-injected docs and the on-demand catalog under one umbrella heading.

Where to find it

Open any project in Omniscio and look at the right-hand sidebar (the "Dashboard" pane that lists Channels, etc.). Find the Auto Context (N) group near the bottom (hover the label for a one-line reminder of what the panel collects). Click to expand. The System Instructions sub-group renders first, above Always-inject and On-demand context. Its sub-heading only appears when at least one of the other two sub-groups also has visible rows — a project with only System Instructions present skips the sub-heading and lists the four rows flat.

The probe fires when the Auto Context group expands; the four rows reflect the on-disk state as of that moment.

How it behaves

What each row looks like

When expanded, the sub-group shows up to four rows, each one a clickable button laid out as two lines:

• Top line (truncates if needed): the file's identity in the form <scope> <label> — project CLAUDE.md, project MEMORY.md, global CLAUDE.md, global MEMORY.md. Tailwind truncate clips with an ellipsis at the right edge if the sidebar is narrow, but the full absolute path is always available as a hover tooltip on the row.
• Second line (smaller, muted): <relative time> · <token count> — for example 2h ago · 3.2k tokens. The dot separator only renders when both halves are present; if one is missing the other appears alone. A small sync-status chip (✓ in sync / ⚠ out of sync) sits on the right when the file has a known synced mirror — see agent-instructions-sync.md for the lockstep contract.

Token count format:

• Under 1,000 → 743 tokens
• 1,000 – 9,999 → 3.2k tokens (one decimal)
• 10,000 – 999,999 → 47k tokens (rounded, no decimal)
• 1,000,000+ → 1.2M tokens (one decimal)

The token count is a size-based estimate, not a real tokenizer count. Omniscio computes it as Math.ceil(bytes / 4) (the shared estimateTokensFromLength helper in src/shared/token-estimate.ts) from the file's fs.stat size — the same 4-bytes-per-token heuristic Auto Context uses for its cap math. This is intentional: it's good enough to tell you whether a file is "small" vs "this is eating my context window," it requires zero file reads (we already have the stat call for mtime), and it adds zero bytes to the bundle (no tokenizer chunk). It will drift from the real tokenizer's count by maybe 10–20% on average — fine for relative sizing, not fine if you need an exact budget.

A row that doesn't exist on disk (e.g. the project hasn't been given a CLAUDE.md yet) is still rendered but at 40% opacity, with cursor-not-allowed and no click handler; its second line reads a muted not created so the empty row explains itself instead of looking broken.

What clicking does

Clicking an existing row opens the file in Omniscio's file peek overlay — the same right-side slide-in panel that opens when you click a file path in an agent message or in the other Auto Context sub-groups. The peek overlay shows the file's contents with syntax highlighting; it does NOT open an external editor and does NOT modify the file. From the overlay you can read, copy, and (via the overlay's own controls) edit-in-Monaco. The row click routes through useFilePeekStore.getState().openFile(project.id, entry.absolutePath), the same call site every other peek surface uses, so behavior is consistent across the app.

There's no separate "open in Explorer" or "delete" affordance on the row itself — keep the surface minimal. If you need those, use the peek overlay's own header buttons.

Why these rows never participate in bulk-select

System Instructions rows are deliberately unselectable when the Auto Context panel is in multi-select mode. The other two sub-groups gain checkboxes; System Instructions stays plain. A stray Ctrl+A + Delete would otherwise wipe CLAUDE.md / MEMORY.md in one confirm dialog, which would reset the agent's project-specific rules + memory — a high-cost destructive accident the redesign explicitly avoids. To edit or remove a System Instructions file, open the row's peek overlay and use the overlay's own controls.

Virtual projects (Settings, Tags, etc.)

For virtual projects — the built-in sidebar entries like Settings, Quick Replies, Stats, Tools, etc. — the sub-group only shows the two global rows (global CLAUDE.md, global MEMORY.md). It hides the project-scoped pair because virtual projects either don't have a real workdir at all (Settings) or map to a sentinel like __claude__ → ~/Claude that doesn't carry a CLAUDE.md. The backend gate is isVirtualProject(project.folderPath) — if true, project rows are skipped server-side, not just hidden client-side.

So on a virtual project you'll see the sub-group count as (N) where N is 0, 1, or 2 depending on whether your global files exist.

Loading and error states

• Loading (first ~50 ms after expand): four full-height skeleton placeholders pulse in place of the rows so the section's height doesn't jump when the probe completes. Skeletons are min-h-[56px] to match the real two-line row height.
• Probe error (extremely rare — project ID not found, IPC dropped): a single 56-px row reads Could not check files in muted text. The sub-group count stays at (0). No retry button — collapse and re-expand the Auto Context group to re-fire the probe.

The probe re-fires when you switch to a different project only if the Auto Context group is open (or it's a first-ever visit with no saved collapse pref). The load effect is keyed off project.id + expanded, with a generation guard so a fast project switch doesn't race a stale response into the new project's UI. A collapsed revisit that already has a saved pref skips the probe (and the docs walk) and renders the cached count instead — see the "lazy load" follow-up in project-docs-auto-expand-postmortem.md.

Why this exists (and what it deliberately is NOT)

The Dashboard sidebar already exposes the auto-injected .claude/docs/ files (always + RAG buckets). What was missing before the redesign was a one-click way to get at the direct AI-context files — the ones the agent reads on every turn, not just the auto-injected reference material. The Auto Context redesign keeps that one-click affordance but folds System Instructions in as the protected first sub-group, so all three categories of "what does this project automatically tell the agent?" live under one heading.

What this sub-group is not:

• Not a CLAUDE.md editor — clicking opens the peek overlay, which is read-by-default. Edit-in-Monaco is one further click inside the overlay.
• Not a full file browser — only those four specific paths. If you want to browse .claude/, open the project folder in Explorer or use the file tree elsewhere.
• Not a token-budget guard — the count is an estimate, not a real tokenizer count, and there's no enforcement. It's a hint, not a cap.
• Not auto-refreshing — the probe runs when the Auto Context group is open (on expand, and on project change while it's open; a collapsed revisit with a saved pref skips it and shows the cached count). It does NOT re-fire on filesystem changes — if you edit CLAUDE.md in another editor while Omniscio is open, the row's mtime stays stale until you re-open the Auto Context group.

For agents

How it works

Frontend — both desktop and mobile render the four rows via SystemInstructionsGroup.tsx, a presentational component that takes pre-loaded files + syncedMirrors from its parent ProjectDocsSection.tsx — mounted by SessionsSidebar on desktop and MobileSessionsList on mobile. The parent owns the IPC call (IMPORTANT_FILES_PROBE) via probe-instructions.ts so the probe + sync-status chip + row rendering can be unit-tested in isolation without entangling the rest of the panel's state. (Until 2026-06-03 mobile shipped a separate ImportantFilesSection that rendered ONLY this sub-group; it was removed when mobile was unified onto the full Auto Context panel — the single-renderer invariant is locked by mobile-auto-context-parity.test.ts.)

Backend — src/main/ipc/file-handlers/important-files-handlers.ts, the IPC.IMPORTANT_FILES_PROBE handler (auto-discovered and registered through src/main/ipc/file-handlers.ts). Wrapped in wrapHandler with Zod input validation (importantFilesProbeSchema — just { projectId: string }). For each of the up-to-four target paths the handler calls a single internal probeFile() helper that does await stat(path) and returns { exists, mtime, tokenEstimate }. Non-existent files (any ENOENT/EACCES/non-regular-file) return { exists: false, mtime: null, tokenEstimate: null } — the response shape is uniform so the renderer doesn't need to special-case errors per-row. The token estimate comes from the single chars/4 helper estimateTokensFromLength(s.size) in src/shared/token-estimate.ts (Math.ceil(length / CHARS_PER_TOKEN), CHARS_PER_TOKEN = 4) — computed from the same stat result used for mtime, so no extra fs.readFile and no async work beyond the existing stat.

Path resolution:

• Project CLAUDE.md → <workdir>/CLAUDE.md via resolveProjectWorkDir(folderPath).
• Project MEMORY.md → <workdir>/.claude/memory/MEMORY.md (the project-local memory hub, NOT global auto-memory).
• Global CLAUDE.md → os.homedir()/.claude/CLAUDE.md.
• Global MEMORY.md → os.homedir()/.claude/memory/MEMORY.md.

Response envelope: standard { success: true, data: { files: Entry[] } }. The files array preserves the server's emit order: project CLAUDE → project MEMORY → global CLAUDE → global MEMORY, with the project pair omitted for virtual projects. The renderer renders them in that exact order; there's no client-side sorting.

Related

This sub-group is one of three inside the same panel, so the Auto Context auto-injection page is the natural next stop — it describes the whole panel, the search filter and the other two sub-groups. The bulk-select machinery this sub-group deliberately opts out of is on the project docs selection page, the sync chip on its rows is explained on the agent instructions sync page, and the overlay a row click opens is described on the peek viewer page.

• project-docs-auto-injection.md — the parent Auto Context feature page: search filter, the three sub-groups, on-disk buckets, and how the underlying docs reach the agent.
• project-docs-selection.md — bulk select / copy / delete on the other two Auto Context sub-groups. System Instructions never participate.
• agent-instructions-sync.md — the synced-mirror sub-rows and the sync-chip contract.
• peek-viewer.md — the file peek overlay that opens on row click.
• .claude/memory/postmortems/archived/important-files-sidebar-section-postmortem.md — design history including the two-line-with-token-count revision (2026-05-10) and the four "DO NOT RETRY" items future agents should respect.