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.