Context Engine

Context Control & Overlays

Control which files are included, excluded, or pinned in your AI context using overlays.

Context Control lets you manipulate what your AI sees without modifying source files. Every include, exclude, or pin creates a reversible overlay stored in .lean-ctx/overlays.json.

What is overlays.json?

overlays.json stores reversible context manipulations — decisions like "exclude this file" or "pin that file" — without touching your source code. It's created automatically when you use ctx_control or ctx_ledger evict.

File format: JSON array of overlay objects, each with a target (file path), operation (include/exclude/pin/…), scope, and timestamp.

Where is it stored?

Overlays are project-scoped and live at <project_root>/.lean-ctx/overlays.json. They are never written to the global ~/.lean-ctx/ directory. If your project root resolves to your home directory, a safety guard prevents writing.

Overlay storage path

<project_root>/.lean-ctx/overlays.json

Should I gitignore it?

Yes. We recommend adding .lean-ctx/ to your .gitignore. The file contains local session state (which files you pinned/excluded) and is not meant for team sharing.

.gitignore

# lean-ctx local state
.lean-ctx/

Available Actions

Use ctx_control (MCP) or lean-ctx control (CLI) with these actions:

Action	Effect	Example
`include`	Force a file into context	`ctx_control action=include target=src/auth.rs`
`exclude`	Remove a file from context	`ctx_control action=exclude target=vendor/`
`pin`	Keep a file permanently in context	`ctx_control action=pin target=README.md`
`unpin`	Remove a pin	`ctx_control action=unpin target=README.md`
`set_view`	Set a read mode for a file	`ctx_control action=set_view target=large.rs value=signatures`
`set_priority`	Adjust ranking priority	`ctx_control action=set_priority target=core.rs value=high`
`mark_outdated`	Flag content as stale	`ctx_control action=mark_outdated target=cache.rs`
`list`	Show all active overlays	`ctx_control action=list`
`history`	Show overlay change log	`ctx_control action=history`
`clear`	Remove all overlays	`ctx_control action=clear`

Overlay Scopes

Each overlay has a scope that determines its lifetime:

Scope	Lifetime	Use Case
`call`	Single tool call	Temporary context for one operation
`session`	Current session (pruned after 24h)	Focus on specific files during a task
`project`	Persists across sessions	Always exclude generated files
`agent`	Tied to a specific agent ID	Agent-specific context preferences
`global`	Permanent	Organization-wide exclusions

Staleness Detection

Overlays store a hash of the target at creation time. If the file changes, the overlay is flagged as stale and the agent is notified. Session and call-scoped overlays are automatically pruned after 24 hours.

Examples

Exclude noisy vendor files

MCP

ctx_control action=exclude target=node_modules/ scope=project
ctx_control action=exclude target=vendor/ scope=project

Pin critical files for a debugging session

MCP

ctx_control action=pin target=src/auth/middleware.rs scope=session
ctx_control action=pin target=src/auth/jwt.rs scope=session

Force signatures-only view for a large file

MCP

ctx_control action=set_view target=src/generated/schema.rs value=signatures

List and clear overlays

MCP

ctx_control action=list
ctx_control action=clear scope=session