From 5095b9043aab380fed1b6354f661bc037ddff2ac Mon Sep 17 00:00:00 2001 From: Nivedit Jain Date: Fri, 24 Jul 2026 12:57:50 +0000 Subject: [PATCH 1/2] docs(agenteye): add Codex session capture page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a public page documenting Codex session capture: what the collector picks up from local OpenAI Codex sessions (CLI, IDE, desktop app), how to turn it on with an events:add API key, and where captured sessions show up. Registered in the en "SDK and CLI" nav group. Value/contract level only — no implementation detail. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NoGWkrsoApuK4RvBmokbM7 --- docs/agenteye/codex-capture.mdx | 53 +++++++++++++++++++++++++++++++++ docs/docs.json | 1 + 2 files changed, 54 insertions(+) create mode 100644 docs/agenteye/codex-capture.mdx diff --git a/docs/agenteye/codex-capture.mdx b/docs/agenteye/codex-capture.mdx new file mode 100644 index 00000000..13d88754 --- /dev/null +++ b/docs/agenteye/codex-capture.mdx @@ -0,0 +1,53 @@ +--- +title: "Codex session capture" +description: "Tail your team's local OpenAI Codex sessions into AgentEye as ordinary sessions and events — with no change to how they run Codex." +--- + +Your engineers already run OpenAI Codex every day. Codex session capture brings those coding sessions into AgentEye as ordinary sessions and events, so you can search, replay, and evaluate them next to everything else you observe. It complements the [Python SDK](/agenteye/python-sdk): the SDK instruments agents you write, while this captures the Codex work your team already does — with no change to how they run it. + +A small background collector reads Codex's local session transcripts as they are written and ships them to AgentEye. One collector per machine captures every local Codex surface at once — there is no per-surface setup. + +--- + +## What it captures + +Every Codex surface that runs **locally** produces the same on-disk session transcripts, and the collector picks up all of them: + +- the Codex **CLI** and `codex exec` +- the **VS Code / IDE extension** +- the **desktop app**, when it runs a session locally + +Each Codex session becomes an AgentEye [session](/agenteye/sessions); its user and assistant messages, reasoning, tool calls, tool results, and token usage become the matching [events](/agenteye/event-stream). The surface each session came from (CLI, IDE, or desktop) is recorded, so you can tell them apart. + +> **Cloud sessions are not captured.** The desktop app increasingly runs sessions in the Codex cloud and keeps only their metadata on the machine — there is no local transcript to read. Only locally-executed sessions are captured. + +--- + +## Turn it on + +Capture is off until you enable it. Install the collector with an API key that has the `events:add` permission (see [API keys](/agenteye/api-keys)), and turn on Codex capture: + +```bash +curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \ + | sh -s -- --key --codex-enabled +``` + +That installs the collector, registers it as a background service, and starts capturing. Confirm it is running: + +```bash +agenteye-collector health +``` + +On first run, your existing Codex sessions are backfilled once and new activity then streams within seconds. Codex's own files are only ever read — never modified, moved, or deleted — and each session is shipped exactly once, even across restarts. + +--- + +## Where it shows up + +Captured sessions appear in **Sessions**, and their events in the **Events** stream, the same as any other agent you observe — so [session replay](/agenteye/sessions), [search](/agenteye/queries), [evaluations](/agenteye/evaluations), and [alerts](/agenteye/alerts) all work on them. Filter by the Codex agent to see them on their own. + +--- + +## Privacy + +Codex transcripts contain the full session — including command output, file contents, and anything Codex read or wrote — and can contain secrets. Captured sessions are shipped as-is, so enable capture only on machines and for teams where centralizing that content in AgentEye is appropriate, and give the collector a key scoped to `events:add` only. See [Security](/agenteye/security) for how your data is kept isolated. diff --git a/docs/docs.json b/docs/docs.json index 3b8e1172..ac1680b8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -64,6 +64,7 @@ "pages": [ "agenteye/python-sdk", "agenteye/python-sdk-skill", + "agenteye/codex-capture", "agenteye/cli", "agenteye/cli-skill", "agenteye/cli-recipes", From ceda9aa0158518a36540b3a7d3795a3778d79070 Mon Sep 17 00:00:00 2001 From: Nivedit Jain Date: Fri, 24 Jul 2026 13:00:16 +0000 Subject: [PATCH 2/2] docs(agenteye): changelog for Codex session capture page (#592) Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NoGWkrsoApuK4RvBmokbM7 --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe083fad..88b10a4a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ - Restore the note explaining why codex is not pinned to a Claude model, which the fix above had deleted along with the line it annotated. The gateway routes Anthropic weighted 1:1 through Bedrock, which 400s on codex's request metadata (#576) — so a Claude-pinned codex probe fails on roughly half its requests, and a coin-flip red in a daily canary is worse than a consistent one. Worth keeping precisely because a single green probe looks like proof that it works. (#591) - Echo the probe's output tail whenever a CLI's verdict is not a clean pass. `run.sh` discarded everything a probe printed except its `VERDICT_JSON` line, so a yellow or red run said *what* broke and never *why*, and re-running produced no more detail because the vendor's error message was thrown away both times — diagnosing the codex regression above needed a full local reproduction purely for want of these twenty lines. Safe in a public log: every credential involved is a registered Actions secret, so GitHub masks it on the way out. (#591) +### Docs +- Add a Codex session capture page for AgentEye: what the collector picks up from local OpenAI Codex sessions (CLI, IDE, desktop app), how to turn it on with an `events:add` key, and where captured sessions show up. Value/contract level only, no implementation detail. (#592) + ## 0.0.14-beta.3 — 2026-07-20 ### Fixes