AGENTS.md

AGENTS.md

Child Agents

• Do not pass the model field to spawn_agent. Let child agents inherit the current agent's model automatically.
• Prefer spawning child agents for independent, bounded sidecar work that can run in parallel.
• Do not delegate the immediate blocking step on the critical path.
• Do not spawn child agents for trivial tasks, single-file edits, or work that depends on tight shared context.
• Min-Max orchestrate swarms of child agents at all times by default, time is of the essence always but you always make sure to not miss out context; token credits are infinite.
• Remember, you're amazing at concurrency and parallelism.

Local Tooling Defaults

• Default to jj for local repository inspection and history manipulation unless the task clearly requires raw Git semantics. Prefer jj st, jj log, jj describe, jj new, jj squash, jj split, jj rebase, jj undo, and jj git push over manual Git commit/rebase/reset flows.
• In jj conflict flows, prefer jj resolve --tool mergiraf before falling back to manual conflict editing.
• Use standard git directly when repo policy, hosted review tooling, hooks, branch naming, or user instructions explicitly depend on Git behavior or terminology.
• When explaining actions to the user, translate jj operations back into familiar Git terms if that improves clarity. Do not assume the user wants jj terminology by default.
• This machine has difftastic wired into Git as the default external diff. Treat plain git diff as syntax-aware by default; git dshow, git dlog, and git ddiff are available when you want explicit difftastic entrypoints.
• This machine has mergiraf registered globally as the Git merge driver via the global attributes file. Expect syntax-aware merges during git merge, rebase, cherry-pick, revert, and related conflict resolution flows.
• atuin is installed and initialized for zsh. Prefer atuin search, atuin history list, atuin stats, and interactive history recall over reconstructing long shell commands from scratch.
• When a task depends on prior local shell usage, check Atuin first before assuming the command needs to be rediscovered manually.

js_repl

• When direct tool calls fail with direct tool calls are disabled; use js_repl and codex.tool(...) instead, treat js_repl_tools_only as active and pivot immediately to js_repl with codex.tool(...) wrappers instead of retrying blocked direct tool calls.
• When js_repl_tools_only is active, do not call normal tools directly again in the same turn. Route shell, git, apply_patch, agent, and other tool usage through a single js_repl lane until the task is done.
• Keep js_repl operations token-efficient: define a small helper such as const run = (command, workdir = codex.cwd, timeout_ms = 20000) => codex.tool("shell_command", { command, workdir, timeout_ms }); once, reuse it, and batch adjacent reads inside one js_repl cell when practical.
• Remember that js_repl top-level bindings persist across cells. Do not redeclare the same const helper or result variable names in later cells; reuse the existing binding, reassign a previously declared let, or choose a fresh descriptive name to avoid Identifier 'x' has already been declared interruptions.
• When a task needs several related checks, prefer one js_repl cell that gathers the read/edit/verify outputs together over a sequence of tiny cells with repeated helper declarations. This is usually faster and avoids persistence collisions.
• Keep shell output narrow under js_repl: prefer rg -n, rg --files, sed -n, nl -ba ... | sed -n, git diff --stat, git show --stat --name-only, and similar bounded commands over broad scans, full-file dumps, or giant JSON payloads.
• When using codex.tool(...) results inside js_repl, emit only the useful field (output, stdout, or the specific property needed) instead of stringifying the whole tool response unless debugging the tool schema itself.
• For edits in js_repl_tools_only mode, send patches through codex.tool("apply_patch", patch) from js_repl instead of retrying blocked direct apply_patch calls.
• If shell or git commands in a restricted runtime start failing with temp/cache errors such as couldn't create cache file '/tmp/xcrun_db...' or fatal: unable to create temp-file, stop retrying the same command. Stay in js_repl, prefer lighter inspection commands first, and if git is still required use a writable home-scoped temp dir (for example TMPDIR=$HOME/.tmp) and low-churn forms such as git --no-pager diff --stat --no-ext-diff or git show --stat --name-only --no-ext-diff.