OrgX Codex Plugin

Codex plugin package for OrgX:

• OrgX MCP server wiring via the canonical resource with the commander tool-profile header
• Operator chronicle reporting for yesterday/week/30-day decisions, PRs, artifacts, goals, gaps, and priorities
• Initiative-aware Codex skills for OrgX execution
• Native first-turn context hydration plus Wizard-owned session capture
• Install-surface metadata for Codex plugin directories and local marketplaces

This repo packages the OrgX setup that Codex needs into the structure described in the official Codex plugins docs:

• .codex-plugin/plugin.json
• .mcp.json
• skills/**/SKILL.md
• assets/

It is the Codex counterpart to the existing OrgX Claude Code and OpenClaw plugin repos.

.codex-plugin/plugin.json   # Codex plugin manifest
.mcp.json                   # OrgX MCP configuration
skills/orgx-initiative-ops/SKILL.md
skills/orgx-runtime-reporting/SKILL.md
hooks/hooks.json
hooks/scripts/hydrate-context-pack.mjs
hooks/scripts/orgx-work-graph-reconcile.mjs
assets/icon.png
assets/logo.png
scripts/install-codex-hooks.mjs
scripts/verify-plugin.mjs

Use OrgX MCP as the source of truth when a task is scoped to an OrgX initiative, workstream, milestone, task, blocker, or decision.

Keep OrgX updated during live Codex execution with progress, artifacts, blockers, and completion events.

For reporting or daily-brief style questions, start with get_operator_chronicle when the live OrgX MCP tool map exposes it. Its reportingNarrative.briefMarkdown is the canonical concise answer for decisions made yesterday, the past week, the past 30 days, artifacts, PR receipts, velocity, top priorities, goals, and gaps.

If an AI client has not refreshed its callable MCP schema after OrgX publishes the direct tool, use the existing orgx_recommend / _orgx_recommend fallback with mode: "morning_brief" and present the same reportingNarrative.briefMarkdown. Direct get_operator_chronicle calls remain preferred when callable; the fallback prevents a stale plugin session from blocking the report.

The plugin owns one native SessionStart adapter at hooks/hooks.json. It fetches /api/v1/context-pack for the exact configured workspace, initiative, workstream, and task hierarchy, writes the bounded result to .codex/orgx-context-pack.json with mode 0600, and returns Codex additionalContext so the accepted state is available in the first model turn.

When the server returns data.sessionWorkContext, the adapter forwards that exact object to the supported Wizard interface:

orgx-wizard sessions context set --file - --cwd "$PWD" --json

The Wizard validates the 4 KiB contract and binds it to the exact project directory. If Wizard is unavailable or rejects the object, the adapter keeps the unchanged context at .codex/orgx-session-work-context.activation-pending.json. Codex sees that the context is pending and must not treat it as activated authority. Both runtime files can contain private organizational context and must stay out of version control. A definitive response with no receipt-ready context clears any prior exact-directory activation so stale authority does not survive; an offline or timed-out request fails open without pretending the server answered.

Project config at .codex/orgx.local.json may contain only scope identifiers. ORGX_API_KEY and an optional ORGX_BASE_URL must come from the process environment; a repository config cannot supply or redirect credentials.

The Wizard is the sole owner of session collection, WorkEpisode policy, durable queueing, acknowledgement, retry, and delivery. Install that capture rail with:

orgx-codex-install-hooks

Plugin-initiated setup defaults to metadata-only. It honors an explicit ORGX_SESSION_WORK_EPISODE_CAPTURE=bounded opt-in and passes the selected policy to orgx-wizard hooks install --targets codex --work-capture .... If the installed Wizard does not support that policy flag, setup reports the exact incompatibility; it never retries with bounded capture.

Client hook coverage is tracked in docs/client-hook-coverage.md. Current verdict: the Codex package covers Codex skills, MCP setup, stale-client chronicle fallback, native context hydration, and Wizard delegation, but it is not sufficient proof that every AI client exposes the same hooks or direct get_operator_chronicle tool. Use that matrix before claiming ChatGPT, Claude Code, or Cursor parity.

Wizard hook events are a passive backstop. They record compact session metadata and safe summaries so Work Graph reconciliation can answer:

• What changed yesterday, this week, and in the past 30 days?
• Which decisions, PRs, artifacts, goals, and priorities should be surfaced?
• Did the session call OrgX MCP?
• Did meaningful work happen without OrgX writeback?
• Are there decisions, blockers, artifacts, people, product surfaces, or goals that should become an OrgX initiative kickoff?

This package includes orgx-codex-reconcile-hooks, a local reconciler that reads the hook outbox and emits a summary-only Work Graph report with a stable work_graph_fingerprint and signup_hydration.hydration_key. That fingerprint is the bridge between a pre-signup audit/share surface and the user's future OrgX workspace: after signup, OrgX can claim the fingerprint, dedupe replays, and attach the redacted Work Graph to a kickoff initiative.

Raw transcripts are not sent by the Wizard capture rail. The reconciler keeps transcripts local and writes only redacted summaries, hashes, evidence refs, Work Graph fingerprints, and approved OrgX activity.

The Codex peer is interactive-only by default. To authorize OrgX to select the user-controlled runner for unattended work, set the following in the runner's service environment and restart it:

ORGX_AUTONOMOUS_DISPATCH_ENABLED=true
ORGX_AUTONOMOUS_REPO_PATH=/absolute/path/to/git-worktree
ORGX_RUNNER_INSTANCE_ID=<installer-persisted-service-id>
ORGX_ACTIVATION_ATTEMPT_ID=<installer-activation-attempt-id>
ORGX_RUNNER_ROLE=candidate

Only the exact string true opts in. The repo path must be a canonical, existing git worktree root owned by the runner configuration; tasks cannot choose or override it. Unset, misspelled, invalid, or conflicting values fail closed. Service installers should persist the path in a mode-0600 state file and use it as the service working directory. Heartbeats publish requested, repo-ready, MCP-ready, and enabled states separately; enabled is true only when all gates pass. Before any autonomous model turn, the peer also proves the exact signed OrgX MCP tool names and schemas through Codex app-server. The installer must configure and authenticate the hosted orgx server with the official codex mcp add / codex mcp login flow; the Gateway key is not an MCP OAuth token. Opted-in peers accept normal user-initiated work only when the Gateway marks it dispatch_class: interactive; unattended work must be marked autonomous and carry the complete signed context. The context contains the actual resolved skill instructions, and the peer verifies their digests against the runtime profile and execution envelope before adding them to the Codex prompt. This permission applies only to the Codex runner and does not authorize unattended use of an Anthropic subscription.

Autonomous services must export a stable ORGX_RUNNER_INSTANCE_ID generated by the installer. A staged candidate and the current canonical service must use different values. The peer binds this identity into both the Gateway heartbeat body and WebSocket query, allowing activation to prove which durable service is online before promotion. Interactive/manual CLI launches may omit the variable; the CLI persists a mode-0600 identity scoped to the workspace and installation under ~/.orgx/codex-peer/runner-instances/.

During managed promotion, the installer also sets one activation attempt ID and a runner role of exactly candidate or canonical. These two values are validated as a pair and included in the presence heartbeat, but not the stream query; the authenticated server-side binding remains authoritative. A partial pair or any other role fails before the peer starts network activity.

A completed Codex turn is not sufficient to claim shipped. For autonomous runs, the peer compiles the required evidence types, verifier independence, minimum outcome confidence, judged score, verdict confidence, and critical observation ceiling from the content-verified mission/work-node/quality-bar bundle. Empty or prose-only runs become blocked; concrete work without a qualified independent verifier becomes awaiting_review; and read-only work cannot satisfy an artifact-producing mission. Only a trusted OrgX verifier record meeting every signed threshold can preserve shipped. Verifier records are rejected by default even when their signature field is well-shaped; a runner-owned verifier callback must authenticate them. The packaged production peer does not configure a permissive callback, so unverified work remains awaiting_review.

Terminal completions and failures are written to a mode-0700 disk outbox before the peer yields them to the Gateway SDK. The peer posts every terminal message independently to the idempotent HTTP receipt endpoint and removes its file only after an HTTP 2xx application acknowledgement. Rejected deliveries survive peer restarts and replay on startup, reconnect/heartbeat, and shutdown. Set ORGX_RECEIPT_OUTBOX_PATH to override the workspace-scoped default under ~/.orgx/codex-peer/receipt-outbox/.

Installers must run the one-shot gate after Codex login, OrgX MCP OAuth, and repo selection, but before persisting autonomous opt-in:

ORGX_AUTONOMOUS_REPO_PATH=/absolute/path/to/git-worktree \
  orgx-codex-peer check-autonomous-readiness

The readiness gate reads Codex app-server mcpServerStatus/list, whose current v2 success value is authStatus: "oAuth". Installers that separately inspect codex mcp list --json must handle that CLI's snake-case surface (auth_status: "o_auth") instead of reusing the app-server literal.

The command needs no Gateway key. It exits zero only when the checkout is valid, Codex is ChatGPT-authenticated, current app-server RPC works, and a read-only, shell-disabled app-server thread proves the authenticated OrgX server exposes exactly the bounded orgx_bootstrap MCP tool. This is an MCP inventory proof, not a claim that Codex has no other non-shell native tools. Real runs still compare every MCP tool schema to the signed per-run manifest.

Dry-run reconciliation does not require OrgX credentials:

orgx-codex-reconcile-hooks \
  --outbox ~/.config/useorgx/wizard/hooks/events.jsonl \
  --output /tmp/orgx-work-graph-report.json

To publish the report to OrgX, provide an API key and opt in explicitly:

ORGX_API_KEY=oxk_... orgx-codex-reconcile-hooks --post

Automatic end-of-session capture and delivery are Wizard-owned. Run orgx-codex-install-hooks; do not add the legacy plugin Stop/reconcile hook. The standalone reconciler remains available for an explicit audit or repair, but it is not a second capture rail.

npm run check

To preview the runtime wiring without editing Codex config:

orgx-wizard hooks doctor

To install the consent-safe Codex capture rail through this plugin:

orgx-codex-install-hooks

This repo now includes a marketplace file at .agents/plugins/marketplace.json that points directly at the plugin repo root. To test it in Codex:

1. Open /Users/hopeatina/Code/orgx-codex-plugin in Codex.
2. Restart Codex.
3. Open /plugins and select the repo marketplace orgx-local.

This is the fastest way to verify the plugin during development because it avoids copying the plugin into a separate plugins directory.

The official docs recommend using the built-in @plugin-creator skill to scaffold local plugins and marketplace entries. That skill was not available in the environment used to create this repo, so this plugin was scaffolded manually against the current published Codex plugin spec.

1. Copy the plugin to your personal Codex plugins directory:

mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/orgx-codex-plugin ~/.codex/plugins/orgx-codex-plugin

2. Add or update ~/.agents/plugins/marketplace.json:

{
  "name": "useorgx-local",
  "interface": {
    "displayName": "OrgX Local"
  },
  "plugins": [
    {
      "name": "orgx-codex-plugin",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/orgx-codex-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

3. Restart Codex and open /plugins.

Because ~/.agents/plugins/marketplace.json is resolved relative to your home directory, the plugin entry must point at ./.codex/plugins/... if the plugin was copied under ~/.codex/plugins/.

The bundled .mcp.json config uses the hosted OrgX streamable HTTP endpoint:

{
  "mcpServers": {
    "orgx": {
      "type": "http",
      "url": "https://mcp.useorgx.com/mcp",
      "oauth_resource": "https://mcp.useorgx.com/mcp",
      "http_headers": {
        "x-orgx-tool-profile": "commander"
      }
    }
  }
}

This follows current OrgX MCP docs and lets OAuth happen in-browser on first use. After bootstrap, the preferred reporting first call is get_operator_chronicle with period: "30d" when the client exposes it. When the hosted MCP bootstrap advertises get_operator_chronicle but a client session still exposes only older OrgX tools, call orgx_recommend with mode: "morning_brief" as the compatibility path. Passive runtime hooks are a reconciliation backstop for session evidence; they are not a substitute for MCP read/write calls during the live operator report.

• Official Codex plugin docs: https://developers.openai.com/codex/plugins
• OrgX MCP docs: https://docs.useorgx.com/docs/api/overview
• Existing OrgX references:
  • orgx-claude-code-plugin
  • orgx-openclaw-plugin