Mike Cann

5 days ago

How to Use the New Convex Codex Plugin in OpenAI Codex

The Convex Codex plugin lets you scaffold and modify Convex backends directly inside OpenAI's coding agent. I installed it, built a real-time collaborative app from a single prompt, deployed it, and then retrofitted an existing client-side app with a synced backend. This walkthrough covers all of that, including the one behavioral detail that trips people up, which is that you have to invoke the plugin explicitly with @convex, because it does not pick up automatically.

If you already know what Codex is and you have at least a passing familiarity with Convex, this piece is for you. The goal is to show you whether the Convex Codex plugin makes Convex the right backend for your Codex workflow, and to do it from the perspective of someone who has run the workflow end to end rather than someone reading the release notes. I have a bias toward writing about things I have actually shipped, so everything below comes from a real session in front of a real agent, not a hypothetical one. Convex's broader positioning on AI code generation gives useful context if you are new to how a reactive backend pairs with generated code, but you do not need it to follow along.

There is a reason this combination is worth a careful look. Coding agents are good at producing code, but they are not always good at producing code that runs against a coherent backend, because the backend is where assumptions pile up and where a generic data layer starts to leak. A plugin that teaches the agent the shape of a specific backend changes that, since the agent stops improvising and starts working from a known model. That is the bet the Convex Codex plugin makes, and the rest of this piece is my attempt to test whether the bet pays off in practice.

What the Convex Codex Plugin Is

The Convex Codex plugin is an official Convex plugin for OpenAI's Codex coding agent. It lets you scaffold new Convex apps and add Convex to existing ones from inside Codex, without leaving the agent to wire up a backend by hand. It is aimed at software engineers who want to combine AI code generation with a reactive, real-time backend, which is a narrower audience than "everyone using Codex," and that narrowness is a feature rather than a limitation. The plugin is not trying to be a general-purpose backend generator. It is trying to make Convex the path of least resistance when you are already working inside Codex.

Convex publishes a family of agent plugins for AI coding tools, and the Codex plugin is one of them. These plugins give the agent development tools for building reactive TypeScript backends, so the model produces Convex-shaped code rather than improvising a generic data layer. That distinction matters more than it sounds, because the failure mode for agent-generated backends is usually not a syntax error. It is a subtle mismatch between what the agent assumes a backend does and what the backend actually does, and that mismatch surfaces later as a sync bug or a query that quietly returns stale data. When the agent is working from platform-specific tooling, that class of mismatch shrinks.

Codex itself is OpenAI's coding agent, and Convex documents the integration directly, so the plugin is a first-party bridge between the two rather than a community workaround. That first-party status is worth weighting when you decide whether to adopt it, because a first-party integration tends to track changes in both the agent and the backend more closely than a third-party shim would. I do not want to overstate this, since the plugin is new and first-party does not guarantee polish, but it does mean the people maintaining the Convex side have a direct line to the behavior you are relying on.

It also helps to be precise about what "plugin" means here, because the word carries different baggage in different tools. In this context, the plugin is a set of tools and instructions that Codex loads so the agent can reason about Convex specifically. It is not a code template you paste in, and it is not a wrapper that hides Convex behind a different API. The agent still writes Convex code that you can read, edit, and own, which is the behavior I want from any tool that generates a backend on my behalf.

Installing the Plugin

You can install the Convex Codex plugin two ways, either through the Codex app UI or through the terminal. Both reach the same plugin and both require a one-time authentication step the first time you connect. Pick whichever matches how you already work in Codex, because there is no functional difference in the result, only a difference in the surface you click through to get there.

Before you start, it helps to know that the authentication step is the part most likely to cause a pause on first use, since it is the moment the plugin connects to your Convex account. It is a one-time step, so once you have done it the connection persists across sessions, and you will not be asked again unless you disconnect. I mention this up front because the auth prompt is easy to mistake for an error if you are not expecting it, and knowing it is coming makes the install feel routine rather than confusing.

Installing from the Codex App UI

In the Codex app, open the Plugins panel, search for "Convex," and add the plugin. Codex will prompt you to authenticate once, after which the plugin stays connected for future sessions. The whole flow takes under a minute when it goes smoothly, and in my run it did.

I will be honest, I am not a terminal person, so this is the path I reach for first. The UI makes the one-time auth step obvious, which is helpful if you have never connected a Convex plugin before, because the panel walks you through the connection rather than leaving you to guess whether it worked. If you are the kind of engineer who lives in a GUI and only drops to the terminal when forced, this is the path that will feel natural, and it produces exactly the same connected plugin as the terminal route.

Installing from the Terminal

If you prefer the terminal, open Codex and type /plugins, then search for Convex and install it from there. The flow is the same underneath, including the one-time authentication, so you are not trading away any capability by choosing the command line. You are simply staying in the environment you already have open, which is reason enough if you spend your day in a shell.

Install confusion is a real thing for this plugin, since it is new and the existing footprint is scattered across GitHub and community threads. If you search for setup help, you will find fragments from different points in the plugin's short life, and some of them will be out of date before long. To avoid working from a stale fragment, I would anchor on the first-party reference rather than a forum post. Convex maintains a Codex setup guide that documents the integration in full, and it is the source I would trust when the community threads disagree with each other, which they will.

Building a New Real-Time App from a Single Prompt

Once the plugin is installed, you can build a working real-time app from one short prompt. The important catch is that you have to call the plugin explicitly, because a plain prompt will not trigger it. This is the detail that separates a clean run from a frustrating one, and it is worth internalizing before you type anything, since the failure is silent rather than loud.

Invoking the Plugin with @convex

You invoke the plugin by including @convex in your prompt. I tested this directly. When I described what I wanted without @convex, the plugin was not used, and the agent built something without the Convex backend, which left me with a result that looked plausible but did not sync. Adding @convex is what tells Codex to bring the Convex tooling into the task, and once I included it the behavior changed completely.

This is the single most useful operational fact in the whole workflow, so it is worth stating plainly. The Convex Codex plugin does not infer that you want Convex from context, even when your prompt clearly describes a real-time, multi-client app that Convex would be the obvious fit for. The agent will happily build you a backend-free approximation instead, and it will not warn you that it skipped the plugin. If you forget the @convex invocation, you will get a non-Convex result and wonder why nothing synced, and you may spend a while debugging an app that was never wired to a backend in the first place.

I want to be careful not to dress this up as a deeper insight than it is. It is a small habit, not a profound one. But it is the kind of small habit that, once you skip it, costs you a confusing ten minutes, so I have trained myself to type @convex first and describe the app second. That ordering makes the invocation impossible to forget, because it is the first thing my fingers do when I start a prompt.

What Got Scaffolded

From one short prompt with @convex, I got a working real-time collaborative drawing app. It synced live across clients, including shared cursors, so two browser windows drawing at the same time stayed in step with each other. That is a real backend doing real-time fan-out, not a mockup, and the distinction matters because shared cursors are exactly the kind of feature that looks trivial in a demo and turns out to be fiddly when you build it by hand. Cursor position has to propagate to every connected client fast enough that the movement feels continuous, and the agent wired that up without me describing the synchronization at all.

What struck me was how little I had to specify. I described the outcome I wanted, not the mechanism, and the plugin filled in the reactive plumbing that makes the outcome work. I did not write a subscription, I did not define a fan-out strategy, and I did not reason about how cursor updates would reach other clients. The agent produced a backend where those concerns were already handled, which is the whole appeal of pairing a reactive backend with a coding agent, since the reactive part is precisely the part that is tedious to hand-roll.

The plugin can do this because it ships the agent specialized tools for Convex, similar in spirit to the portable agent skills Convex uses to teach AI agents how to perform specific backend tasks. The agent is not guessing at Convex APIs, it is working from instructions designed for the platform, which is why the generated code looked like Convex code a person would write rather than a generic approximation of it. I read through what it produced, and it used Convex's query and mutation patterns the way the documentation recommends, not the way an agent improvising from first principles would.

I do not want to imply the output was flawless, because I only built one app and one app is not a representative sample. But the code was coherent, it ran, and it did the real-time thing it was supposed to do on the first try, which is more than I expected from a single prompt against a new plugin. If the rest of my testing had been disappointing, that first run alone would have kept me curious.

Deploying with Static Hosting

You can deploy a Convex app built this way by asking the agent to add static hosting. I prompted it to host the dev deployment and give me a shareable live URL, and it added the static hosting component and returned a link. That closed the loop from a local build to something I could send to someone else, which is the moment a project stops being a private experiment and becomes a thing other people can touch.

This step matters because building the app is only half the goal. Shipping a URL you can share is what makes the workflow useful in practice rather than a demo that lives only on your machine, since a real-time app that nobody else can open is a real-time app with nothing to sync against. The collaborative drawing board only proved it worked once I opened the shared URL in a second window and watched the cursors move together, and that proof depended on having a URL to open in the first place.

I will note that I hosted the dev deployment rather than standing up a separate production deployment, because my goal was to share a working link quickly rather than to ship something durable. That is the right move for a demo and the wrong move for an app you intend to keep, so treat the static hosting step as the start of a deployment story rather than the end of one. The plugin got me to a shareable link in a single prompt, which was exactly what I wanted at that stage, and the path from there to a production-grade setup is a separate decision you make when the app earns it.

The broader point is that the deploy step fit the same shape as everything else in the workflow. I described the outcome, the agent did the wiring, and I got back a concrete artifact, in this case a URL, rather than a list of steps to perform myself. That consistency is part of what makes the workflow feel coherent, because you are not switching mental models between building and shipping.

Adding Convex to an Existing App

The plugin is not only for greenfield projects. You can point it at an app you already have and convert it into a synced, multi-client experience. This retrofit path is the one most readers will care about, since most of us have existing apps rather than blank slates, and a tool that only works on new projects is a tool you reach for far less often than one that works on the code already on your disk.

The retrofit case is also the harder test, because converting an existing app means the agent has to understand the code that is already there before it can add a backend to it. A greenfield build starts from nothing, so the agent controls every assumption. A retrofit has to fit into assumptions someone else, or an earlier version of you, already made, and that is where a tool that does not understand the target backend tends to produce something that almost works.

The Client-Side To-Do List I Started With

I started with a plain client-side to-do list. It held state in the browser and nothing more, so a change made in one browser never showed up in another. There was no shared backend, which is exactly the limitation Convex is meant to remove, and it is a limitation that is easy to ship by accident, since a browser-only to-do list looks complete right up until a second person opens it. The app worked perfectly for one user on one device and fell apart the instant you expected it to be shared, which is the most common way a quick prototype reveals it was never actually finished.

I chose a to-do list on purpose, because it is the canonical small app and because its limitation is obvious. Everyone understands what a to-do list should do, everyone understands why state trapped in one browser is a problem, and nobody has to squint to see whether the retrofit worked. If the items synced across browsers, the conversion succeeded, and if they did not, it failed, with no ambiguity in between.

Converting It to a Synced, Multi-Client App

I prompted @convex to make the to-do list collaborative, and it added a Convex backend that synced to-dos across clients in real time. After the change, a to-do added in one browser appeared in another without a manual refresh, which is the exact behavior the original app lacked and the exact behavior that turns a private list into a shared one. I did not have to reload, I did not have to poll, and I did not have to reason about how the update would travel between clients, because the reactive backend handled the propagation the moment the data changed.

The retrofit took the same single-prompt shape as the greenfield build, which is the point. You describe the outcome, invoke the plugin, and let it wire up the backend, whether you are starting from nothing or from an app that already has a shape. That symmetry is more reassuring than it might seem, because it means you do not have to learn two workflows, one for new projects and one for old ones. The mental model is identical, and only the starting code differs.

I will hedge here in the same way I did with the drawing app. I converted one small, well-understood app, and a to-do list is about as friendly a retrofit target as exists. A larger app with more entangled client state would be a harder test, and I would expect the conversion to need more back-and-forth than a single prompt. But the fact that the simple case worked cleanly, with the same workflow as the greenfield build, is a genuine signal, and it is the signal that makes me want to point the plugin at something more complicated next.

What This Does and Doesn't Do Yet

The Convex Codex plugin is new, and the integration is early. The most important constraint today is the one I keep returning to, which is that you have to invoke the plugin explicitly with @convex, because it will not pick up Convex from a plain prompt on its own. I am repeating this on purpose, since it is the single piece of operational knowledge that determines whether your first session goes smoothly or leaves you debugging an app that was never connected to a backend.

It is worth being honest about what I have and have not verified. I built one greenfield app and retrofitted one existing one, both of them small, and both of them worked. That is encouraging, but it is two data points, not a stress test, and I would not extrapolate from my session to a claim about how the plugin behaves on a large, messy codebase. When I say the workflow is consistent and the output was coherent, I mean within the scope of what I actually ran, and you should weight it accordingly.

I expect this will improve over time as the plugin matures, and the capability surface is likely to grow, since that is the usual trajectory for a first-party integration that the maintainers are actively building. It is hard to know exactly which rough edges will get smoothed first, and I would rather say that plainly than pretend I can predict the roadmap. The explicit invocation requirement is the kind of friction that often disappears as a tool matures, but I have no inside knowledge that it will, so I am treating it as a present-tense fact rather than a temporary one.

For now, treat the explicit invocation as a required habit rather than a nice-to-have. Knowing that one detail is the difference between a clean real-time build and a confusing result where nothing syncs, and it is cheap to internalize, since it costs you four characters at the start of a prompt. Everything else in the workflow rewarded a light touch, where I described outcomes and the agent handled mechanism, but the invocation is the one place where the tool needs something explicit from you, and it does not warn you when you forget.

Frequently Asked Questions

Q: How do I install the Convex plugin in Codex? A: Install it from the Codex app UI by opening the Plugins panel, searching for "Convex," and adding it, or from the terminal by typing /plugins and installing Convex from there. Either way, you complete a one-time authentication the first time you connect, and after that the plugin stays connected across sessions.

Q: Do I have to type @convex, or will Codex use Convex automatically? A: You have to type @convex. I tested a plain prompt without it, and the plugin was not used, so the agent built something without the Convex backend. Including @convex is what tells Codex to bring the Convex tooling into the task, and there is no warning when you leave it out, which is why forgetting it produces a confusing result rather than an obvious error.

Q: Can I add Convex to an existing app with the Codex plugin? A: Yes. I started with a client-side to-do list that had no shared backend, prompted @convex to make it collaborative, and the plugin added a Convex backend that synced to-dos across clients in real time. The retrofit followed the same single-prompt shape as building a new app, so you do not have to learn a separate workflow for existing projects.

Q: Can I deploy an app built with the Convex Codex plugin? A: Yes. You can prompt the agent to add the static hosting component, which hosts the dev deployment and gives you a shareable live URL. I hosted a dev deployment to share a link quickly, which is the right move for a demo, so treat it as the start of a deployment story rather than a production-grade setup.

Q: What can I build with the Convex Codex plugin? A: Real-time, multi-client apps. From a single prompt I built a collaborative drawing app with live sync and shared cursors, and I converted a static to-do list into a synced one. Both worked within the scope of what I tested, which was two small apps rather than a large or entangled codebase, so weight that accordingly when you plan something bigger.

Where the Convex Codex Plugin Goes From Here

The Convex Codex plugin gives you a direct path from an AI prompt to a real-time, full-stack app, whether you are starting fresh or upgrading an existing project. The workflow is consistent across both cases, since you install the plugin, invoke it with @convex, describe the outcome, and let it wire up the backend, then add static hosting when you are ready to share. The integration is early, so expect it to grow, but the core build-and-retrofit loop already works today, at least on the small apps I ran it against.

If I had to name the single thing that makes the plugin worth trying, it is that the reactive parts of the backend are exactly the parts you do not have to think about. Shared cursors, live-syncing to-dos, real-time fan-out across clients, these are the features that are tedious to hand-roll and easy to get subtly wrong, and they are the features the plugin handled without me specifying the mechanism. That is the combination the integration is selling, an agent that produces Convex-shaped code and a backend whose hardest parts come for free, and in my testing the combination held up.

Install the Convex plugin in Codex and build your first real-time app, then keep the full integration documentation for Codex handy for the deeper configuration details you will want once you move past a first run. If you are new to the platform, you can start a free Convex project and have a backend ready before your next prompt, which is the fastest way to find out whether this workflow fits the way you already build.