Skip to main content
The Gainable plugin for OpenAI Codex brings the same build-and-refine experience to Codex. Describe what you want and Codex runs the right gaia commands, forwarding any questions back to you in chat.

​
Prerequisites

Install and authenticate the CLI first (the plugin drives it): 
npm i -g "@gainable.dev/cli"
gaia login --key gak_xxx_yyy
See Install the CLI for details.
Unlike Claude Code, Codex plugins don’t ship a binary on your PATH — that’s why the gaia CLI is installed separately from npm. Both plugins share the exact same package.

​
Install the plugin

1

Add the Gainable marketplace

codex plugin marketplace add gainable-inc/cli
codex plugin marketplace list
Confirm a gainable marketplace appears in the list.
2

Install the plugin

codex plugin add gainable@gainable
Or interactively: run /plugins inside a Codex session, find gainable under the marketplace you just added, and install it there.
To refresh after an update, run codex plugin marketplace upgrade. To uninstall later, run codex plugin remove gainable@gainable.

​
Use it

1

Open a project folder

mkdir my-app && cd my-app
gaia init     # pick a project, or skip this for a brand-new build
codex
2

Invoke the skill

Type @ or $ to bring up the gaia and gaia-code skills, or just describe your task and Codex selects the right one:
  • “List my Gainable apps”
  • “Add a probability column to the deals table”
  • “Build me a CRM for tracking SaaS deals”
3

Answer any questions

When the harness needs a decision, Codex presents the options as a numbered list in chat — reply with the number or the option name and it continues.

​
Skip the approval prompts

Codex asks before running each new gaia subcommand outside its sandbox (the CLI talks to the Gainable server, so it needs network access). Choosing always allow in the TUI only allows that exact subcommand — you’d be prompted again for the next one. Usually you don’t have to do anything: gaia init (and the auto-init in gaia build) seeds a project-scoped .codex/rules/gaia.rules that allows every gaia command in that workspace. Codex loads it once you trust the project. To allow gaia globally instead, add the same prefix rule to ~/.codex/rules/default.rules (create the file if it doesn’t exist): 
prefix_rule(
    pattern = ["gaia"],
    decision = "allow",
    justification = "Gainable harness CLI - safe HTTP calls to build.gainable.dev",
)
Restart Codex to pick it up, and verify with: 
codex execpolicy check --rules ~/.codex/rules/default.rules -- gaia apps list
Rules match command prefixes and the most restrictive decision wins. Codex splits compound shell commands and evaluates each part separately, so a broad gaia allow can’t be used to smuggle other commands past approval — gaia build && rm -rf / still prompts.

​
How Codex differs from Claude Code

Same harness, same CLI, same two modes — only the agent’s interface differs:
Claude CodeCodex
Invoke a skillSlash commands (/gainable:*)Type @ or $, e.g. @gaia
Forwarding harness questionsAskUserQuestion pickerNumbered list in chat
Build progressLive task listPlain-text stage updates
Getting the gaia binaryFrom npm (@gainable.dev/cli)From npm (same package)
Codex requires you to approve plugin hooks before they run, so the project-orientation hook won’t fire until you trust it. That’s expected — the skills re-state your project context themselves, so nothing breaks if it doesn’t run.

​
Asking Codex to write the code itself

By default Codex uses chat mode, where the Gainable harness does the work. To have Codex hand-write the app code with the same validators the Build Agent uses, opt in explicitly:
“Code the sponsors view yourself with a hero KPI section.”
Phrases like “code it yourself” or “without the harness” switch Codex to code mode (gaia code): it pulls a local mirror of your app, edits files, validates, and pushes. See code mode in the command reference.

​
Next steps

Command reference

Every gaia command behind the plugin.

Claude Code plugin

The same experience in Claude Code.