Omniscio

Auto Context — auto-inject files like Claude.ai Projects (part 2)

The second half of the Auto Context page: flagging a doc as an authoritative project instruction, letting an external agent add or remove files through CLI Control with an inbox approval, and the machinery behind the injection — the builders, the per-engine first-message paths, the budget and the kill switch.

On this page

What it is

This is part 2 of the Auto Context (.claude/docs/ auto-injection) page. That page covers what Auto Context is, where the sidebar group and the .claude/docs/ folder live, and how files are added, ordered and counted on the way into a session. This half carries the rest: the flag that promotes a doc from background reference into a binding instruction, the CLI Control surface an outside tool uses to change the folder, and the machinery that builds the injection in the first place.

Where to find it

Two surfaces here, both reached outside the Auto Context panel itself. Inject as instruction is a right-click action on a doc row inside the Auto Context group. CLI Control is Omniscio's local HTTP server, which an external tool — another Claude Code window, a script, a macro — calls to add or remove files, with your approval in the inbox as the gate.

How it behaves

Inject a doc as an authoritative instruction

The always and rag buckets both deliver a doc as reference material — context the agent may consult. Sometimes you instead want a doc to be an instruction the agent must follow — a house style, an "always do X" rule, a workflow. For that, flag the doc as an instruction.

How. Right-click any markdown/text doc in the Auto Context panel → Inject as instruction (toggle it back with Stop injecting as instruction). Flagged docs show a small Instruction badge on their row.

What changes. A flagged doc is pulled OUT of the first-message ## Injected Project Docs block (the background context the agent can skim past) and delivered instead as the project-instructions fragment of the session's system prompt — a standing block whose banner reads [ PROJECT INSTRUCTIONS ], carried on every turn rather than once as background context. This is the per-project equivalent of Settings → Agent Instructions → Custom Instructions (which is global); flagging a doc scopes that same authority to one project. It reaches every engine, not just Claude. (It is withheld for Clean Room sessions and the Ask-Omniscio / Ask-page helpers, the same gate the other custom-instruction fragments use.)

Good to know:

  • A flagged doc claims its share of the injection budget first, ahead of the background docs — so a large instruction doc can be the reason a background doc is skipped. That is deliberate: you elevated it, so it wins the budget. (The two share one budget rather than getting one each, which is what keeps a session's first message inside the context window its engine actually enforces.)
  • If a flagged doc is so large it does not fit the budget on its own, its body is withheld rather than cut in half — the agent is told the instruction exists, that it is binding, and given the full path to read it. A half-delivered rule set is worse than a missing one, so it is never truncated. The doc's row shows the same skipped warning a background doc gets; if you see it, unflag a doc or move the project to a larger-window engine.
  • Like all doc injection, it takes effect on the next session's first message — not on sessions already running.
  • Rename a flagged doc and the flag follows the new name; delete it and the flag cleans itself up.
  • Only a top-level text/markdown doc is eligible — a rag/ doc or a binary can't be an instruction. The body is injected verbatim and unfenced (so the agent reads it as instruction, not data), so keep instruction docs concise and directive.

Under the hood the flag is a per-project list of filenames (projects.doc_instruction_json, toggled via the files:set-project-doc-instruction IPC); the content is assembled by buildProjectInstructionsContent and delivered as the engine system-prompt bundle's project-instructions fragment. The instruction bodies are also written to .claude/amc-instructions.md on disk, but no engine reads that file — the bundle fragment is the real delivery, which is why the flag reaches external engines too. Invariants (exclusion from the always-bucket, first claim on the shared budget, authoritative routing): project-docs-injection-contract.md (instruction-doc-excluded-from-always-bucket-but-NOT-from-the-budget).

Adding/removing files from an external agent (CLI Control)

If you want an external AI tool — Claude Code in another window, ChatGPT via a script, an AutoHotKey macro — to add or remove files in a project's .claude/docs/ without you opening Explorer, Omniscio's CLI Control server (see cli-control.md) exposes four endpoints under /project/:id/docs:

  • GET /project/:id/docs — list the current .claude/docs/ contents (read-only, auth-gated). The listing is nested under the standard data key (like every sibling CLI read) and splits files into files (the always bucket) and ragFiles (the rag bucket) with separate totalBytes / ragTotalBytes totals so external agents can tell which bucket each file lives in without re-classifying paths.
  • POST /project/:id/docs — enqueue an upload that Omniscio copies in after you approve it in the inbox. The request body accepts an optional bucket: 'always' | 'rag' field (default 'always' for backward compatibility); 'rag' routes the file into the rag/ sub-folder and skips the 100 MB per-project quota check.
  • DELETE /project/:id/docs/:filename — enqueue a delete that runs after you approve it in the inbox. Also accepts the bucket query parameter to disambiguate when a filename exists in both buckets (e.g. ?bucket=rag); an unrecognised bucket value is a 400 rather than a silent fall back to always.
  • POST /project/:id/docs/reorder — set the sidebar display order of the project's docs. Unlike the two mutations above this one applies immediately — it is a view preference, not a change to your knowledge folder, so it is not approval-gated.

Both mutations land as pending rows in the same cli_pending_actions queue that gates settings PATCH and session lifecycle — they appear in Omniscio's inbox as approve/reject cards and have no side effect until you click Approve. That's the user-in-the-loop guarantee: an external agent cannot silently rewrite your knowledge folder. The pending-action card shows which bucket the file targets so you can reject an always-bucket upload that should have been rag (or vice versa) before it lands. See cli-control.md for the full request/response shapes (filename rules, 25 MB per-file cap, 100 MB per-project quota — always bucket only, idempotency header, error codes).

The path-based upload contract — agent writes a temp file, passes its absolute path, Omniscio does the copy — keeps the request body constant-size regardless of file size and dodges base64 bloat.

Auto Context (.claude/docs/ auto-injection) is the first half of this page — the buckets, the sidebar group, ordering, and the first-message chip. The contracts and source files named under For agents above hold the invariants behind everything this half describes.

Last verified 2026-10-06