claude-settings-to-codex

claude-settings-to-codex is a CLI that converts a Claude Code settings.json file into a Codex-oriented config.toml plus a conversion report.

It focuses on permissions.allow, permissions.ask, and permissions.deny. Because Codex cannot represent Claude's per-command allowlist and denylist rules exactly, this tool performs a best-effort safe approximation and records incompatible parts in the report.

For common Git and GitHub CLI workflows, the report also suggests reusable Codex prefix_rule candidates such as ["git", "push"] or ["gh", "pr", "create"] so users can approve those operations once instead of being prompted every time. It also recognizes Claude wildcard-style entries like Bash(git:*) and Bash(gh:*), mapping them to broader Codex prefix candidates such as ["git"] and ["gh"]. Those recommendations are also written into config.toml as developer_instructions, because Codex does not expose a static per-command allowlist in config.toml. Denied Bash entries are excluded from these recommendations.

Usage

npx claude-settings-to-codex

When you run it inside any project directory, it uses these default paths relative to the current directory:

• Input: .claude/settings.json
• Output: .codex/config.toml
• Report: conversion-report.md

You can also override the paths explicitly:

npx claude-settings-to-codex \
  --input ./path/to/settings.json \
  --output ./.codex/config.toml \
  --report ./conversion-report.md

Network handling:

npx claude-settings-to-codex --network off
npx claude-settings-to-codex --network auto
npx claude-settings-to-codex --network on

• off: always generate network_access = false
• auto: set network_access = true only when commands such as npm install, curl, git push, git:*, or gh:* are detected
• on: always generate network_access = true

If you do not pass --network, the default is auto.

Local Development

If you want to test the CLI locally before publishing:

npm link
cd /path/to/target-project
claude-settings-to-codex

You can also run it directly from this repository:

node src/cli.js --help

Conversion Policy

• Extract and analyze Bash(...) rules
• Generate approval_policy = "on-request" by default
• Generate network_access with --network auto semantics by default
• Use sandbox_mode = "workspace-write" when at least one Bash permission exists, otherwise read-only
• Detect common Git / GitHub command families and suggest reusable prefix_rule approvals in the report
• Recognize wildcard-style Bash permissions like Bash(git:*) and Bash(gh:*)
• Write suggested prefix_rule families into developer_instructions so Codex can request durable approvals using those prefixes
• Prefer the most specific matching prefix_rule candidate to avoid over-broad approvals
• Leave exact allow and deny mappings as unsupported or lossy items in the report
• Approximate Claude ask entries with on-request
• Treat gh ..., git push, git pull, git fetch, and git:* commands as network-requiring when --network auto is used

Test

npm test

Publishing To npm

1. Log in to npm: npm login
2. Check whether the package name is available: npm view claude-settings-to-codex
3. Run the tests: npm test
4. Review the package contents: npm pack --dry-run
5. Publish: npm publish --access public

After publishing, users can run it from any project like this:

cd /path/to/project
npx claude-settings-to-codex