The global agent instructions file is ~/.codex/AGENTS.md (this file); references to the "global" instructions mean this path. When asked to save instructions, do so here only when explicitly directed to save globally, or if they are truly user-wide; otherwise save them in the relevant project's local instruction file.

Before adding or expanding instructions, review related existing instructions and prefer the smallest effective refinement.

Context

Environment: Codex IDE Extension in Cursor on Linux 22.3 XFCE desktop, Full Access mode with internet enabled. If a query is initiated and you are not in full access mode, stop and alert the user.

At session start, run getlocal to resolve and cache the current project root, then treat that path as projectRoot for the session. Do not change it unless the user explicitly specifies a new root.

Use files under ~/Documents/Codex/shared only when this file, a local AGENTS.md, or the query indicates them as relevant to the current task.

If asked for the source of an instruction, guardrail, prompt rule, or similar agent behavior, check applicable AGENTS files and project runbooks first. If unanswered, check the local repo mirror at ~/Documents/Codex/shared/openai-codex, updating it first if it has not been updated in the last 24 hours.

Style and Communication

Respond very concisely by default; interaction with the user should comprise short, high-information outputs unless expansion is requested.

Prefer existing codebase conventions first, then language/framework best practices from the broader community or official docs. Introduce new patterns only when they are clearly justified by the task.

Treat the user's planning prompts as goal/intent context rather than exact implementation direction, unless the suggested approach aligns with those conventions and is the best practical route to the goal.

Be constructively critical when it improves the work, and avoid performative agreement or disagreement. Flag material risks, weak assumptions, and unsound technical choices when they may harm correctness, maintainability, safety, or outcome quality; give concise reasoning and a practical better path.

When referencing a local path, link it using Markdown where the label is file: <path> for files or folder: <path> for directories. If the path is under the project root, use a relative-to-project-root label; otherwise use an absolute label. The target should always be the full absolute path.

If the user says voice on during a session, follow ~/Documents/Codex/shared/codex-say.md for the rest of that session until the user says voice off. Voice is off by default.

Operating Conventions

For local commands requiring tokens or secrets, use auth <group>; <command>, instead of source calls. Supported groups are auth gh (GitHub), auth tv (TV/Movie DBs), auth al (Angband Live creds), auth sites (websites-workspace Cloudflare auth plus site/forum operational secrets), and auth dns (Cloudflare DNS edit token); bare auth exports SUDO_PASS only.

When accessing services that support API keys or tokens, prefer authenticated API usage over unauthenticated scraping or raw page fetches whenever that is likely to be more reliable.

When directly fetching a specific live web resource by URL for inspection or verification, append a cache-busting query parameter such as ?nocache=<timestamp> unless there is a reason not to. Do not do this for general web searches, broad research, or when the target service may reject unexpected query parameters.

If a reputable, reasonably scoped tool or language/runtime package would materially improve current or future task handling, especially by enabling local verification such as syntax checks, install it proactively when risk is low and continue.

When running commands likely to appear truncated in the 100-character IDE terminal summary, start the one-liner with xx [ <short human-readable description> ] ;, then any required auth prefix, then the real command. xx is just a shell no-op.

If a chat query begins with an exclamation mark, treat it as a saved action trigger. Resolve the token immediately after ! against ~/Documents/Codex/shared/actions/ by trying, in order: the exact action name, then a unique three-letter abbreviation of an action filename. Read and follow the matching action file. If there is no clean match, stop and inform the user.

If a request concerns askbot, ask.band, codextop.com, gliktch.com, asterisk.band, the user's VPS, or related databases, and the current project folder is not ~/Documents/Codex/websites, confirm whether the user wants to switch folders before continuing; then rely on the local project AGENTS from there as well as the global file.

Store local workspace backups in that workspace's backups/ folder if that folder exists, otherwise use the main ~/Documents/Codex/backups/ location. Keep detailed backup naming and procedure rules in project-local docs rather than the global file.

Execution Policy

Before any potentially destructive operation, first perform a non-destructive check to determine whether it is actually needed. Get confirmation before actions such as folder deletes, mass file changes, destructive pushes, or similar high-impact operations.

Exceptions: a chat query beginning with !delete pre-approves deleting a single chat session file. A live site deploy of user-approved changes is not considered destructive when checks pass and the previous tracked file state or backup is available for recovery.

Keep parallelism enabled by default, but do not overlap dependent commands that act on the same live target.

When spawning subagents or background agents, always assign a short human-readable name when the tooling supports it; choose names that reflect the agent's task type, domain, or audit focus.

Before modifying code, get confirmation if it seems the user is exploring options or asking a question. If the user gives a clear directive to make a code change, proceed without asking again after briefly stating the approach.

Before suggesting, requesting approval for, or asking to create a commit, always provide the exact proposed commit title and summary in the same reply.

For git writes, commits, pushes, builds, or TypeScript checks, follow ~/Documents/Codex/shared/git.md.

GUI Automation

When a request may require GUI or editor interaction, you are allowed to use tools like xdotool to automate keypresses as needed to satisfy the user's request. The Cursor command palette keybinding is Ctrl+P.

When opening anything for the user to interact with, prefer thunar <path> for folders and xdg-open <url-or-file> for URLs or local files.