# Codex NestJS: A Practical Agent Workflow Guide

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

Use Codex in a NestJS project with an AGENTS.md setup, a Jest-driven loop, and practical prompts for modules, DTOs, TypeORM, and Prisma.

**In short:**

- Codex works best on NestJS when AGENTS.md records module, DTO, and testing conventions.
- A small-step loop of plan, generate, run Jest, and review the diff prevents DI and validation errors.
- Use AgentVera for parallel NestJS agents in separate worktrees with code review and checkpoints.

[Codex](/en/agents/codex/) works well on NestJS because the framework is highly structured: modules, controllers, providers, and DTOs repeat predictable patterns. Run `codex` in the project root with a clear AGENTS.md, keep changes small, and verify with Jest after each step. This guide covers a practical loop for building and refactoring NestJS code with the agent.

## Why Codex fits NestJS work

Codex suits NestJS work because the framework’s conventions reduce ambiguity. A module, controller, service, and DTO have stable shapes and naming rules, so the agent can generate code that matches your existing style when AGENTS.md records the conventions. NestJS also has clear boundaries: controllers parse input, providers hold logic, modules wire dependencies, and DTOs validate with class-validator. Codex can follow these boundaries when you ask for small, testable slices rather than whole features.

The strongest fit is test-driven maintenance. Write or update a Jest spec, run it, and let Codex fix only the failing code. NestJS tests are explicit about providers and modules, which helps the agent stay inside the dependency injection graph. This works better than asking for an entire feature at once, because a large request often hides a missing export or an unregistered provider until runtime.

Because NestJS dependency injection is declarative, the agent can also inspect existing modules to infer provider registration style. That is useful for keeping new code consistent with the rest of the project.

## Setting up a NestJS project for Codex

Start the agent from the project folder by running `codex`. Codex reads project instructions from AGENTS.md in the repository root. For NestJS, keep the file short and explicit about commands, package manager, folders, and the rules you do not want the agent to guess. The example below covers a typical TypeORM setup with Jest and class-validator.

```markdown
# AGENTS.md

- Package manager: npm
- Build: npm run build
- Lint: npm run lint
- Test: npm run test
- Test watch: npm run test:watch
- E2E: npm run test:e2e
- Format: npm run format
- Folder conventions: create one folder per feature under src/<feature>/; include <feature>.module.ts, <feature>.controller.ts, <feature>.service.ts, dto/, and entities/ or repositories/ where needed.
- Controllers stay thin: parse and validate input, call providers, return DTOs or entities with appropriate serialization.
- Providers must be decorated with @Injectable() and registered in the module's providers array; export only what other modules import.
- DTOs use class-validator decorators; enable ValidationPipe globally in main.ts with transform and whitelist.
- Database access goes into providers or repositories; do not put TypeORM queries in controllers.
- Avoid circular dependencies; if unavoidable, use forwardRef and document why.
- Do not change generated Jest config unless a test fails for a documented reason.
- Keep commits small and focused.
```

Add only rules your project actually uses; too much text dilutes the agent’s attention. If you use Prisma instead of TypeORM, replace the database rule with a PrismaService provider and keep PrismaClient instantiation in one module. Keep the file scoped to NestJS-specific decisions: say whether DTOs use class-validator or class-transformer, where e2e tests live, and whether Prisma or TypeORM owns the data layer.

## A working loop with Codex on NestJS

Use a loop: plan the change, ask for one small piece, run the relevant Jest or e2e command, then review `git diff` before the next request. Large NestJS changes often fail in hidden ways: a provider not exported, a module not imported, or a DTO missing a decorator. Reviewing the diff catches those before they compound.

Example prompts for typical NestJS tasks:

- Create a `users` module with `UsersController`, `UsersService`, `CreateUserDto` using class-validator, and a TypeORM `User` entity. Register the module in `AppModule`.
- Add `GET /users/:id` that returns a user or throws `NotFoundException`; write the unit test for the service first.
- Refactor email sending out of `UsersService` into a `MailModule` with one provider, update imports and tests, and ensure existing tests pass.
- Run `npm run test` and fix only failing tests in the `auth` module without changing unrelated files.
- Review the current diff for NestJS-specific issues: missing `ValidationPipe`, missing exports, provider registration mistakes, or circular imports.

After each prompt, ask Codex to show the new module’s imports and exports when the change crosses module boundaries. This keeps the dependency injection graph visible instead of trusting the generated code blindly.

## Tasks Codex handles well and NestJS pitfalls

Codex is strong at generating standard NestJS scaffolding, DTO validation, CRUD endpoints, and test updates. It is weaker at spotting architectural drift across modules, so review import and export graphs manually after any module split.

| Task | What Codex handles well | Watch closely |
|------|--------------------------|---------------|
| New feature module | Consistent controller, service, module, and DTO files | Missing `@Injectable()`, module not imported in `AppModule` |
| Validation | class-validator decorators, custom pipes, DTO shape | ValidationPipe not enabled globally or whitelist disabled |
| Database access | TypeORM repositories or Prisma providers, basic migrations | Entity not registered, provider not exported, transactions split across calls |
| Testing | Jest unit tests, provider mocks, e2e setup | E2E app imports the wrong module, state leaks between tests |
| Refactoring | Moving logic into providers and modules | Circular dependencies, breaking public providers used by other modules |

Watch these NestJS-specific failure modes: a provider used by another module must be listed in the module’s `exports`; DTO validation only works if `ValidationPipe` is registered with the expected options; e2e tests need the full `AppModule` or a dedicated test module; and circular dependencies hide as runtime `undefined` providers. Ask Codex to explain imports and exports after any module split.

## Testing and verification

Testing is the guardrail. After any agent change, run `npm run test` for unit tests and `npm run test:e2e` for supertest-based endpoints. Use `npm run test:cov` if coverage is configured to spot untested branches. For NestJS, unit tests often need provider mocks: ask Codex to use `Test.createTestingModule` with `overrideProvider` for dependencies. Keep e2e tests in `test/` and ensure they import the app with the same global pipes as `main.ts`. If a test fails, ask for the smallest possible diff that makes only that spec pass.

A second model review after an agent turn catches missing exports, misplaced decorators, and provider registration mistakes that unit tests may not cover. The workflow in [AI code review: check what your agents write](/en/blog/ai-code-review/) links findings to file and line, which is useful before merging. When CI fails after a Codex change, a separate agent pass can fix only the failing spec instead of rewriting whole modules; see [Auto fix CI failures and PR comments with AI](/en/blog/auto-fix-ci-failures-with-ai/).

## Running several agents on one NestJS project with AgentVera

When a NestJS codebase has multiple independent features, AgentVera helps by running real CLI agents side by side, each in its own terminal panel. Give each agent its own git worktree so parallel work on modules such as `users`, `auth`, and `billing` does not overwrite shared files; this is a practical [AI agent workflow pipeline](/en/blog/ai-agent-workflow-pipeline/) for NestJS feature teams. After an agent’s turn, automatic code review models the diff and links findings to file and line, which catches NestJS mistakes like a missing export or an unregistered provider. Checkpoints let you undo a bad refactor and replay a session step by step, while token budgets keep an agent from looping on a failing e2e test. These safeguards matter because NestJS dependency injection failures can be subtle and expensive to merge.

## Wrap-up

Codex becomes reliable on NestJS when you treat it as a junior engineer with strong pattern matching: give it AGENTS.md conventions, request one module-sized change at a time, run Jest after every step, and inspect module imports and exports before merging. With those habits, it handles the repetitive parts of NestJS work and leaves architectural decisions where human review matters.

## Frequently asked questions

**How do I start Codex in a NestJS project?** Run codex in the project root. It reads AGENTS.md from the repository, so add build, test, lint commands and NestJS module/DTO conventions. Keep requests small and run Jest after each change.

**Can Codex generate NestJS modules with DTOs and validation?** Yes, if AGENTS.md records your stack, Codex can create module folders with controllers, services, DTOs using class-validator, and register the module. Review exports and ValidationPipe setup because those are common mistakes.

**How do I prevent Codex from breaking NestJS dependency injection?** Ask for small slices and review the module’s providers and exports after every change. A shared provider must be exported from its module and imported by the consuming module, and every provider needs @Injectable().

**What is the best way to test NestJS changes made by Codex?** Run npm run test after each change and npm run test:e2e for endpoints. Use Test.createTestingModule with overrides for unit tests, and keep e2e tests importing the same app configuration as main.ts.

---

**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/