> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gainable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex plugin

> Build and refine Gainable apps from inside OpenAI Codex

The Gainable plugin for [OpenAI Codex](https://developers.openai.com/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):

```bash theme={null}
npm i -g "@gainable.dev/cli"
gaia login --key gak_xxx_yyy
```

See [Install the CLI](/cli/installation) for details.

<Note>
  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.
</Note>

## Install the plugin

<Steps>
  <Step title="Add the Gainable marketplace">
    ```bash theme={null}
    codex plugin marketplace add gainable-inc/cli
    codex plugin marketplace list
    ```

    Confirm a `gainable` marketplace appears in the list.
  </Step>

  <Step title="Install the plugin">
    ```bash theme={null}
    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.
  </Step>
</Steps>

<Tip>
  To refresh after an update, run `codex plugin marketplace upgrade`. To uninstall later, run `codex plugin remove gainable@gainable`.
</Tip>

## Use it

<Steps>
  <Step title="Open a project folder">
    ```bash theme={null}
    mkdir my-app && cd my-app
    gaia init     # pick a project, or skip this for a brand-new build
    codex
    ```
  </Step>

  <Step title="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"
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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):

```python theme={null}
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:

```bash theme={null}
codex execpolicy check --rules ~/.codex/rules/default.rules -- gaia apps list
```

<Note>
  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.
</Note>

## How Codex differs from Claude Code

Same harness, same CLI, same two modes — only the agent's interface differs:

|                              | Claude Code                    | Codex                         |
| ---------------------------- | ------------------------------ | ----------------------------- |
| Invoke a skill               | Slash commands (`/gainable:*`) | Type `@` or `$`, e.g. `@gaia` |
| Forwarding harness questions | `AskUserQuestion` picker       | Numbered list in chat         |
| Build progress               | Live task list                 | Plain-text stage updates      |
| Getting the `gaia` binary    | From npm (`@gainable.dev/cli`) | From npm (same package)       |

<Note>
  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.
</Note>

## 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](/cli/commands#code-mode-gaia-code).

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="terminal" href="/cli/commands">
    Every `gaia` command behind the plugin.
  </Card>

  <Card title="Claude Code plugin" icon="robot" href="/cli/claude-code">
    The same experience in Claude Code.
  </Card>
</CardGroup>