convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
ucsahinn

Codex Chef

ucsahinn/codex-chef

Setup seguro e multilíngue de Codex para Windows com agents e MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Kit de configuração Windows-first para Codex com agents nomeados, servidores MCP pré-configurados, skills curados, workflows de plugins locais e validação de segurança antes de qualquer execução. Inclui documentação em 6 idiomas e padrões mais seguros para uso em produção.

Instalação

$npx convez-ai ucsahinn/codex-chef

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 3 semanas
Versão
v1.7.10
Issues abertas
1
Contribuidores
1

Casos de uso

  • Configurar Codex de forma segura em Windows/WSL com padrões robustos
  • Deployer agents e skills pré-validados sem risco de execução não autorizada
  • Onboarding de equipes multilíngues com documentação em 6 idiomas

Veredito

Excelente starter pack para desenvolvedores Windows que precisam de Codex com gates de segurança e boas práticas nativas. A abordagem multilíngue e documentação estruturada reduzem o atrito de onboarding, mas requer familiaridade prévia com agents e MCP para aproveitar ao máximo.

README

A tradução para o português deste README ainda está na fila.

Codex Chef

Codex Chef gives a Windows-first Codex setup a clean starting point: safer defaults, a named specialist team, curated skills, MCP defaults, local plugin workflows, and validation that users can inspect before anything touches their machine.

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.

The multilingual README entry points and six-language deep docs coverage are part of the release surface, so users do not have to start from English-only docs. English and Turkish carry the full operator detail for install, expected output, and release notes; Deutsch, Español, Português (Brasil), and Français keep safety summaries plus source section indexes so users know where the authoritative full-detail docs live.

Copy-Paste Install

Windows PowerShell:

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

Safe preview first:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -All -WhatIf
node scripts/plan-install.mjs --all --json --redact-paths

Repair an existing global Codex setup without deleting user skills:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Repair -WhatIf
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Repair

Codex Chef CLI wraps the same safe scripts in one Windows-friendly menu:

npm run chef
npm run chef -- --status
npm run chef -- --preview
npm run chef -- --reset --apply
npm run chef -- --repair --apply
npm run chef -- --install --apply
npm run chef -- --skills
npm run chef -- --mcp
npm run chef -- --auth
npm run chef -- --logs
npm run chef -- --status --no-log

The menu labels every action with its write boundary. --status, --doctor, --preview, --skills, --mcp, --auth, and --logs are read-only for global/user state by default. They normally create ignored repo-local audit logs under tmp/chef-cli/logs; add --no-log for strict no-filesystem-write audits. --reset --apply, --repair --apply, and --install --apply are the write paths; they route to the backup-backed installer or repair script instead of deleting user state. In an interactive terminal, --skills lets you pick one reviewed skill by number and installs it only when you rerun with --apply. --mcp lets you pick one connector by number to see transport, endpoint or package, setup, auth, verification, source, and rollback notes without enabling account connectors. CLI logs are ignored and not part of the source package.

If GitHub release, push, or workflow checks fail because local GitHub authentication is stale, refresh GitHub CLI or Git Credential Manager according to your organization policy. Keep account-scoped credential repair outside this repository and never paste tokens into repo files, logs, prompts, skills, rules, or shell history.

Automation-friendly one-shot install without questions:

.\scripts\install.ps1 -All

What You Get After Install

Codex Chef installs a reviewed Codex baseline, not a hidden sync from someone else's machine. The install source is this repo: templates/codex/config.*.toml, templates/codex/agents/*.toml, plugins/codex-chef-workflows, and the manifest-backed install plan.

SurfaceWhat lands on your machine
Agent team21 registered Codex subagent role files under ~/.codex/agents/*.toml.
Durable guidanceGlobal ~/.codex/AGENTS.md with safe routing, verification, and approval rules.
MCP defaults7 useful MCP servers enabled and 8 authenticated/high-risk connectors parked disabled.
Plugin + skillsLocal codex-chef-workflows plugin, three bundled skills, and sixteen optional curated global skills.
Safety gatesBackups, dry-run planning, secret scanning, validation, and approval-gated risky actions.

At the end of the installer, Codex Chef prints a capability board with the agent team, default-ready MCPs, disabled opt-in MCPs, local plugin skills, and reviewed global skills. It also prints MCP setup notes for tooling, OAuth, filesystem-path, and SUPABASE_DB_URL requirements, so first-run gaps are visible before a task needs the connector. That is the quick "what did I just get?" screen after setup.

Enterprise Routing Board

Codex Chef also ships catalog/routing-profiles.json, a machine-readable task-shape routing contract. It tells Codex which subagents, skills, MCPs, and config/profile flags should be used for common enterprise work such as current docs research, context placement, bug root cause, frontend verification, security review, MCP connector changes, release readiness, SEO, docs, and starter health.

npm run codex:routing
npm run codex:status

This is safe autonomy, not hidden execution. Matching agents, skills, MCPs, and flags are required when the task shape appears, but destructive, credentialed, publishing, deployment, database, and broad filesystem actions stay approval-gated.

MCP Connector Board

Codex Chef treats MCPs as explicit capabilities, not hidden account sync. The useful local/research connectors are ready; account, database, production, and broad filesystem connectors stay parked until you opt in.

StatusMCPsWhy
Ready by default OpenAI Docs · Context7 · Sequential Thinking · Playwright · Chrome DevTools · Serena · MemorySafe research, code navigation, browser evidence, and local non-secret context.
Disabled by default Filesystem · GitHub · Figma · Linear · Notion · Sentry · ▲ Vercel · SupabaseThese can expose private files, accounts, telemetry, deployments, or databases, so you enable them only when the task needs them.

Run npm run codex:status after install to see the live MCP setup board, effective routing controls, and any installed-runtime drift without mutating global Codex state.

If ~/.codex/config.toml already exists, the installer backs it up and merges only missing Codex Chef agent/MCP/safety tables. Your existing MCP entries, tokens, profiles, and tuned settings are preserved unless you deliberately use -Force / --force.

Installed Agent Team

These are Codex subagent role definitions, not separate background services. Codex uses their names, descriptions, and TOML role files when routing a task.

  • Code Mapper (code_mapper) - repo map
  • Docs Researcher (docs_researcher) - official docs
  • Context Architect (context_architect) - routing surface
  • Prompt Architect (prompt_architect) - prompt system
  • MCP Integrator (mcp_integrator) - connectors
  • Product Strategist (product_strategist) - scope
  • Engineering Planner (engineering_planner) - architecture
  • Design Reviewer (design_reviewer) - UX polish
  • DevEx Auditor (devex_auditor) - onboarding
  • Root-Cause Debugger (root_cause_debugger) - investigation
  • QA Lead (qa_lead) - user flows
  • Performance Auditor (performance_auditor) - speed
  • Google SEO Auditor (google_seo_auditor) - search visibility
  • Docs Author (docs_author) - docs coverage
  • Spec Author (spec_author) - executable specs
  • Code Reviewer (code_reviewer) - fresh review
  • Frontend Verifier (frontend_verifier) - rendered UI
  • Security Auditor (security_auditor) - threat paths
  • Test Verifier (test_verifier) - test evidence
  • Release Verifier (release_verifier) - publish gates
  • Codex Doctor (codex_doctor) - setup health

Skills Included

Codex Chef ships three local plugin skills. They are bundled with the codex-chef-workflows plugin and are checked by npm run validate:plugin-skills so they cannot quietly drift out of the repo. With -All or -InstallSkills, the installer can also add sixteen reviewed public and first-party skills for maintenance, debugging, refactoring, security, testing, browser verification, SEO, web quality, docs, MCP building, context engineering, prompt architecture, skill authoring, and one broad frontend workflow.

  • Chef Operator (codex-chef-operator) - plugin-local
  • Offline Diagram Triplet (offline-diagram-triplet) - plugin-local
  • Context Budget Planner (context-budget-planner) - plugin-local
  • Dependency Upgrade (dependency-upgrade) - optional global
  • Frontend Builder (frontend-skill) - optional global
  • Security Best Practices (security-best-practices) - optional global
  • GitHub CI Fixer (gh-fix-ci) - optional global
  • Systematic Debugging (systematic-debugging) - optional global
  • Refactor Planner (request-refactor-plan) - optional global
  • Webapp Testing (webapp-testing) - optional global
  • Test-Driven Development (test-driven-development) - optional global
  • SEO (seo) - optional global
  • Accessibility (accessibility) - optional global
  • Web Quality Audit (web-quality-audit) - optional global
  • Documentation And ADRs (documentation-and-adrs) - optional global
  • MCP Builder (mcp-builder) - optional global
  • Context Starter (ai-project-starter) - optional global, first-party
  • Prompt Architect Skill (prompt-architect) - optional global, first-party
  • Skill Forge (ai-skill-create) - optional global, first-party

Extra design, React/Vercel, prompt, memory, token, and context skills stay in catalog/skills.json as manual opt-ins instead of default installs. That keeps the starter broad without losing references such as impeccable, design-taste-frontend, image-to-code, high-end-visual-design, web-design-guidelines, vercel-react-best-practices, vercel-optimize, vercel-cli-with-tokens, context-map, and what-context-needed.

The key distinction: Codex Chef solves LLM token/context planning with the bundled local context-budget-planner; deployment-token or vendor-auth skills remain opt-in because they can touch accounts or duplicate existing triggers.

First-party ecosystem skills are part of the reviewed -All / -InstallSkills set:

  • ai-project-starter - project context foundations, starter docs, agent instruction files, and vibe-coding guardrails.
  • prompt-architect - plan-first, approval-gated Codex prompt packages and prompt audits.
  • ai-skill-create - create, validate, forward-test, and package Codex skills and plugins.

Manual opt-in example:

npx skills add pbakaus/impeccable --skill impeccable --agent codex --yes --global

MCP Defaults

Codex Chef installs MCP config entries, not hidden account connections. Useful local/research servers are enabled; authenticated, database, production, and broad filesystem connectors stay disabled until a task explicitly needs them.

Default enabled:

  • OpenAI Developer Docs (openaiDeveloperDocs) - official OpenAI/Codex docs.
  • Context7 (context7) - current library and framework docs.
  • Sequential Thinking (sequential-thinking) - structured decomposition for complex tasks.
  • Playwright (playwright) - browser snapshots, console/network evidence, and UI checks.
  • Chrome DevTools (chrome-devtools) - isolated Chrome inspection with redacted network headers.
  • Serena (serena) - semantic code navigation and repo symbol search.
  • Memory (memory) - local memory graph for non-secret project context.

Default disabled until opt-in:

  • Filesystem (filesystem) - broad local file access; set an intentional path before enabling.
  • GitHub (github) - private repo/PR context through account authorization.
  • Figma (figma) - private design files and workspace context.
  • Linear (linear) - issues, projects, and team planning context.
  • Notion (notion) - private docs and databases.
  • Sentry (sentry) - production error and telemetry context.
  • ▲ Vercel (vercel) - project and deployment platform context.
  • Supabase (supabase) - database access through SUPABASE_DB_URL.

If a user already has ~/.codex/config.toml, the installer now preserves it and adds only missing Codex Chef agent/MCP/safety tables. Existing MCP entries, tokens, profiles, and user-tuned settings are not overwritten unless -Force / --force is used after preview and backup.

🌐 Language Entry Points

LanguageREADME
README.de.md
README.es.md
README.md
README.pt-BR.md
README.tr.md
README.fr.md

Start Here

GoalLink
Install safelyQuick Start
Preview changes before writing anythingDry Run
Inspect the full install planInstall Plan
See what gets installedInstall Surface
Understand Codex capabilitiesCapability Map
Map ECC/GStack-style workflowsWorkflow Surface Map
Verify before publishingVerification
Read release notesRelease Notes
Prepare GitHub metadataGitHub Settings
Review advisory inputsAdvisory Sources
Troubleshoot Windows/Codex issuesTroubleshooting
Upgrade an existing setupUpgrade 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 safe preview:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -All -WhatIf

Bash or WSL safe preview:

./scripts/install.sh --all --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 -Interactive

Bash or WSL:

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

Install Parameters

PowerShellBash/WSLPurpose
-All--allInstall the reviewed Codex Chef surface: managed Codex files, plugin workflows, and curated skills.
-Interactive--interactiveAsk before optional choices and show the plan before applying.
-WhatIf--dry-runPreview without writing files, Git settings, or skills.
-Repair--repairReconcile an existing global Codex setup with backups; preserves user skills and local approval rules.
-Force--forceReplace existing managed Codex Chef targets after backup. Use only after reviewing a dry run.
-NoBackup--no-backupSkip backup creation for managed target changes. This is unsafe for normal use; prefer the default backup behavior.
-InstallSkills--install-skillsInstall or reconcile only the reviewed global skill catalog.
-InstallGitGuards--install-git-guardsOpt in to global Git ignore and pre-commit guards for this Windows user.
-PlainOutput--plain-outputUse ASCII-friendly output for older terminals and CI logs.

Useful verification commands:

CommandWhat it proves
npm run codex:statusRepo health, installed runtime drift, MCP setup notes, routing profiles, and effective controls.
npm run codex:status:allSame status board plus expected curated skills and optional Git guard checks.
npm run verify:install:runtime -- --expect-skills --expect-git-guardsRead-only proof that the installed CODEX_HOME has 21 agents, 15 MCP entries, managed files, and curated skills.
npm run verify:skills:online -- --timeout-ms=90000Network-backed proof that all 16 reviewed skill sources still resolve.
codex exec --strict-config "Summarize the active Codex setup in three short bullets."Real Codex startup, strict config compatibility, auth, and model-call smoke test.

After installation, restart Codex and run:

codex doctor --summary
npm run codex:status
npm run verify:install:runtime
codex exec --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. -All includes the reviewed skill set, but it does not change global Git config unless you also opt in to Git guards.

Existing user config is protected by default: if ~/.codex/config.toml already exists, the installer backs it up and merges only missing Codex Chef agent/MCP/safety tables. Existing tables are preserved. Other managed files such as AGENTS.md, agent files, rules, and the plugin marketplace are skipped unless you explicitly add -Force / --force. Use force only for a deliberate upgrade after reviewing the preview; the installer backs up managed targets first.

For existing global Codex users, prefer repair before force. -Repair / --repair previews or applies backup-backed reconciliation for Codex Chef-managed files, merges missing config blocks, refreshes the plugin marketplace entry without dropping unrelated plugins, and reports extra or duplicate global skills as cleanup candidates instead of deleting them.

Operating Model

  1. Map unfamiliar code with code_mapper.
  2. Use context_architect when you need to decide whether behavior belongs in prompts, AGENTS.md, skills, plugins, MCP, hooks, memory, rules, or config.
  3. Verify current APIs and product behavior with docs_researcher; use prompt_architect for reusable prompts, briefs, and instruction systems.
  4. Use mcp_integrator before enabling or troubleshooting connectors and MCP tool exposure.
  5. Implement in the main thread with repo instructions and selected skills.
  6. Use test_verifier, frontend_verifier, or security_auditor when the task needs deeper evidence.
  7. Use codex_doctor for starter health and drift checks.
  8. 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

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

SignalEvidence
Public-safe by designNo tokens, auth files, sessions, memories, cookies, private keys, or machine-specific state are included.
Real validationnpm run check runs repo, docs, install-plan, agent drift, MCP drift, skill-source, supply-chain, and security checks.
Secret scanning readyGitleaks command is documented and the Git hook runs it when available.
Multilingual docsDeutsch, 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 visualsSVG assets include title, description, motion, reduced-motion fallback, and README alt text.
Skill source gatecatalog/skills-lock.json is checked against installable skill metadata.
Local skill gatenpm run validate:plugin-skills checks every bundled skill, reference file, UI metadata file, and catalog entry.
Offline diagramsBundled offline-diagram-triplet emits Mermaid, editable Excalidraw, SVG, PNG, and Markdown with zero network.
Context budgetBundled context-budget-planner keeps large tasks focused with source priority, token budgeting, and compaction handoff.
Agent drift gatecatalog/agents.json and catalog/agent-research-corpus.json are checked against Windows/Unix config blocks, role TOML files, required guardrail blocks, and source-backed item counts.
Doctor gatenpm run codex:doctor summarizes repo-only Codex starter health without global writes.
Status boardnpm run codex:status combines repo health, installed runtime drift, Codex doctor checks, and skill context-budget warnings.
Repair modenpm run repair:install -- --apply and installer -Repair / --repair fix managed drift after backup while preserving unrelated marketplace plugins and user skills.
Install plan gatemanifests/install-plan.json and the install-state preview schema are validated before installer execution.
Conservative MCPsAuthenticated account, database, and broad filesystem connectors stay disabled.
Source-backed guidanceResearch notes record source type, confidence, support, and outdated-risk.
Agent-readable indexllms.txt gives coding agents a compact map of install targets, docs, safety boundaries, and high-signal comparison sources.
Public-safe triageCODEOWNERS and issue templates route bugs, features, questions, and security reports without private data.
CI alignmentGitHub 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:

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.

Ver o original no GitHub

Bom para

Relacionados