Skip to content
Back to search

chatgpt-codex-plugin-autopilot

Self-hosting ChatGPT/Codex Plugin autopilot — copy-in, repo-owned. Converts agentic repos into validated, deterministically packaged Plugins.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/immamdouhaboammar--chatgpt-codex-plugin-autopilot/badge.svg)](/listings/immamdouhaboammar--chatgpt-codex-plugin-autopilot)

HTML

<a href="/listings/immamdouhaboammar--chatgpt-codex-plugin-autopilot"><img src="/api/listings/immamdouhaboammar--chatgpt-codex-plugin-autopilot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Clone and run the universal installer (links skills into all detected AI harnesses)
git clone https://github.com/imMamdouhaboammar/chatgpt-codex-plugin-autopilot.git
bash chatgpt-codex-plugin-autopilot/install.sh

# Or via npm/Bun
bun add -g chatgpt-codex-plugin-autopilot
# npx chatgpt-codex-plugin-autopilot

Supported AI harnesses: **Claude Code**, **Gemini CLI / Antigravity**, **Codex**, **Cursor**.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 489 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ChatGPT/Codex Plugin Autopilot
  2. [![CI](https://github.com/imMamdouhaboammar/chatgpt-codex-plugin-autopilot/actions/workflows/ci.yml/badge.svg)](https://github.com/imMamdouhaboammar/chatgpt-codex-plugin-autopilot/actions/workflows/ci.yml)
  3. [![Release](https://img.shields.io/github/v/release/imMamdouhaboammar/chatgpt-codex-plugin-autopilot?label=release&color=4F6FFF)](https://github.com/imMamdouhaboammar/chatgpt-codex-plugin-autopilot/releases/latest)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
  5. [![Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Plugin%20Autopilot-blue?logo=github)](https://github.com/marketplace/actions/chatgpt-codex-plugin-autopilot)
  6. [![Skills: 9](https://img.shields.io/badge/skills-9-blueviolet)](./skills/)
  7. [![Tests: 96](https://img.shields.io/badge/tests-96%20passing-brightgreen)](./tests/)
  8. [![Author: Mamdouh Aboammar](https://img.shields.io/badge/author-Mamdouh%20Aboammar-orange)](https://github.com/imMamdouhaboammar)
  9. > **Self-hosting Plugin autopilot** — convert agentic repositories into focused, validated, deterministically packaged ChatGPT/Codex Plugins.
  10. >
  11. > © 2026 **Mamdouh Aboammar** — MIT License
  12. ---
  13. There are excellent agentic workflows sitting inside repositories that most people will never use.
  14. Sometimes they live in `AGENTS.md`. Sometimes they are buried in playbooks, prompts, custom agents, scripts, commands, or repo-specific conventions. They may work brilliantly for the original author and still be awkward to discover, install, or reuse in ChatGPT and Codex.
  15. Plugin Autopilot is built for that gap.
  16. Give it an agentic repository. It finds the workflows worth sharing, helps decide what should become public Skills, keeps internal material out of the package, chooses whether an external MCP/app boundary is genuinely required, adds a common host-workspace Skill for file/repository work, prepares the visual identity and Plugin Directory listing, executes local verification when the host allows it, validates the package, and builds deterministic release artifacts.
  17. And Plugin Autopilot is itself a Plugin. It packages and validates the same Skills it uses to convert other repositories.
  18. ## Install
  19. ```bash
  20. # Clone and run the universal installer (links skills into all detected AI harnesses)
  21. git clone https://github.com/imMamdouhaboammar/chatgpt-codex-plugin-autopilot.git
  22. bash chatgpt-codex-plugin-autopilot/install.sh
  23. # Or via npm/Bun
  24. bun add -g chatgpt-codex-plugin-autopilot
  25. # npx chatgpt-codex-plugin-autopilot
  26. ```
  27. Supported AI harnesses: **Claude Code**, **Gemini CLI / Antigravity**, **Codex**, **Cursor**.
  28. ## Quick start
  29. ```bash
  30. # Analyze a repository for plugin conversion
  31. python3 skills/chatgpt-codex-plugin-autopilot/scripts/analyze_repo.py /path/to/repo --json
  32. # Validate an existing plugin package
  33. python3 skills/chatgpt-codex-plugin-autopilot/scripts/validate_plugin.py . --json
  34. # Build a verified release ZIP
  35. python3 scripts/build_release.py --out-dir dist
  36. # Run the full test suite
  37. python3 -m unittest discover -s tests -v
  38. ```
  39. ## GitHub Action (Marketplace)
  40. Integrate Plugin Autopilot directly into any agentic repository or CI/CD workflow with zero setup.
  41. ```yaml
  42. # .github/workflows/plugin.yml
  43. name: ChatGPT & Codex Plugin Autopilot
  44. on:
  45. push:
  46. branches: [main]
  47. tags: ['v*']
  48. pull_request:
  49. workflow_dispatch:
  50. jobs:
  51. autopilot:
  52. runs-on: ubuntu-latest
  53. steps:
  54. - uses: actions/checkout@v4
  55. - name: Run Plugin Autopilot
  56. uses: imMamdouhaboammar/chatgpt-codex-plugin-autopilot@v1
  57. with:
  58. path: '.'
  59. action: 'auto' # 'auto' | 'analyze' | 'validate' | 'package' | 'build-directory-pack'
  60. output-dir: 'dist'
  61. fail-on-error: 'true'
  62. summary: 'true'
  63. - name: Attach Plugin Release Artifact
  64. if: startsWith(github.ref, 'refs/tags/v')
  65. uses: softprops/action-gh-release@v2
  66. with:
  67. files: |
  68. dist/*.zip
  69. dist/SHA256SUMS
  70. ```
  71. ### Action Modes
  72. | Mode | Purpose | Description |
  73. | :--- | :--- | :--- |
  74. | `auto` *(default)* | Adaptive Execution | Detects if `.codex-plugin/plugin.json` exists; validates and packages if present, otherwise analyzes repository workflows. |
  75. | `analyze` | Repo Discovery | Scans `AGENTS.md`, Skills, playbooks, and commands to produce actionable plugin architecture recommendations. |
  76. | `validate` | Preflight Linting | Runs full security and contract verification (manifests, semver, SVG luminance, archive safety). |
  77. | `package` | Deterministic Release | Compiles a clean, byte-for-byte deterministic ZIP archive with computed SHA-256 checksums. |
  78. | `build-directory-pack` | Submission Assets | Prepares listing metadata, icons, and reviewer packets for ChatGPT/Codex Plugin Directory submission. |
  79. ### Inputs & Outputs
  80. - **Inputs:**
  81. - `path`: Target repository or plugin directory (default: `.`)
  82. - `action`: Mode to execute: `auto` | `analyze` | `validate` | `package` | `build-directory-pack` (default: `auto`)
  83. - `create-pr`: Automatically scaffold plugin files and open a Pull Request when running in analyze mode (default: `false`)
  84. - `pr-title`: Title for the scaffold Pull Request (default: `🤖 [Plugin Autopilot] Scaffold ChatGPT/Codex plugin structure`)
  85. - `pr-branch`: Custom branch name for the PR (default: auto-generated `plugin-autopilot/scaffold-<timestamp>`)
  86. - `output-dir`: Directory for packaged release archives (default: `dist`)
  87. - `fail-on-error`: Halt workflow step on validation errors (default: `true`)
  88. - `summary`: Output rich markdown summary to GitHub Step Summary (default: `true`)
  89. - **Outputs:**
  90. - `ok`: `true` if operation completed successfully without errors
  91. - `architecture`: Detected architecture (`skills-only` | `mcp-backed` | `hybrid`)
  92. - `skills-count`: Number of discovered or validated skills
  93. - `plugin-path`: Path to built release ZIP archive
  94. - `sha256`: SHA-256 digest of release package
  95. - `pr-url`: Web URL of opened Pull Request (when `create-pr: true`)
  96. - `pr-number`: Issue/PR number of opened Pull Request
  97. ### 🤖 Auto-Scaffold Pull Requests (`create-pr: true`)
  98. When integrated into any repository with agentic skills, prompts, or workflows, Plugin Autopilot can automatically inspect your codebase and open a Pull Request ready for review:
  99. ```yaml
  100. # .github/workflows/autopilot-scaffold.yml
  101. name: Scaffold ChatGPT / Codex Plugin
  102. on:
  103. workflow_dispatch:
  104. permissions:
  105. contents: write
  106. pull-requests: write
  107. jobs:
  108. scaffold:
  109. runs-on: ubuntu-latest
  110. steps:
  111. - uses: actions/checkout@v4
  112. - name: Autopilot Scaffold PR
  113. uses: imMamdouhaboammar/chatgpt-codex-plugin-autopilot@v0.8.0
  114. with:
  115. create-pr: true
  116. ```
  117. The auto-generated PR will include:
  118. 1. `.codex-plugin/plugin.json`: Plugin manifest derived from repository discovery.
  119. 2. `assets/`: Valid SVG brand logos (`logo-light.svg`, `logo-dark.svg`, `mark.svg`).
  120. 3. `submission/listing.json`: Directory listing packet for ChatGPT / Codex submission.
  121. 4. `skills/`: Reusable agent skills compiled from discovered workflow candidates.
  122. 5. `.github/workflows/codex-plugin.yml`: Automated CI/CD pipeline to validate and package future plugin releases.
  123. ## The 0.6 flow
  124. ```text
  125. AGENTIC REPO
  126. |
  127. v
  128. DISCOVER
  129. Skills, agents, playbooks, prompts, commands, runtime signals
  130. |
  131. v
  132. DECIDE
  133. preserve | compile | reference | runtime | internal | discard
  134. |
  135. v
  136. COMPILE
  137. Turn real workflows into focused portable Skills
  138. |
  139. v
  140. WORKSPACE
  141. Add host-native read/list/search/grep/write/patch/shell/Python behavior
  142. |
  143. v
  144. EXECUTE
  145. Use host Python and repository tools when available, with real evidence
  146. |
  147. v
  148. DESIGN
  149. Shape the Plugin around user jobs
  150. |
  151. v
  152. BRAND
  153. Create product-specific light + dark SVG identity
  154. |
  155. v
  156. LIST
  157. Prepare public Plugin Directory metadata and reviewer material
  158. |
  159. v
  160. PROVE
  161. Tests -> preflight -> deterministic package -> clean extraction
  162. ```
  163. The goal is not to copy every folder from a repository into a Plugin. The goal is to preserve the useful agentic behavior and make it portable without pretending the Plugin has permissions or tools the current host did not provide.
  164. ## Start with repository discovery
  165. ```bash
  166. python3 skills/chatgpt-codex-plugin-autopilot/scripts/analyze_repo.py /path/to/repo --json
  167. ```
  168. The analyzer is dependency-free and read-only. It reports:
  169. - existing Skills
  170. - agent definitions such as `AGENTS.md`
  171. - workflow/playbook/command/prompt candidates
  172. - MCP/app/hook signals
  173. - `skills-only`, `MCP-backed`, or `hybrid` architecture recommendation
  174. - a `hostWorkspace` capability profile
  175. - conversion next actions
  176. - warnings such as undeclared `.mcp.json` or `.app.json`
  177. For repository conversions, the analyzer recommends a common workspace baseline with:
  178. ```text
  179. read
  180. list
  181. search
  182. grep
  183. write
  184. patch
  185. shell
  186. python
  187. ```
  188. These are host-native capabilities. Plugin Autopilot does not invent Plugin manifest permissions for them.
  189. ## Add workspace behavior to the generated Plugin
  190. For a file or repository-oriented Plugin:
  191. ```bash
  192. python3 skills/chatgpt-codex-plugin-autopilot/scripts/install_host_workspace_skill.py /path/to/plugin
  193. ```
  194. This installs `skills/host-workspace-operator/` into the target Plugin.
  195. The installer is deliberately conservative:
  196. - if the Skill is missing, it installs the canonical copy
  197. - if the installed copy is identical, it does nothing
  198. - if the target contains a customized copy, it refuses to overwrite it
  199. The generated Skill follows a simple operating rule:
  200. - read/list/search/grep before mutation
  201. - patch before broad replacement when possible
  202. - write only when the workflow is authorized to change files
  203. - shell only when repository commands are actually needed
  204. - Python for deterministic parsing, transformations, hashes, packaging, and verification
  205. - never claim a tool ran when the host did not provide it
  206. ## Host Python in ChatGPT and Codex
  207. `skills/sandbox-python-executor/` adds an execution policy for local deterministic work.
  208. OpenAI refers to Code Interpreter as the **python tool**. When ChatGPT provides that tool and verification matters, the Skill tells the model to actually use it instead of returning a code block and calling the work tested.
  209. Typical uses:
  210. - parse manifests and reports
  211. - inspect archives
  212. - calculate SHA256
  213. - run Plugin Autopilot's dependency-free Python validators/packagers
  214. - transform mounted files
  215. - verify deterministic calculations
  216. When Python is unavailable, the Skill requires the model to say so and keep execution-dependent conclusions unverified.
  217. This does not add a remote code-execution service or fake `code_interpreter` field to the Plugin manifest.
  218. ## Included Skills
  219. ### `chatgpt-codex-plugin-autopilot`
  220. The main orchestrator for conversion, validation, packaging, submission preparation, and release discipline.
  221. ### `agentic-repo-discovery`
  222. Finds candidate agentic workflows and sets the public/private boundary.
  223. ### `workflow-to-skill-compiler`
  224. Converts real playbooks, commands, prompt chains, and agent workflows into portable Skills while preserving decisions, approvals, tests, evidence, and stop conditions.
  225. ### `plugin-experience-architect`
  226. Defines the public Skill set, architecture, starter prompts, host-workspace capability profile, mutation boundary, and discovery behavior.
  227. ### `host-workspace-operator`
  228. A shared policy for native read/list/search/grep/write/patch/shell/Python operations supplied by the host.
  229. ### `sandbox-python-executor`
  230. Requires real Python execution evidence when the host exposes Python and deterministic execution matters.
  231. ### `plugin-brand-identity-designer`
  232. Creates a product-specific square SVG identity with light and dark variants plus a compact icon.
  233. ### `plugin-directory-listing-writer`
  234. Prepares accurate Plugin Directory fields, starter prompts, capability language, public URLs, and reviewer-facing metadata.
  235. ### `submission-pack-builder`
  236. Assembles evidence for the exact validated artifact without confusing local readiness with OpenAI approval.
  237. ## Host tools are not Plugin permissions
  238. OpenAI surfaces and models can expose different tool sets. Modern models may support capabilities such as file search, Code Interpreter, hosted shell, apply patch, computer use, MCP, and tool search, but availability depends on the product/model/session.
  239. Plugin Autopilot therefore uses capability-oriented Skills rather than undocumented manifest fields.
  240. For example, a generated Skill can say:
  241. ```text
  242. search for the relevant implementation
  243. read the matching files
  244. patch the smallest required change
  245. run the relevant tests
  246. ```
  247. The current host decides which actual tools satisfy those operations.
  248. For an external authenticated service, use a documented MCP/app boundary. For local workspace behavior, use the host-native capability profile.
  249. ## Architecture choices
  250. Autopilot supports:
  251. - **Skills-only** for portable workflows that need no external service
  252. - **MCP-backed** when the core job depends on external authenticated data/actions
  253. - **Hybrid** when reusable process lives in Skills while remote operations live behind MCP/apps
  254. Local read/write/search/grep/shell/Python behavior alone does not make a Plugin MCP-backed.
  255. Plugin Autopilot itself remains Skills-only.
  256. ## Brand pack
  257. Autopilot-prepared public Plugins should include:
  258. ```text
  259. assets/
  260. logo-light.svg
  261. logo-dark.svg
  262. <composer-icon>.svg
  263. ```
  264. The light and dark variants share one geometry and should represent the real job of the Plugin.
  265. ## Directory listing pack
  266. Build it with:
  267. ```bash
  268. python3 skills/chatgpt-codex-plugin-autopilot/scripts/build_directory_pack.py . --listing submission/listing.json --json
  269. ```
  270. The repository-maintained pack covers Name, Subtitle, Description, Category, Developer name, Website, Customer support, Privacy policy, Terms, Version, Package name, Capabilities, starter prompts, and brand asset paths.
  271. Publisher identity still has to match the verified OpenAI identity used during submission. Repository metadata cannot prove that by itself.
  272. ## Strict preflight
  273. When execution is available, actually run:
  274. ```bash
  275. python3 skills/chatgpt-codex-plugin-autopilot/scripts/validate_plugin.py . --json
  276. python3 skills/chatgpt-codex-plugin-autopilot/scripts/build_directory_pack.py . --listing submission/listing.json --json
  277. python3 skills/chatgpt-codex-plugin-autopilot/scripts/package_plugin.py . /tmp/plugin-a.zip --json
  278. python3 skills/chatgpt-codex-plugin-autopilot/scripts/package_plugin.py . /tmp/plugin-b.zip --json
  279. cmp /tmp/plugin-a.zip /tmp/plugin-b.zip
  280. unzip -Z1 /tmp/plugin-a.zip
  281. ```
  282. Then extract the archive into a clean directory and validate the extraction again.
  283. ## Self-hosting contract
  284. This repository uses its own Plugin scripts and Skills to check its own release surface.
  285. A release is blocked unless:
  286. 1. unit/regression tests pass
  287. 2. the directory listing pack passes
  288. 3. the staged Plugin self-validates
  289. 4. the package contains all expected Skills, including workspace and Python execution policies
  290. 5. deterministic archive builds match
  291. 6. archive contents are inspected
  292. 7. a fresh extraction validates again
  293. Local verification:
  294. ```bash
  295. python3 -m unittest discover -s tests -v
  296. python3 skills/chatgpt-codex-plugin-autopilot/scripts/build_directory_pack.py . --listing submission/listing.json --json
  297. python3 scripts/self_check.py
  298. python3 scripts/build_release.py --out-dir dist
  299. ```
  300. The release scripts do not claim OpenAI Plugin Directory approval.
  301. ## Current distribution context
  302. The Plugin Directory is the public discovery surface across ChatGPT and Codex. Plugins can package Skills and, when required, app/MCP integrations. Skills remain the portable workflow unit.
  303. The current OpenAI contract can change. Plugin Autopilot therefore requires re-checking official OpenAI documentation before public submission or when changing tool/dependency declarations.
  304. ## Skills included (9)
  305. | Skill | Purpose |
  306. |---|---|
  307. | `chatgpt-codex-plugin-autopilot` | Main orchestrator — conversion, validation, packaging, submission |
  308. | `agentic-repo-discovery` | Find candidate agentic workflows and set the public/private boundary |
  309. | `workflow-to-skill-compiler` | Convert playbooks, commands, and prompts into portable Skills |
  310. | `plugin-experience-architect` | Define public Skill set, architecture, and discovery behavior |
  311. | `host-workspace-operator` | Native read/list/search/grep/write/patch/shell/Python operations |
  312. | `sandbox-python-executor` | Require real Python execution evidence when available |
  313. | `plugin-brand-identity-designer` | Create product-specific SVG identity (light + dark + icon) |
  314. | `plugin-directory-listing-writer` | Prepare accurate Plugin Directory fields and reviewer metadata |
  315. | `submission-pack-builder` | Assemble submission evidence without confusing local proof with approval |
  316. ## Architecture
  317. ```mermaid
  318. flowchart TD
  319. A["Agentic Repository"] --> B["Discover\nSkills · Agents · Playbooks · Commands · Signals"]
  320. B --> C["Decide\npreserve · compile · reference · runtime · discard"]
  321. C --> D["Compile\nPortable Skills from real workflows"]
  322. D --> E["Workspace\nhost-workspace-operator for read/write/shell/Python"]
  323. E --> F["Execute\nPython verification with real evidence"]
  324. F --> G["Design\nPlugin experience and public surface"]
  325. G --> H["Brand\nSVG identity — light + dark + icon"]
  326. H --> I["List\nPlugin Directory metadata and reviewer pack"]
  327. I --> J["Prove\nTests → Preflight → Deterministic ZIP → Clean extraction"]
  328. J --> K["Release\nVerified ZIP + SHA256SUMS on GitHub"]
  329. ```
  330. ## Goal
  331. Make useful agentic workflows easier for other people to discover and use without stripping away the checks that make them reliable.
  332. A good conversion should leave users with a Plugin that can understand the job, inspect the relevant workspace, make only authorized changes, execute real verification when tools are available, explain what it actually did, and package the result cleanly for ChatGPT and Codex.
  333. ## Copy-in, repo-owned
  334. You copy this template into your repo and run `./init.sh` once. From that point on the kit is yours — no external package, no upstream dependency at runtime. Edit the config, rename things, delete a skill you don't need.
  335. ```bash
  336. # Clone into your project, then init
  337. git clone https://github.com/imMamdouhaboammar/chatgpt-codex-plugin-autopilot.git
  338. bash chatgpt-codex-plugin-autopilot/init.sh
  339. ```
  340. `init.sh` will:
  341. 1. Verify Python 3 is available
  342. 2. Read your `plugin.json` and confirm the author and version
  343. 3. Count skills present in `skills/`
  344. 4. Run `self_check.py` to verify the release surface
  345. 5. Run the full test suite
  346. 6. Print ownership confirmation and next steps
  347. After `init.sh` passes, the repository is yours. There are no upstream calls at runtime. A future packaged version (a plugin plus an installable engine) waits until the template has proven itself across a few real projects.
  348. > **A personal note from Mamdouh Aboammar:**
  349. > I built this for my own development work with AI coding agents. The principles and choices here reflect my own preferences and workflows — not a universal best practice. Take what's useful, change what isn't, and shape it to fit how you like to work.
  350. ---
  351. ## Author & license
  352. **Mamdouh Aboammar** — [github.com/imMamdouhaboammar](https://github.com/imMamdouhaboammar)
  353. © 2026 Mamdouh Aboammar. All rights reserved.
  354. Released under the [MIT License](./LICENSE).
  355. This repository — including all Skills, scripts, documentation, brand assets, and release tooling — is the original work of Mamdouh Aboammar. Contributions are welcome under the terms described in [CONTRIBUTING.md](./CONTRIBUTING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.