Repository navigation
feat: package Altimate for the Codex directory with guided setup #9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
hkaltai
merged 5 commits into
main
from
feat/AI-10711-codex-public-directory-plugin-mcp-hooks
Nov 18, 2026
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
9e55325
feat: build hook-free Codex directory package with guided setup
hkaltai aad714b
fix: use official Altimate artwork for listing icons
hkaltai 7a1a397
fix: validate directory package inputs and clarify contracts
hkaltai 632f238
fix: reject dot-relative MCP package paths
hkaltai 1736c27
fix: harden directory packaging and installer handoff
hkaltai File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| name: Directory package | ||
|
|
||
| on: | ||
| pull_request: | ||
| push: | ||
| branches: [main] | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| jobs: | ||
| package: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 | ||
| - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 | ||
| with: | ||
| python-version: '3.11' | ||
| - name: Test directory packaging | ||
| run: bash tests/directory-zip.sh | ||
| - name: Build skills-only directory ZIP | ||
| run: python3 scripts/build_directory_zip.py | ||
| - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 | ||
| with: | ||
| name: altimate-code-directory | ||
| path: dist/*.zip | ||
| if-no-files-found: error | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,3 +2,5 @@ | |
| .scratch/ | ||
| .github/meta/ | ||
| *.log | ||
| dist/ | ||
| __pycache__/ | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # Altimate Code | ||
|
|
||
| This desktop plugin provides skills for dbt and warehouse work and dbt/SQL review. | ||
| Choose plugin setup or ask “Set up Altimate” to get started. Setup is user initiated. | ||
|
|
||
| The Altimate CLI is installed separately. Setup checks for `altimate-code` or | ||
| `altimate`, explains installation choices, and guides you to authenticate in your | ||
| own terminal. You can request the npm installation: | ||
|
|
||
| ```sh | ||
| npm install -g @altimateai/altimate-code | ||
| ``` | ||
|
|
||
| For the standalone installer, follow the | ||
| [CLI installation instructions](https://github.com/AltimateAI/altimate-code) | ||
| in your own terminal. Then choose a dbt/warehouse task or request a dbt/SQL review. | ||
|
|
||
| This directory package excludes lifecycle hooks. For optional automatic session | ||
| behavior and workspace team rules, follow the | ||
| [full GitHub plugin installation](https://github.com/AltimateAI/altimate-codex-plugin#install). | ||
| Disable the directory copy first to avoid duplicate skills. Review and trust the | ||
| manual plugin's hooks before use. This is a guided switch, not an automatic upgrade. | ||
| To switch back, disable the manual copy and re-enable the directory copy. | ||
|
|
||
| Read [PRIVACY.md](PRIVACY.md) before enabling learning. The CLI and its provider | ||
| have separate authentication and data processing. See [TERMS.md](TERMS.md) and | ||
| [SECURITY.md](SECURITY.md), or [get support](https://github.com/AltimateAI/altimate-codex-plugin/issues). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| # Altimate Code: directory installation | ||
|
|
||
| Altimate Code provides skills for dbt and warehouse work and dbt/SQL review. | ||
| The Altimate CLI must be installed separately. Run plugin setup (`get-started`) | ||
| to check the CLI, choose an installation method and configure authentication in | ||
| your terminal. Setup is user-initiated, not an automatic popup. | ||
|
|
||
| ## Two distributions | ||
|
|
||
| | Capability | Public-directory ZIP | GitHub marketplace plugin | | ||
| |---|---|---| | ||
| | Altimate Code and review skills | Included, identical source files | Included | | ||
| | Guided setup skill and listing images | Included | Included | | ||
| | Lifecycle hooks and legacy commands | Excluded | Included | | ||
| | Local stdio MCP | Excluded by default; optional approved-partner build | Included when the source plugin provides it | | ||
| | Automatic team rules and optional learning | Not provided by this package | Requires trusted hooks, a linked workspace and a compatible CLI | | ||
|
|
||
| The GitHub plugin remains in `.codex-plugin/plugin.json` format. Do not add a | ||
| root Agent Plugins `plugin.json`: format changes can change hook loading. | ||
| The directory build derives a separate archive without modifying that source. | ||
|
|
||
| ## Build from the repository | ||
|
|
||
| Run `python3 scripts/build_directory_zip.py`. The version comes from the source | ||
| manifest; the output is `dist/altimate-code-<version>.zip`. CI builds and uploads | ||
| this archive after its package tests pass. The archive root is the plugin root, | ||
| not a wrapping repository folder. Repeated builds of identical sources produce | ||
| identical bytes. Increase the source version for a new submission. | ||
|
|
||
| The builder includes only Markdown skills, image assets (with validated square | ||
| SVG listing icons), the legacy manifest, | ||
| the user-facing DIRECTORY-README.md (as README.md) and legal/security documents. It removes hooks, legacy commands, | ||
| app references and MCP registration, and sets `requires_local_executor: true`. | ||
| It rejects missing manifest-referenced icons and onboarding files, and unsupported | ||
| file types. It does not parse links or resource references inside skill Markdown; | ||
| check those manually during installation testing. New skills that require scripts need a deliberate | ||
| packaging change and tests before they can be included. | ||
|
|
||
| Only after OpenAI confirms local MCP eligibility for the submitting organization, | ||
| use `python3 scripts/build_directory_zip.py --include-local-mcp`. This requires a | ||
| source `.mcp.json` with stdio servers and creates a distinct `-local-mcp.zip`. | ||
| MCP `env` values must be `${VARIABLE}` references; literal values are rejected. | ||
| Only `mcpServers` is accepted at the top level, with `command`, `args`, `cwd`, | ||
| `env` and optional `type: "stdio"` per server. Unknown fields are rejected. | ||
| Commands and arguments use a deliberately small portable grammar: names and | ||
| relative paths containing ASCII letters, digits, underscores, dots, hyphens and | ||
| slashes; paths cannot contain empty, dot or parent components. `${PLUGIN_ROOT}` | ||
| may prefix a path. Options use `--name`, `-n`, or `--name=value`; glued path flags, | ||
| URI/colon syntax, other variables, absolute and home-relative paths are rejected. | ||
| Credential-named options must use environment references instead. This is not a | ||
| general-purpose secret scanner: review all names and arguments for secrets before | ||
| upload. Arbitrary shell expressions and launcher-specific syntax are unsupported. | ||
| The flag records the operator's choice; it cannot verify OpenAI allowlisting. | ||
| It does not add a server or bundle the separately installed CLI. Confirm that | ||
| external CLI dependency is accepted for your submission before uploading. | ||
|
|
||
| ## Before submitting | ||
|
|
||
| The listing images use the existing Altimate gradient mark from | ||
| `AltimateAI/altimate-frontend`, `apps/web/src/assets/images/altimate_logo.svg`, | ||
| revision `854b86ad83d8d1a6cab576aab1dad1abfc573f78`. | ||
| The source SHA-256 is `d643aeef2a7ff3442901391f32b3f6bef280e9e8c7bcc164727030a0e93f6d1b`. | ||
| Only the outer SVG dimensions and viewBox differ: transparent square padding | ||
| centers the original artwork without changing its paths, gradients or colors. | ||
|
|
||
| - Complete organization/publisher identity verification and confirm submission | ||
| access. A successful build is not directory approval. | ||
| - Test a clean desktop install, setup and the actual skills using the built ZIP. | ||
| - Select the listing route before the first upload: OpenAI currently does not | ||
| support adding MCP to an existing skills-only listing. This builder does not | ||
| implement a remote HTTPS MCP service. | ||
| - If skills-only submissions are rejected, reply to the review email or contact | ||
| your OpenAI representative with the submission and organization IDs. Setting | ||
| `requires_local_executor` does not bypass eligibility requirements. | ||
| - Recheck the [submission rules](https://developers.openai.com/plugins/deploy/submission) | ||
| and [desktop-only rules](https://developers.openai.com/plugins/deploy/desktop-only). | ||
| Desktop-only directory installation is documented for the ChatGPT desktop app; | ||
| do not promise public-directory CLI installation. | ||
|
|
||
| ## Optional hooks | ||
|
|
||
| For automatic session behavior, follow the | ||
| [GitHub installation instructions](https://github.com/AltimateAI/altimate-codex-plugin#install). | ||
| Disable the directory copy before enabling the manual plugin. Review and trust | ||
| hooks in `/hooks` in Codex CLI; new or changed definitions need review again. | ||
| Read [the privacy policy](https://github.com/AltimateAI/altimate-codex-plugin/blob/main/PRIVACY.md) | ||
| before enabling learning. To return to the directory version, disable the manual | ||
| plugin and re-enable the directory copy. The directory's core skills remain useful | ||
| without hooks; this optional flow must be disclosed during submission review. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.