Cursor + Codex as an editor–agent workflow

How to pair Cursor as your AI IDE with Codex as a scripted agent for safe, scoped repo-wide changes—with real costs and a concrete end-to-end pattern.

Cursor + Codex: what you’re actually deciding If your team already writes code in Git branches and ships via CI, the real question is not “Cursor or Codex?” but “Do we separate interactive editing from scripted agents?”. This guide argues yes: run Cursor as your AI-native IDE for exploration and review, and add Codex as a separate, scripted agent for tightly scoped, batch repository-wide changes. That split gives you three things all-in-one assistants rarely do: explicit scope control (file lists and branches), clear safety boundaries (diff-only, CI-enforced), and predictable Codex cost on top of usage-based Cursor plans. The trade-off is setup overhead: you will wire Codex into Git and CI, not just click a plugin. This article walks through the concrete workflow, using a representative refactor (HTTP client migration) to show how Cursor maps the change and Codex implements it, plus a worked cost model and failure modes so you can decide whether this pattern is worth adopting. If you want the bigger-picture context first, you can pair this with the stack-level outline in the best AI development stack for 2026 . Why pair Cursor with Codex instead of a single tool Two distinct roles: IDE vs agent Cursor is an AI-native IDE forked from Visual Studio Code with integrated assistant, codebase-aware edit and chat, and test generation features, not just a plugin bolted onto another editor, as described in its own positioning and by independent descriptions of its VS Code origins on Wikipedia . It is built for interactive work: reading code, editing a few files, running tests, reviewing diffs. Codex in its current form is a coding-optimised assistant exposed via the OpenAI Responses API and as a product inside ChatGPT workspaces, with a key model codex-mini-latest priced per token. It is better treated as a service than a co-pilot: you script calls, give it structured inputs (file contents, instructions), and get back code or patches. In this pattern: Cursor owns: local development, understanding the codebase, inline edits, quick refactors, and visual diff review. Codex owns: repeatable, scoped batch work—codemods, mechanical migrations, cross-cutting edits across tens or hundreds of files. If you’re deciding whether Cursor should be the core of your stack in the first place, it helps to read it alongside the separate Cursor review for 2026 , which dives deeper into Cursor’s strengths and limits as an AI IDE, and the comparison in GitHub Copilot vs Cursor for a head-to-head look at editor-first stacks. What Codex is and how it’s sold OpenAI’s Codex product is now delivered in two main ways: As codex-mini-latest and related models via the Responses API. As of the latest OpenAI Codex pricing update, the codex-mini-latest model on the Responses API is listed at US$1.50 per 1M input tokens and US$6.00 per 1M output tokens , with a 75% discount on cached prompt tokens . Always confirm these numbers on the current Codex pricing page before budgeting, as OpenAI may update them. As an integrated feature inside ChatGPT workspaces (e.g. Business, Enterprise), where Codex usage draws down a shared workspace credits balance on a pay‑as‑you‑go basis. Some workspace configurations support Codex‑only seats and promotional credits, but the presence or absence of any fixed seat fee depends on the specific ChatGPT plan and workspace setup; check the current Codex pricing and ChatGPT Business documentation for details. For a deeper breakdown of ChatGPT tiers and how credits work in practice, see ChatGPT pricing 2026. Legacy Codex endpoints in the classic OpenAI API were deprecated with a shutdown date of 20 March 2023. Any new agent should target the current OpenAI Responses API and the officially documented Codex models there, not the deprecated Codex API routes. Why not just Cursor’s built-in AI or Copilot? Popular assistants like GitHub Copilot (integrated across VS Code, JetBrains, Neovim and others per its own documentation) and Cursor’s built-in AI are optimised for inline completions and localised edits. They are indispensable for day-to-day coding, but they are not designed as transparent batch agents for large repo changes: Scope control : all-in-one assistants typically operate on the current file or a small context window. Multi-file refactors rely on the IDE glue, not explicit file lists you can audit. Observability : you get diffs in Git, but rarely a structured log of what the AI was asked to do across a batch run. Cost visibility : metering is bundled into the assistant subscription; it is difficult to attribute API spend to specific codemods or migrations. By separating Cursor (editor) and Codex (agent) you can: Run Codex only via scripts that take explicit paths.txt or globs. Force everything through feature branches and CI. Meter Codex usage by token across repositories and workflows. The trade-off: you will maintain command-line tools or services for Codex calls and keep them in sync with your repo architecture. If you prefer a terminal-first agent rather than an IDE, the trade-offs are explored in Claude Code terminal-first agentic coding . Who this workflow is and isn’t for This pattern fits teams that: Run production repositories where cross-cutting refactors (e.g. migrations, logging unification) happen at least quarterly. Already work with Git feature branches, pull requests and CI-enforced tests. Want separation between interactive editing and auditable agents that never push directly to main . Teams that mostly want smarter autocomplete and occasional inline fixes, or that are locked into JetBrains-only workflows, are better served by a single assistant in the existing IDE. For a deeper trade-off analysis between Cursor and other tools, see the separate comparison of IDE-first vs terminal-first stacks in Cursor vs Claude Code vs code/terminal agents . Setting up Cursor for exploration and visual review Install, connect repos, confirm Git Cursor is a fork of Visual Studio Code, so installation and basic ergonomics mirror VS Code’s, as described in public documentation and its Wikipedia entry. High-level setup for this workflow: A marketing screenshot of the Cursor editor illustrates the AI-native IDE environment the article recommends for code exploration, chat-based understanding, and inline edits before batch changes. Cursor’s official models and pricing table grounds the article’s assumption of a per-user subscription around the Pro and Teams tiers, which feed into the later cost model. Install Cursor on each developer machine. Use built-in Git integration to clone or open repositories from GitHub/GitLab/Bitbucket over SSH or HTTPS. Confirm standard Git operations in Cursor: switching branches, creating new branches, staging, committing and pushing. Configure Cursor’s AI and indexing Cursor’s marketing describes AI features such as repository-level understanding, codebase chat and test generation. For this workflow: Enable project indexing so Cursor can answer questions about the codebase. Large monorepos may need selective indexing depending on Cursor’s practical limits, which are not fully specified publicly. If you’re dealing with very large repos, the separate guide on Cursor indexing for large existing codebases is a useful complement to this section. Set default models and any privacy/telemetry toggles aligned with your organisation’s policy. For large repos, consider multiple Cursor workspaces (per service or module) instead of indexing the entire monorepo at once. Exploration workflow in Cursor Use Cursor as the front-end for understanding and designing changes: Use code search and codebase chat to find all call sites of an API or dependency. Ask the assistant to summarise a module or explain how a feature flag is wired end-to-end. Perform small, localised edits directly in Cursor with the AI edit tools—typically within one or a handful of files. This step is where the impact radius is mapped and edge cases are captured before any batch work. For more detailed rules on keeping Cursor useful but safe on production repos, there is a dedicated guide on production-ready Cursor rules. Visual review conventions Cursor’s Git integration gives side-by-side diffs and staging. For an AI-heavy workflow: Always create a feature branch before invoking Cursor AI on anything non-trivial. After an AI edit, review the diff in Cursor , not just the inline suggestion. Run tests locally where reasonable from within the editor terminal before committing. A useful convention is that Cursor is allowed to propose changes; humans own commits and explanation in commit messages. Keeping Cursor aligned with HEAD Because Cursor maintains an internal view of the repository, stale local branches can confuse both the developer and the AI. Practical hygiene: Rebase or merge main into feature branches regularly. Avoid long-lived branches where Codex will later apply patches—sync them before applying agent-generated changes. Configuring Codex for scoped implementation work Choose Codex access path There are two main patterns, based on OpenAI’s product documentation: Direct API : Use the Responses API with codex-mini-latest . You get fine-grained control, straightforward metering (per token) and flexibility to integrate with any CI or script. ChatGPT workspace : Use Codex via a ChatGPT Business/Enterprise workspace with pay-as-you-go credits and Codex-only seats, as described in OpenAI’s team pricing page. This can simplify billing and governance in smaller organisations but gives less low-level control than direct API integrations. This article assumes API-first, as it maps directly to CLI tools and CI jobs. If you’re still weighing ChatGPT-based workflows vs dedicated coding tools, it may help to pair this guide with the broader ChatGPT vs Claude comparison for real work . API setup and repository mirrors To keep Codex scoped, Codex should never have direct read/write access to a production remote repo: Create a mirror repository per production repo, e.g. my-service-codex-mirror , hosted in a separate organisation or namespace with restricted access, as described in more detail in the separate guide on making a production repo safe and cheap for Codex. Synchronise the mirror via read-only CI jobs or periodic git push --mirror from a controlled service account. For a worked pattern that includes GitHub branch protections and CI, see the safe-branch design in Design a Safe Codex Workflow on GitHub . Set environment variables in the Codex tooling environment: OPENAI_API_KEY , CODEX_REPO_PATH (pointing to the mirror), and any branch naming convention variables. Prompt design for scoped tasks Codex should be constrained by: An explicit file list or directory glob, e.g. paths to all files using a deprecated HTTP client. A compact design spec for the change (see the later concrete example). Hard constraints : no new dependencies, no changes outside listed files, maintain backward compatibility. A scaffolded instruction block for Codex might look like: Task: Migrate from axios to fetch in the following files. Constraints: - Only modify the files listed. - Preserve function signatures and exported types. - Run existing unit tests in your reasoning; do not invent new ones unless required. - Maintain current logging and error handling patterns. For each file, output a unified diff (patch) in <patch> tags. Integrating Codex with Git Codex itself does not run git ; the surrounding tooling should: Create a new feature branch in the mirror repo , such as codex/http-migration-2026-09 . Collect files to change (e.g. via rg "axios" src/ > paths.txt then normalise to unique file paths). Call Codex with the selected files’ contents and instructions. Write Codex’s unified diff output to a patch file. Apply the patch with git apply ; reject the run if git apply fails. Push the branch to the main repo and open a PR, or export the patch for local application within Cursor. Codex pricing and cost expectations As of the latest OpenAI Codex pricing update, codex-mini-latest pricing on the Responses API is: Item Price Notes Input tokens US$1.50 per 1M 75% discount for cached prompt tokens Output tokens US$6.00 per 1M Billed separately from input Patterns implied by this rate card: Input is relatively cheap; large context windows are manageable. Output is costlier; very verbose patches can dominate spend. Prompt caching matters if the same system/content is reused for many similar tasks. Later sections apply these numbers to a realistic refactor. Always verify current prices on OpenAI’s official pricing pages before committing to a budget. A concrete Cursor + Codex workflow on a real repository Representative task: HTTP client migration Consider a Node/TypeScript service using axios , migrating to fetch or a custom HTTP wrapper across ~80 modules. This is cross-cutting, error-prone and time-consuming to do by hand—an ideal Codex candidate, but only if scoped and reviewed carefully. Step 1 – Map impact surface in Cursor In Cursor, on a feature branch like chore/http-client-migration : Use search for import axios and .get( /other methods to find patterns. Use codebase chat to ask: “Show all modules that wrap axios into helper functions.” Identify central wrappers vs scattered direct uses. Note integration tests that touch external HTTP calls. Capture key decisions in a new document, e.g. docs/http-client-migration.md , created in Cursor: Which new client to use (e.g. global fetch with a lightweight wrapper). How to handle timeouts and retries compared with axios . Any backward-compatibility requirements. Step 2 – Design the change Still in Cursor, refine the plan with AI help but do not touch the implementation across the repo yet. The design document might include: “Create src/lib/httpClient.ts exposing get , post , etc.” “Replace direct axios imports outside this file with imports from httpClient .” “Preserve error types exposed to callers.” Cursor fits well here: it can propose the new wrapper module, sketch usage examples and help reason about trade-offs. Once the wrapper and tests for it are merged or at least stabilised in the branch, freeze the design and use it as a stable spec for Codex. Step 3 – Scope Codex work In the Codex tooling (CLI or service, pointed at the mirror of the repo): Ensure the mirror is synced to the commit corresponding to the feature branch in the main repo. In the mirror, create a branch codex/http-client-migration . Generate a file list: e.g. rg "axios" src -l > filelist.txt . Read docs/http-client-migration.md from the repo as the design spec. The Codex prompt should then take: The design document content (as compressed as possible). The contents of each file in filelist.txt , one by one or batched. Instructions to emit unified diffs only. To stay within token limits and minimise risk, run Codex in batches, e.g. 20–30 files per call, grouped by directory. Step 4 – Apply Codex patch For each batch: Call the Responses API with a system prompt describing the repo and safety rules, user content including the design and per-file content, and instructions for Codex to output a diff. Save the diff to a patch file, e.g. patch-1.diff . Run git apply --3way patch-1.diff in the mirror repo’s branch. Fail the script on conflicts. Run at least npm test or a fast subset of tests in CI or locally in the mirror environment. Push codex/http-client-migration to a temporary remote or export patches for the real repo. Depending on governance, either of the following can be used: Open a PR from the mirror repo into the main repo (if connected), or Apply the patches locally on the Cursor branch ( git am / git apply ), then push normally. Step 5 – Review and refine in Cursor Back in Cursor, with the patched feature branch checked out: Inspect the Codex-generated diffs in the UI. Pay attention to error handling, logging, and subtle behavioural changes. Use Cursor’s inline AI edits for small refinements (naming, minor style issues), not large behavioural changes, to keep Codex work auditable. Ensure commit messages clearly indicate Codex batch work, e.g. prefix with [codex] . This is the stage where human judgement and Cursor’s visual diff tooling catch issues that Codex may have missed. Step 6 – PR and CI Once the branch looks acceptable: Push to the main remote and open a PR as usual. Let CI run full test and lint suites. Ask reviewers to pay extra attention to Codex-altered files, but treat them like any other diff. Recent academic work on AI coding agents, including studies that evaluate pull-request quality and acceptance rates, highlight PR-level outcomes as important metrics for judging these tools. That makes this review stage central if Codex-driven workflows are to be measured rigorously. Optionally, use labels like ai-generated for tracking. A separate article on Codex + Vercel preview-to-production workflows shows how to hook this into branch-based deploys so each Codex batch has an isolated preview environment, detailed in Codex + Vercel: preview-to-production workflow. Token and cost estimate for this example This section uses arithmetic derived from OpenAI’s published prices and simple assumptions; it is not based on logs. Assume: 80 files, average 200 lines each. ~4 tokens per word and ~1.3 tokens per character are typical; for estimation, assume 800 tokens per 200-line file (moderate TypeScript density). Design document: ~1,000 tokens. Codex outputs patches roughly equal in size to the modified input per file (another 800 tokens). Batched into 4 runs of ~20 files each. Per run (20 files): Input tokens: design (1,000) + files (20 × 800 = 16,000) ≈ 17,000 tokens. Output tokens: 20 patches × 800 ≈ 16,000 tokens. Total for 4 runs : Input: 4 × 17,000 = 68,000 ≈ 0.068M tokens. Output: 4 × 16,000 = 64,000 ≈ 0.064M tokens. Cost calculation using OpenAI’s listed prices: Input: 0.068M × US$1.50/1M ≈ US$0.102. Output: 0.064M × US$6.00/1M ≈ US$0.384. Total ≈ US$0.49 for this 80-file migration before any caching. Even if the files are twice as long and the prompt size is doubled, the total remains well under US$2 for this run. The bigger costs are human review time and the risk of subtle bugs, not API spend. Failure modes to watch: Under-specified design → Codex may diverge in error handling or logging patterns across files. Batch too large → context truncation can drop constraints; keep runs modest. Branch drift between mirror and main repo → merge conflicts or broken tests. Cost modelling: what this workflow actually costs Cursor seat cost The Cursor pricing page lists paid plans such as Pro, Teams, and Enterprise, on top of a free level of usage. Pro increases AI usage and features for individual developers, Teams adds pooled usage and collaboration features, and Enterprise adds advanced security, compliance and administration options. Use the live pricing page language for the exact plan names and feature sets, as these may change. For many small teams using this pattern, a Pro-type plan at roughly US$20 per developer per month, as currently listed, is the relevant baseline for cost modelling. For a deeper breakdown of where those Cursor costs actually land in real use, the separate article on Cursor pricing and limits goes into more detail. Codex usage tiers by scenario Using the assumptions and OpenAI’s published token prices, a few normalised scenarios are: Scenario Description Cursor spend Codex tokens (in/out) Estimated Codex cost All-in monthly Solo, light 1 developer, 1–2 medium refactors/month 1 × US$20 Pro = US$20 ~0.4M in, 0.2M out In: 0.4 × 1.50 = 0.60; Out: 0.2 × 6 = 1.20; Total ≈ US$1.80 ≈ US$22/month Team of 5, moderate Regular small tasks + occasional migrations 5 × US$20 Pro = US$100 ~3M in, 1.5M out In: 3 × 1.50 = 4.50; Out: 1.5 × 6 = 9.00; Total ≈ US$13.50 ≈ US$115/month Team of 10, heavy Frequent codemods and API-wide changes 10 × US$20 Pro = US$200 ~10M in, 5M out In: 10 × 1.50 = 15.00; Out: 5 × 6 = 30.00; Total ≈ US$45.00 ≈ US$245/month 3 users via ChatGPT Business Codex from workspace credits 3 × US$20 Business = US$60 ~2M in, 1M out In: 2 × 1.50 = 3.00; Out: 1 × 6 = 6.00; Total ≈ US$9.00 ≈ US$69/month Across these, Codex usage is typically 10–20% of the editor seat spend , often less if batch work is occasional. Marginal cost of common tasks Using the token arithmetic from the HTTP migration example and OpenAI’s prices: A 200-file refactor might easily remain under ~0.5M tokens input and 0.3M output (≈US$0.75 + US$1.80 ≈ US$2.55). Ten small bug-fix tasks on 3–5 files each might land under ~0.3M input and 0.15M output (≈US$0.45 + US$0.90 ≈ US$1.35). In both cases, Codex is inexpensive compared to developer time. The economic question becomes whether the engineering overhead of this workflow pays off. Levers to control spend Scope aggressively : only send necessary file contents and the minimal design context. Exploit prompt caching : reuse the same system and design prompts across many calls. Prefer Cursor for single-file work : avoid Codex for small refactors; use the IDE assistant instead. CI guards : automatically fail or alert on unexpectedly large diffs to catch runaway Codex output. Repository patterns that make agents effective Make modules and interfaces explicit Codex and Cursor work best when the codebase has: Clear module boundaries (e.g. src/lib , src/services ). Stable, documented interfaces for cross-service calls. Minimal circular dependencies, which complicate mechanical changes. Directory-level README.md files and CODEOWNERS help both humans and AI locate the right abstractions and constraints. Prompts can then say “follow patterns in README” rather than reinvent conventions. Tests as the gatekeeper Tests are the primary line of defence for AI-generated diffs: Ensure critical flows have unit and integration tests that can be run in CI on Codex branches. Consider a slightly stricter coverage or test suite for PRs with Codex-labelled commits. Branch and commit discipline To keep audits and rollbacks manageable: Use a naming scheme for Codex branches, e.g. codex/<short-task-id> . Keep Codex-generated changes in separate commits from manual fixes. Tag releases that include major AI-generated refactors for easier post-incident analysis. Monorepos and partial workspaces For large monorepos: Use partial checkouts or narrow worktrees for Codex and Cursor, focusing on specific services. Create per-service Cursor workspaces so the AI index stays under practical limits. Drive Codex file lists from service directories, not the entire monorepo. Separate guidance on terminal-first agents in monorepos is available in the article on Claude Code and terminal-first agentic coding , which is useful if a team prefers that style and may choose a different stack. Integrating Cursor + Codex into CI/CD and review Pre-commit and CI checks To keep AI-generated code from bypassing checks: Use pre-commit hooks (lint, formatting) on all branches including Codex ones. Make CI non-optional on main and release branches, blocking merges when tests fail. Optionally add a CI step that flags unusually large diffs or high churn in critical directories when commits contain a Codex marker. Annotating AI-generated diffs For GitHub: Use branch naming and commit prefix conventions to identify Codex activity. Optionally build a small bot that comments on PRs summarising which files were modified by Codex, based on metadata from the agent scripts. Review process adjustments Reviewers can treat Codex and Cursor-origin changes differently: Cursor-local changes (a few files, local refactors) follow normal review. Codex batch changes merit deeper scrutiny, especially around edges like error handling and subtle logic. Require at least one reviewer who owns the relevant module for cross-cutting Codex changes. Usage and budget tracking Since Codex is metered per token: Log each Codex run with timestamp, repository, branch, approximate token counts and purpose. Aggrega