Codex Chef

🌐 Docs: 🇩🇪 Deutsch | 🇪🇸 Español | 🇬🇧 English | 🇧🇷 Português (Brasil) | 🇹🇷 Türkçe | 🇫🇷 French / Français
_{Deutsch · Español · English · Português (Brasil) · Türkçe · French}

Codex Chef is a Windows-first Codex setup kit for power users and small teams. It packages a repeatable local Codex baseline: durable instructions, conservative config, specialist agents, approval rules, MCP defaults, curated skill metadata, plugin packaging, validation scripts, multilingual README entry points, and six-language deep docs.

This is an unofficial community starter, not an OpenAI product. It is mapped to current official Codex documentation and keeps risky actions approval-gated by default.

🌐 Language Entry Points

Language	README
🇩🇪 Deutsch	README.de.md
🇪🇸 Español	README.es.md
🇬🇧 English	README.md
🇧🇷 Português (Brasil)	README.pt-BR.md
🇹🇷 Türkçe	README.tr.md
🇫🇷 French / Français	README.fr.md

⚡ Start Here

Goal	Link
Install safely	Quick Start
Preview changes before writing anything	Dry Run
Inspect the full install plan	Install Plan
See what gets installed	Install Surface
Understand Codex capabilities	Capability Map
Map ECC/GStack-style workflows	Workflow Surface Map
Verify before publishing	Verification
Read release notes	Release Notes
Prepare GitHub metadata	GitHub Settings
Review advisory inputs	Advisory Sources
Troubleshoot Windows/Codex issues	Troubleshooting
Upgrade an existing setup	Upgrade Guide

🧭 What This Repo Is

Codex Chef turns scattered local setup knowledge into a public, reviewable starter repository. It helps users answer:

What should live in AGENTS.md, config, skills, plugins, MCP, rules, or hooks?
Which connectors are safe by default?
Which global files are touched by setup?
How do I verify this before trusting it?
How do I extend it without leaking secrets or weakening approvals?

🧩 Install Surface

The installers copy these managed templates:

~/.codex/AGENTS.md
~/.codex/config.toml
~/.codex/agents/*.toml
~/.codex/rules/default.rules
~/.codex/plugins/codex-chef-workflows
~/.agents/plugins/marketplace.json

Optional switches can also install:

Global Git ignore rules at ~/.gitignore_global
A global Git pre-commit hook under ~/.githooks
Curated public Codex skills from catalog/skills.json

🚫 What It Does Not Do

The installer does not:

Store tokens, cookies, auth files, private keys, memories, sessions, or local project state.
Enable authenticated account, database, production, or broad filesystem MCP connectors by default.
Commit, push, create releases, deploy, publish packages, rotate secrets, or change GitHub settings.
Delete user data without first backing up managed targets, unless the user explicitly chooses -NoBackup or --no-backup.

🔎 Dry Run First

PowerShell:

.\scripts\install.ps1 -All -Force -WhatIf

Bash or WSL:

./scripts/install.sh --all --force --dry-run

Dry runs print the target Codex/Agents homes and the changes that would happen without touching real files, Git settings, or global skills.

🧾 Install Plan

For a machine-readable no-write plan:

node scripts/plan-install.mjs --all --json

For quick discovery before reading the full JSON:

node scripts/plan-install.mjs --list-profiles
node scripts/plan-install.mjs --list-operations

The plan is backed by manifests/install-plan.json and records each managed
operation, collision policy, backup behavior, risk level, and required flag.
It is inspired by ECC's manifest-driven install architecture, but remains
Codex-only and does not import ECC's global config, hooks, MCPs, or skill
catalog. See ECC Compatibility.

⚡ Quick Start

PowerShell:

git clone https://github.com/ucsahinn/codex-chef.git
cd codex-chef
Set-ExecutionPolicy -Scope Process Bypass -Force
.\scripts\install.ps1 -All -Force

Bash or WSL:

git clone https://github.com/ucsahinn/codex-chef.git
cd codex-chef
chmod +x scripts/install.sh
./scripts/install.sh --all --force

After installation, restart Codex and run:

codex doctor --summary
codex --strict-config "Summarize the active Codex setup."

Use -InstallSkills / --install-skills or -InstallGitGuards / --install-git-guards when you only want one optional part of the setup.

🧠 Operating Model

Map unfamiliar code with code_mapper.
Use context_architect when you need to decide whether behavior belongs in prompts, AGENTS.md, skills, plugins, MCP, hooks, memory, rules, or config.
Verify current APIs and product behavior with docs_researcher; use prompt_architect for reusable prompts, briefs, and instruction systems.
Use mcp_integrator before enabling or troubleshooting connectors and MCP tool exposure.
Implement in the main thread with repo instructions and selected skills.
Use test_verifier, frontend_verifier, or security_auditor when the task needs deeper evidence.
Use codex_doctor for starter health and drift checks.
Use release_verifier before push, tag, release, package, deploy, or publication.

The result is a small specialist-team workflow inside Codex while the main thread stays focused on decisions, implementation, and final evidence.

🎬 Visual Overview

Workflow overview showing install, route, research, implement, and verify steps

🛡️ Safe Defaults

Sandbox stays enabled.
Approval policy stays interactive.
Workspace command network access stays off.
Shell subprocesses inherit only a trimmed environment with default secret exclusions.
Authenticated remote connectors stay disabled until a task needs them.
MCP tools that can touch external systems prompt before risky actions.
Skills are installed only from package/skill pairs in the catalog and lock file.
Deletion, cleanup, overwrite, credential access, publish, push, and release operations remain approval-gated.

✅ Trust Signals

Signal	Evidence
🛡️ Public-safe by design	No tokens, auth files, sessions, memories, cookies, private keys, or machine-specific state are included.
🧪 Real validation	`npm run check` runs repo, docs, install-plan, agent drift, MCP drift, skill-source, supply-chain, and security checks.
🔐 Secret scanning ready	Gitleaks command is documented and the Git hook runs it when available.
🌐 Multilingual docs	Deutsch, Español, English, Português (Brasil), Türkçe, and Français README and deep documentation files are present; six-language deep docs are enforced by validation.
🎬 Accessible visuals	SVG assets include title, description, motion, reduced-motion fallback, and README alt text.
🧩 Skill source gate	`catalog/skills-lock.json` is checked against installable skill metadata.
📐 Offline diagrams	Bundled `offline-diagram-triplet` emits Mermaid, editable Excalidraw, SVG, PNG, and Markdown with zero network.
🤖 Agent drift gate	`catalog/agents.json` is checked against Windows/Unix config blocks and role TOML files.
🩺 Doctor gate	`npm run codex:doctor` summarizes repo-only Codex starter health without global writes.
🧾 Install plan gate	`manifests/install-plan.json` and the install-state preview schema are validated before installer execution.
🔌 Conservative MCPs	Authenticated account, database, and broad filesystem connectors stay disabled.
🧭 Source-backed guidance	Research notes record source type, confidence, support, and outdated-risk.
📣 Public-safe triage	CODEOWNERS and issue templates route bugs, features, questions, and security reports without private data.
♻️ CI alignment	GitHub Actions runs the same `npm run check` path plus shell parser checks.

📁 Repository Layout

.github/                 CI workflow plus issue and PR templates
assets/                  Public-safe README visuals
catalog/                 Skill and MCP source metadata
README*.md               Multilingual public entry points
docs/                    Six-language setup and verification guides
manifests/               No-write install plan metadata
plugins/                 Bundled local Codex plugin
schemas/                 Lightweight validation schemas
scripts/                 Install, doctor, and validation scripts
templates/codex/         Files copied into ~/.codex
templates/git/           Optional global Git hygiene files

🧾 Verify Locally

npm run check
git diff --check
gitleaks detect --redact --no-banner --no-git --verbose

Optional online skill-source check:

npm run verify:skills:online

Online skill verification uses the network and the Skills CLI. It is intentionally separate from the default offline gate.

📚 Documentation

Every deep guide has English, German, Spanish, Brazilian Portuguese, Turkish, and French files. For example, docs/install.md is paired with docs/install.de.md, docs/install.es.md, docs/install.pt-BR.md, docs/install.tr.md, and docs/install.fr.md.

📚 Official Codex References

Primary source: https://developers.openai.com/codex/codex-manual.md

Focused docs:

Skills: https://developers.openai.com/codex/skills
Plugins: https://developers.openai.com/codex/plugins
MCP and connectors: https://developers.openai.com/api/docs/guides/tools-connectors-mcp
Windows: https://developers.openai.com/codex/windows
Config, permissions, rules, hooks, and AGENTS.md are mapped in docs/research-notes.md.

🚀 Publishing Boundary

This repo is built to be public-ready after validation, but the installer is local-only. Commit, push, tag, release, package publishing, deployments, and GitHub settings changes must be explicit human decisions after local verification.