Codex Studio is a local image studio. You create, review, and organize AI images with your Codex/ChatGPT login.

Project site · Source and issues

The app runs on your machine. The UI is React/Vite. The API is Bun/Hono. Each image job can use either ChatGPT HTTP (GPT Image 2.5 Flare, GPT Image 2.5 Sunburst, or GPT Image 2 when available) or codex app-server; when both are ready, the Studio execution selector keeps both routes available.

The main Codex path does not need OPENAI_API_KEY. Assets, job history, logs, and SQLite state live in your Studio Library, not in this repo.

• Generate and edit images in the studio UI.
• Browse workspaces, recipes, recent jobs, and assets in one place.
• Keep job history and catalog metadata in local SQLite.
• Use Codex first. Optional Grok Imagine, Google Nano Banana, and Antigravity providers stay behind the backend.
• Keep local assets out of git.

Product tour

Create pairs a freeform text/image workspace and composer on the left with compact recipe cards on the right. Library focuses on search and review; using an image as a reference opens Create. Each recipe keeps a separate draft per workspace, with a central preview and a right configuration panel. On narrow windows, Result and Configure tabs share the space. Styles and Character Lab open their explorers on demand. Use a result as a reference or reuse its settings to continue explicitly.

Library search queries the whole workspace catalog. Jobs separates active work, results needing review, and history; the inspector shows returned images before technical details. Animation frames show linked job status separately from attached frames. Sprite Atlas labels fixture checks separately from validation of imported art.

Catalog and persistent jobs	Studio Settings
Guided recipes	Style systems

Quick start

You need:

• Bun on PATH. Install it yourself from https://bun.sh/docs/installation. Codex Studio never silent-installs Bun.
• Codex CLI from https://github.com/openai/codex
• Codex CLI with codex login for the local app-server route.
• Optional ChatGPT subscription login through Studio Settings Sign in for the HTTP route. That login is not bundled.
• A modern browser

The first-run surface is a detect, consent, mutate, stream, re-validate loop. One primary button follows this order:

1. Missing Bun: open the official Bun installer.
2. Missing Codex CLI and no Studio ChatGPT Sign in: open the Codex install docs.
3. ChatGPT login missing: Sign in from Studio Settings, or open a visible codex login terminal.
4. Studio Library or Bootstrap Configuration missing: in-app Setup, or bun run studio:onboard --setup.
5. Everything else ready except Codex Product Runtime, and Studio ChatGPT Sign in is not ready: Start app-server.
6. Ready: Open Studio.

Ask Codex is an extra path when Codex CLI exists. Copy prompt stays a fallback. Optional providers are separate backend rows, not Studio installers.

The default Studio Library is a folder named Codex Studio in your user home. Existing STUDIO_LIBRARY_DIR is kept. The app does not auto-migrate AI-Studio-Library. New generations go under outputs/<workspace>/ inside that library.

Portable zip: double-click Codex Studio.bat on Windows or Codex Studio.command on macOS. Read PORTABLE.txt. If STUDIO_LIBRARY_DIR is unset, portable start uses Codex Studio Library beside the unpacked folder. Linux is best-effort. Electron is a development shell, not this user channel.

To use Grok Imagine:

1. Sign in with xAI from Studio Settings, or install Grok Build and run grok login.
2. XAI_API_KEY in .env.local also works on the same HTTP path.
3. Make sure that bun run providers:preflight -- --provider=grok reports canAttempt=true.

To use Google Nano Banana directly:

1. Set GOOGLE_API_KEY or GEMINI_API_KEY to a restricted Gemini key; or enable the Generative Language API, create a Desktop app OAuth client, and set GOOGLE_OAUTH_CLIENT_ID plus GOOGLE_CLOUD_PROJECT_ID.
2. For OAuth, add your account to the consent-screen test users when the app is still in testing, then connect Google from Studio Settings. GOOGLE_OAUTH_CLIENT_SECRET is optional.
3. Confirm that bun run providers:preflight -- --provider=google reports canAttempt=true.

Direct requests use the Interactions API and current Nano Banana models. An API key takes priority over OAuth. OAuth requests charge quota to GOOGLE_CLOUD_PROJECT_ID. Studio requests store: false, but Google's service terms and account controls still apply.

To use Nano Banana through Antigravity:

1. Install the official agy CLI, open it interactively once, and complete its Google authentication.
2. Run agy models, then confirm that bun run providers:preflight -- --provider=antigravity reports canAttempt=true.
3. Select Antigravity in Studio. Its model setting chooses an Antigravity reasoning model; Nano Banana runs behind the CLI as the generate_image tool.

Studio never reads or copies Antigravity credentials. It runs one sandboxed headless conversation in a temporary workspace, imports one validated image, and leaves Antigravity's own artifact history in place.

Studio stores xAI, Google, and ChatGPT OAuth tokens in the current user's private app-data folder, separate from the portable or shareable Studio Library and never in SQLite. Grok Build and Antigravity keep their own CLI login state. Provider API keys stay in the backend environment. Home and the Styles recipe support Codex, Grok, Google, and Antigravity. Styles can generate from a prompt or from managed library references. Codex stays the first default provider.

App readiness is the source of truth. Bun and Codex version strings are only diagnosis. If the Codex path or app-server support is unclear, run bun run runtime:doctor.

Do not set STUDIO_CODEX_CLI_PATH to a node_modules/.../vendor binary. Use a supported launcher such as the desktop binary or codex.cmd.

Fast path: ask Codex in this repo to run first setup, or use Copy prompt / Ask Codex on the onboarding surface. That prompt points at skills/codex-studio-setup/SKILL.md.

Set up Codex Studio for first run.

Manual path:

bun install
bun run studio:onboard --setup
bun run studio:init
bun run dev

Then open:

• UI: http://localhost:17222
• Local API health: http://localhost:17223/api/health

First minute

1. Start the app with bun run dev.
2. Make sure that the toolbar shows the local backend and the Codex session as ready.
3. Choose a workspace or create one.
4. Open Recipes for guided workflows, or stay in Studio for direct prompts.
5. Generate. Then review results in the grid and the queue.

Settings

Run bun run studio:init to create local defaults and apply pending SQLite migrations. The command is safe to run again. It does not replace an existing Studio Library.

For manual setup, copy .env.example to .env.local.

Worker capacity is configured on the host and takes effect after a server restart. STUDIO_MAX_CONCURRENT_JOBS is the global ceiling (default 4, range 1–16). Each STUDIO_MAX_CONCURRENT_<PROVIDER>_JOBS value limits that provider (default 1, no higher than the global ceiling). The Codex-named setting now controls only Codex; set the global variable explicitly when updating an older checkout. Invalid limits stop startup. Jobs separates Active, Review, and History, with a workspace filter for each view. Active contains only queued and running jobs; jobs needing review stay in Review and do not appear as loading images in the gallery. Batch progress and retry are available within each job, and Worker details shows active slots and provider limits. Queued jobs show why they are waiting. Available providers take turns; jobs within one provider keep their arrival order. Cancellation and asset import retain their slot until processing finishes.

By default, the Studio Library lives under your OS home directory as Codex Studio. Set a custom absolute path only when you need one:

# Windows
STUDIO_LIBRARY_DIR=C:\Users\<your-user>\Codex Studio

# macOS
STUDIO_LIBRARY_DIR=/Users/<your-user>/Codex Studio

# Linux
STUDIO_LIBRARY_DIR=/home/<your-user>/Codex Studio

Preferred Output Path in Settings is an External Output Source scan hint. Generate still writes inside the Studio Library.

If you use optional external adapters, keep Provider Secrets in backend environment variables. Do not put them in SQLite, logs, screenshots, docs, or committed files.

Grok Build CLI login stays under GROK_HOME. Antigravity owns its CLI login and artifacts. Studio Sign in tokens stay in the current user's private app-data folder.

Use the provider control in the top Command Center to switch the next image job between Codex, Grok, Google, and Antigravity. The control shows runtime readiness. It stores the choice in Studio Settings. Deeper diagnostics stay in the same menu. Codex stays the initial default.

Useful commands

bun run dev
bun run runtime:doctor
bun run providers:preflight
bun run studio:onboard
bun run studio:init
bun run check
bun run test
bun run build
bun run validate:fast
bun run validate
bun run validate:release

In VS Code, run the same commands from Terminal -> Run Task. Daily tasks start with 🚀 dev, 🧪 test, 🔍 check, and 🏗 build. Setup and infrequent tasks (🧱 init, 📦 deps, 🛡 release, 🔌 providers) sit later in the list.

Maintenance:

bun run storage:audit
bun run storage:compact
bun run storage:thumbnails:backfill
bun run tooling:logs:prune

Documentation

• Agent rules
• Dependencies
• Troubleshooting
• Portable launch
• Electron development shell
• Style preset authoring
• Contributing
• Security

Status

Codex Studio is in open-source preview.

• Local development is documented and works.
• The default path is Codex-first and local-first.
• Optional provider adapters are backend integrations, not the product center.
• Grok Imagine image generation and managed local image edits use Studio Sign in, XAI_API_KEY, or Grok Build CLI login.
• Google Nano Banana uses the Interactions API through a restricted API key or Studio-owned desktop OAuth. Antigravity is a separate local CLI path and never supplies Google credentials to Studio.
• Native video is a later media-domain decision.
• Desktop packaging is not the user channel. Use the browser plus portable launchers, or bun run dev in a checkout.

---

• For technical detail, read the docs folder.
• For feature requests, open an issue or a pull request.
• If this project is useful, star it or become a sponsor.

---

Support the further development of this tool 🤍