coreweave/forge-agent-lens-for-codex

coreweave/forge-agent-lens-for-codex

Description: CoreWeave Forge Agent Lens for OpenAI Codex

Language: TypeScript

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 1

Created: 2026-09-30T00:32:41Z

Pushed: 2026-10-09T00:42:19Z

Default branch: main

Fork: no

Archived: no

README:

Forge Agent Lens for Codex


CoreWeave Forge Agent Lens integration for the OpenAI Codex CLI that traces agent turns, model calls, token usage, and tool calls.

When a turn finishes, a Codex Stop hook starts a detached collector, so tracing does not block Codex. The collector reads the Codex rollout file and sends the turn to Agent Lens as one trace. Turns from the same Codex session share a conversation ID, so Agent Lens shows them as one conversation.

> [!WARNING] > Content capture is on by default. Prompts, assistant output, reasoning, tool > arguments and results, and the working directory are sent to Agent Lens. See > [Content capture](#content-capture) to leave them out.

Requirements

• macOS or Linux
• Node.js 20.6 or newer
• A current Codex CLI with hooks and rollout logging enabled
• A W&B API key and an Agent

Lens project in entity/project form

codex --ephemeral is not supported because it does not write a rollout file.

Install

Install the package, set your project and API key, then install the hook:

npm install --global @coreweave/forge-agent-lens-for-codex
export FORGE_TRACE_PROJECT=/
export WANDB_API_KEY= # or use `wandb login`
forge-agent-lens-for-codex install

Review and enable the new hook with /hooks in Codex. For a one-off automation run, Codex also supports --dangerously-bypass-hook-trust.

install records the existing rollouts as already exported, so history from before installation isn't uploaded. Use [collect --all](#headless-runs-and-explicit-collection) to backfill it deliberately.

Configuration

| Setting | Environment variable | settings.json key | Default | | ------------------ | ----------------------------- | ------------------- | ----------------------- | | Agent Lens project | FORGE_TRACE_PROJECT | project | required | | W&B API key | WANDB_API_KEY | not stored | matching .netrc entry | | Provider name | FORGE_CODEX_PROVIDER_NAME | provider_name | openai | | Include content | FORGE_CODEX_INCLUDE_CONTENT | include_content | true | | Debug logging | FORGE_CODEX_DEBUG | debug | false |

Forge SDK owns trace-server resolution and transport. Use WANDB_BASE_URL for a custom W&B deployment or WF_TRACE_SERVER_URL for an explicit trace-server override. When resolving .netrc, forge-agent-lens-for-codex looks up api.wandb.ai by default or the host (including a custom port) from WANDB_BASE_URL.

State, settings, and the collector log live under ~/.forge-agent-lens-for-codex/. Set FORGE_CODEX_HOME only for isolated development or test environments.

Content capture

Set FORGE_CODEX_INCLUDE_CONTENT=false to omit the content listed above. Spans keep model names, token usage, timing, tool names, call IDs, and MCP server names. This package does not perform PII scrubbing or semantic redaction.

For interactive Stop-hook collection, set include_content to false in ~/.forge-agent-lens-for-codex/settings.json. A variable set only on the codex client command may not reach hooks run by an already-running Codex app server. The environment of the hook process takes precedence over the settings file, so leave FORGE_CODEX_INCLUDE_CONTENT unset there or set it to false before sensitive turns. The environment variable is reliable for explicit forge-agent-lens-for-codex collect.

What gets traced

Each turn becomes one trace:

invoke_agent codex the turn, from your prompt until Codex stops
├─ chat each model call, with token usage
└─ execute_tool each tool call and its result

Spans use the standard OpenTelemetry GenAI (gen_ai.*) attributes and are timed from the rollout's timestamps. Successful exports advance a per-session cursor, so the same completed turn is never sent twice. If an export fails, the cursor doesn't advance and the turn is retried at the next Stop.

Limitations

• codex mcp, direct app-server/API sessions, aborted turns without a Stop

event, and Windows are not supported.

• Subagent operations appear as tool spans. Their separate rollout files are

not reconstructed as nested traces.

Headless runs and explicit collection

Some codex exec environments do not run the Stop hook. Wrap the command to baseline cursor-less rollout files, run Codex, and collect new work afterward:

forge-agent-lens-for-codex run -- codex exec "fix the failing test"
forge-agent-lens-for-codex run --json -- codex exec "fix the failing test"

The wrapper always returns the wrapped command's exit code. A tracing failure is reported to stderr but does not replace that code.

Existing sessions with cursors may also contain pending turns, so run sweeps them after the command. A pre-existing cursor-less file is never backfilled by the wrapper if it could not be baselined safely.

collect --all is an explicit backfill. A rollout without a cursor is read from offset zero, so this command can send history created before installation:

forge-agent-lens-for-codex collect --all
forge-agent-lens-for-codex collect --all --json

Status, upgrade, and uninstall

forge-agent-lens-for-codex status
forge-agent-lens-for-codex status --json
forge-agent-lens-for-codex uninstall

Status reports only whether an API key resolved; it never prints the secret. Uninstall removes only the forge-agent-lens-for-codex-hook handler and preserves unrelated hook groups and handlers.

The hook records the Node.js and package paths it was installed with. To upgrade, or after switching Node.js versions, reinstall the package and rerun install:

npm install --global @coreweave/forge-agent-lens-for-codex@latest
forge-agent-lens-for-codex install

See the [changelog][changelog] for what changed in each release.

Development

git clone https://github.com/coreweave/forge-agent-lens-for-codex.git
cd forge-agent-lens-for-codex
npm ci
npm run...