dotfiles-public/dot_codex/AGENTS.md

Global Codex Configuration

Tool Preferences

Search And Navigation

• Always use rg over grep for code search.
• Prefer narrow searches over broad sweeps.
• Use precise file globs and code-aware navigation when available.
• Prefer MCP tools when they provide better precision than shell commands.

Code Manipulation

• Read the relevant code before editing.
• Prefer structural understanding over blind text replacement.
• Make the smallest change that solves the problem.
• Do not rewrite surrounding code without a concrete reason.

Verification

• Every change needs verification.
• Verification can be tests, a build, a targeted command, or frontend validation with Playwright.
• For non-trivial work, state the verification method before implementing.

Language Patterns

Python

• Prefer black or ruff format for formatting.
• Prefer ruff for linting.
• Use type hints on public code.
• Prefer pytest.
• Check for .venv/ or venv/ before assuming interpreter paths.

Go

• Use gofmt.
• Prefer go vet for linting and go test ./... for verification.
• Check go.mod for module structure.
• Do not ignore errors with _ unless there is a defensible reason.

TypeScript

• Prefer prettier and eslint when present.
• Check package.json for the repo's actual test and build commands.
• Check tsconfig.json before changing compiler-sensitive code.
• Prefer strict typing patterns.

Workflow Principles

Research First

Before changing unfamiliar code:

1. Identify the relevant files and relationships.
2. Understand the local pattern in that area.
3. Check for similar implementations elsewhere.
4. Look for tests that define expected behavior.

Plan Before Implement

For non-trivial work:

1. State what is changing and why.
2. Name the files or components likely to change.
3. Define how the change will be verified.
4. Note obvious risks or breakpoints.

Preserve Context

• Keep findings compressed and structured.
• Reuse existing project artifacts like .claude/progress.md, PITFALLS.md, and project CLAUDE.md when they exist.
• If a repo already uses .claude/ planning or checkpoint files, continue to respect them rather than inventing a second system.

Session Workflow

Starting A Session

1. Check for .claude/progress.md and load it as prior context when present.
2. Read PITFALLS.md if present.
3. Read project instructions from AGENTS.md. Codex is also configured to treat project CLAUDE.md as a fallback instruction file.

During Work

• Research unfamiliar areas before editing.
• Make plans for non-trivial work.
• Review changes before commit when risk is non-trivial.

Ending A Session

• If the repo uses .claude/progress.md, update it when useful.
• If there are uncommitted changes, leave the next session enough context to resume cleanly.

Shell

• Use zsh-compatible syntax when writing shell commands or scripts.
• Assume ~/.zshrc can affect shell behavior.

Anti-Patterns

• Do not search broadly and read dozens of files without narrowing scope.
• Do not change code before understanding the local pattern.
• Do not skip verification.
• Do not rewrite code that does not need to change.
• Do not add comments, docstrings, or annotations to untouched code without a clear reason.

System Knowledge Journal (Obsidian)

Maintain a running journal of host/environment changes in the Obsidian vault at Tech/Infrastructure/, using the shared sysjournal helper (on PATH). This is for system administration, NOT ordinary work inside a code repo.

Trigger — the task changes the machine/environment, not just repo code: system config; services/daemons (systemd/launchd/cron); networking/DNS/VPN/firewall; VMs & host-level containers; drivers/kernel/boot; disks/mounts; build toolchains & global/system package installs; or wiring an app into the host (a systemd unit, cron job, opened port, service account).

Do NOT journal feature work, bug fixes, refactors, or tests inside a project repo. Discriminator: does it change state outside the repo, on the host? If no → skip. Straddle case (you build an app and install it as a service): journal only the host-wiring part (the unit/cron/port), not the app code.

1. Recall first. Before diagnosing or acting on such a task, search the journal and read relevant hits: sysjournal search <keywords> (e.g. sysjournal search systemd relay port)
2. Journal after. Once the change is made or the problem resolved: sysjournal new "Short Descriptive Title" --type change --status deployed --tags systemd,relay Then fill in the created note (its path is printed): Why, What changed, Design decisions / gotchas, Verify (command + observed result), Status / follow-ups. Link related notes with [[wikilinks]].

Keep it a real record — what changed, why, the gotcha you hit, how you verified. sysjournal help for the frontmatter schema (the System Log MOC.md Dataview index depends on it).