Karmas Coder connects to the local Codex CLI. OpenAI owns authentication, account limits, models, and provider behavior; Karmas Coder wraps the session in a durable task with terminals, browser tools, diffs, worktrees, approvals, and Git delivery.

Install

OpenAI provides native installers for macOS, Linux, and Windows. Package-manager options include:

npm install -g @openai/codex

brew install --cask codex

Karmas Coder looks for the codex executable. Verify it after installation:

codex --version

Authenticate

Run Codex and choose the authentication path for your account:

codex

For ChatGPT-backed access, select Sign in with ChatGPT. Codex can also use an API key or a custom model provider configured in its own config.toml.

You can start the explicit login flow with:

codex login

Check the current state with:

codex login status

When Codex is configured to use a non-OpenAI model provider, authentication may be supplied through that provider’s environment variables instead of codex login.

Verify

From a fresh terminal:

codex --version
codex login status

Then start Codex in a disposable repository and ask it to inspect the project without making changes. Resolve CLI or account errors there before debugging Karmas Coder.

Connect to Karmas Coder

Enable Codex

Open Karmas Coder provider settings and confirm that Codex is detected.

Confirm the binary

Karmas Coder uses codex by default. Set a custom binary path only when you intentionally maintain another installation.

Inspect models and reasoning

Refresh the provider and confirm that the model picker reflects the current Codex catalog and reasoning options.

Run a small task

Start with a clean repository and a bounded objective. Review permissions and the working environment before sending the first turn.

Capabilities in Karmas Coder

Codex sessions can expose:

Model and reasoning-effort selection
Plan and execution behavior
Command, tool, and file-change events
Approval requests and user input
Session resume and reconnect behavior
Context and usage information where available
Native steering of a running turn
Codex-specific account and version health checks

Native steering lets Karmas Coder deliver a follow-up to a supported active Codex turn without cancelling it first. It does not bypass Codex permissions or guarantee immediate action.

Karmas Coder discovers Codex behavior from the installed CLI. A newer CLI may expose capabilities that an older build does not.

Configuration

Codex keeps its own configuration, normally under ~/.codex/config.toml or $CODEX_HOME/config.toml.

Changing the Codex model provider, authentication environment, sandbox rules, or approval settings can change what Karmas Coder sees. Keep provider configuration in Codex rather than duplicating secrets in Karmas Coder.

Updating

Update through the installation method you used:

npm install -g @openai/codex@latest

or:

brew upgrade --cask codex

Restart Karmas Coder after updating.

Troubleshooting

Codex is not detected

Run codex --version in a fresh terminal.
Check whether multiple codex binaries exist on PATH.
Remove or correct an obsolete custom binary path in Karmas Coder.
Restart Karmas Coder after installation or shell-profile changes.

Karmas Coder reports that Codex is not authenticated

Run codex login status, then codex login if needed. For a custom model provider, verify its required environment variables and Codex configuration instead.

Authentication check reports `url is not supported for stdio`

This is a configuration error: the same MCP server has both HTTP and stdio settings. Karmas Coder rebuilds its saved, managed gateway entry with only its HTTP settings when checking Codex or starting a session. Authentication checks run from the prepared Codex home so the desktop's working directory cannot add a conflicting project configuration. Your original Codex configuration and other MCP servers remain unchanged. If codex login status also fails outside Karmas Coder, correct the conflicting transport settings in that Codex configuration.

Models or reasoning options differ

Check the selected Codex installation, account, CLI version, and config.toml. Karmas Coder does not invent model access beyond what the runtime reports.

A new Codex feature is missing

Update the CLI and start a new session. Existing sessions may retain capabilities negotiated when they were created.

Default model and startup recovery

Karmas Coder 0.8.4 uses GPT-6 Astra as the default Codex model for a fresh selection. Existing saved model choices remain available. Its supported effort ladder runs from Low through Ultra, with Medium as the default; actual availability still comes from your Codex runtime and account.

After a confirmed startup failure, correct the reported provider problem and retry from the composer. Preserve any existing working-tree changes when restarting a provider session.

Official documentation

Continue with Your first task or Provider handoffs.

Questions, favorites and banked resets in 0.9.0

Supported Codex sessions can ask non-blocking questions: answer the card while the task continues. Blocking multiple-choice questions can be cancelled. Question behavior depends on the request type; a non-blocking card is not a reason to ignore a required approval.

The model picker uses current Codex discovery and supports starred model-and-effort presets. Unsupported settings are normalized to the provider's available options. Resuming a session avoids requesting duplicate history.

Usage panels show banked reset credits when the account exposes them. Use reset asks for confirmation and spends one existing credit only after rechecking the account and limits. A five-hour or weekly limit must have 10% or less remaining. If a result is unconfirmed, Retry reset checks the same attempt rather than starting a new redemption.

Import local Codex projects to bring existing conversations into Karmas Coder. Computer Use beta is available on macOS.