OMP Context Files (historical)

Lifecycle: HISTORICAL SUPPORTING
Recovered from legacy wiki path content/docs-omp/context-files.md (attic copy retained; not deleted).
Prefer current SSOT pages for production decisions. Last promoted: 2026-07-20.

tags:
 
- omp
- docs
- context-files
- configuration
- system-prompt
 
---
 
title: "Context files"
description: "Oh My Pi (omp) is a coding agent for the terminal: subagents, plan mode, LSP, DAP, hindsight memory, hashline edits, and time-traveling rules — with a native Rust engine doing the heavy lifting."
tags:
 
- omp
- docs
- context-files
- configuration
- system-prompt
 
---

The four files

Drop one of these next to your project (or under ~/.omp/agent/ for global scope) and omp picks it up at the next session start. No reload, no config entry — discovery is filesystem-driven.

Where they live

Project files are walked from the current working directory upward to the repository root (or your home directory when outside a repo), so any ancestor checkout root is fair game. Global files sit under ~/.omp/agent/ and apply to every session.

<repo>/AGENTS.md            # project notes (also walked from subdirs)
<repo>/.omp/SYSTEM.md       # project: replace the system prompt
<repo>/.omp/APPEND_SYSTEM.md
<repo>/.omp/RULES.md
 
~/.omp/agent/AGENTS.md      # global notes
~/.omp/agent/SYSTEM.md      # global: replace the system prompt
~/.omp/agent/APPEND_SYSTEM.md
~/.omp/agent/RULES.md

Neighbouring harness files are also discovered: Codex AGENTS.md, Claude CLAUDE.md, Cursor rules, .clinerules, Copilot instructions, opencode context files. Each loaded entry shows up in /extensions with its source path.

Resolution order

When more than one AGENTS.md exists, omp concatenates them in this order, most general first:

1. Global — ~/.omp/agent/AGENTS.md

2. Project ancestors — every AGENTS.md walking up from cwd, farthest first

3. Nearest .omp/AGENTS.md walking up from cwd

For SYSTEM.md and APPEND_SYSTEM.md, only one file applies: the nearest project file wins over the global one rather than concatenating with it. For RULES.md, both scopes apply — the global ~/.omp/agent/RULES.md and the nearest project .omp/RULES.md are each loaded as always-apply rules when present.

AGENTS.md in practice

Treat AGENTS.md as a README for the agent. Conventions, build commands, the one file that’s deceptively load-bearing, the directory layout it should default to. The agent reads it once at session start, so keep it tight — a long file burns context every turn.

# Project notes for the agent
 
## Conventions
 
- Bun, not Node. Use `bun test`, not `npm test`.
- React Router v6 with file-based routes under `src/routes/`.
- No utility classes inside <Prose>; use plain HTML tags.
 
## Where things live
 
- `src/components/docs/` &mdash; PageHeader, Prose, nav.ts
- `src/routes/docs/` &mdash; one file per page
 
## Don&rsquo;tt touch
 
- `bun.lock` &mdash; regenerated by `bun install`.
- `public/clips/` &mdash; binary assets, do not rewrite.

RULES.md and sticky behaviour

RULES.md is the file you reach for when an instruction has to stay enforced. omp loads it as an always-apply rule and injects its full contents into the system prompt, so it rides along on every request — even after many turns of conversation. Use it for hard constraints (“never commit secrets”, “always run just test before yielding”), not for general notes — those belong in AGENTS.md.

Replacing the system prompt

SYSTEM.md swaps the built-in system prompt wholesale. You lose the carefully tuned instructions that ship with omp, including tool-usage guidance. Prefer APPEND_SYSTEM.md unless you specifically want a different agent persona.

# ~/.omp/agent/APPEND_SYSTEM.md
 
You are pairing with a security-focused engineer. When reviewing diffs,
call out: missing input validation, unsafe deserialization, secrets in
logs, and authn/authz changes that broaden access.

Disabling discovery

| Knob | Effect | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | disabledProviders (setting) | Disable individual discovery providers (e.g. agents-md, claude) — toggle them from /extensions. | | --no-rules | Skip rule discovery entirely for this run — RULES.md, .omp/rules/, and other rule sources. | | --system-prompt <text\\ | @file> | Override the system prompt from the CLI — takes priority over SYSTEM.md. |

Run omp -p '/extensions' to confirm which files actually loaded. See CLI reference for full flag details and Skills, Prompt templates, and Hooks for the other customization surfaces.\n