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
One-time Terminal setup
Add the private plugin source once, then use Agency OS inside the Codex app.
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 the exact GitHub username you are signed in with.
- OKMuhammad added you as a collaborator to asmaldigital/agency-os-codex.
- OKYou accepted the GitHub collaborator invitation at github.com/asmaldigital/agency-os-codex/invitations.
- OKYou have Codex installed on your computer.
The repository is private. Accept the invite first, then run the Terminal setup command below. If you skip the GitHub invite step, the install command will fail even if the command is typed correctly.
Install Steps
The Agency OS plugin will not appear in the Codex app by default. Add it once in Terminal, then use it from the Codex app.
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 private Agency OS plugin source
After accepting the GitHub invite, run this one-time Terminal command exactly as shown. This connects Codex to the private Agency OS Codex repository.
Terminal
codex plugin marketplace add asmaldigital/agency-os-codex --ref main
4
Restart Codex and install from the app
Quit and reopen the Codex app. Go to Plugins, find Agency OS Codex, then install or enable it there.
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, Agency OS Codex should appear in the Codex app under Plugins. 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 private plugin source when Muhammad announces a new Agency OS Codex version.
Terminal
codex plugin marketplace upgrade agency-os-codex-marketplace
After the upgrade finishes, restart the Codex app, 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
If Terminal says you are logged in, but the install still says remote: Repository not found, that GitHub account does not have accepted access to the private repo yet. Send Muhammad the exact username shown in Terminal, accept the GitHub collaborator invite at github.com/asmaldigital/agency-os-codex/invitations, then run gh auth login again.
Agency OS does not appear in the Codex app
Restart Codex, then open Plugins again. If it still does not appear, rerun the one-time Terminal 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 private plugin source, 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.