orgx-codex-plugin — плагин для Claude Code: функции и установка
Плагин orgx-codex-plugin подключает OrgX MCP и навыки для работы с инициативами, а также передаёт контекст проекта в Codex. Он пригодится для отчётов о работе и обновления статуса задач в OrgX.
MIT ★ 1 596 обновлён 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install orgx-codex-plugin@awesome-codex-pluginsЧто делает orgx-codex-plugin
Плагин связывает OrgX MCP с навыками orgx-initiative-ops и orgx-runtime-reporting. Первый помогает работать в контексте инициативы, задачи или блокера; второй передаёт в OrgX прогресс, артефакты и события завершения. Для сводок навык использует get_operator_chronicle, если инструмент доступен в подключении.
Хук SessionStart получает контекст рабочего пространства и сохраняет его в .codex/orgx-context-pack.json, чтобы он попал в первый ход Codex. Сбором сессий и доставкой событий управляет Wizard; локальный сборщик формирует отчёт Work Graph из кратких обезличенных сводок. Сырые транскрипты остаются локально.
Для работы нужны ORGX_API_KEY и, при необходимости, ORGX_BASE_URL в окружении процесса. Установка в Claude Code выполняется командами маркетплейса ниже. Конфигурация проекта может содержать идентификаторы области, но не учётные данные; файлы контекста могут содержать внутренние сведения и не должны попадать в Git.
Какие задачи решает
- связать задачу по инициативе с данными OrgX MCP
- передать в OrgX ход работы, блокеры и артефакты
- получить сводку о решениях и приоритетах за выбранный период
- подготовить локальный отчёт Work Graph по событиям хуков
Примеры запросов агенту
- Разбери эту задачу в контексте инициативы OrgX и проверь связанные блокеры.
- Передай в OrgX прогресс по текущей работе и приложи итоговый артефакт.
- Составь краткую сводку по решениям, PR и приоритетам за прошедшую неделю.
Как установить orgx-codex-plugin
Через маркетплейс плагинов
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install orgx-codex-plugin@awesome-codex-pluginsПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы об orgx-codex-plugin
Как установить orgx-codex-plugin в Claude Code?
Выполните команды по порядку: /plugin marketplace add hashgraph-online/awesome-codex-plugins, затем /plugin install orgx-codex-plugin@awesome-codex-plugins.
Что делает orgx-codex-plugin?
Подключает OrgX MCP и навыки для инициатив и отчётности. Хук передаёт контекст проекта в первый ход Codex, а Wizard управляет сбором и доставкой данных сессии.
Что нужно настроить для подключения к OrgX?
Задайте ORGX_API_KEY в окружении процесса и при необходимости ORGX_BASE_URL. Файл .codex/orgx.local.json предназначен только для идентификаторов области.
Исходный текст
orgx-codex-plugin · MIT
# 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
## Why this plugin exists
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.
Distribute this native runtime package through manual installation or the local
Codex marketplace. It includes lifecycle hooks, which the
[public directory submission requirements](https://developers.openai.com/plugins/deploy/submission)
exclude. The separate ChatGPT directory candidate uses a hook-free package;
valid listing metadata here does not make this runtime package eligible for
public directory submission.
## Structure
```text
.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
```
## Included skills
### `orgx-initiative-ops`
Use OrgX MCP as the source of truth when a task is scoped to an OrgX initiative,
workstream, milestone, task, blocker, or decision.
### `orgx-runtime-reporting`
Keep OrgX updated during live Codex execution with progress, artifacts,
blockers, and completion events.
After the matching MCP deployment, `commander` exposes the existing
`orgx_update_work` operation for one reviewable output attachment: current work
target, workspace, stable retry key, durable output location and optional plain
answer, linked decisions and source notes. Inspect the stored artifact to read
its canonical context, files and run receipt. Attaching leaves approval and
completion pending. The runtime skill documents the bounded payload and retry
behavior; Wizard continues to own passive capture, and the peer's terminal
receipt outbox does not upload files.
For reporting or daily-brief style questions, start with
`get_operator_chronicle` when the live OrgX MCP tool map exposes it. Its
`chronicle.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.
For a selected `commander` connection, `orgx_recommend` with
`mode: "morning_brief"` is another reporting read when actually callable.
Its narrative is at `chronicle.reportingNarrative.briefMarkdown`. Refresh the MCP
connection when its callable inventory differs from the selected profile.
## Runtime hooks and first-turn context
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:
```bash
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:
```bash
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](./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.
## Subscription runner autonomy
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:
```bash
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:
```bash
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, read-only `orgx_get_workspace_context` MCP tool
(the hosted `v2` catalog no longer registers `orgx_bootstrap`). 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:
```bash
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:
```bash
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.
## Local verification
```bash
npm run check
```
To preview the runtime wiring without editing Codex config:
```bash
orgx-wizard hooks doctor
```
To install the consent-safe Codex capture rail through this plugin:
```bash
orgx-codex-install-hooks
```
## Install locally in Codex
### Repo-local marketplace
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.
### Personal marketplace
1. Copy the plugin to your personal Codex plugins directory:
```bash
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`:
```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/`.
## MCP server behavior
The bundled `.mcp.json` config uses the hosted OrgX streamable HTTP endpoint:
```json
{
"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` only when
actually callable, with `mode: "morning_brief"`. Read its
`chronicle.reportingNarrative.briefMarkdown`. 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.
The `commander` selector serves the peer's signed runtime contracts. The default
endpoint exposes named workflow operations and portable receipt imports; keep
the peer's selector unless its signed manifest and payloads change together.
Refresh authenticated `tools/list` after updating the plugin or MCP server.
`server.json` describes the default catalog, not this connection's inventory.
`orgx_submit_receipt` records condensed runtime reporting; portable
`orgx_submit_work_receipt` imports an entire receipt document. The Gateway
terminal outbox and passive hooks use independent HTTP paths. Autonomous
execution continues to enforce its signed tool names and schemas.
## Sources used
- 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`
© OrgX Team · MIT · hashgraph-online/awesome-codex-plugins