AGENTS.md

Git Workflow

• Before any merge, rebase, sync, or continuation after interruption, re-check live state:
  • feature worktree: git status --short, git branch --show-current
  • main worktree: git status --short
  • in-progress state: git status, .git/MERGE_HEAD, .git/rebase-merge, .git/rebase-apply
  • remote/PR state: git fetch origin; when a PR may exist, gh pr view --json number,state,mergeStateStatus,isDraft,headRefName,baseRefName,url
  • branch delta: git diff --stat main...HEAD and git log --oneline main..HEAD
• Keep both worktrees clean before merge/rebase. Checkpoint local changes in main with git add -A && git commit -m "temp-before-merge-<branch>"; skip only if main is clean.
• Prefer GitHub PR update/rebase/merge when a PR or GitHub merge path exists. Use local main merge only when no PR/GitHub path exists or the user explicitly asks for a local merge.
• Standard path: commit task, create/switch feature branch, rebase on main, then use the chosen PR/local merge path.
• Never use automatic conflict-bias strategies blindly (-X theirs, -X ours, git checkout --theirs ., git checkout --ours .). Inspect conflicts intentionally.
• Avoid rebasing long-lived mixed-history branches if it pulls broad unrelated conflicts. Abort and use a fresh branch from main plus task-relevant cherry-picks.
• If package.json, tests.md, or files under tests/ conflict during merge/rebase, start from the local/checkpoint version, then explicitly compare incoming changes and reconcile required updates before continuing.
• Before local main merge, diff-compare all branch changes against main.
• After merge/sync, verify the target really contains the commit with git branch --contains <commit>, git log --oneline origin/main -10, or a file-level diff against origin/main.

Commits

• Commit after each discrete task or sub-task.
• Do not batch unrelated tasks into one commit.
• Use a specific commit message describing the change.

PR Review Bots

• Treat Qodo/CodeRabbit comments as advisory, not authoritative.
• For PR update + review requests: push branch, update PR summary/verification notes when changed, then post a plain PR comment containing exactly /review.
• Do not use draft reviews or batch review APIs to trigger Qodo.
• Before applying a bot fix, inspect the current code path and classify the comment as real, stale/resolved, rejected, or docs-only.
• This app server is local-user facing and is not intended to be exposed as a public internet service. Reject Qodo/CodeRabbit security hardening comments that assume a hostile remote caller for local project import/export, including saved-root allowlists, import parent restrictions, ZIP upload caps, or local path redaction, unless they identify a concrete path where this local-only server becomes remotely reachable or bypasses existing authentication.
• Prefer a focused regression test for accepted bugs. After fixing, run the narrow test plus relevant build/typecheck, push, and re-check PR comments/status.
• Completion reports must distinguish confirmed fixes from stale or rejected bot comments.

Performance

• Every feature/behavior change needs a performance audit before completion.
• Ground the audit in measurements, profiler output, traces, request counts, bundle/build output, or concrete code-path analysis. If live measurement is infeasible, say what was not measured.
• Documentation-only changes do not require a performance audit.
• For startup, thread loading, realtime rendering, routing, API, filesystem, git, or module-loading changes, explicitly check duplicate requests, blocking work, unbounded fanout, large payloads, and cache invalidation risk.
• Prefer profiler helpers for browser/startup/thread work: pnpm run profile:browser and pnpm run profile:thread; reports land under output/playwright/.
• Profiler server setup:
  1. Ensure node_modules exists. In side worktrees, reuse a compatible shared dependency tree instead of installing from scratch.
  2. Before reusing 127.0.0.1:4173, inspect the listener with lsof -nP -iTCP:4173 -sTCP:LISTEN and lsof -a -p <PID> -d cwd.
  3. If 4173 belongs to another worktree, old main checkout, or stale Vite state, stop only that 4173 process and restart from the current cwd.
  4. Never stop the persistent tmux server on 5173.
  5. Start/current server command: pnpm run dev --host 127.0.0.1 --port 4173.
  6. Reject profiler output from an error page, stale worktree, indefinite Loading threads..., or zero API traffic caused by failed app boot. Fix readiness and rerun.
• General profile command: PROFILE_BASE_URL=http://127.0.0.1:4173 PROFILE_WAIT_MS=7000 pnpm run profile:browser.
• Thread route profile command: PROFILE_BASE_URL=http://127.0.0.1:4173 PROFILE_ROUTE='#/thread/<thread-id>' PROFILE_WAIT_MS=7000 pnpm run profile:browser; use pnpm run profile:thread when appropriate.
• Inspect duplicateCounts, warnings, totalApiKB, topApiSummary, and slowestApiRows; open the matching trace zip with npx playwright show-trace when deeper request/render timing is needed.

Tests And Verification

• Test changes before reporting completion when feasible.
• Update the relevant manual test doc under tests/<domain>/ after feature work. Keep tests.md as the root index only. Add/adjust only the relevant section and preserve existing cases.
• Manual test entries must include feature/change name, prerequisites/setup, exact actions, expected results, and rollback/cleanup notes when applicable.
• For new/changed UI, verify light and dark themes. If dark screenshots show light surfaces on a dark page, fix CSS/theme wiring.
• Run Browser Use or Playwright only when the user explicitly asks for browser automation testing, or when a repo-specific rule below requires it.
• CJS smoke test is required for package/runtime/module-loading changes: build first, run node -e "require(...)" or the closest public CJS entry, confirm expected exports, and report the exact command/result.

Browser And Playwright

• Prefer Browser Use for navigation, clicking, typing, screenshots, snapshots, and visible local UI checks.
• Use Playwright CLI directly when verification needs request interception/route stubbing, synthetic network failures, modifying localStorage/session storage, or other page-context mutation that the in-app Browser bridge cannot perform reliably.
• If falling back from Browser Use, state the exact limitation, keep the same target/viewport, and save screenshots under output/playwright/.
• Playwright scripts should default to CJS: const { chromium } = require('playwright').
• Playwright sequence: use 127.0.0.1:4173, verify the server is current, exercise the changed flow, capture light/dark screenshots for UI work, include 375x812 and 768x1024 for responsive/mobile changes, wait 2-3 seconds before final screenshots, and leave 4173 running unless asked to stop.
• Screenshot reports must include tested URL, viewport, assertion/result summary, absolute screenshot path(s), and inline Markdown image(s).
• If Playwright assertions fail, fix and rerun before reporting completion.
• For chat parsing/file-link/browse-link changes, TestChat validation is mandatory: send a unique marker with representative markdown/link content, inspect the rendered row, assert hrefOk, titleOk, and textOk, and save output/playwright/testchat-<feature>-cjs.png.

Dev Servers

• In worktrees, reuse an existing compatible node_modules tree when available. Do not prompt to remove/recreate a shared dependency directory just to run dev commands.
• Pass Vite flags directly to this repo's wrapper: pnpm run dev --host 127.0.0.1 --port 5173; do not insert an extra --.
• For dev-server fixes, verify the exact user-requested command afterward.
• Never kill or restart the tmux-managed 5173 server unless the user explicitly asks.
• Treat 4173 as reusable/disposable verification infrastructure. Verify its cwd before using it; restart only stale 4173 processes.

UI Rules

• For shared route surfaces and large feature UIs, put decisive dark-theme overrides in src/style.css instead of relying only on component-scoped :global(:root.dark) blocks.
• Do not introduce native browser dropdowns (<select>) for app controls such as provider, model, branch, runtime, folder, language, or settings pickers. Use the app's custom dropdown/menu components so styling, search, dark theme, and option layout stay consistent.
• Browser assertions must inspect the real changed UI, not sidebar previews or base page load.
• For refresh-persistence fixes, include post-refresh evidence that the state persisted.

Provider/Auth Docker Workflow

• Use this only when changes touch Docker startup, Codex auth detection, OpenCode Zen/OpenRouter/custom providers, provider model loading, app-server config, chat send/reply handling, or failed-turn error rendering.
• Build/package first: pnpm run build, pnpm pack --pack-destination /tmp, then build an OrbStack/Docker image installing the packed codexapp tarball plus @openai/codex, using CODEX_HOME=/codex-home and command codexapp --port ${PORT:-4190} --no-password --no-open --no-tunnel --no-login.
• Test isolated containers on unique localhost ports for: no auth Zen fallback, invalid/expired auth Codex error persistence after reload, malformed auth fallback, and provider switch from Zen to OpenRouter.
• Before success, report tested ports, provider/config summary, exact commands, screenshot paths, whether invalid auth persisted after reload, and whether duplicate live overlay count was zero.

Fast Docker Feature Tests

• Use this for local-only feature checks that do not need packaged install behavior, for example project import/export HTTP endpoints.
• Build the reusable base image once with docker build -t codexapp-fast-test-base:latest -f scripts/docker-fast-test-base.Dockerfile ..
• For each test run, prefer scripts/run-docker-fast-test.sh; it runs pnpm run build, mounts the current repo read-only, reuses a Docker CODEX_HOME volume, and starts node /repo/dist-cli/index.js on 127.0.0.1:${PORT:-4191}.
• Do not rebuild a packed-image Docker artifact for these checks unless the task specifically needs package install, npm tarball contents, postinstall behavior, auth/provider startup, or published npx behavior.
• To reset state, remove the named volume printed by the script or pass a new CODEXAPP_DOCKER_FAST_HOME=<volume> value.

NPX / A1 Validation

• For npx package behavior tests, publish first and test the published @latest.
• Run npx validation on the Oracle host unless the user explicitly asks otherwise.
• For Oracle A1 UI validation from Mac, start the A1 server with Codex CLI in PATH using pnpm run dev --host 0.0.0.0 --port 4173, use the Tailscale URL such as http://100.127.77.25:4173, verify both UI and filesystem effects, and save screenshot evidence.

LLM Wiki

• llm-wiki/raw/ is immutable source material; never edit raw files after creation.
• Prefer updating existing pages under llm-wiki/wiki/ over creating duplicates.
• Keep factual wiki claims tied to one or more raw source files.
• For ingest: add raw source, update/create topic pages, and update llm-wiki/wiki/index.md.
• Never create or maintain separate wiki logging/changelog files or logging sections anywhere in the repo. Git commit messages are the main and only chronological log for wiki work and related documentation changes.
• For query: read llm-wiki/wiki/index.md first, then relevant pages.
• For lint: check orphans and stale/contradictory claims; put follow-up questions in the relevant wiki topic page or a tracked issue, not any log/changelog file.

Wiki index

• Read Zen hybrid routing before changing Zen model discovery, per-model protocol dispatch, or tool-stream translation.