Use Perpensa skills in Codex

The private Perpensa plugin provides three read-only workflows for Codex:

Workflow	Example request
Prepare priorities	“Use Perpensa to tell me what to fix first in my application.”
Explain an update	“Use Perpensa to explain why this update is a priority.”
Prepare a security briefing	“Prepare a current security briefing for this application using Perpensa.”

The instructions are packaged with the plugin. Results are read from Perpensa through MCP. These workflows do not start scans, apply fixes, accept risk, export files, submit feedback, send messages or create PRs. Their output appears in the conversation.

Requirements

You need Codex desktop with private plugin support, membership in a Pro or Team organization, and an allowed MCP connection. Contact Perpensa support to get the private plugin package. The public plugin directory is outside this initial release.

Use Read results permission for the connection. The other permissions are not needed by these workflows. Follow Connect an assistant with MCP for the existing authorization, organization selection, expiry and revocation rules. Installing a skill does not grant access to any organization or application.

Import the private plugin archive

Use perpensa-private-1.0.2.zip in the desktop plugin upload dialog. The archive contains the plugin manifest, MCP configuration and the three skills directly at its root. Select the ZIP and add the plugin, then follow the connection flow and authorize only Read results.

Do not upload a compressed private marketplace folder. That folder contains the plugin under plugins/perpensa/ and is intended for the CLI installation route below, not the archive importer. The earlier perpensa-private-1.0.0.tar.gz marketplace archive is unsuitable for this dialog.

Install from a local marketplace instead

The package contains a private marketplace and a perpensa plugin. Keep its folder intact. Perpensa support supplies the package and its version.

Register and install that package using the Codex CLI on the same machine as Codex desktop:

codex plugin marketplace add /absolute/path/to/perpensa-private-1.0.2
codex plugin add perpensa@perpensa-private --json

Use the path supplied with your package rather than the example. Restart Codex desktop so it reloads the installed plugin, then start a new chat and verify that the three Perpensa skills are available. Installing the plugin does not authorize the connection.

If the package uses a registered personal Perpensa connector, authorize that connector in the plugin connection flow. A package containing a direct MCP endpoint uses the existing OAuth browser flow for that endpoint. Never paste a token or OAuth code into a conversation. Do not authorize broader permissions just to work around a failed installation.

Ask for a result

Name the organization and application, and the environment when relevant. Codex resolves names to the objects you can access. If names are ambiguous, it asks you to choose before reading the results. A workflow covers one organization at a time.

You can invoke $perpensa-priorities, $perpensa-explain-update or $perpensa-security-briefing explicitly, or ask for the corresponding goal in ordinary language. The response can be in your requested language.

Priorities show the first five entries by default; ask for a different number if needed. The ordering and categories come from Perpensa. Explanations use the recorded detail and distinguish unknown information from observed signals.

The security briefing describes the current state. It does not establish how many vulnerabilities were fixed this week without comparable historical data. The priority list omits fully accepted risks, so a briefing based on that list cannot give an exhaustive count of accepted risks.

Understand incomplete results

An empty priority list is not evidence that an application is safe when scan coverage is incomplete. The response identifies coverage gaps and evidence dates. Its response timestamp does not mean all dependencies were just scanned.

If pagination or a service error prevents a complete read, Codex should label the result partial. Missing scores or exploitation signals remain unknown. An accepted risk has not necessarily been fixed.

If access expires, is revoked or is reduced, use the existing reconnection flow. A locally installed skill cannot bypass that refusal. Previously read information may remain in the conversation; revocation prevents new access, not deletion of earlier chat content. Treat reports according to your organization’s data policy.

Update or return to a previous package

Skill instructions are versioned snapshots. Results stay live, but a Perpensa update does not replace the instructions in an installed plugin. Contact Perpensa support for a new package and its version when instructions change.

Add the new package path as the perpensa-private source and install it again:

codex plugin marketplace add /absolute/path/to/perpensa-private-1.0.3
codex plugin add perpensa@perpensa-private --json

Restart desktop, open a new chat and verify the installed version and expected behavior. If Codex reports that the named marketplace already exists, remove that marketplace source and add the new package before reinstalling:

codex plugin marketplace remove perpensa-private
codex plugin marketplace add /absolute/path/to/perpensa-private-1.0.3
codex plugin add perpensa@perpensa-private --json

For rollback, use the previous package path and reinstall its version in the same way. This does not widen permissions or restore a revoked connection.

See OpenAI’s private plugin guide for host installation details. Imported server skills are also snapshots rather than live instructions; the future public import flow requires its own validation.