# Codex TypeScript: a practical guide for strict projects

URL: https://agentvera.dev/en/blog/codex-for-typescript/ · Published: 2026-11-01

Learn how to run Codex on TypeScript projects with strict mode, tsconfig-aware AGENTS.md setup, tsc in CI, and review steps to catch type-only mistakes.

**In short:**

- Codex works best in TypeScript when AGENTS.md pins build, test, and lint commands plus strict mode expectations.
- Use small typed prompts, run tsc and tests after each change, and review diffs for any or unsafe assertions.
- Parallel agents with worktrees and automatic code review reduce conflicts and catch type regressions early.

`Codex TypeScript` means running the [Codex](/en/agents/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](/en/blog/how-to-use-codex-cli/).

| 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](/en/blog/auto-fix-ci-failures-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](/en/blog/ai-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.

## Frequently asked questions

**Can Codex use tsconfig strict mode when editing TypeScript?** Yes, but you must make the rules explicit. Codex reads AGENTS.md and project files, so list strict options there and require tsc --noEmit after each change; it will then follow those rules.

**How do I configure Codex for a TypeScript monorepo?** In AGENTS.md, describe each package’s commands, tsconfig references, and shared type locations. Tell Codex to run commands from the package directory and not edit another package’s tsconfig to silence import errors.

**What are common TypeScript errors Codex introduces?** The most common are any leaks, non-null assertions that hide null checks, lost generic parameters, and as casts that bypass type errors. It may also widen a union to string or unknown while trying to satisfy the compiler.

**How do I run multiple Codex agents on one TypeScript repo without conflicts?** Use AgentVera with separate git worktrees for each agent so they do not overwrite shared files. Automatic code review and token budgets keep type changes small and reviewable before merge.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/