Flowly
Log inDownload
Docs/Features/Codex Runtime
Features

Codex Runtime

Hand a heavy coding turn to OpenAI's Codex app-server while Flowly stays the shell around it. Opt-in, off by default.

Flowly can delegate a coding turn to the OpenAI Codex app-server instead of running the turn in its own loop. When the codex_session tool is enabled, Flowly spawns the codex CLI as a subprocess, sends the turn to it, and projects Codex's streamed items (commands, file edits, tool calls) back into the conversation inline β€” so it reads as one continuous session.

This is an opt-in tool, disabled by default. It is not a runtime swap: your normal Flowly agent loop is unchanged unless you turn it on.

Codex runs the coding turn, but Flowly stays the shell: sessions, memory, skills, approvals, and the gateway all still belong to Flowly.

Prerequisites

The Codex CLI must be installed and authenticated on the same machine as Flowly:

# Install the Codex CLI
npm i -g @openai/codex

# Authenticate (writes tokens Codex reads on startup)
codex login

Codex auth and Flowly auth are separate β€” codex login is required even if you are signed in to Flowly.

Enabling

Enable the tool from your shell or from a live session:

flowly codex enable      # turn the codex_session tool on
flowly codex status      # show whether it's enabled + codex CLI health
flowly codex disable     # back to Flowly's own runtime

Inside a session you can toggle it with the slash command:

/codex on
/codex off
/codex sandbox <read-only|workspace-write|full-access>
/codex tools on|off

Enabling sets tools.codexSession.enabled to true in ~/.flowly/config.json.

Working directory

Codex runs commands and edits files relative to a working directory. Set it once and it persists:

flowly codex cwd ~/projects/myapp    # set the directory Codex runs in
flowly codex cwd                     # show the current directory

or in a session:

/codex cwd ~/projects/myapp

The directory is stored in tools.codexSession.cwd. When unset, Flowly resolves a directory deterministically (explicit override β†’ per-session value β†’ FLOWLY_CWD β†’ agents.defaults.cwd β†’ your workspace) and passes it to Codex when the thread starts.

Flowly tools inside Codex

Codex ships its own toolset (shell, file edits, planning). To keep Flowly's richer tools available during a Codex turn, Flowly registers itself as an MCP callback (flowly-tools) that Codex can call back into. The callback exposes:

  • web_search
  • web_fetch
  • video_analyze
  • skill_view
  • skills_list

This is controlled by tools.codexSession.exposeFlowlyTools.

Configuration

All keys live under tools.codexSession in ~/.flowly/config.json (camelCase on disk):

KeyWhat it does
enabledTurns the codex_session tool on or off.
codexBinPath to the codex binary (when not on PATH).
codexHomeOverrides CODEX_HOME for the subprocess (Codex state dir).
cwdPersistent working directory for Codex.
turnTimeoutSHard deadline for a single Codex turn (watchdog). Default 600.
postToolQuietTimeoutSWedge timeout after a tool call with no further output. Default 90.
approvalPolicyHow Codex command/edit approvals are handled: on-request (default), never, auto-review, granular.
sandboxCodex sandbox profile for the turn: read-only, workspace-write (default), full-access.
exposeFlowlyToolsRegisters the flowly-tools MCP callback.
Codex runtime requires the

codex CLI at version 0.125.0 or newer; flowly codex enable checks this and the runtime self-heals across the 0.125 item-state format. enable also accepts --sandbox <profile> and --expose-tools to set those two keys up front.

Reliability

A few safeguards keep long Codex turns from hanging:

  • Self-heal on a lost thread. If a resumed Codex thread no longer exists, Flowly drops the dead thread and transparently starts a fresh one rather than erroring.
  • Watchdogs. A hard per-turn deadline (turnTimeoutS) and a post-tool quiet timeout (postToolQuietTimeoutS) stop a stalled turn.
  • OAuth failures are surfaced as a clear "run codex login" message.