Add TraceRoot Codex observability plugin (v0.1.0)

.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "traceroot-codex-plugin",
+  "interface": { "displayName": "TraceRoot" },
+  "plugins": [
+    {
+      "name": "tracing",
+      "source": { "source": "local", "path": "./plugins/tracing" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Coding"
+    }
+  ]
+}

.gitattributes

@@ -0,0 +1,9 @@
+# The committed bundle is a generated artifact (Codex runs it directly — there is
+# no build step on install). Keep it tracked, but treat it as generated: collapse
+# it in PR diffs and exclude it from GitHub language stats.
+plugins/tracing/dist/index.mjs linguist-generated=true -diff
+
+# Lockfile and license text are not human-reviewed line-by-line — collapse them in
+# diffs and keep them out of language stats so the reviewable diff is real code.
+pnpm-lock.yaml linguist-generated=true -diff
+LICENSE linguist-generated=true -diff

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: Typecheck, test, lint:dist
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm run typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Lint dist
+        run: pnpm run lint:dist

.gitignore

@@ -0,0 +1,13 @@
+node_modules
+*.log
+.DS_Store
+.superpowers/
+.env
+.env.*
+coverage/
+.idea/
+.vscode/
+*.tgz
+
+# NOTE: plugins/tracing/dist/ is intentionally committed (Codex runs the bundle
+# directly — no build step on install). Do not ignore it.

README.md

@@ -1,5 +1,55 @@
 # traceroot-codex-plugin
 
-TraceRoot Observability Plugin for OpenAI Codex.
+Trace OpenAI Codex sessions to [TraceRoot](https://traceroot.ai). Every query becomes **one live trace** — agent turn, model calls, tool calls, file edits, and any subagents it spawns — streamed as the agent works and linked to your git repo. No daemon; tracing never blocks Codex.
 
-> 🚧 Work in progress — placeholder README. Implementation coming soon.
+## Install
+
+```bash
+codex plugin marketplace add traceroot-ai/traceroot-codex-plugin
+```
+
+Enable it in `~/.codex/config.toml`:
+
+```toml
+plugin_hooks = true
+
+[plugins."tracing@traceroot-codex-plugin"]
+enabled = true
+```
+
+## Configure
+
+Add `~/.codex/traceroot.json` — that's all that's required:
+
+```json
+{
+  "enabled": true,
+  "api_key": "your-key-from-app.traceroot.ai"
+}
+```
+
+Get your API key at [app.traceroot.ai](https://app.traceroot.ai). (The plugin runs as a Codex hook, which doesn't reliably inherit your shell environment, so the config file is preferred over environment variables.)
+
+<details>
+<summary>Optional settings</summary>
+
+Resolved highest-precedence first: env vars → project `.codex/traceroot.json` → global `~/.codex/traceroot.json` → defaults.
+
+| JSON key | Env var | Default | Notes |
+|----------|---------|---------|-------|
+| `enabled` | `TRACE_TO_TRACEROOT` | `false` | Turn tracing on (an API key must also be set). |
+| `api_key` | `TRACEROOT_API_KEY` | — | Required. |
+| `host_url` | `TRACEROOT_HOST_URL` | `https://app.traceroot.ai` | Point at a self-hosted instance. |
+| `max_chars` | `TRACEROOT_CODEX_MAX_CHARS` | `20000` | Truncate long span attributes. |
+| `debug` | `TRACEROOT_CODEX_DEBUG` | `false` | Log to stderr. |
+| `fail_on_error` | `TRACEROOT_CODEX_FAIL_ON_ERROR` | `false` | Off by default — tracing never blocks a Codex turn. |
+
+</details>
+
+## Privacy
+
+Only what appears in your traces is sent to your TraceRoot host: prompts, tool inputs/outputs (which can include commands and file contents), model and token info, and git repo/branch. If your tools handle secrets, their inputs/outputs are part of the trace.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

package.json

@@ -0,0 +1,32 @@
+{
+  "name": "traceroot-codex-plugin",
+  "version": "0.1.0",
+  "description": "Trace OpenAI Codex sessions to TraceRoot",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsdown --config plugins/tracing/tsdown.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint:dist": "pnpm run build && git diff --exit-code -- plugins/tracing/dist/index.mjs"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.1",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.205.0",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "@opentelemetry/semantic-conventions": "^1.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsdown": "^0.18.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.0"
+  },
+  "engines": { "node": ">=22" },
+  "packageManager": "pnpm@10.14.0"
+}

plugins/tracing/.codex-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "tracing",
+  "version": "0.1.0",
+  "description": "Trace OpenAI Codex sessions to TraceRoot.",
+  "author": { "name": "TraceRoot", "email": "support@traceroot.ai", "url": "https://traceroot.ai" },
+  "homepage": "https://github.com/traceroot-ai/traceroot-codex-plugin#readme",
+  "repository": "https://github.com/traceroot-ai/traceroot-codex-plugin",
+  "license": "Apache-2.0",
+  "keywords": ["codex", "hooks", "traceroot", "observability", "tracing"],
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "Tracing",
+    "shortDescription": "Trace Codex sessions to TraceRoot",
+    "longDescription": "Streams each Codex query to TraceRoot as one live trace — agent turns, model calls, tool executions (incl. file edits), token usage, and spawned subagents nested in the same trace, linked to your git repo. Stateless hooks, no daemon, fail-open.",
+    "developerName": "TraceRoot",
+    "category": "Coding",
+    "capabilities": ["Read"],
+    "websiteURL": "https://traceroot.ai",
+    "brandColor": "#5B8DEF",
+    "screenshots": []
+  }
+}