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 standarddatakey (like every sibling CLI read) and splits files intofiles(thealwaysbucket) andragFiles(theragbucket) with separatetotalBytes/ragTotalBytestotals 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 optionalbucket: 'always' | 'rag'field (default'always'for backward compatibility);'rag'routes the file into therag/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 thebucketquery parameter to disambiguate when a filename exists in both buckets (e.g.?bucket=rag); an unrecognised bucket value is a400rather than a silent fall back toalways.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.
Related
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