# Dev Codex Sync Settings From Claude > Sync the user's Claude Code workflow skills into the OpenAI Codex CLI settings repo ($HOME/.codex) as Codex-native ports, fix the Codex .gitignore for new local state, then commit and push. Use when: (1) user says '/dev-codex-sync-settings-from-claude', 'sync codex settings', 'sync claude skills to codex', 'port skills to codex', or 'update codex from claude'; (2) after updating ~/.claude workflow skills (big-plan, x, x-as-pr, x-wt-teams) and Codex should catch up; (3) the $HOME/.codex repo has drifted behind $HOME/.claude. The ports are condensed Codex-native REWRITES, never file copies. - Skill: `takazudo/dev-codex-sync-settings-from-claude` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add takazudo/dev-codex-sync-settings-from-claude` - Raw SKILL.md: https://api.skillmd.com/api/skills/takazudo/dev-codex-sync-settings-from-claude/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: takazudo (https://skillmd.com/u/takazudo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/takazudo/dev-codex-sync-settings-from-claude --- # dev-codex-sync-settings-from-claude The user's primary agent is Claude Code, but they also run OpenAI's Codex CLI. Codex reads skills from `$HOME/.codex/skills` (a git repo, remote `Takazudo/codex-settings`). This skill re-syncs the Claude-side workflow skills into Codex whenever `$HOME/.claude` has moved ahead. Run it FROM Claude Code — it reads `$HOME/.claude/skills` and writes `$HOME/.codex/skills`. ## The one rule that matters Codex is NOT Claude Code. A Codex skill is a **condensed, Codex-native rewrite** of the Claude skill — never a copy. Claude sources run 200–1100 lines; good Codex ports run ~40–150 lines: they drop Claude-harness minutiae and translate Claude concepts (Task tool, agent teams, Opus/Sonnet/Haiku subagents) into Codex primitives (`spawn_agent` / `send_input` / `wait_agent` / `close_agent`). Before writing or refreshing any port, read [references/codex-port-contract.md](references/codex-port-contract.md) — the house style and adaptation rules every port follows. Copying a Claude `SKILL.md` verbatim into Codex is the main failure mode; don't. ## What the Codex repo tracks `$HOME/.codex/` is a git repo that intentionally tracks: - `.gitignore` - `README.md` — how a machine is set up, and why `config.toml` is not tracked - `agents/` — per-model agent profiles (e.g. `sol.toml`, `terra.toml`) - `config.toml.example` — the **portable** template the live config is seeded from (see below) - `hooks/` - `scripts/` — includes `bootstrap-config.sh`, which seeds a machine's `config.toml` - `skills/` — the ported workflow skills plus separately-installed reference skills The live `config.toml` is **not** tracked — it is gitignored, and machine-local by design. Everything else in `$HOME/.codex` is machine-local runtime state (sqlite DBs, `auth.json`, sessions, caches) and stays gitignored. ### config.toml is untracked — template + bootstrap, not a clean filter The live `config.toml` is **gitignored**. Codex rewrites it constantly with machine-local project trust records, desktop-app paths, marketplace metadata, generated MCP settings and runtime state — at last count 40 `[projects."/Users/…"] trust_level` tables of machine-absolute paths, which are meaningless on the WSL machines and accumulate forever. What is tracked instead: - **`config.toml.example`** — the portable defaults. - **`scripts/bootstrap-config.sh`** — run once per machine, after cloning to `CODEX_HOME`: ```bash "$HOME/.codex/scripts/bootstrap-config.sh" ``` It copies the template to `config.toml` **only when no local config exists**, and never overwrites one. Change portable defaults by editing `config.toml.example`. **The trade to know about:** because bootstrap never overwrites, machines that already have a `config.toml` do *not* pick those changes up — that has to be done by hand. Keep machine-specific entries (`[projects]`, `[marketplaces]`, generated MCP settings, hook state, absolute paths) only in the ignored live config. Settings that belong to one codebase go in that codebase's own `.codex/config.toml`. #### Don't rebuild the clean filter An earlier design tracked `config.toml` behind a git clean filter that pinned `model`, `model_reasoning_effort` and the `[tui.model_availability_nux]` counters at staging time. It was real, and it is gone on purpose: - **`35ad713`** (2026-07-11) added `.gitattributes` + `scripts/normalize-config-toml.js`. - **`aaf192a`** (2026-07-23) deleted both and untracked `config.toml`, adding the template, the bootstrap script and `README.md` in their place. Twelve days, then replaced. A filter can pin a volatile *field*; it cannot make 40 machine-absolute path tables shareable, which was the real problem. The absence of `normalize-config-toml.js` is a **decision, not an oversight** — a later session read it as one and nearly rebuilt it. If tracked volatile fields ever come back, read `$HOME/.codex/README.md` first. (For comparison, `$HOME/.claude/settings.json` **keeps** its clean filter. Its payload is a large curated `permissions.allow` list that genuinely must propagate to every machine, and a copy-once bootstrap would stop that — the asymmetry is about ownership, not file format.) ## Canonical skill set to keep synced The user's Codex workflow centers on `/big-plan`, `/x-wt-teams`, `/x-as-pr`. Keep these plus everything they reference in sync: - **Entry points:** `big-plan`, `x`, `x-as-pr`, `x-wt-teams` (canonical) + `x-wt-team` (thin alias → x-wt-teams) - **Support:** `cleanup-resources`, `deep-review` (= `/code-review` + `/codex-review`), `verify-ui` (external — sourced from `Takazudo/zudo-test-wisdom`, NOT `$HOME/.claude/skills`; only sync/keep it on machines where that repo's setup installed it), `watch-ci`, `pr-revise`, `gh-fetch-issue` - **Codex-native helpers:** `codex-2nd`, `codex-review`, `codex-research`, `codex-writer` Rule of thumb: the set = the workflow trio + every skill named in their "Related Skills" sections. If a Claude workflow starts referencing a new helper, add its Codex port too. Reference skills installed on the Codex side by other tools (e.g. the Cloudflare pack: `cloudflare*`, `workers-best-practices`, `wrangler`, `durable-objects`, `agents-sdk`, `sandbox-sdk`, `turnstile-spin`, `web-perf`) are NOT ported from Claude — leave them as-is and commit them in their own group. **Utility & Codex-only skills (don't prune):** - `db` + `ss` — utility ports of the Claude Dropbox loaders. `db` carries the resolution engine (Dropbox root, directory settle, sync retries, placeholder materialization) and `ss` is the thin screenshot shorthand that adds only latest-N selection, so **refresh them as a pair** — engine changes land in `db`, and `ss` must keep pointing at it. Two adaptations to re-apply each time: Codex runs on WSL/Linux, so the helpers lead with `stat -c %Y` / `stat -c %s` (BSD `stat -f` as fallback), the reverse of the macOS-first Claude source; and Codex has no `$ARGUMENTS` / `` !`cmd` `` / `allowed-tools` frontmatter, so the cutoff is captured by an explicit `date +%s` first action. The Claude side splits the engine into `db/references/resolve.md`; the Codex port inlines it into `db/SKILL.md` and keeps only `references/env-secrets.md` separate. - `ccref` — Codex-only, no Claude source. It bridges Codex to the Claude skills (`~/.claude`, `./.claude`) + `CLAUDE.md`. It has no upstream to sync from — leave it in place; never treat it as "missing" and never overwrite it. - `refer-another-project` — utility port of the Claude skill. Two Codex adaptations to re-apply on refresh: slug resolution uses `find "$HOME/repos" -mindepth 2 -maxdepth 2 -type d -name ` (NOT the Claude source's `$HOME/repos/*/` glob, which is a fatal `no matches found` under Codex's interactive zsh), and update mode drops the Claude-only `-co` backend flag (Codex `x-as-pr` is already Codex-native). ## Sync workflow 1. **Gitignore audit.** `cd $HOME/.codex`, run `git status --short`. Any untracked machine-local runtime state belongs in `.gitignore`: versioned sqlite (`goals_*.sqlite*`, `logs_*.sqlite*`, `memories_*.sqlite*`, `state_*.sqlite*`), `generated_images/`, `installation_id`, `models_cache.json`, `session_index.jsonl`, `history.jsonl`. Codex bumps the version number in state filenames (`logs_1` → `logs_2`), so use generalized globs (`logs_*.sqlite*`), never pinned names. Confirm with `git check-ignore `. 2. **Drift check.** For each canonical skill, compare the `$HOME/.claude/skills//SKILL.md` source against the `$HOME/.codex/skills//SKILL.md` port. Add missing ports; flag ones whose source gained behavior the port lacks (new flags, new steps, renamed sub-skills). Read both and judge behavioral drift — no line diff needed. 3. **Port / refresh.** For each missing or drifted skill, write a Codex-native `SKILL.md` per the port contract. On a refresh, preserve the existing port's structure rather than rewriting from scratch. 4. **Verify the ports as a set.** Frontmatter `name` matches the directory name; every skill named in a "Related Skills"/routing section is a canonical Codex name; flags are spelled identically across files; no dangling Claude-only instruction survives (the `Claude X -> Codex spawn_agent` mapping lines are expected and fine). 5. **Commit + push** — see below. ## Large syncs: fan out When several skills drifted at once, porting them is embarrassingly parallel. Optionally drive it with a Workflow: one drafter per skill (each reads its Claude source + current Codex port + the port contract and returns the final `SKILL.md`), then one consistency-verifier over all drafts. Write the returned content to disk yourself to keep editorial control and run the set-level verify. For one or two skills, just do it inline. ## Commit + push Group into separate commits so history stays legible: 1. `.gitignore` changes — `chore: ignore local Codex state files` 2. the workflow-skill sync — `feat(skills): sync Codex-native workflow skills from ~/.claude` 3. any newly-installed reference skills, as-is — `chore(skills): add reference skills` Then push. Prefer `/commits push` — it offloads the git work to a subagent and handles the grouping. Never stage machine-local state; after committing, both of these must return nothing: ```bash git -C "$HOME/.codex" ls-files | grep -E '\.sqlite|auth\.json' git -C "$HOME/.codex" ls-files config.toml ``` The second is the one that regresses quietly: the live `config.toml` must stay **untracked** (see above). If it ever shows up in `ls-files`, something re-added it — `git rm --cached config.toml`, don't "fix" it by reintroducing a filter.