Codex Vue.js: A Practical Guide for Vue Developers

Codex works well on Vue.js projects when you give it a concise AGENTS.md, keep tasks small, and verify every change with Vitest and Vue Test Utils. Start Codex with codex in the project folder, as described in the Codex guide, and treat its output as a draft, not a final PR. This guide covers the practical loop for Vite, Pinia, and the Composition API and shows where to watch the agent closely.

Codex and Vue: a strong fit for SFCs

Vue.js is a good fit for Codex because single-file components (SFCs) keep template, script, and scoped style in one file, so the agent has the full component context without searching. The Composition API with <script setup> is especially explicit: props, emits, refs, computed values, and functions are visible in one block, making it easier for Codex to produce correct TypeScript than with Options API magic. Pinia stores are plain modules with state, getters, and actions, so the agent can follow a consistent pattern. Vite and Vitest give instant feedback, which matters because the agent should run tests after every change rather than making large edits.

Give the agent a project map with AGENTS.md

Create AGENTS.md at the project root. Codex reads it on start, so keep it short and specific. For a Vue.js project, tell the agent the exact commands, folder contract, Vue version, and non-negotiable rules. Here is a realistic example:

# Vue.js project instructions

## Commands
- `npm run dev` - start Vite dev server
- `npm run build` - production build
- `npm run test:unit` - run Vitest once
- `npm run lint` - ESLint including .vue files
- `npm run typecheck` - vue-tsc --noEmit

## Folders
- `src/components/` - presentational SFCs, no store imports
- `src/composables/` - reusable Composition API logic
- `src/stores/` - Pinia stores
- `src/views/` - route-level components
- `src/tests/unit/` - Vitest specs

## Vue.js rules
- Use `<script setup lang="ts">`.
- Use `defineProps<T>()` with `withDefaults` for default props.
- Never mutate props or rely on Options API `data`/`methods`.
- Access Pinia state in components via `storeToRefs`.
- Keep SFCs under 300 lines; extract composables or child components.
- Use `@vue/test-utils` `shallowMount` for unit tests and `flushPromises` for async assertions.

A daily workflow: small steps and test feedback

Make a plan, ask for a small diff, run tests and typecheck, then review the diff. Do not ask Codex to refactor an entire app in one turn. For a broader CLI workflow, see How to use Codex CLI.

Example prompts for typical Vue.js tasks:

• Refactor src/components/UserTable.vue to <script setup> with typed props and a Pinia action for loading users. Replace Options API state with ref and computed, then run npm run test:unit.
• Add a Pinia store src/stores/cart.ts with items, totalItems, and addItem. Write unit tests using createPinia and setActivePinia, then run npm run typecheck.
• Create a composable src/composables/useDebouncedSearch.ts that debounces a ref with setTimeout and exposes a computed result. Add Vitest tests using fake timers.
• Find all SFCs that mutate props directly and fix them to emit events or use local state. Keep each change in its own commit.
• Add inline validation to src/components/CheckoutForm.vue using reactive form state and computed errors. Keep the SFC under 250 lines and add two tests.

Vue.js tasks Codex handles well, and common pitfalls

Codex handles new SFCs, Options API to script setup conversions, Pinia store creation, and Vitest specs well. It is less reliable when it must reason about reactivity across several files. The table below summarizes where it shines and where to check its work.

Common specific pitfalls: in a template, refs are auto-unwrapped, but Codex sometimes writes {{ count.value }}; in scripts, it may forget .value. It may destructure a reactive object and accidentally lose reactivity. It may mutate a prop from a child component, which breaks one-way data flow. For Pinia, it may return a new object from an action without updating state, or use store.state in a component instead of storeToRefs. Review every diff with those patterns in mind.

Verifying Vue components with Vitest and Vue Test Utils

Testing is not optional. After every Codex change, run the full unit suite and typecheck. For Vue, use Vitest with @vue/test-utils and a global setup that sets up Pinia. Ask Codex to run npm run test:unit and paste failing output into the next prompt. For component tests, prefer shallowMount with stubs for child components so the test targets one SFC. Use flushPromises before asserting after API calls. Check that tests assert user-visible behavior or emitted events, not just implementation details. An automated second pass is useful here; see AI code review for how a review model can catch Vue-specific mistakes such as missing storeToRefs or prop mutation.

Parallel agents on Vue projects with AgentVera

AgentVera is a desktop app that runs coding agents’ real command line tools, including Codex, side by side in one window with each agent in its own terminal panel. For Vue.js work, run several agents in parallel in separate git worktrees, as described in AI agent workflow, so one can handle a Pinia store while another builds SFCs without overwriting files. Automatic code review after each turn links findings to file:line, which is useful for catching Vue reactivity mistakes. Checkpoints let you undo a single turn when a store refactor breaks a component, and token budgets keep long refactors from spiraling.

Final thoughts

Treat Codex as a fast junior Vue developer with good recall but no judgment about reactivity. A short AGENTS.md, small prompts, and a strict test loop turn it into a useful pair programmer for SFCs, Pinia stores, and composables. Keep the agent focused, review every diff, and let your existing Vue tooling catch what the model misses.