Codex TypeScript means running the Codex coding agent inside a TypeScript project and steering it with strict compiler settings, tsconfig context, and an AGENTS.md file. Start codex in the project folder, keep changes small, and verify every step with tsc --noEmit, tests, and lint. This guide covers a practical loop that avoids the common type-erosion mistakes Codex can make, especially in strict-mode and monorepo setups.
Strict TypeScript benefits from Codex’s type graph awareness
Codex is useful for TypeScript because it can hold the whole type graph of a change in context: update an interface, narrow a union in a reducer, and adjust call sites without losing the compiler’s feedback. With AGENTS.md it knows your build, test, and lint commands, so it can run tsc --noEmit and fix type errors instead of guessing. In a strict project with noUncheckedIndexedAccess, exactOptionalPropertyTypes, and noImplicitOverride, a small change can ripple through utilities, mappers, and tests. Codex is strongest at that mechanical propagation when the rules are explicit. It is not a replacement for the compiler; the typechecker remains the source of truth, and the agent should treat its output as the finish line for each step.
Configure AGENTS.md for a strict TypeScript repo
Make the project legible before the first prompt. Codex reads project instructions from AGENTS.md, which is the place to pin commands, folder conventions, and TypeScript rules. Keep the file short and specific; the agent should not need to explore the repo just to know how to typecheck. For example:
# AGENTS.md
## Commands
- Install: `pnpm install`
- Build: `pnpm build` (runs `tsc -b` and `vite build`)
- Typecheck: `pnpm typecheck` (runs `tsc --noEmit`)
- Test: `pnpm vitest run`
- Lint: `pnpm eslint .`
## TypeScript rules
- `tsconfig.json` uses `"strict": true`, `"noUncheckedIndexedAccess": true`, and `"exactOptionalPropertyTypes": true`.
- Do not introduce `any` or non-null assertions (`!`).
- Prefer `unknown` with type guards over `any`.
- Keep generic constraints explicit and avoid `as` casts to silence errors.
- Use branded types for domain IDs, not plain strings.
## Folders
- `packages/api/src` — server code, entry `index.ts`
- `packages/web/src` — React client
- `packages/shared/src` — shared types and utilities
## Workflow
- Run `pnpm typecheck`, `pnpm test`, and `pnpm lint` before finishing.
- In monorepo packages, run commands from the package directory unless stated otherwise.In a monorepo, add a short note per package or reference the root tsconfig.base.json. Tell the agent which package owns each command and where shared types live, so it does not cross package boundaries when resolving imports. Update AGENTS.md whenever you add a script or change a folder; stale commands cause the agent to run the wrong check and report false success.
A compile-driven loop: plan, patch, typecheck, review
The most reliable loop is plan, small step, compile, review. Ask Codex to read tsconfig.json and describe the affected types before writing code. Then ask for one function or one file at a time. After each change, run the project’s typecheck and tests yourself or have Codex run them, then inspect the diff for type-erosion markers. For general CLI habits, see How to use Codex CLI: a step-by-step guide.
| Task | Good prompt |
|---|---|
| Add a field to an interface | “Read tsconfig.json and src/api/routes/users.ts. Add a role field to the User interface and update every object literal and mapper. Run pnpm typecheck and pnpm test.” |
| Convert a union to a discriminated union | “Refactor src/utils/parse.ts to return a discriminated union with a kind field instead of throwing. Keep strict mode and update the caller in src/index.ts.” |
| Extract a generic repository | “Add generics to src/services/repository.ts so find is keyed by a table name and returns the correct entity type. Do not use any or type assertions.” |
| Fix a type error in a React component | “In src/components/Table.tsx, the row prop is too loose. Narrow it with a generic that extends Record<string, unknown> and run pnpm test.” |
The prompts ask for a compiler command at the end, which forces the agent to confront type errors instead of leaving them for you. After Codex reports success, read the diff. The red flags specific to TypeScript are as, !, any, lost generic parameters, and changes that widen a union to string or unknown.
What Codex gets right and where it adds unsafe casts
Codex handles mechanical type propagation well: adding an optional property to an interface and fixing all object literals, converting a union to a discriminated union, extracting a generic helper, updating imports after a file move, and resolving monorepo path alias errors. It also does a decent job of removing dead branches after a type narrows, as long as the narrowing is explicit.
Watch it closely when the change touches callbacks or async code. TypeScript narrows a value in an outer function, but inside a setTimeout or a .then callback the narrowing may not persist unless the value is assigned to a const before the callback. Codex sometimes adds as casts to silence errors instead of preserving the narrowing. Other pitfalls: any introduced in test files, generic defaults expanding to unknown, readonly objects being mutated through a non-readonly alias, and strictNullChecks violations hidden with !. In monorepos, the agent may edit tsconfig.json in one package to make an error disappear instead of fixing the import in another package; review those files separately.
Verify with tsc and tests before merging
Testing TypeScript work means more than running tests. Run tsc --noEmit or the project’s typecheck script after every agent turn; this catches type regressions even when runtime tests pass. If the project uses vitest, jest, or node --test, run the full suite plus the typecheck. Ask Codex to add type-level tests with expectTypeOf or tsd only when the project already uses them; otherwise it may introduce a new dependency. In CI, keep tsc as a required check before merge. When Codex fixes a CI failure, ask it to reproduce the failing command locally and show the error before changing code. The article Auto fix CI failures and PR comments with AI describes a loop that returns type errors and test failures to the agent instead of letting them sit in a pull request.
Parallel agents with worktrees and review in AgentVera
When several agents work on one TypeScript repo, AgentVera is the control plane. Run each Codex instance in its own git worktree so changes to tsconfig.json, shared types, and test files do not overwrite each other. Automatic code review at the end of each agent turn flags unsafe assertions, any leaks, and lost narrowing with findings linked to file:line. Token budgets cap per-agent and per-day usage, which prevents a broad refactor from running away. Approvals keep risky type changes visible before merge.
Wrap-up: treat Codex like a fast type propagator
Treat Codex as a fast junior TypeScript programmer with a short memory: give it precise context, strict rules, and a command that proves the code compiles. Keep AGENTS.md current, run tsc and tests after every change, and review diffs for type erasure before merging. With that loop, Codex becomes a useful refactoring and type-fixing tool on a TypeScript project.