Access
Private GitHub repo
You need collaborator access before Codex can install the plugin.
Plugin
Agency OS Codex
The Codex edition of the Agency OS workflows and skills.
Install method
Codex marketplace
Add the private repo as a plugin marketplace, then install from Codex.
Before You Start
Complete these checks first. Most install problems happen because the GitHub invite was not accepted or GitHub is not authenticated locally.
- OKYou sent Muhammad your GitHub username.
- OKMuhammad added you as a collaborator to asmaldigital/agency-os-codex.
- OKYou accepted the GitHub collaborator invitation.
- OKYou have Codex installed on your computer.
The repository is private. If you skip the GitHub invite step, the install command will fail even if the command is typed correctly.
Install Steps
Run these commands in your terminal. Keep the repo name exactly as shown.
1
Install Codex
If Codex is already installed, you can skip this step.
Terminal
npm install -g @openai/codex
2
Sign in to GitHub
This lets Codex access the private repository through your collaborator permission.
Terminal
gh auth login
If you do not have GitHub CLI installed, install it from cli.github.com, then run the command again.
3
Add the Agency OS Codex marketplace
This connects Codex to the private plugin marketplace inside the repository.
Terminal
codex plugin marketplace add asmaldigital/agency-os-codex --ref main
4
Open Codex and install the plugin
Open the plugin browser, choose the Agency OS Codex marketplace, then install the Agency OS Codex plugin.
Terminal
codex
Inside Codex
/plugins
5
Start Agency OS
Start a new Codex thread after installation, then ask Codex to run Agency OS.
Prompt
Use Agency OS Codex. Run agency os.
Verify It Worked
After installation, you should see Agency OS Codex in the Codex plugin list. A successful first run will create your local Agency OS workspace and begin the guided setup.
Optional access test
git ls-remote https://github.com/asmaldigital/agency-os-codex.git
If that command shows repository refs instead of an access error, your GitHub access is working.
Getting Updates
New installs use the latest version from the private GitHub repository. Existing installs do not always update automatically, so refresh the marketplace when Muhammad announces a new Agency OS Codex version.
Terminal
codex plugin marketplace upgrade agency-os-codex-marketplace
After the upgrade finishes, restart Codex or start a new Codex session, then open /plugins and update or reinstall Agency OS Codex if Codex shows that option.
Practical rule: new members install the latest version; existing members should run the upgrade command to pull the newest plugin files.
Troubleshooting
Use these fixes if the install does not work the first time.
Repository not found or permission denied
Confirm that Muhammad added the exact GitHub username you are using, then accept the collaborator invitation in GitHub. After that, run gh auth login again.
The marketplace does not appear in Codex
Restart Codex, then open /plugins again. If it still does not appear, rerun the marketplace command and check that the repo name is asmaldigital/agency-os-codex.
The plugin installs but Agency OS does not start
Start a new thread after installation and use the prompt: Use Agency OS Codex. Run agency os.
You installed an older version
Existing installs do not always update automatically. Refresh the marketplace, restart Codex, then reinstall or update the plugin if Codex shows that option.
Terminal
codex plugin marketplace upgrade agency-os-codex-marketplace
Do not share the private repository link publicly. Access is controlled by GitHub collaborator permissions.