CowboyLogic/ai-dev / skills/client-config-codex
client-config-codex
FlaggedManage OpenAI Codex CLI configuration files including config.toml, project .codex/config.toml, profiles, model providers, sandbox and approval settings, permission profiles, rules files, MCP servers, hooks, skills, plugins, custom agents, AGENTS.md instructions, and requirements.toml. Use this skill whenever the user wants to view, edit, add, or understand any Codex setting: trusted projects, approval policy, sandbox mode, network access, allow-listing commands, MCP servers, hooks, skills, plugins and marketplaces, model or reasoning effort, custom model providers, authentication, sessions, or AGENTS.md. Trigger on: "configure codex", "codex config.toml", "trust this project in codex", "codex approval policy", "codex sandbox", "add MCP server to codex", "codex hook", "codex rules", "codex profile", "codex plugin", "set codex model", "codex AGENTS.md", or "show my codex config".
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 3.0 KB |
| SKILL.md | skill md | 8.9 KB |
| references/agents-plugins.md | markdown | 12.8 KB |
| references/cli-commands.md | markdown | 21.2 KB |
| references/config-schema.md | markdown | 43.0 KB |
| references/hooks.md | markdown | 17.0 KB |
| references/instructions.md | markdown | 7.5 KB |
| references/mcp.md | markdown | 12.9 KB |
| references/permissions.md | markdown | 23.9 KB |
| references/skills.md | markdown | 6.6 KB |
| scripts/show-config.py | script | 19.1 KB |
| scripts/update-references.py | script | 6.8 KB |
| sources.json | config | 3.8 KB |
references/agents-plugins.md
View on GitHub# Agents and Plugins Reference
Plugins package reusable capabilities. Subagents delegate work to parallel agents. Verified
against codex-cli 0.163.0.
## Plugins
A plugin can bundle any of:
- **Skills:** reusable instructions, references, and helper scripts.
- **MCP servers:** connections to external systems, with their own auth.
- **Hooks:** lifecycle commands. Scripts must exist in the execution environment, and hooks need
review and trust before they run. See [hooks.md](hooks.md).
- **Browser extensions** and **apps** (connectors).
Plugins work in Codex CLI and the ChatGPT desktop app. The IDE extension does **not** support
plugins. Bundled skills and tools appear in a **new** session after install. Restart or start a
new session before expecting them.
### `codex plugin` commands
```bash
codex plugin list [--marketplace NAME] [--available] [--json]
codex plugin add PLUGIN@MARKETPLACE # or: codex plugin add PLUGIN -m NAME
codex plugin remove PLUGIN@MARKETPLACE # uninstalls and removes the local cache
codex plugin marketplace list [--json]
codex plugin marketplace add SOURCE [--ref REF] [--sparse PATH]... [--json]
codex plugin marketplace upgrade [NAME] [--json] # refresh Git marketplace snapshots; omit NAME for all
codex plugin marketplace remove NAME [--json]
```
- `marketplace add` SOURCE is a local path, `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git
URL. `--sparse` (repeatable) does a sparse checkout for Git sources.
- `plugin list --json` prints `installed` and `available` arrays; `--available` adds uninstalled
marketplace plugins to the JSON. Entries carry `pluginId`, `name`, `marketplaceName`, `version`,
`installed`, `enabled`, `source`, `marketplaceSource` (`sourceType`, `source`), `installPolicy`,
and `authPolicy`. `marketplace list --json` returns `{"marketplaces": [...]}` with `name`, `root`,
and `marketplaceSource` per entry.
- `plugin add --json` prints `pluginId`, `name`, `marketplaceName`, `version`, `installedPath`, and
`authPolicy`; `plugin remove --json` prints `pluginId`, `name`, and `marketplaceName` (field names
from the upstream command reference; not run here, because both commands install or uninstall).
- There is **no** `plugin enable` or `plugin disable` subcommand. Toggle in the CLI with
`/plugins` (select an installed plugin and press Space), or set `enabled` in `config.toml`.
- `/plugins` in a session opens the plugin browser, grouped by marketplace tabs.
- Do not run `add`, `remove`, or `marketplace add` without the user asking. They change installed
state and can trigger auth flows.
### Configuration keys
```toml
[marketplaces.my-team]
source_type = "git" # "git" or "local"
source = "owner/repo" # Git location, or an absolute local marketplace root
ref = "main" # optional branch, tag, or commit
sparse_paths = [".agents/plugins", "plugins/tools"] # optional, Git only
[plugins."tools@my-team"] # key is plugin-name@marketplace-name
enabled = true
[plugins."tools@my-team".mcp_servers.sample] # state and policy for an MCP server the plugin bundles
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]
disabled_tools = []
[plugins."tools@my-team".mcp_servers.sample.tools.search]
approval_mode = "approve"
```
- Marketplaces can be defined in system, cloud-managed, user, or trusted-project `config.toml`.
A local marketplace root contains `.agents/plugins/marketplace.json`.
- `sparse_paths` must include the marketplace catalog and any local plugin directories it
references.
- `plugins.<plugin>.enabled` reads the effective merged config. Trusted-project settings can
override user, cloud-managed, and system defaults. It does not override workspace-managed
states. A marketplace refresh can install or refresh configured plugins even when disabled.
- `[plugins._default] enabled = <bool>` sets a default for installed plugins (new in 0.163.0;
undocumented upstream, from the 0.163.0 config source and schema). Without it, a plugin keeps
the enablement of its source. With it, a plugin whose own `enabled` is unset takes the default,
and an explicit `plugins."<plugin>@<marketplace>".enabled` overrides it. The default cannot
enable a plugin that its source disabled.
- Plugin-bundled MCP servers launch from the plugin. User config controls only on/off and tool
policy, not the transport command.
- Admins can pin `[features].plugins` and `[features].remote_plugin` in `requirements.toml`, and
set `features.plugin_sharing = false` to block workspace sharing. Under
`allow_managed_hooks_only = true`, plugin hooks are skipped. `[features].plugins = false` disables
plugins, including for API-key sign-in.
- `requirements.toml` can also restrict marketplace sources and plugin MCP servers (documented in the
config reference, not exercised here):
`[marketplaces] restrict_to_allowed_sources = true` with
`[marketplaces.allowed_sources.<name>]` entries whose `source` is `git` (`url`, optional `ref`),
`host_pattern` (`host_pattern`), or `local` (`path`); and
`[plugins.<plugin>.mcp_servers.<server>]` with an `identity` (`command` or `url`), where
plugin-bundled servers without a matching entry are disabled.
### Manifest and marketplace files
- The manifest is `.codex-plugin/plugin.json` at the plugin root. The docs confirm the path and
these behaviors: `hooks` may point at `./hooks/hooks.json` (default is `hooks/hooks.json`), and
bundled MCP servers and their OAuth fields (`clientId`, `callbackUrl`, camelCase) live in the
manifest or the plugin's `.mcp.json`.
- The marketplace catalog is `.agents/plugins/marketplace.json`.
> [!NOTE]
> The fetched docs do not document the manifest or catalog schemas. They defer to
> <https://developers.openai.com/plugins/build/plugins> (local scaffolding, marketplace setup,
> manifests, packaging), which is not part of this reference. Fields seen in 26 plugin manifests
> installed on a 0.163.0 machine: `plugin.json` has `name`, `version`, `description`, `author`, `homepage`,
> `repository`, `license`, `keywords`, `skills` (for example `"./skills/"`), `hooks`, `mcpServers`
> (for example `"./.mcp.json"`), `apps` (for example `"./.app.json"`), `interface`, and, in some
> installed manifests, `bundledContentVariant` (purpose undocumented).
> `marketplace.json` has `name`, `interface.displayName`, and a `plugins` array whose entries have
> `name`, `source` (`{"source": "local", "path": "./plugins/x"}`), `policy` (`installation`, for
> example `AVAILABLE`; `authentication`, for example `ON_INSTALL`), and `category`. Treat these as
> observations, not a contract.
> Fetch the developer guide before authoring one.
### Where plugins live
- `codex plugin list` shows each plugin's `SOURCE` path, and `plugin add --json` returns
`installedPath`. Use those, not assumptions.
- On 0.163.0, installed copies sit under
`~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/` (observed, not documented).
Marketplace roots for bundled and curated catalogs sit under `~/.codex/.tmp/` and
`~/.cache/codex-runtimes/`. Do not hand-edit any of these. Remove with `codex plugin remove`.
### Auth and availability
- Signing in with an API key allows browsing and installing supported OpenAI-curated plugins in
the CLI and desktop app. Some plugins are unavailable because their connection flows need
unsupported OAuth capabilities.
- Uninstalling removes the plugin bundle only. Separately connected MCP integrations stay
connected until you disconnect them.
- Plugin capabilities run under the host's sandbox and approval policy. Installing or enabling a
plugin never trusts its hooks.
### Skills versus plugins
Use a plain skill folder for local authoring and repo-scoped workflows. Build a plugin when you
need to distribute a skill, bundle two or more skills, or ship skills alongside a connector. See
[skills.md](skills.md).
## Subagents (overview)
Codex spawns specialized agents in parallel and collects their results in one response. Use them
for read-heavy work such as exploration, tests, triage, and summarization. Be careful with
parallel writers, since edits can conflict. Each subagent does its own model and tool work, so
runs cost noticeably more tokens than a single-agent run.
- Codex delegates only when asked. A direct request ("spawn two agents..."), an applicable
`AGENTS.md`, or a skill that requests delegation triggers it. Descriptions alone do not.
- Subagents inherit the parent's sandbox policy and live runtime overrides (`/permissions`,
`--yolo`). In interactive CLI sessions, approval requests from inactive threads still surface,
labeled with the source thread. Press `o` to open it. In non-interactive runs an action that
needs new approval fails.
- `/subagents` switches between active agent threads; `/agents` opens the agent command center.
- If no subagent model or `model_reasoning_effort` is configured, the subagent inherits the
parent's model and effort. If an explicit spawn request or an `[agents]` default selects a model
without an effort, the subagent uses that model's default reasoning effort.
### Built-in agents
| Name | Role |
|------|------|
| `default` | General-purpose fallback |
| `worker` | Execution-focused: implementation and fixes |
| `explorer` | Read-heavy codebase exploration |
A custom agent with the same `name` overrides a built-in.
### `[agents]` table in `config.toml`
| Key | Purpose |
|-----|---------|
| `agents.enabled` | Multi-agent tools on or off. Default `true` |
| `agents.max_concurrent_threads_per_session` | Cap on concurrent spawned threads, excluding the primary (`agents.max_threads` is a legacy alias) |
| `agents.default_subagent_model` | Default model for spawned agents |
| `agents.default_subagent_reasoning_effort` | Default effort for spawned agents |
| `agents.interrupt_message` | Record a model-visible message on interruption. Default `true` |
Explicit spawn values override the `default_*` keys. Any other key directly under `[agents]` is
read as a role table (`[agents.<name>]` with `description`, `config_file`,
`nickname_candidates`), so a misspelled scalar such as `max_thread = 3` fails config loading.
`multi_agent` is a stable feature flag, on by default (`codex features list`). `multi_agent_v2` is a
separate stable flag that is off by default. From the 0.163.0 config source (not documented
upstream): an enabled `features.multi_agent_v2` takes precedence over `agents.enabled`, and
`agents.max_depth` is ignored by V2.
`features.multi_agent_v2` also accepts a table. The table form turns V2 on only through its own
`enabled = true`: from the 0.163.0 source, `enabled` is the only field that sets the flag, so a
table without it leaves V2 at its default of off, however many other options it sets. Other keys
in the 0.163.0 config schema that have a description there: `max_concurrent_threads_per_session`,
`wait_agent_enabled` (expose the V2 `wait_agent` tool), `disable_direct_message` (disable the
model's direct-message tools; spawning and automatic child results remain),
`expose_spawn_agent_model_overrides` (expose `model` and `reasoning_effort` on the V2 spawn tool),
`subagent_developer_instructions` (override inherited developer instructions for subagents
that have no role-specific instructions), `preserve_fork_prefix` (new in 0.163.0: keep the
parent's model-visible history on full forks and append the child instructions; default `false`,
and legacy compaction without a reusable context baseline still rebuilds), and
`disable_native_tools` (new in 0.163.0: hide the native multi-agent tools while keeping the V2
runtime for host-provided tools). `usage_hint_enabled` is a deprecated compatibility field whose
value is ignored.
### Custom agent files
Each agent is one standalone TOML file: `~/.codex/agents/` (personal) or `.codex/agents/`
(project). Every file needs `name`, `description`, and `developer_instructions`. The `name` field
is authoritative, not the filename.
> [!IMPORTANT]
> Do not write or debug custom agent files from this reference. Load the sibling skill
> `skills/agent-creator-codex/` (its `SKILL.md` and `references/config-reference.md`). It owns the
> file format, which keys Codex actually applies, model and effort resolution, `[agents.<name>]`
> role tables, examples, and troubleshooting.
The general docs and the sibling skill differ on one point:
> [!NOTE]
> The fetched subagents docs say a custom agent file can set `sandbox_mode`, `mcp_servers`, and
> other `config.toml` keys, and that unset ones inherit from the parent. Live probes recorded in
> `agent-creator-codex` show Codex applies only a bounded set of role-file keys and ignores
> `sandbox_mode`, `approval_policy`, and `mcp_servers` (the child inherits the parent's). Follow
> `agent-creator-codex`, not the general docs, when the two differ.
`codex agents` (top-level) is unrelated to custom agent files. It browses agent **sessions** on
the shared local app-server daemon.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |