Skip to main content

​
Context Layers

Overdeck distributes context — engineering rules, project guidance, machine quirks — to the coding-agent harnesses it drives through a layered system. You author small canonical markdown files; pan sync renders them into the files each harness actually reads.

​
Canonical terminology

Use these names when adding or moving context; they are the vocabulary the agents themselves are taught: The rendered outputs are harness context files — never edit those directly. Edit the source layer or rule, then run pan sync.
There is no “global context template”. A request phrased that way means either a bundled rule (every machine) or the global layer (one machine).

​
The shorthand: “add a <scope> rule”

In practice you (and your agents) only need four phrases — the scope word alone routes the content: After any of them: pan sync, and the change reaches new sessions.

​
Bundled rules

Overdeck ships engineering rules inside the package under sync-sources/rules/. Each rule carries a scope: frontmatter key:
  • scope: universal — folded into every machine’s rendered global context;
  • scope: dev — folded in only on a overdeck source checkout, for rules about developing Overdeck itself.
Rules ship with pan install and refresh on every pan sync.

​
What each harness actually reads

Each harness consumes context through its own native mechanism. pan sync renders the global layer (your global.md + the bundled rules) once per harness; spawn-time plumbing delivers it: The pi-global.md / codex-global.md files are Overdeck-owned render artifacts — the harnesses do not know about them. They exist so the global layer has a stable, inspectable rendered form per harness. Project layer rendering follows each harness’s native convention directly: it is written into a managed region of the project’s CLAUDE.md (for Claude Code) and the project’s AGENTS.md (for Pi and Codex, which both follow the AGENTS.md convention).

​
Managed regions — your files are never clobbered

pan sync only ever owns the span between these markers:
Everything outside the markers — in ~/.claude/CLAUDE.md, a project’s CLAUDE.md, or a project’s AGENTS.md — is preserved verbatim across every sync. One explicit managed block is removed: a BEGIN/END BEADS INTEGRATION region, whose generic conservative Git profiles conflict with Overdeck-managed work agents. Hand-authored content is never removed. The first sync that touches a file with pre-existing hand-authored content snapshots it into ~/.overdeck/backups/<timestamp>/context/ before writing. A project’s files are touched only if its .overdeck/context/project.md exists. When an Overdeck upgrade changes context, hooks, agents, or skills after your last sync, the dashboard shows a Sync now banner. Click it to run the host’s pan sync; the banner clears once the installed package and sync manifest match.

​
Harness-specific blocks

A layer file targets a single harness with Mustache-style blocks; text outside any block renders for every harness:
Blocks may be stacked to target several harnesses; {{#harness:codex}} is also recognized.

​
CLI

pan sync runs the context render as part of its broader sync (skills, agents, rules). The dashboard’s Context page edits the same files with per-harness previews.

​
Changes apply to new sessions only

Harnesses read their context files at session startup. After editing a layer and running pan sync, running sessions keep their old context — only newly spawned agents and conversations pick up the change.