Global Codex Operating Rules

A compact, evidence-driven global AGENTS.md for Codex. It keeps durable personal rules for autonomy, approval boundaries, multi-agent work, verification, and reporting without trying to reimplement Codex in prose.

The complete, copy-ready contract is in AGENTS.md.

Why this exists

Codex is already capable of planning, using tools, spawning subagents, and verifying work. A global instruction file should steer those capabilities with stable personal preferences; it should not duplicate the product manual or become a second workflow engine.

OpenAI's guidance says a short, accurate AGENTS.md is more useful than a long file of vague rules, and recommends adding guidance after repeated mistakes. It also distinguishes durable instructions from reusable skills and mechanical configuration.

This repository applies that guidance to a practical baseline:

• universal behavior stays in the global file;
• repository facts and commands stay in repository-level AGENTS.md files;
• repeated task procedures become skills;
• model, sandbox, MCP, and feature settings stay in configuration;
• tests, hooks, and policy enforce what can be checked deterministically.

Why the lean version won

This file is the result of comparing three approaches:

Approach	What we found	Decision
Plain Codex with no personal rules	Capable, but it cannot know your durable approval and reporting preferences	Too little
A comprehensive global operating contract	Consistent, but duplicates native behavior and consumes context on every task	Too much
A concise global contract with scoped repository guidance and skills	Preserves the important boundaries while letting Codex use its native capabilities	Chosen

The research began with a larger multi-agent policy and a separate shell workflow prototype. The audit found that native Codex already handled ordinary agent orchestration. The larger runtime remained useful only for recurring, large, read-only batch jobs that genuinely need saved definitions and resume. Those narrow mechanics do not belong in a universal global file.

See RESEARCH.md for the evidence, alternatives, and limitations.

Install

Codex reads the global file from ~/.codex/AGENTS.md.

macOS and Linux

Back up an existing file before replacing it:

backup="$HOME/.codex/AGENTS.md.backup-$(date +%Y%m%d-%H%M%S)"
cp -p "$HOME/.codex/AGENTS.md" "$backup"
install -m 0644 AGENTS.md "$HOME/.codex/AGENTS.md"

Start a new Codex session so it rebuilds the instruction chain.

Windows PowerShell

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
Copy-Item "$HOME\.codex\AGENTS.md" "$HOME\.codex\AGENTS.md.backup-$stamp"
Copy-Item ".\AGENTS.md" "$HOME\.codex\AGENTS.md" -Force

Restart Codex after installation.

Layer repository guidance

Keep the global file universal. Put these details in the nearest repository AGENTS.md:

• purpose and architecture;
• canonical setup, run, test, lint, and build commands;
• code and review conventions;
• generated or protected paths;
• repository-specific approval gates;
• observable definition of done.

Closer repository instructions can specialize the global baseline for their subtree.

Design rules

Changes to this contract should stay:

• concise and imperative;
• universal across repositories;
• based on observed recurring friction;
• non-sensitive and safe to share;
• focused on outcomes rather than model-specific implementation details.

If a rule needs a long procedure, examples, scripts, or reference material, it probably belongs in a skill instead.

Relationship to Dynamic Workflows for Codex

VAMFI/dynamic-workflows-for-codex explores a fuller multi-agent operating contract. This repository is the distilled global baseline produced after auditing that approach against current Codex capabilities. The projects can coexist:

• use this repository for everyday global guidance;
• use the larger project as an orchestration reference or experiment.

Scope and disclaimer

This repository:

• does not add tools, permissions, models, or background execution;
• does not override higher-priority platform, system, or organization policy;
• does not guarantee that every model or Codex release behaves identically;
• is not affiliated with or endorsed by OpenAI.

Codex and AGENTS.md are referenced only to describe compatibility.

Sources

• Codex best practices
• Custom instructions with AGENTS.md
• Codex subagents
• Build skills
• Codex configuration

Contributing

See CONTRIBUTING.md. Changes should include a concrete recurring failure or ambiguity that the proposed rule prevents.

License

MIT. See LICENSE.