Local Codex Agent Setup

Set up Codex CLI as a local coding agent on the Arch host. This workflow keeps Codex running from the host repo, stores personal defaults in ~/.codex/AGENTS.md, stores project rules in the repo AGENTS.md, and starts Codex with workspace-write sandboxing.

Install Codex CLI on the host

Install Codex CLI with host-level npm. This is separate from the project frontend npm environment.

npm i -g @openai/codex

Use the latest package command later when upgrading the host CLI.

npm i -g @openai/codex@latest

Create global Codex instructions

Put personal defaults in the global Codex instructions file. These rules apply across local Codex sessions unless a repo adds more specific instructions.

mkdir -p ~/.codex
nano ~/.codex/AGENTS.md

• Keep global rules broad.
• Use this file for personal working preferences.
• Put project-specific commands, paths, and restrictions in the repo AGENTS.md instead.

Create repo instructions

Open the target repo on the Arch host and create or edit the repo-level AGENTS.md file.

cd ~/projects/your-repo
nano AGENTS.md

Use the repo file for rules that are specific to that codebase.

• Codex should act as a code reader and editor only.
• Do not run npm, lint, build, tests, or Docker unless explicitly asked.
• Do not search .venv, node_modules, .next, dist, build, coverage, cache, or generated folders.
• Do not commit, push, create pull requests, or change branches unless explicitly asked.
• The user owns servers, validation runs, dependency changes, package manager commands, and deployment operations.

Start Codex from the repo root

Start Codex from the repo root with workspace-write sandboxing. Codex can read and edit workspace files, and it asks before actions outside the sandbox or higher-risk commands.

cd ~/projects/your-repo
codex --sandbox workspace-write --ask-for-approval on-request

Use a safe first prompt

Use a first prompt that points Codex at AGENTS.md and restates the operating boundary for the session.

Use AGENTS.md. Work as a code reader/editor only.
Do not run npm, lint, build, tests, Docker, commits, pushes, or branch changes.
If validation is needed, tell me the command and I will run it.

Use common TUI commands

Command	Use
/clear	Start a fresh visible chat in the current TUI
/diff	Show changed files
/status	Show current session status
/exit	Exit Codex

Restart after instruction changes

After many tasks, or after changing AGENTS.md, exit Codex and restart it from the repo root. This gives the next session a clean visible chat and the current instruction files.

/exit

cd ~/projects/your-repo
codex --sandbox workspace-write --ask-for-approval on-request

File locations

• Global Codex instructions: ~/.codex/AGENTS.md
• Repo Codex instructions: AGENTS.md
• Run Codex from the repo root.
• Use host-level npm for Codex CLI install and upgrades.