Custom subagents in ~/.codex/agents/*.toml are not applied on spawn
Resolved 💬 1 comment Opened Jun 7, 2026 by chrizzlekicks Closed Jun 9, 2026
What version of Codex CLI is running?
0.137.0
What subscription do you have?
Plus
Which model were you using?
gpt-5.4
What platform is your computer?
Linux 7.0.10-arch1-1 x86_64 unknown
What terminal emulator and version are you using (if applicable)?
alacritty + tmux
Codex doctor report
{
"schemaVersion": 1,
"generatedAt": "1780825184s since unix epoch",
"overallStatus": "ok",
"codexVersion": "0.137.0",
"checks": {
"app_server.status": {
"id": "app_server.status",
"category": "app-server",
"status": "ok",
"summary": "background server is not running",
"details": {
"control socket": "/home/chrizzle/.codex/app-server-control/app-server-control.sock",
"daemon state dir": "/home/chrizzle/.codex/app-server-daemon",
"mode": "ephemeral",
"pid file": "/home/chrizzle/.codex/app-server-daemon/app-server.pid (missing)",
"settings": "/home/chrizzle/.codex/app-server-daemon/settings.json (missing)",
"status": "not running",
"update-loop pid file": "/home/chrizzle/.codex/app-server-daemon/app-server-updater.pid (missing)"
},
"remediation": null,
"durationMs": 0
},
"auth.credentials": {
"id": "auth.credentials",
"category": "auth",
"status": "ok",
"summary": "auth is configured",
"details": {
"auth file": "/home/chrizzle/.codex/auth.json",
"auth storage mode": "File",
"stored API key": "false",
"stored ChatGPT tokens": "true",
"stored agent identity": "false",
"stored auth mode": "chatgpt"
},
"remediation": null,
"durationMs": 0
},
"config.load": {
"id": "config.load",
"category": "config",
"status": "ok",
"summary": "config loaded",
"details": {
"CODEX_HOME": "/home/chrizzle/.codex",
"config.toml": "/home/chrizzle/.codex/config.toml",
"config.toml parse": "ok",
"cwd": "/home/chrizzle/projects/flacser",
"enabled feature flags": "shell_tool, unified_exec, shell_snapshot, terminal_resize_reflow, sqlite, hooks, enable_request_compression, multi_agent, apps, tool_suggest, plugins, in_app_browser, browser_use, browser_use_external, computer_use, plugin_sharing, image_generation, skill_mcp_dependency_install, steer, guardian_approval, goals, collaboration_modes, tool_call_mcp_elicitation, personality, fast_mode, tui_app_server, workspace_dependencies",
"feature flag overrides": "none",
"feature flags enabled": "27",
"log dir": "/home/chrizzle/.codex/log",
"mcp servers": "0",
"model": "gpt-5.4",
"model provider": "openai",
"sqlite home": "/home/chrizzle/.codex"
},
"remediation": null,
"durationMs": 0
},
"git.environment": {
"id": "git.environment",
"category": "git",
"status": "ok",
"summary": "git version 2.54.0",
"details": {
".git entry": "directory",
"PATH git #1": "/usr/bin/git",
"PATH git entries": "1",
"git branch": "main",
"git build options": "git version 2.54.0; cpu: x86_64; built from commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0; sizeof-long: 8; sizeof-size_t: 8; shell-path: /bin/sh; rust: enabled; gettext: enabled; libcurl: 8.19.0; OpenSSL: OpenSSL 3.6.2 7 Apr 2026; zlib-ng: 2.3.3; SHA-1: SHA1_DC; SHA-256: SHA256_BLK; default-ref-format: files; default-hash: sha1",
"git exec path": "/usr/lib/git-core",
"git version": "git version 2.54.0",
"repo detected": "true",
"repo root": "/home/chrizzle/projects/flacser",
"selected git": "/usr/bin/git"
},
"remediation": null,
"durationMs": 25
},
"installation": {
"id": "installation",
"category": "install",
"status": "ok",
"summary": "installation looks consistent",
"details": {
"PATH codex #1": "/home/chrizzle/.nvm/versions/node/v22.13.1/bin/codex",
"current executable": "/home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex",
"install context": "npm (package /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl, bin /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin, resources /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/codex-resources, path /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/codex-path)",
"managed by bun": "false",
"managed by npm": "true",
"managed package root": "/home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex",
"npm update target": "/home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex"
},
"remediation": null,
"durationMs": 183
},
"mcp.config": {
"id": "mcp.config",
"category": "mcp",
"status": "ok",
"summary": "no MCP servers configured",
"details": {},
"remediation": null,
"durationMs": 0
},
"network.env": {
"id": "network.env",
"category": "network",
"status": "ok",
"summary": "network-related environment looks readable",
"details": {
"proxy env vars": "none"
},
"remediation": null,
"durationMs": 0
},
"network.provider_reachability": {
"id": "network.provider_reachability",
"category": "reachability",
"status": "ok",
"summary": "active provider endpoints are reachable over HTTP",
"details": {
"ChatGPT base URL": "https://chatgpt.com/backend-api/ reachable (HTTP 403)",
"reachability mode": "ChatGPT auth"
},
"remediation": null,
"durationMs": 127
},
"network.websocket_reachability": {
"id": "network.websocket_reachability",
"category": "websocket",
"status": "ok",
"summary": "Responses WebSocket handshake succeeded",
"details": {
"DNS": "2 IPv4, 2 IPv6, first IPv4",
"auth mode": "chatgpt",
"connect timeout": "15000 ms",
"endpoint": "wss://chatgpt.com/backend-api/<redacted>",
"handshake result": "HTTP 101 Switching Protocols",
"model provider": "openai",
"models etag present": "true",
"provider name": "OpenAI",
"proxy env vars": "none",
"reasoning header": "false",
"server model present": "false",
"supports websockets": "true",
"wire API": "responses"
},
"remediation": null,
"durationMs": 790
},
"runtime.provenance": {
"id": "runtime.provenance",
"category": "runtime",
"status": "ok",
"summary": "running npm on linux-x86_64",
"details": {
"commit": "unknown",
"current executable": "/home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex",
"install method": "npm (package /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl, bin /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin, resources /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/codex-resources, path /home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/codex-path)",
"platform": "linux-x86_64",
"version": "0.137.0"
},
"remediation": null,
"durationMs": 0
},
"runtime.search": {
"id": "runtime.search",
"category": "search",
"status": "ok",
"summary": "search is OK (bundled)",
"details": {
"search command": "/home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/codex-path/rg",
"search command readiness": "file exists",
"search provider": "bundled"
},
"remediation": null,
"durationMs": 0
},
"sandbox.helpers": {
"id": "sandbox.helpers",
"category": "sandbox",
"status": "ok",
"summary": "sandbox configuration is readable",
"details": {
"approval policy": "OnRequest",
"codex-linux-sandbox helper": "/home/chrizzle/.codex/tmp/arg0/codex-arg0Eyz5wt/codex-linux-sandbox",
"execve wrapper helper": "/home/chrizzle/.codex/tmp/arg0/codex-arg0Eyz5wt/codex-execve-wrapper",
"filesystem sandbox": "restricted",
"network sandbox": "restricted"
},
"remediation": null,
"durationMs": 0
},
"state.paths": {
"id": "state.paths",
"category": "state",
"status": "ok",
"summary": "state paths and databases are inspectable",
"details": {
"CODEX_HOME": "/home/chrizzle/.codex (dir)",
"active rollout files": "53 files, 12887447 total bytes, 243159 average bytes",
"archived rollout files": "0 files, 0 total bytes, 0 average bytes",
"goals DB": "/home/chrizzle/.codex/goals_1.sqlite (file)",
"goals DB integrity": "ok",
"log DB": "/home/chrizzle/.codex/logs_2.sqlite (file)",
"log DB integrity": "ok",
"log dir": "/home/chrizzle/.codex/log (dir)",
"memories DB": "/home/chrizzle/.codex/memories_1.sqlite (file)",
"memories DB integrity": "ok",
"sqlite home": "/home/chrizzle/.codex (dir)",
"state DB": "/home/chrizzle/.codex/state_5.sqlite (file)",
"state DB integrity": "ok"
},
"remediation": null,
"durationMs": 270
},
"state.rollout_db_parity": {
"id": "state.rollout_db_parity",
"category": "threads",
"status": "ok",
"summary": "rollout files and state DB thread inventory agree",
"details": {
"default model provider": "openai",
"rollout DB active files": "53",
"rollout DB active rows": "53",
"rollout DB archive mismatches": "0",
"rollout DB archived files": "0",
"rollout DB archived rows": "0",
"rollout DB duplicate DB paths": "0",
"rollout DB duplicate rollout thread ids": "0",
"rollout DB malformed file names": "0",
"rollout DB missing active rows": "0",
"rollout DB missing archived rows": "0",
"rollout DB model providers": "openai=53",
"rollout DB rows": "53",
"rollout DB scan cap reached": "false",
"rollout DB scan errors": "0",
"rollout DB sources": "cli=39, subagent:thread_spawn=10, subagent:review=4",
"rollout DB stale rows": "0"
},
"remediation": null,
"durationMs": 298
},
"system.environment": {
"id": "system.environment",
"category": "system",
"status": "ok",
"summary": "OS language de-DE",
"details": {
"LANG": "de_DE.UTF-8",
"LC_CTYPE": "C.UTF-8",
"os": "Arch Linux [64-bit]",
"os language": "de-DE",
"os type": "Arch Linux",
"os version": "Unknown"
},
"remediation": null,
"durationMs": 1
},
"terminal.env": {
"id": "terminal.env",
"category": "terminal",
"status": "ok",
"summary": "terminal metadata was detected",
"details": {
"COLORTERM": "truecolor",
"DISPLAY": "present",
"TERM": "alacritty",
"WAYLAND_DISPLAY": "present",
"color output": "enabled",
"effective locale": "C.UTF-8",
"multiplexer": "tmux 3.6b",
"stderr is terminal": "true",
"stdin is terminal": "true",
"stdout is terminal": "true",
"terminal": "unknown",
"terminal size": "170x40",
"tmux allow-passthrough": "off",
"tmux client termname": "alacritty",
"tmux extended-keys": "on",
"tmux focus-events": "on",
"tmux set-clipboard": "external",
"tmux xterm-keys": "on"
},
"remediation": null,
"durationMs": 50
},
"terminal.title": {
"id": "terminal.title",
"category": "title",
"status": "ok",
"summary": "terminal title default",
"details": {
"terminal title activity": "true",
"terminal title items": "activity, project-name",
"terminal title project source": "git repo root",
"terminal title project value": "flacser",
"terminal title source": "default"
},
"remediation": null,
"durationMs": 0
},
"updates.status": {
"id": "updates.status",
"category": "updates",
"status": "ok",
"summary": "update configuration is locally consistent",
"details": {
"cached latest version": "0.137.0",
"check for update on startup": "true",
"last checked at": "2026-06-06T20:18:40.678323770Z",
"latest version": "0.137.0",
"latest version status": "current version is not older",
"npm update target": "/home/chrizzle/.nvm/versions/node/v22.13.1/lib/node_modules/@openai/codex",
"update action": "npm install -g @openai/codex",
"version cache": "/home/chrizzle/.codex/version.json"
},
"remediation": null,
"durationMs": 319
}
}
}What issue are you seeing?
Custom subagents placed in ~/.codex/agents/*.toml are not being applied when spawning a child agent.
Instead, the child:
- gets a generic nickname
- inherits the parent runtime model/reasoning settings
- records agent_path = null
This happens even with a minimal fresh repro agent.
Observed child metadata:
agent_nickname = "Kierkegaard"
agent_path = null
model = "gpt-5.4"
reasoning_effort = "medium"
The child completed the task successfully, but none of the custom agent identity/settings appeared to load.
Docs referenced:
- https://developers.openai.com/codex/subagents
- https://developers.openai.com/codex/config-basic#configuration-precedence
What steps can reproduce the bug?
Create ~/.codex/agents/zz-doc-auditor-repro.toml:
name = "zz-doc-auditor-repro"
description = "Temporary repro agent for verifying custom subagent loading."
nickname_candidates = ["ZZReproNick"]
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
developer_instructions = """
You are a temporary repro subagent. Do a tiny read-only repository check and report one short sentence.
"""
Then in an interactive Codex session, ask:
Use the custom zz-doc-auditor-repro subagent for this repository as a repro test. Read README.md and reply with exactly one short sentence saying whether the file exists. Do not edit anything.
What is the expected behavior?
The child should use the custom agent identity:
- nickname from nickname_candidates such as ZZReproNick
- non-null agent_path
- custom agent config applied
Additional information
The docs mention that parent live runtime overrides are reapplied to children, which may explain inherited model settings, but it does not explain:
- generic nickname instead of nickname_candidates
- agent_path = null
- apparent failure to load the custom agent file itself
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗