Codex

Tuneloop captures OpenAI Codex sessions via a SessionEnd hook that backgrounds the upload so it completes within Codex's strict hook timeout.

Hook Configuration

The hook is a SessionEnd entry in Codex's hooks.json that launches tuneloop-ingest upload as a detached background process:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "[ -x \"$HOME/.tuneloop/bin/tuneloop-ingest\" ] && nohup \"$HOME/.tuneloop/bin/tuneloop-ingest\" upload >/dev/null 2>&1 &"
          }
        ]
      }
    ]
  }
}

Codex enforces a 3-second maximum timeout on SessionEnd hooks, so the upload runs detached in the background rather than blocking the hook.

The tuneloop-ingest CLI reads its server URL and token from ~/.tuneloop/config.json:

{
  "server": "https://tuneloop.yourcompany.com",
  "token": "your-ingest-token"
}

Individual Setup

Install the CLI and configure the hook:

curl -fsSL https://tuneloop.yourcompany.com/install.sh | sh -s -- --token YOUR_INGEST_TOKEN
tuneloop-ingest setup --source codex

The setup command:

1. Writes the server URL and token to ~/.tuneloop/config.json
2. Writes the SessionEnd hook to ~/.codex/hooks.json

After setup, every Codex session is automatically uploaded when it ends.

Backfill

To upload existing sessions that predate the hook installation:

tuneloop-ingest backfill --source codex

Options:

• --since 2025-01-01 — only sessions after this date
• --limit 100 — cap the number of sessions
• --dry-run — preview what would be uploaded

Re-running backfill is safe — the server deduplicates on content hash.

Enterprise Rollout

The hook command contains no secrets — it just invokes tuneloop-ingest, which reads credentials from ~/.tuneloop/config.json on the local machine. Rollout has two parts: distributing the hook, and distributing the credentials.

Managed hooks via requirements.toml (recommended)

Codex supports admin-enforced configuration via requirements.toml that cannot be overridden by users. Deploy the hook as a managed requirement:

Create a requirements.toml with the Tuneloop hook and deploy it to the managed location for your platform:

On macOS, you can also deploy via MDM configuration profiles using the com.openai.codex preference domain with the config encoded as base64 in the requirements_toml_base64 key.

Set allow_managed_hooks_only = true in requirements.toml to ensure only managed hooks run, blocking any user or project-level hooks.

Note that Codex distributes the hook configuration but not the scripts themselves — the tuneloop-ingest CLI must be delivered separately via your MDM or configuration management tool.

Distributing the CLI and credentials

Deploy these alongside the managed configuration:

• CLI: install tuneloop-ingest to ~/.tuneloop/bin/
• Config: write ~/.tuneloop/config.json with the server URL and token

Project-level hooks

You can also commit a hooks.json to .codex/ in each repository. The hook file is safe to commit — no secrets are included. Developers still need the CLI and ~/.tuneloop/config.json on their machine.

Note that non-managed hooks require explicit user trust in Codex — each developer will be prompted to review and approve the hook on first use.

Transcript Location

Codex writes session transcripts to ~/.codex/sessions/. Tuneloop groups thread files into logical sessions, folding subagent threads under their root ancestors.