OpenAI Codex CLI recipe

The OpenAI Codex CLI executes tasks inside a sandboxed workspace. This recipe ships a ~/.codex/post-task.sh that publishes whatever the agent left in ./out/ (or another agreed-upon directory) and prints the URL back to the agent transcript.

Prerequisites

• The CLI is installed: bv --version works.
• You’ve run bv init --token <token> once (see Authenticate).
• Your Codex tasks emit a directory (out/, dist/, public/).

Recipe: post-task script

#!/usr/bin/env bash
# ~/.codex/post-task.sh — runs after every Codex task.
set -euo pipefail

WS="${CODEX_WORKSPACE:-.}"

# Try a few conventional output directories, fall back to skipping.
for dir in "$WS/out" "$WS/dist" "$WS/build" "$WS/public"; do
  if [[ -d "$dir" ]]; then
    TARGET="$dir"
    break
  fi
done
: "${TARGET:=}"
if [[ -z "$TARGET" ]]; then
  echo '{"ok":true,"published":false,"reason":"no output directory found"}'
  exit 0
fi

bv push --json "$TARGET"

Make it executable: chmod +x ~/.codex/post-task.sh.

Then point Codex at it via your ~/.codex/config.toml:

[hooks]
post_task = "~/.codex/post-task.sh"

(Adjust the key name to match the Codex CLI version you have installed — the hook name has shifted across releases.)

Recipe: inline tool

If you prefer not to ship a hook script, declare a Codex tool the agent can invoke directly:

[[tools]]
name = "publish_preview"
description = "Publish ./out as a private butverify site and return its URL."
command = ["bv", "push", "--json", "out"]

The agent can call it explicitly and use the URL from the JSON response.

Tips

• Each bv push provisions a new site_id. Pin the resulting site (bv pin <site-id>) once you’ve found one you want to keep across retention windows.
• The --json output includes site_id, url, and expires_at — the agent can echo any of those back to the human in subsequent turns.