Band Band

Codex

Codex is one of the three coding agents Band ships out of the box. Band uses the @openai/codex-sdk Node SDK, which wraps the standalone codex CLI binary and exchanges JSONL events over stdin/stdout. The adapter exposes cost tracking, session listing, mode switching, and model selection.

Prerequisites

  1. Install the Codex CLI binary so codex is on your PATH (Band runs which codex at construction time to resolve it).
  2. Authenticate with your OpenAI account using the Codex CLI's normal sign-in flow.
  3. Verify the binary works: codex --version.

On first launch Band detects codex automatically and adds an entry to the codingAgents setting. You can override the path or the model from Settings if you have a custom build.

Modes

The Codex adapter exposes two modes that map onto the SDK's sandbox setting:

  • edit — sandbox: workspace-write. The agent can read, edit files, and run commands in the worktree.
  • plan — sandbox: read-only. The agent browses files in read-only mode for planning passes.

Models

Band ships a hardcoded list of GPT-5-family models that the Codex CLI supports (gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex, gpt-5.2-codex). All of these cap at a 400k-token context window inside the Codex CLI tier. Selecting a model from another provider (e.g. a Claude model) is silently ignored — the adapter falls back to Codex's default.

Session Listing & Resume

Codex stores session transcripts under ~/.codex/sessions/. Band reads that directory to populate the session list per workspace and exposes getSessionMessages for paging through history. Sending a message with an existing sessionId resumes the thread via codex.resumeThread(), so Band continues the conversation in context.

Skills

The adapter discovers skills in three locations and merges the lists, with later sources overriding earlier ones:

  • ~/.codex/skills/.system/ — built-in skills shipped with Codex.
  • ~/.codex/skills/ — user-global skills.
  • <workspace>/.codex/skills/ — project-local skills.

Cost Tracking

Codex emits per-turn token usage on the turn.completed event. Band accumulates input, output, and reasoning-output tokens per session into a process- local LRU map (capped at 500 sessions) so totalProcessedTokens stays monotonic across multiple runSession calls in the same Codex thread. The cumulative counts are reset when the server restarts.

Configuration Options

  • model — Default model id. Per-message overrides are accepted but ignored if the value isn't a known Codex model.
  • executablePath — Path to the codex binary if it isn't on PATH.
  • maxTurns — Maximum number of agentic turns per session.

Differences vs Claude Code

  • No interactive tool prompts. The Codex SDK does not surface user-input requests, so all tool calls are auto-approved within the chosen sandbox.
  • No PreToolUse hooks. Codex doesn't have a hook system, so the "needs attention" status flip that Claude Code uses for AskUserQuestion / ExitPlanMode doesn't apply here.
  • Process-local cumulative cost. Token totals are per-process and not durable across server restarts.