claude-sync

Convert your Codex CLI configuration to Claude Code format. This skill reads ~/.codex/config.toml, translates model identifiers, plugins, environment variables, and trust level, then writes the result to ~/.claude/settings.json — after showing a preview and creating a timestamped backup.

Trigger phrases: "sync codex to claude", "convert codex config to claude", "update claude settings from codex"

---

Step 1 — Source Reader

Read the Codex configuration file and report what was found.

Run the following command:

cat ~/.codex/config.toml 2>/dev/null

If the command fails or the file does not exist, print the following message and stop immediately — do not proceed to any further step:

Error: ~/.codex/config.toml not found.
Expected path: ~/.codex/config.toml

To create a Codex config, run Codex CLI and configure your preferred model and
settings. Once ~/.codex/config.toml exists, re-run this skill.

If the file exists and was read successfully, display a summary of what was found:

Source: ~/.codex/config.toml — found

  model            : <value of model field, or "(not set)">
  plugins          : <count of [plugins.*] sections where enabled = true> enabled
  env vars         : <count of keys in [shell_environment_policy.set]>
  project entries  : <count of [projects.*] sections>

Collect the raw parsed values for use in the following steps:

• SOURCE_MODEL — the value of the top-level model field
• SOURCE_PLUGINS — list of plugin keys where enabled = true
• SOURCE_ENV_VARS — all key-value pairs from [shell_environment_policy.set]
• SOURCE_PROJECTS — all [projects."/path"] entries and their trust_level values
• SOURCE_REASONING_EFFORT — value of model_reasoning_effort if present

---

Step 2 — Model Converter

Map the Codex Bedrock ARN model identifier to the Claude Code short name.

Use this exact table (no other mappings exist in this version of the skill):

Codex model (Bedrock ARN)	Claude Code model
us.anthropic.claude-sonnet-4-5-20250929-v1:0	claude-sonnet-4-6
us.anthropic.claude-haiku-4-5-20251001-v1:0	claude-haiku-4-5

Note: us.anthropic.claude-sonnet-4-5-20250929-v1:0 always converts to claude-sonnet-4-6. If the original Claude Code setting was claude-sonnet-4-5, a round-trip through Codex will normalise it to claude-sonnet-4-6. This is intentional: both short names target the same underlying model via this ARN.

Note: Opus ARNs (claude-opus-4-8, claude-opus-4-5) are not yet in this table. Their Bedrock ARNs have not been corroborated in this repository. If your Codex config uses an Opus ARN, a FreshnessGuard [WARN] will fire and Step 10 will help you add the correct mapping.

Conversion logic:

1. Look up SOURCE_MODEL in the left column of the table above.
2. If a match is found: set CONVERTED_MODEL to the value in the right column.
3. If no match is found:
   • If the value looks like a GPT model (e.g. gpt-5, gpt-5.5): set CONVERTED_MODEL to the original value, mark it as WARN_MODEL_NO_CLAUDE_EQUIVALENT, and note "not a Claude model — no equivalent exists".
   • For any other unrecognised value: set CONVERTED_MODEL to the original value and mark it as WARN_MODEL_UNMAPPED for FreshnessGuard.

Also check SOURCE_ENV_VARS for a key named ANTHROPIC_MODEL:

• If present and its value matches a Bedrock ARN in the left column, replace it with the corresponding Claude Code short name.
• Set CONVERTED_ANTHROPIC_MODEL_ENV to the updated value.

---

Step 3 — Plugin Syncer

Convert Codex [plugins.*] sections to Claude Code enabledPlugins object entries.

For each key in SOURCE_PLUGINS (plugins where enabled = true in Codex):

• Add "<plugin-key>": true to CONVERTED_PLUGINS.

Additive merge rule: this list represents additions only. In Step 9 (Config Writer), existing enabledPlugins entries already in ~/.claude/settings.json that are not present in SOURCE_PLUGINS will be preserved unchanged — they are not removed.

If SOURCE_REASONING_EFFORT is present in the source config:

• Do not add it to CONVERTED_PLUGINS or any other output field.
• Add it to the FreshnessGuard INFO list: model_reasoning_effort has no Claude Code equivalent and will not be converted.

---

Step 4 — Env Var Converter

Convert [shell_environment_policy.set] key-value pairs to Claude Code env object.

For each key-value pair in SOURCE_ENV_VARS:

• Copy the key and value verbatim to CONVERTED_ENV.
• Exception: if the key is ANTHROPIC_MODEL and CONVERTED_ANTHROPIC_MODEL_ENV was set in Step 2, use CONVERTED_ANTHROPIC_MODEL_ENV as the value instead of the raw Bedrock ARN.

Do not read or modify [shell_environment_policy.inherit] — that field has no equivalent in Claude Code settings and is left in Codex only.

---

Step 5 — Permissions / Trust Converter

Map Codex per-project trust_level to Claude Code permissions.allow.

Run the following command to determine the current working directory:

pwd

Examine SOURCE_PROJECTS:

• Look up the entry for the current working directory in SOURCE_PROJECTS (i.e. the [projects."<pwd>"] section whose path matches the output of pwd).

  • If that entry exists and has trust_level = "trusted": generate the following baseline allow list and set CONVERTED_PERMISSIONS_ALLOW:

    ["Bash(gh:*)", "Bash(git:*)", "Read(*)"]
    

  • If that entry exists and has trust_level = "untrusted", or if no entry matches the current directory, or if SOURCE_PROJECTS is empty: set CONVERTED_PERMISSIONS_ALLOW to an empty list [].

Do not use trust entries for other project paths to influence the current directory's permissions — Codex trust is scoped per project path and should not spill over.

Limitation: trust_level = "trusted" expands to a fixed baseline allow list ["Bash(gh:*)", "Bash(git:*)", "Read(*)"]. This is a coarse approximation — the original permissions.allow rules from the source system are not recoverable from trust_level alone. The baseline may grant more or fewer permissions than were originally configured. Always verify manually before relying on this in production.

Note for preview: always include the following rationale line beneath the permissions output:

Note: trust_level is a coarse signal. Manual review of permissions.allow is recommended
before relying on this setting in production.

---

Step 6 — Preview Engine

Show the complete configuration that will be written and ask for confirmation.

Read the current ~/.claude/settings.json if it exists:

cat ~/.claude/settings.json 2>/dev/null || echo "(file does not exist)"

Apply the additive plugin merge before rendering: merge CONVERTED_PLUGINS with any existing enabledPlugins entries already in ~/.claude/settings.json. Plugins present in the existing file but absent from CONVERTED_PLUGINS are included in the preview (and will be written unchanged in Step 9). The preview must reflect exactly what Step 9 will write — no surprises after confirmation.

For each field in the converted output, label it:

• NEW — field is not present in the current ~/.claude/settings.json
• CHANGED — field is present but the value differs from the current value
• (no label) — field matches current value exactly (still shown for completeness)

Display the full proposed ~/.claude/settings.json content as formatted JSON:

Proposed ~/.claude/settings.json:
──────────────────────────────────
{
  "model": "<CONVERTED_MODEL>",           ← NEW / CHANGED / (unchanged)
  "env": {                                ← NEW / CHANGED / (unchanged)
    "<KEY>": "<VALUE>",
    ...
  },
  "permissions": {                        ← NEW / CHANGED / (unchanged)
    "allow": [
      ...
    ]
  },
  "enabledPlugins": {                     ← NEW / CHANGED / (unchanged)
    "<plugin-key>": true,
    ...
  }
}
──────────────────────────────────
Note: trust_level is a coarse signal. Manual review of permissions.allow is recommended
before relying on this setting in production.

Add a note beneath the JSON block:

Note: all other keys in the existing ~/.claude/settings.json (e.g. theme,
defaultMode, extraKnownMarketplaces) are preserved unchanged and are not shown above.

Then display all FreshnessGuard warnings and info notices collected from Steps 2 and 3, verbatim as recorded. Do not reformat or summarise them.

Display the conversion summary:

Summary: <X> settings converted, <Y> warnings

Finally, prompt the user:

Proceed? (yes/no):

If the user responds with anything other than yes, y, or proceed (case-insensitive):

Cancelled. No files were modified.

Stop immediately. Do not execute Steps 8 or 9.

---

Step 7 — Freshness Guard

After all converters have run (Steps 2–5), collect any unmapped or unrecognised values and emit the appropriate notices. These are shown inside the preview in Step 6, before the confirmation prompt.

For each unrecognised model name (WARN_MODEL_UNMAPPED from Step 2):

[WARN] 'us.anthropic.claude-...' not found in mapping table. The table in this skill
       may be outdated. See '## Keeping the Skill Current' to add a new entry.

For GPT or non-Claude models (WARN_MODEL_NO_CLAUDE_EQUIVALENT from Step 2):

[WARN] 'gpt-5' has no Claude Code equivalent. The value will be passed through as-is.
       Verify manually that this model identifier is valid in Claude Code.

For model_reasoning_effort (INFO from Step 3):

[INFO] 'model_reasoning_effort' has no Claude Code equivalent. It will not be converted.

All warnings and info notices are non-blocking — they do not prevent the conversion from proceeding if the user confirms.

If any WARN_MODEL_UNMAPPED warnings were recorded, Step 10 (Auto-Update Proposer) will run after Step 9 and offer to submit a mapping PR automatically.

---

Step 8 — Backup Handler

Before writing, create a timestamped backup of the existing target file.

Check whether ~/.claude/settings.json exists:

ls ~/.claude/settings.json 2>/dev/null && echo "exists" || echo "not found"

If the file exists, create a timestamped backup:

cp ~/.claude/settings.json ~/.claude/settings.json.bak-$(date +%Y%m%d-%H%M%S)

Report the backup path to the user:

Backup created: ~/.claude/settings.json.bak-<YYYYMMDD-HHMMSS>

If the file does not exist:

No existing ~/.claude/settings.json found. Creating fresh config.

In both cases, proceed to Step 9.

---

Step 9 — Config Writer

Write the converted configuration to ~/.claude/settings.json.

Full-object merge: start from the full existing ~/.claude/settings.json object (read from the backup created in Step 8, or an empty object on first-time setup). Replace only the four converted fields: model, env, permissions, and enabledPlugins. All other top-level keys already present in the file (e.g. theme, alwaysThinkingEnabled, effortLevel, includeCoAuthoredBy, defaultMode, extraKnownMarketplaces) are preserved unchanged. Do not remove or overwrite any key that is not one of the four converted fields.

Additive merge for enabledPlugins: within the enabledPlugins object, merge CONVERTED_PLUGINS with existing entries. Existing plugin entries absent from CONVERTED_PLUGINS are preserved.

Write the merged JSON to ~/.claude/settings.json. The file must be valid JSON with no trailing commas, no comments, and exactly one newline at the end of file.

Report completion:

Successfully wrote ~/.claude/settings.json

Total settings written : <count of top-level keys written>
Warnings               : <Y>

If any warnings were present, remind the user:

Review the [WARN] items above and update this skill's mapping table if needed.
See '## Keeping the Skill Current' below.

---

Step 10 — Auto-Update Proposer

Runs only when one or more WARN_MODEL_UNMAPPED warnings were recorded in Step 2 and the main conversion flow has completed (Step 9 finished, or the user cancelled at Step 6). Skip entirely if no WARN_MODEL_UNMAPPED warnings exist.

This step automates the manual steps in ## Keeping the Skill Current.

Phase 1 — Determine the Claude Code short name

For each unmapped Bedrock ARN the Claude Code short name is unknown. Attempt to infer it from the ARN structure:

• Extract the model family: the word after claude- and before the first digit group. e.g. us.anthropic.claude-sonnet-4-7-20260101-v1:0 → family = sonnet
• Extract the version: the two digit groups immediately after the family. e.g. 4-7
• Proposed short name: claude-{family}-{major}-{minor} e.g. claude-sonnet-4-7

Note: inference is not guaranteed to be accurate (e.g. the claude-sonnet-4-5 ARN maps to claude-sonnet-4-6). Always confirm with the user before proceeding.

Display the inferred name and ask for confirmation:

[AUTO-UPDATE] Unmapped Bedrock ARN: <arn>
  Inferred Claude Code short name : <inferred-name>

Is this correct? Press Enter to accept, type a corrected name, or type 'skip':

Phase 2 — Confirm the proposed mapping

[AUTO-UPDATE] Proposed new mapping:
  Codex ARN   : <arn>
  Claude Code : <short-name>

Add this row to both skill files and open a draft PR? (yes/no):

If the user responds with anything other than yes, y, or proceed:

[AUTO-UPDATE] Skipped. See '## Keeping the Skill Current' to add the mapping manually.

Stop this step.

Phase 3 — Locate the otc-awesome-llm repository

find ~ -maxdepth 5 -name "SKILL.md" -path "*/claude-sync/SKILL.md" 2>/dev/null \
  | head -1 | xargs -I{} sh -c 'cd "$(dirname {})/../.." && pwd'

If a path is found, confirm with the user. If not found, ask:

[AUTO-UPDATE] Could not locate the otc-awesome-llm repo automatically.
Enter the full path to your local clone (e.g. ~/repos/otc-awesome-llm), or 'skip':

Once a candidate path is provided, validate it before any git operations:

# 1. Verify it is a git working tree
[ -d "$REPO/.git" ] && echo "git-repo=yes" || echo "git-repo=no"

# 2. Verify the remote targets the right repo
git -C "$REPO" remote get-url origin 2>/dev/null

• If .git/ is absent: the path is an installed copy, not a clone. Ask the user to provide the path to their local clone of optum-tech-compute/otc-awesome-llm, or skip to abort.
• If the remote URL does not contain optum-tech-compute/otc-awesome-llm: warn the user — a PR opened against this remote will not land in the right repo. Ask them to confirm the path or type skip.

Store the confirmed, validated path as REPO.

Phase 4 — Insert the new mapping rows

Use the Edit tool to add one row to each file immediately after the last existing row in its mapping table.

In $REPO/codex/skills-templates/claude-sync/SKILL.md (Step 2 table):

| `<arn>` | `<short-name>` |

In $REPO/claude-code/skills/codex-sync/SKILL.md (Step 2 table):

| `<short-name>`  | `<arn>`  |

Phase 5 — Branch, commit, and open a draft PR

Before branching, verify the working tree is clean to avoid sweeping unrelated changes into the auto-PR:

git -C "$REPO" status --porcelain 2>/dev/null

If the output is non-empty (uncommitted changes exist), print:

[AUTO-UPDATE] The repository has uncommitted changes. Branching now could include
unrelated edits in the PR. Stash or commit those changes first, then re-run
this skill, or type 'skip' to add the mapping manually.

Stop this step if the user types skip.

git -C "$REPO" checkout -b fix/skills-add-<short-name>-model-mapping
git -C "$REPO" add codex/skills-templates/claude-sync/SKILL.md \
  claude-code/skills/codex-sync/SKILL.md
git -C "$REPO" commit -m \
  "fix(skills): add <short-name> <-> Bedrock ARN model mapping"
git -C "$REPO" push -u origin fix/skills-add-<short-name>-model-mapping

Then open a draft PR:

gh pr create \
  --repo optum-tech-compute/otc-awesome-llm \
  --title "fix(skills): add <short-name> model mapping" \
  --body "Auto-generated by claude-sync Auto-Update Proposer.

New mapping discovered during conversion:
- Codex ARN   : \`<arn>\`
- Claude Code : \`<short-name>\`

Please review and merge to make the mapping available to all users." \
  --draft

Report success:

[AUTO-UPDATE] Draft PR opened: <url>
Merge it to make the '<short-name>' ↔ Bedrock ARN mapping available to all users.

---

Keeping the Skill Current

This section explains how to update this skill when new Codex-compatible Bedrock ARN models are released.

When to update

Update this skill whenever a new Claude model becomes available in AWS Bedrock and you see a [WARN] not found in mapping table message when running the skill.

Where the mapping table lives

The table is in Step 2 — Model Converter of this file:

codex/skills-templates/claude-sync/SKILL.md

How to find the Bedrock ARN for a new model

Two options:

1. From Codex: Select the new model in the Codex CLI interface, then open ~/.codex/config.toml. The model field will contain the exact Bedrock ARN.
2. From AWS: Open the AWS Bedrock console → Foundation models → find the model → copy the Model ID (cross-region inference format, e.g. us.anthropic.claude-*).

How to add a new model mapping

In Step 2 of this file, add a row to the mapping table:

| `us.anthropic.claude-NEW-MODEL-v1:0` | `claude-new-model` |

The left column is the Bedrock ARN (from ~/.codex/config.toml). The right column is the Claude Code short name (from ~/.claude/settings.json).

How to submit the update

The fastest path is to let Step 10 (Auto-Update Proposer) do it for you — it runs automatically after a conversion that triggered a [WARN] and offers to open a draft PR with the new row already inserted.

To do it manually, follow the otc-awesome-llm PR workflow described in CLAUDE.md:

1. Create a feature branch: git checkout -b fix/claude-sync-model-mapping
2. Edit this file to add the new row
3. Run npm run validate && npm test to confirm the skill passes validation
4. Commit: fix(skills): update model mapping in claude-sync
5. Push and open a PR against main