---
title: System Instructions (Auto Context sub-group)
---

# 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](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)` 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](../../.claude/memory/postmortems/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](../../src/renderer/src/features/dashboard/SystemInstructionsGroup.tsx), a presentational component that takes pre-loaded `files` + `syncedMirrors` from its parent [ProjectDocsSection.tsx](../../src/renderer/src/features/dashboard/ProjectDocsSection.tsx) — mounted by `SessionsSidebar` on desktop and `MobileSessionsList` on mobile. The parent owns the IPC call (`IMPORTANT_FILES_PROBE`) via [probe-instructions.ts](../../src/renderer/src/features/dashboard/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](../../tests/unit/lint/mobile-auto-context-parity.test.ts).)

**Backend** — [src/main/ipc/file-handlers.ts](../../src/main/ipc/file-handlers.ts), the `IPC.IMPORTANT_FILES_PROBE` handler. 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 is `Math.ceil(s.size / 4)` computed from the same stat result used for `mtime` — no extra `fs.readFile`, 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](project-docs-auto-injection.md) 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](project-docs-selection.md) page, the sync chip on its rows is explained
on the [agent instructions sync](agent-instructions-sync.md) page, and the overlay a row click
opens is described on the [peek viewer](peek-viewer.md) page.

- [project-docs-auto-injection.md](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](project-docs-selection.md) — bulk select / copy / delete on the other two Auto Context sub-groups. System Instructions never participate.
- [agent-instructions-sync.md](agent-instructions-sync.md) — the synced-mirror sub-rows and the sync-chip contract.
- [peek-viewer.md](peek-viewer.md) — the file peek overlay that opens on row click.
- [.claude/memory/postmortems/archived/important-files-sidebar-section-postmortem.md](../../.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.