Codex for Sui

What this does

Codex is good at Sui the moment it knows Sui's rules, and bad at it by default — left alone, it reaches for Solidity habits, invents framework APIs, and writes SDK calls against a JSON-RPC client that has been deprecated. This page installs a standing rule file that corrects all three, permanently, for every task in the repo.

It does not install Codex, and it does not touch your application or contract code.

When Codex is the right tool

Reach for Codex when the work is already well specified: implement this function, write tests for this module, turn this design into Move or TypeScript. It is strong on spec-driven invariants and on generating tests that follow the shape of existing ones, and it is comfortable working through several tasks in parallel while you review.

Use Cursor for daily editing. Use Claude Code when you need shell-heavy debugging.

How to install it

Press Copy markdown at the top of this page and paste it into Codex — CLI or IDE — with your repo open.

What you copy is not this page. It is an instruction set written for the agent: it inventories your repo first, reports what it found, and then creates the rule file. You do not need to add a prompt in front of it — pasting is enough.

If you would rather point an agent at a URL than paste, the same payload is served as plain markdown at /start-building/ai-setup/codex/agent.md.

What lands on disk

Codex reads AGENTS.md, and it merges those files from the repo root down to whatever it is editing. That inheritance is useful here, because it means the rules do not have to go in a shared file at the root.

The preferred target is a new AGENTS.md in the directory that holds your Move.toml. In most repos that file does not exist yet, so nothing is at risk, and the rules only load when Codex is actually working on Move — which keeps them out of context while you are editing frontend code.

If you want them repo-wide instead: when no root AGENTS.md exists, one gets created; when it does exist, a ## Sui / Move section is appended rather than the file being replaced. That distinction matters more than it sounds — a common setup symlinks AGENTS.md to CLAUDE.md, and an agent told to "create AGENTS.md" will happily write through the link and destroy the other file.

For a setup that follows you across every Sui repo without being committed, the same body works in ~/.codex/AGENTS.md, the global instructions file Codex reads before any project file.

Two details worth knowing once you have more than one of these. An AGENTS.override.md replaces the regular AGENTS.md at the same level, which is the first thing to check when rules you installed appear not to load. And the combined chain — global plus every file from the repo root down to what Codex is editing — is capped at 32 KiB by default and truncated once it fills, so a bloated global file crowds out the repo-specific rules you care more about. Keeping the Sui rules beside Move.toml rather than at the root helps here too.

What the rules actually enforce

Your repo outranks the rules. The edition and dependency rev come from your Move.toml, read at the time of asking — never from a value baked into a rule that was true when someone wrote it. Move sources are found by locating Move.toml, not by assuming a sources/ directory. Commands use whichever package manager your lockfile implies.

Ownership is treated as security. Object ownership, the key / store / copy / drop abilities, and transfers are handled as security-critical rather than mechanical. Visibility has to match intent, so public never gets widened just to make something compile. Admin, mint, and publisher capabilities must be gated, and shared-object mutations come with a note about congestion and authorization.

Deprecated clients are flagged, not silently rewritten. New code defaults to SuiGrpcClient from @mysten/sui/grpc, with SuiGraphQLClient for indexed or historical queries and @mysten/dapp-kit-react for new UI. Where old SuiClient code already exists, the agent is told to point it out and propose a migration — not to start rewriting working call sites in the middle of an unrelated task.

Ask for diffs, and for reasoning on the dangerous parts

Two habits do most of the work with Codex. Ask for unified diffs rather than prose descriptions of changes, so you review what actually lands. And require an explanation of the security impact before it changes a capability, a shared object, or an entry function — those are the edits where a plausible-looking patch is permanent once deployed.

Keep prompts scoped to a package subtree. Handing it the whole monorepo makes the answers worse, not better.

How to tell it worked

Ask Codex to review your Move package for ownership and capability bugs, without listing what to look for.

If the rules loaded, the answer talks about abilities, entry versus public visibility, and capability gating unprompted, and it quotes the real edition from your Move.toml instead of a generic one. If it gives you a vague code-style review, check that the AGENTS.md you created is on the path from the repo root to the file being edited.

Skills, if you want more depth

Rules are always on and should stay short. Skills load on demand and can be long, which makes them the right home for deep procedures — a Move security review pass, a zkLogin debugging walkthrough, a Walrus upload checklist.

Official Sui skills install with skills add mystenlabs/skills, run through whichever package runner your project uses. Start with --list rather than a name you remember: the catalogue moves, and the upstream README currently lags the repo. Task-specific ones live under Start building → Browse AI prompts, saved as .agents/skills/<name>/SKILL.md. Check what you already have installed first — duplicate skills covering the same ground make the agent pick arbitrarily.

One safety note

Never put private keys, mnemonics, or production secrets in a rule file, a prompt, or a generated config sample. Rule files are always in context, they get committed, and they end up in screenshots.