trace-codex plugin

.agents/plugins/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "braintrust-codex-plugins",
+  "interface": {
+    "displayName": "Braintrust Codex Plugins"
+  },
+  "plugins": [
+    {
+      "name": "braintrust",
+      "source": {
+        "source": "local",
+        "path": "./plugins/braintrust-codex-plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer tools"
+    },
+    {
+      "name": "trace-codex",
+      "source": {
+        "source": "local",
+        "path": "./plugins/trace-codex"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Observability"
+    }
+  ]
+}

.github/workflows/ci.yaml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+        working-directory: plugins/trace-codex
+
+      - name: Run tests
+        run: make test

.github/workflows/release.yaml

@@ -0,0 +1,93 @@
+name: Release trace-codex
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release, e.g. 0.2.0 (no leading v)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+env:
+  PLUGIN_DIR: plugins/trace-codex
+  MANIFEST: plugins/trace-codex/.codex-plugin/plugin.json
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Require main branch
+        run: |
+          if [ "${{ github.ref }}" != "refs/heads/main" ]; then
+            echo "::error::Releases must run on main (got '${{ github.ref }}')."
+            exit 1
+          fi
+
+      - name: Validate version format
+        run: |
+          if ! printf '%s' "${{ inputs.version }}" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::Version '${{ inputs.version }}' is not valid semver (expected MAJOR.MINOR.PATCH, no leading v)."
+            exit 1
+          fi
+
+      - name: Set tag
+        id: vars
+        run: echo "tag=trace-codex-v${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+
+      - name: Ensure tag does not already exist
+        run: |
+          if git rev-parse "refs/tags/${{ steps.vars.outputs.tag }}" >/dev/null 2>&1; then
+            echo "::error::Tag ${{ steps.vars.outputs.tag }} already exists."
+            exit 1
+          fi
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: latest
+
+      - name: Update plugin manifest version
+        run: |
+          tmp="$(mktemp)"
+          sed -E 's/("version"[[:space:]]*:[[:space:]]*")[^"]*(")/\1${{ inputs.version }}\2/' "$MANIFEST" > "$tmp"
+          mv "$tmp" "$MANIFEST"
+          echo "Updated $MANIFEST:"
+          grep '"version"' "$MANIFEST"
+          # Fail if the bump did not take (e.g. unexpected manifest format).
+          grep -q '"version": "${{ inputs.version }}"' "$MANIFEST"
+
+      - name: Commit, tag, and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add "$MANIFEST"
+          git commit -m "chore(trace-codex): release v${{ inputs.version }}"
+          git tag "${{ steps.vars.outputs.tag }}"
+          git push origin HEAD
+          git push origin "${{ steps.vars.outputs.tag }}"
+
+      - name: Build release binaries
+        working-directory: ${{ env.PLUGIN_DIR }}
+        run: |
+          bun install --frozen-lockfile
+          # Cross-compiles every target (darwin/linux x arm64/x64) into bin/.
+          bun run build
+          ls -la bin/
+
+      - name: Create GitHub release with autogenerated notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ steps.vars.outputs.tag }}" \
+            --title "${{ steps.vars.outputs.tag }}" \
+            --target "${{ github.sha }}" \
+            --generate-notes \
+            "$PLUGIN_DIR"/bin/codex-hook-darwin-arm64 \
+            "$PLUGIN_DIR"/bin/codex-hook-darwin-x64 \
+            "$PLUGIN_DIR"/bin/codex-hook-linux-x64 \
+            "$PLUGIN_DIR"/bin/codex-hook-linux-arm64

.gitignore

@@ -0,0 +1 @@
+.DS_Store

AGENTS.md

@@ -4,20 +4,34 @@ Guidelines for AI agents working in this repo.
 
 ## Repo purpose
 
-This repo packages the [Braintrust MCP server](https://www.braintrust.dev/docs/integrations/developer-tools/mcp) as a [Codex marketplace plugin](https://developers.openai.com/codex/plugins). The key files are:
+This repo is a monorepo of two independent [Codex marketplace plugins](https://developers.openai.com/codex/plugins):
 
-- `.codex-plugin/plugin.json` — plugin manifest (version, UI metadata, default prompts)
-- `.mcp.json` — MCP server definition
-- `skills/braintrust/` — agent skills exposed through the plugin
+- `plugins/braintrust-codex-plugin/` — packages the [Braintrust MCP server](https://www.braintrust.dev/docs/integrations/developer-tools/mcp) plus a routing skill.
+- `plugins/trace-codex/` — an opt-in plugin that traces Codex sessions to Braintrust (session, turn, and tool spans) via Codex lifecycle hooks. Do **not** merge tracing behavior into the MCP/skills plugin; they are separate, independently installable plugins.
+
+Both plugins are listed as separate entries in `.agents/plugins/marketplace.json` (the repo marketplace).
+
+Key files for the MCP/skills plugin:
+
+- `plugins/braintrust-codex-plugin/.codex-plugin/plugin.json` — plugin manifest (version, UI metadata, default prompts)
+- `plugins/braintrust-codex-plugin/.mcp.json` — MCP server definition
+- `plugins/braintrust-codex-plugin/skills/braintrust/` — agent skills exposed through the plugin
+
+Key files for the tracing plugin:
+
+- `plugins/trace-codex/.codex-plugin/plugin.json` — plugin manifest
+- `plugins/trace-codex/hooks/hooks.json` — lifecycle hook config
+- `plugins/trace-codex/src/` — the hook client + event server (compiled to `bin/codex-hook`)
 
 ## Making changes
 
 - **Skills**: There is only one simple skill in this repo which handles routing and tool definitions, it should not be modified significantly.
-- **MCP config**: edit `.mcp.json` to change the MCP server command or environment variables.
-- **Plugin metadata**: edit `.codex-plugin/plugin.json` for display name, description, brand color, default prompts, etc.
+- **MCP config**: edit `plugins/braintrust-codex-plugin/.mcp.json` to change the MCP server command or environment variables.
+- **Plugin metadata**: edit the relevant `.codex-plugin/plugin.json` for display name, description, brand color, default prompts, etc.
+- **Marketplace**: edit `.agents/plugins/marketplace.json` to change plugin entries, categories, or install policies.
 
 ## Releasing a new version
 
-1. Bump `"version"` in `.codex-plugin/plugin.json`.
+1. Bump `"version"` in the relevant plugin's `.codex-plugin/plugin.json`.
 2. Commit, tag, and create a GitHub release (see README for exact commands).
 3. Do **not** skip the git tag — releases are tracked via tags so users can see a changelog.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Braintrust Data, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,30 @@
+# Root Makefile.
+#
+# Delegates to each plugin's own Makefile so CI only needs to run `make test`
+# here. When a new plugin gains a Makefile, add it to PLUGIN_DIRS below.
+
+SHELL := /bin/bash
+
+PLUGIN_DIRS := plugins/trace-codex
+
+.PHONY: test build clean $(PLUGIN_DIRS)
+
+# Default: run every plugin's `test` target.
+test: $(PLUGIN_DIRS)
+
+# Run `make test` in each plugin directory.
+$(PLUGIN_DIRS):
+	@echo "==> $@"
+	$(MAKE) -C $@ test
+
+build:
+	@for dir in $(PLUGIN_DIRS); do \
+		echo "==> build $$dir"; \
+		$(MAKE) -C $$dir build; \
+	done
+
+clean:
+	@for dir in $(PLUGIN_DIRS); do \
+		echo "==> clean $$dir"; \
+		$(MAKE) -C $$dir clean; \
+	done

README.md

@@ -1,41 +1,18 @@
-# Braintrust Codex Plugin
+# Braintrust Codex Plugins
 
-A [Codex plugin](https://developers.openai.com/codex/plugins) that connects the Braintrust MCP server to the Codex marketplace, enabling agents to query Braintrust evals, logs, experiments, datasets, prompts, and traces.
+This repo is a monorepo of Braintrust [Codex plugins](https://developers.openai.com/codex/plugins)
 
-## Local setup
+## Quickstart
 
-Follow the [Codex plugin local install guide](https://developers.openai.com/codex/plugins/build#install-a-local-plugin-manually) to sideload this plugin.
+Add this repo as a Codex plugin marketplace:
 
-A reference PR showing a working local setup: https://github.com/braintrustdata/braintrust/pull/13536
+```bash
+codex plugin marketplace add braintrustdata/braintrust-codex-plugin
+```
 
-Once installed it should look like this:
+Then install the plugins you want:
 
-<img width="1067" height="1229" alt="image" src="https://github.com/user-attachments/assets/b9acaa81-3f95-4164-b65e-17355fc69f5b" />
-
-## Contributing
-
-When adding or modifying a skill, update the skill files under `skills/braintrust/` and test locally before opening a PR.
-
-## Releasing
-
-1. Bump the version in `.codex-plugin/plugin.json`:
-   ```json
-   { "version": "0.2.0" }
-   ```
-
-2. Commit the version bump:
-   ```bash
-   git add .codex-plugin/plugin.json
-   git commit -m "chore: bump version to 0.2.0"
-   ```
-
-3. Create a git tag and GitHub release:
-   ```bash
-   git tag v0.2.0
-   git push origin main --tags
-   gh release create v0.2.0 --title "v0.2.0" --notes "Describe what changed"
-   ```
-
-Users can see the changelog via [GitHub Releases](https://github.com/braintrustdata/braintrust-codex-plugin/releases).
-
-To make the repo public, ping **#wg-infra** or **#eng** on Slack.
+- mcp and skills: `codex plugin add braintrust@braintrust-codex-plugins`
+- trace codex sessions to braintrust: `codex plugin add trace-codex@braintrust-codex-plugins`
+    - run: `TRACE_TO_BRAINTRUST=true BRAINTRUST_PROJECT=my-coding-agent codex`
+    - see plugin's [README](/plugins/trace-codex/README.md) for details and config options