Codex plugin installation and management

Offing ships as a portable Agent Plugins package with a Codex compatibility manifest. It bundles the canonical Offing Skill and a local, read-only stdio MCP server. No Offing account or hosted Offing service is required.

Requirements

• Codex CLI or Codex in the ChatGPT desktop app with plugin support.
• Node.js 22 or newer.
• Access to the npm registry the first time the pinned Offing runtime is launched.

Dependency guard

The plugin ships a PostToolUse hook (hooks/hooks.json, matched to apply_patch) and the Skill carries the same instruction for sessions where hooks are off. When a patch adds a dependency that Offing's lifecycle rules mark as deprecated, Codex receives a warning with the evidence and the replacement, and you see a one-line notice.

It reads the patch Codex applied and checks only what the patch added or changed, in package.json, requirements*.txt, constraints*.txt, pyproject.toml, GitHub workflows, and action.yml. Existing dependencies never produce repeated warnings.

Offing: pkg:npm/request@2.88.2 — request is deprecated (high, deprecated).
The package is fully deprecated and no new changes are expected.
Replacement: Native fetch or a maintained HTTP client.
Evidence: https://www.npmjs.com/package/request

• Trust the hook first. Codex does not run plugin hooks until you review them: enabling the plugin does not trust its hooks. Run /hooks in Codex and trust the Offing hook. Trust is tied to the hook's contents, so a plugin update asks again.
• It never blocks or edits files. It warns and cites sources; you and Codex decide what to do. If the check cannot run, the hook says so instead of staying silent, and the patch is unaffected.
• It is local. It runs offing check from the same pinned release as the MCP server; no repository content leaves your machine. A package with no rule produces no output, which is absence of evidence, not a safety claim.
• If hooks are off ([features] hooks = false) or you do not trust the hook, the Skill still tells Codex to call the check_dependency tool before adding a dependency.

The script is generated from integrations/dependency-guard/guard.mjs, shared with the Claude plugin. Set OFFING_CHECK_COMMAND to use another Offing command, for example a local build.

Install from this repository

The repository marketplace is discovered from .agents/plugins/marketplace.json and exposes the package as offing@offing-codex:

codex plugin add offing@offing-codex

For a remote checkout, add or refresh the repository marketplace first:

codex plugin marketplace add velella-sh/offing --ref main
codex plugin add offing@offing-codex

Restart the current Codex session after installation so the packaged Skill and MCP server are discovered together.

Verify the installation

List the installed plugin:

codex plugin list --json

Then ask Codex to run the packaged workflow:

Scan this repository for supported lifecycle risks.
Explain the highest-severity Offing finding.
Create migration context for this deprecation.
Verify that the finding is gone after my change.

The installed workflow must expose scan, list, explain, context, and verify. Suggested migration commands are returned as guidance and are never executed by Offing.

Maintainers can run the same end-to-end check against an installed cache path:

npm run validate:codex-plugin -- --plugin-root /absolute/path/to/installed/offing

Update

For the repo-local marketplace, reinstall the plugin so the cache is rebuilt from the current package:

codex plugin remove offing@offing-codex
codex plugin add offing@offing-codex

For a Git-backed marketplace added from velella-sh/offing, refresh its snapshot before reinstalling:

codex plugin marketplace upgrade offing-codex

The package pins its MCP runtime to the same semantic version as the plugin manifest, preventing a silent mix of plugin metadata and runtime versions.

Remove

codex plugin remove offing@offing-codex

If the repository marketplace was added explicitly and is no longer needed:

codex plugin marketplace remove offing-codex

Removal deletes the installed plugin cache. It does not modify the repository being scanned.

Local data and permissions

• The MCP process runs locally over stdio and reads only repository paths authorized by the host.
• Offing does not upload repository contents, require credentials, edit files, run migration commands, or open a network listener.
• Tool results can contain repository paths and short source excerpts and are returned to the Codex host.
• The host remains responsible for filesystem approvals and any later edits an agent makes.

See Privacy for the complete data boundary and Codex submission for public-directory review status.