Codex global agent setup

Reusable global configuration for Codex planning, custom subagents, and destructive-operation safeguards.

This setup configures Codex to:

• Build an implementation-ready plan before editing.
• Delegate independent work to custom Luna and Terra workers.
• Apply the same destructive-operation safeguards to the main agent and all subagents.
• Block direct recursive deletion of the filesystem root or user home.
• Require approval for other recursive deletion and destructive development commands.

The configuration has been tested with Codex CLI 0.144.0. Custom-agent schemas, model availability, and command rules may change. Review the current Codex subagent documentation, rules documentation, and sandbox documentation before installing it.

Repository layout

.
├── AGENTS.md
├── README.md
├── config.example.toml
├── agents/
│   ├── luna-xhigh.toml
│   └── terra-high.toml
└── rules/
    └── safety.rules

File	Install location	Purpose
AGENTS.md	~/.codex/AGENTS.md	Global planning, subagent-delegation, and destructive-operation instructions
agents/luna-xhigh.toml	~/.codex/agents/luna-xhigh.toml	Bounded and focused work using Luna at xhigh
agents/terra-high.toml	~/.codex/agents/terra-high.toml	Debugging and integration work using Terra at high
rules/safety.rules	~/.codex/rules/safety.rules	Executable destructive-command guardrails
config.example.toml	Merge into ~/.codex/config.toml	Recommended sandbox and approval defaults

The safety rules are also available as a focused GitHub Gist.

Install

Clone the repository and create the global directories:

git clone https://github.com/digitalknk/codex-global-agent-setup.git
cd codex-global-agent-setup
mkdir -p ~/.codex/agents ~/.codex/rules

Review every file before installing it.

Install the custom agents

install -m 0644 agents/luna-xhigh.toml ~/.codex/agents/luna-xhigh.toml
install -m 0644 agents/terra-high.toml ~/.codex/agents/terra-high.toml

Model availability varies by Codex client, account, and workspace. Replace gpt-5.6-luna or gpt-5.6-terra if those models are unavailable to you.

Install the global instructions

If ~/.codex/AGENTS.md does not exist:

install -m 0644 AGENTS.md ~/.codex/AGENTS.md

If it already exists, merge the relevant sections manually. Do not overwrite instructions you still need.

Install the safety rules

Open rules/safety.rules and replace every instance of /Users/YOUR_USERNAME with your absolute home directory. Linux users will usually use /home/YOUR_USERNAME instead.

Then install the file:

install -m 0644 rules/safety.rules ~/.codex/rules/safety.rules

Use an absolute path. Codex rules compare command arguments against exact prefixes, so do not rely on ~ or $HOME expanding inside a rule pattern.

Merge the example config

Merge these settings from config.example.toml into your existing ~/.codex/config.toml:

approval_policy = "on-request"
approvals_reviewer = "user"
sandbox_mode = "workspace-write"

Do not replace a complete configuration file with the example. Existing files may contain model choices, plugins, MCP servers, notification commands, and project trust settings.

Restart Codex after installing or changing .rules files. Start a new task after changing global instructions or custom agents.

Validate the rules

codex execpolicy check evaluates a command against a rule file without executing the command after --.

Check that filesystem-root deletion is forbidden:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/safety.rules \
  -- rm -rf /

Check your configured home path:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/safety.rules \
  -- rm -rf /Users/YOUR_USERNAME

Check that recursive deletion elsewhere requires approval:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/safety.rules \
  -- rm -rf /some/project

Expected decisions:

rm -rf /                       forbidden
rm -rf /Users/YOUR_USERNAME    forbidden
rm -rf /some/project           prompt

The rules also prompt for common destructive Git, filesystem, container, infrastructure, Kubernetes, and database commands. Test the commands relevant to your environment before relying on the policy.

When combining rule files, pass each one to the checker:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  --rules ~/.codex/rules/safety.rules \
  -- git clean -fdx

Codex uses the most restrictive decision when multiple prefix rules match.

How delegation works

The global AGENTS.md asks Plan mode to identify independent work and select a worker for each delegated step:

• luna_worker handles bounded, mechanical, focused, or speed-sensitive work.
• terra_worker handles ambiguous, debugging-heavy, cross-cutting, or integration-sensitive work.

Plan mode may use read-only subagents for investigation. Implementation starts only after the user approves the plan, starts a goal, or otherwise authorizes execution.

The main agent remains responsible for collecting results, resolving conflicts, and running final verification.

Safety model

This repository uses separate layers:

• AGENTS.md contains planning, subagent-delegation, and destructive-operation instructions.
• safety.rules evaluates supported command prefixes.
• workspace-write keeps normal work inside the active workspace boundary.
• on-request and approvals_reviewer = "user" keep the user in the approval path.

No prompt or prefix-rule file can cover every destructive action. Alternate tools, complex shell scripts, remote APIs, and application integrations may perform destructive operations without matching these examples. Keep sandboxing enabled, review approval requests, maintain backups, and inspect changes before publishing or deploying them.

Sharing and privacy

Do not publish your complete ~/.codex/config.toml, default.rules, MCP credentials, notification command paths, project trust entries, private hostnames, session logs, memories, tokens, cookies, or machine-specific paths without reviewing and sanitizing them.

The files in this repository use placeholder paths and contain no credentials.

License

MIT