code AGENTS.md

Every Code Repository Guidance

Repo workflow metadata lives in .github/github.json; keep that file aligned with branch roles, validation gates, GitHub signal capabilities, workflow names, PR/release policy, docs routing, and local cleanup policy when those facts change.

Every Code is the product in this repository; code is the command users type. Use Every Code for the product name in prose, docs, UI copy, issue text, release text, and first mentions. Use Every Code CLI for the product CLI surface, and the code command when referring to the executable. Use the Every Code agent for the assistant identity; Code is only a short display name after Every Code context is established. Use Every Code harness for the runtime/session wrapper that we restart and dogfood, and Every Code runtime for process/session/tool-execution internals.

Upstream import sources are just-every/code and openai/codex. Treat just-every/code as a fork upstream/import source. Treat openai/codex / Codex CLI as the original/direct upstream and provenance source. The current product architecture is Codex CLI as the substrate with Every Code layered on top. Locally, codex-rs is a read-only mirror of openai/codex:main; edit Rust sources under code-rs, the Every Code product workspace built on the Codex CLI substrate.

CODE_HOME / ~/.code are the primary config and state locations. CODEX_HOME / ~/.codex are compatibility fallbacks. Keep CODEX_* names when they are part of external, backend, or upstream compatibility; add CODE_* aliases or rename only through a scoped migration. See docs/upstream-import-policy.md#code-and-codex-compatibility-policy before changing environment variable behavior.

Rust implementation lives under code-rs:

• Crate names are ownership markers. Imported Codex substrate crates may keep their upstream codex-* names only when they remain compatibility-critical or mostly upstream-shaped. Every Code-owned crates and new product-layer crates should use code-* names unless a documented external compatibility contract requires the upstream spelling.
• When using format! and you can inline variables into {}, always do that.
• Treat codex-rs as a read-only mirror of openai/codex:main; edit Rust sources under code-rs, including imported Codex-based sources that become part of the Every Code product workspace.
• When aligning with upstream, prefer moving code-rs closer to current Codex CLI shapes and adding Every Code behavior as a small product-layer overlay. Do not make codex-rs mirror Every Code or edit it directly.

Completion/build step

• Always validate using ./build-fast.sh from the repo root. This is the single required check and must pass cleanly.
• ./build-fast.sh can take 20+min to run from a cold cache!!! Please use long timeout when running ./build-fast.sh or waiting for it to complete.
• Policy: All errors AND all warnings must be fixed before you’re done. Treat any compiler warning as a failure and address it (rename unused vars with _, remove mut, delete dead code, etc.).
• Do not run additional format/lint/test commands on completion (e.g., just fmt, just fix, cargo test) unless explicitly requested for a specific task.
• NEVER run rustfmt
• Before release-bound work lands on main, run ./pre-release.sh to mirror the release preflight (dev-fast build, CLI smokes, workspace nextest).

Optional regression checks (recommended when touching the Rust workspace):

• cargo nextest run --no-fail-fast — runs all workspace tests with the TUI helpers automatically enabled. The suite is green after the resume fixtures/git-init fallback updates; older Git builds may print a warning when falling back from --initial-branch, but tests still pass.
• Focused sweeps stay quick and green: cargo test -p code-tui --features test-helpers, cargo test -p code-cloud-tasks --tests, and cargo test -p mcp-types --tests.

When debugging regressions or bugs, write a failing test (or targeted reproduction script) first and confirm it captures the issue before touching code—if it can’t fail, you can’t be confident the fix works.