A complete engineering workspace for OpenAI Codex: personal and project instructions, 23 native specialist agents plus a search utility, eight focused skills, named profiles, project templates, an advisory edit hook, and a tested installer with backups.
Keep reusable preferences global. Put concrete commands, architecture, hardware,
and delivery constraints in the project. Install only what belongs at each level.
The configuration follows official OpenAI documentation, uses
Codex's native formats. Reasoning agents inherit your selected model and effort;
the bounded search utility uses gpt-5.6-terra with low reasoning.
Requires macOS or Linux, Python 3.11+, Git, and Codex CLI 0.154.0 or newer. See compatibility for the tested baseline.
git clone https://github.com/roadhero/codex-setup.git
cd codex-setup
git checkout v1.1.0
python3 scripts/install.py # preview
python3 scripts/install.py --apply # install with backupsAlternatively, download a versioned archive and SHA256SUMS from Releases, verify it as described in installation, and run the same installer from the extracted directory. No remote script is piped into a shell.
Start a fresh Codex session in your project after installation:
cd /path/to/project
codexProfiles are optional: --profile setup-build explicitly selects workspace writes
and on-request approvals, which are also this kit's global defaults.
Use --profile setup-review for read-only review or --profile setup-compute for
the compute profile. Your existing configuration can override the installed defaults.
The installer preserves existing configuration, MCP connections, authentication, plugins, and unrelated skills. It adds missing defaults, appends a marked guidance block, and refuses conflicting custom assets. See installation and rollback.
| Component | What it provides |
|---|---|
| Global instructions | Focused engineering agreements, task completion, Git hygiene, and verification |
| Configuration | Workspace sandbox, on-request approvals, live web search, bounded subagents |
| 24 native agents | 23 specialist roles plus a bounded read-only repository search utility |
| Eight skills | Web, Android, iOS, compute, onboarding, quality gates, release preparation, and documentation reconciliation |
| Profiles | Separate build, review, and compute configuration files |
| Project templates | Root/component instructions and trusted-project configuration |
| Worked examples | Web, Android, iOS, and compute project context |
| Edit hook | Optional native post-edit whitespace feedback; no file mutation |
| Command policy | Narrow native-rule guidance and a testable example |
| Installation | Preview, backup, idempotent install, conflict refusal, and guarded restoration |
| Release tooling | Version/tag parity, tested archives, checksums, and GitHub release automation |
A root AGENTS.md and .codex/config.toml configure this repository itself.
Other repositories inherit the personal setup and add local context as needed.
Read STRUCTURE.md for the complete layout.
With the current global guidance installed, start Codex in a project and describe your coding task. When project guidance is missing, Codex is instructed to create AGENTS.md from actual repository facts and continue your task automatically. Existing guidance is preserved; project trust still applies. This instruction-driven workflow is available starting in v1.0.1 and skips read-only questions/reviews. For an empty project, include the product and stack in your request; say "skip project setup" to opt out. No separate onboarding command is required.
You can also ask Codex to use $codex-new-repo explicitly to inspect a repository
and create or update its instructions. For a static starter:
python3 scripts/install.py --project /absolute/path/to/repo --stack android
python3 scripts/install.py --project /absolute/path/to/repo --stack android --applyWith --apply, the project option also performs global installation; otherwise
it previews both scopes without writing files. Existing instructions are
preserved; replace starter guidance with real project facts. Supported stacks are
web, android, ios, and compute. It never initializes Git, publishes a
project, or grants project trust. See project setup.
Use $codex-quality-gate for the project's actual formatter and verification
commands, $codex-release-prep for release work, and $codex-reconcile-docs for
documentation drift. Platform skills are selected by task or invoked explicitly.
Request specialist work when useful: “Have architect inspect the design and
code-reviewer review the diff independently, then combine the findings.” Global
guidance delegates broad, independent repository lookups to repo-explorer when
useful; simple lookups stay local, and explicit requests not to delegate prevail.
Read repository exploration, workflow,
and agent responsibilities.
python3 scripts/install.py --hooks
python3 scripts/install.py --hooks --applyRestart Codex and review/trust the definition using the /hooks slash command. The hook provides
whitespace feedback after apply_patch; it never rewrites files and is not a
commit guard or secret scanner. Use project Git hooks and CI for mandatory gates.
Hook behavior and limitations.
python3 scripts/validate.py
python3 -m unittest discover -s tests -vCI runs the same checks on macOS and Linux. Tests use temporary destinations and never install into your real home. Native startup/discovery checks and the limits of verification are documented in validation.
- Installation, upgrades, and rollback
- Configuration and permissions
- Project setup and monorepos
- Workflow and Git practices
- Hooks, skills, and agents
- Troubleshooting and compatibility
- Design decisions and official sources
- Release process, changelog, and v1.1.0 notes
- Contributing and security policy
MIT licensed. This is a community project, not an official OpenAI product.