codex-user-config-template

English | 简体中文

Public-safe template for creating a private Codex user-configuration repository without publishing personal memory, preferences, credentials, account state, or machine-local runtime details.

This is a Codex-specific public template: keep a Codex working environment portable through a public-safe template plus a private overlay for real memory, preferences, credentials, local paths, installed state, backup, verification, restore, and rollback. Cross-runtime adaptation is out of scope for this repository.

Start here

If you want to...	Go here
Create your own private Codex config repo	Use this template as the public-safe starting point
Check what is safe to copy	docs/ and placeholder examples under config/, memory/, and skills/
Review the public-safe instruction starter	AGENTS.md
Preserve request-intake and capability-routing boundaries	docs/request-intake-and-capability-boundaries.md
Verify the template	python -B scripts/verify.py
Check the current official Codex config contract	python -B scripts/audit_codex_upstream.py --baseline config/upstream-contract.json --config config/common.example.toml
Understand this template's boundary	Repository Role

Independent Template Context

This repository is an independently usable public Codex-specific configuration template. It demonstrates a public-template/private-overlay pattern through repository-owned structure, validation, and setup guidance.

codex-user-config-template
  -> provides public-safe structure, placeholders, validation, and setup guidance

private codex-user-config
  -> owns real Codex memory snapshots, preferences, install policy, backups, and rollback

optional reviewed Skill policy/source repository
  -> may publish governed Skill policy or releases for private consumers

Use this repository as a self-contained safe starting point. Optional external Skill policy or releases remain separately governed inputs, not topology authority.

Repository Role

This repository is a template, not a live user configuration. It helps a user build their own private Codex configuration repository with clear safety boundaries, portable structure, and verification hooks. It intentionally targets Codex-specific files and workflows while removing private content.

This repository ships a public-safe starter root AGENTS.md as a thin, portable, always-on kernel. It keeps only durable invariants for goal fidelity, authority, evidence, repository safety, minimal capability use, and stop conditions. It is not a complete live instruction stack, personal memory, credential surface, or wholesale replacement for a user's existing AGENTS.md. Treat it as starter material to review and adapt deliberately.

Runtime Layering

The template prefers native reasoning first:

thin AGENTS.md kernel                 hot, always-on invariants
task-bound Skill                     warm, only for an explicit request or reproducible residual gap
detailed docs, examples, and probes  cold review material

The Agent owns task-time continuity and capability orchestration. Keep sequential work in the bound checkout unless a host limit or scope boundary requires a verified handoff. Capability exposure follows demand and ends when that demand ends.

Installation, listing, or visibility does not activate a Skill, tool, Plugin, MCP server, App, Hook, plan, test, or prior artifact as task authority.

What This Repository Provides

• A public-safe repository layout for a private Codex configuration baseline.
• A minimal valid Codex configuration example plus public-safe metadata placeholders.
• Verification scripts that check the template stays public-safe and structurally valid.
• A reviewed baseline plus a live audit that detects official Codex configuration-surface drift.
• Documentation for public/private sync, license boundaries, and private setup.
• Public-safe request-intake and capability-routing guidance kept as cold review material for task-bound use, not copied wholesale into the hot kernel.
• A public-safe root AGENTS.md starter that avoids private memory, local paths, credentials, account state, and runtime-only assumptions.

What This Repository Does Not Own

• Real Codex memory snapshots.
• Personal preferences, prompts, account choices, or local machine paths.
• OAuth state, credentials, tokens, cookies, browser sessions, logs, caches, or app runtime state.
• Third-party Skill content governance; use a curated Skills repository for that.
• General resource discovery, scoring, or web-wide lifecycle governance.

Relationship To The Private Repository

Recommended model:

codex-user-config-template
  -> provides public-safe structure, docs, placeholder examples, and validation

private codex-user-config
  -> consumes the template as a starting point
  -> owns real preferences, memory snapshots, local install policy, backups, verification, and rollback
  -> must remain private unless carefully declassified

Public-to-private sync can be automated for reusable template surfaces. Private-to-public promotion must be filtered, reviewed, and manually approved.

Do not run blind synchronization for active instruction files. If a user already has a root AGENTS.md, preserve their local preferences, authority boundaries, and existing project or user rules. The public starter AGENTS.md may be used as an initial baseline or reviewed update source, not as an automatic overwrite.

Optional External Inputs

Reviewed Skill releases may come from an independently governed curated repository. The private user configuration decides whether to pin, install, verify, or reject them. Runtime use still requires an explicit request or a reproducible residual gap that native reasoning did not resolve. No external repository can modify this template or a private consumer automatically.

A private bootstrap should install the thin kernel alone by default. Project first-party collaboration Skills only through explicit opt-in after a residual gap is reproduced. Re-running the default bootstrap is not deprojection; the responsible lifecycle mechanism should remove an existing projection deliberately and verify the resulting state.

Layout

config/                  Valid Codex example, template metadata, and reviewed upstream baseline
AGENTS.md                Public-safe thin collaboration kernel
docs/                    Cold public/private, intake/routing, and setup guidance
hooks/                   Hook policy placeholder, not live automation
memory/                  Memory boundary placeholder, not real memory
scripts/verify.py        Offline public-safety and structure validation
scripts/audit_codex_upstream.py
                         Networked comparison with the current official Codex schema
skills/                  Skill install-policy placeholder, not vendored Skills

Verification

Run:

python -B scripts/verify.py
python -B scripts/audit_codex_upstream.py \
  --baseline config/upstream-contract.json \
  --config config/common.example.toml

The first command is deterministic and offline. The second fetches the current official Codex schema, validates the example, and reports newly added or removed top-level configuration surfaces. GitHub Actions runs both checks on changes and runs the upstream audit weekly. A changed upstream baseline is a review signal, not permission to copy new settings into a private configuration.

Update Rules

1. Keep this repository public-safe by default.
2. Add only placeholders, examples, schemas, scripts, and generic documentation.
3. Do not copy private configuration, memory, credentials, local paths, account state, or personal preference files into this repository.
4. Promote reusable private improvements only through a filtered, reviewed, public-safe change.
5. Review official Codex schema drift before updating config/upstream-contract.json.

Safety Boundaries

Treat private configuration as the authority for a user's actual environment. Treat this template as scaffolding only. If a change might expose personal information, account state, private preferences, or local runtime details, keep it out of this repository.