Codex CLI cannot tag / explicitly invoke configured subagents like the Codex app

What version of Codex CLI is running?

codex-cli 0.147.0

What subscription do you have?

Plus

Which model were you using?

gpt-5.6-sol

What platform is your computer?

Win 11 Pro x64

What terminal emulator and version are you using (if applicable)?

PowerShell

Codex doctor report

{
  "schemaVersion": 1,
  "generatedAt": "1786552514s since unix epoch",
  "overallStatus": "warning",
  "codexVersion": "0.147.0",
  "checks": {
    "app_server.status": {
      "id": "app_server.status",
      "category": "app-server",
      "status": "ok",
      "summary": "background server is not running",
      "details": {
        "control socket": "<REDACTED_LOCAL_PATH>",
        "daemon state dir": "<REDACTED_LOCAL_PATH>",
        "mode": "ephemeral",
        "pid file": "<REDACTED_LOCAL_PATH> (missing)",
        "settings": "<REDACTED_LOCAL_PATH> (missing)",
        "status": "not running",
        "update-loop pid file": "<REDACTED_LOCAL_PATH> (missing)"
      },
      "remediation": null,
      "durationMs": 0
    },
    "auth.credentials": {
      "id": "auth.credentials",
      "category": "auth",
      "status": "ok",
      "summary": "auth is configured",
      "details": {
        "auth file": "<REDACTED_LOCAL_PATH>",
        "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": "<REDACTED_LOCAL_PATH>",
        "config.toml": "<REDACTED_LOCAL_PATH>",
        "config.toml parse": "ok",
        "cwd": "<REDACTED_LOCAL_PATH>",
        "enabled feature flags": "<redacted>",
        "feature flag overrides": "memories=true, prevent_idle_sleep=true",
        "feature flags enabled": "41",
        "log dir": "<REDACTED_LOCAL_PATH>",
        "mcp servers": "0",
        "model": "gpt-5.6-sol",
        "model provider": "openai",
        "sqlite home": "<REDACTED_LOCAL_PATH>"
      },
      "remediation": null,
      "durationMs": 3
    },
    "git.environment": {
      "id": "git.environment",
      "category": "git",
      "status": "ok",
      "summary": "git version 2.54.0.windows.1",
      "details": {
        "PATH git #1": "C:\\Program Files\\Git\\cmd\\git.exe",
        "PATH git entries": "1",
        "git build options": "git version 2.54.0.windows.1; cpu: x86_64; built from commit: 2b8a3ab140826ac423c2845ef81d4c6ac4f7bf3c; sizeof-long: 4; sizeof-size_t: 8; shell-path: D:/git-sdk-64-build-installers/usr/bin/sh; rust: disabled; feature: fsmonitor--daemon; gettext: enabled; libcurl: 8.19.0; OpenSSL: OpenSSL 3.5.6 7 Apr 2026; zlib: 1.3.2; SHA-1: SHA1_DC; SHA-256: SHA256_BLK; default-ref-format: files; default-hash: sha1",
        "git exec path": "C:/Program Files/Git/mingw64/libexec/git-core",
        "git version": "git version 2.54.0.windows.1",
        "repo detected": "false",
        "selected git": "C:\\Program Files\\Git\\cmd\\git.exe"
      },
      "remediation": null,
      "durationMs": 171
    },
    "installation": {
      "id": "installation",
      "category": "install",
      "status": "ok",
      "summary": "installation looks consistent",
      "details": {
        "PATH codex #1": "<REDACTED_LOCAL_PATH>",
        "PATH codex #2": "<REDACTED_LOCAL_PATH>",
        "PATH codex #3": "<REDACTED_LOCAL_PATH>",
        "PATH codex #4": "<REDACTED_LOCAL_PATH>",
        "PATH codex #5": "<REDACTED_LOCAL_PATH>",
        "PATH codex entries": "5",
        "current executable": "<REDACTED_LOCAL_PATH>",
        "install context": "npm (<REDACTED_LOCAL_PATHS>)",
        "managed by bun": "false",
        "managed by npm": "true",
        "managed by pnpm": "false",
        "managed package root": "<REDACTED_LOCAL_PATH>",
        "npm update target": "<REDACTED_LOCAL_PATH>"
      },
      "remediation": null,
      "durationMs": 512
    },
    "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": 249
    },
    "network.websocket_reachability": {
      "id": "network.websocket_reachability",
      "category": "websocket",
      "status": "ok",
      "summary": "Responses WebSocket handshake succeeded",
      "details": {
        "DNS": "1 IPv4, 1 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": 1401
    },
    "runtime.provenance": {
      "id": "runtime.provenance",
      "category": "runtime",
      "status": "ok",
      "summary": "running npm on windows-x86_64",
      "details": {
        "commit": "unknown",
        "current executable": "<REDACTED_LOCAL_PATH>",
        "install method": "npm (<REDACTED_LOCAL_PATHS>)",
        "platform": "windows-x86_64",
        "version": "0.147.0"
      },
      "remediation": null,
      "durationMs": 1
    },
    "runtime.search": {
      "id": "runtime.search",
      "category": "search",
      "status": "ok",
      "summary": "search is OK (bundled)",
      "details": {
        "search command": "<REDACTED_LOCAL_PATH>",
        "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": "Never",
        "codex-linux-sandbox helper": "none",
        "execve wrapper helper": "none",
        "filesystem sandbox": "unrestricted",
        "network sandbox": "enabled"
      },
      "remediation": null,
      "durationMs": 0
    },
    "state.paths": {
      "id": "state.paths",
      "category": "state",
      "status": "ok",
      "summary": "state paths and databases are inspectable",
      "details": {
        "CODEX_HOME": "<REDACTED_LOCAL_PATH> (dir)",
        "active rollout files": "326 files, 634326959 total bytes, 1945788 average bytes",
        "archived rollout files": "0 files, 0 total bytes, 0 average bytes",
        "goals DB": "<REDACTED_LOCAL_PATH> (file)",
        "goals DB integrity": "ok",
        "log DB": "<REDACTED_LOCAL_PATH> (file)",
        "log DB integrity": "ok",
        "log dir": "<REDACTED_LOCAL_PATH> (dir)",
        "memories DB": "<REDACTED_LOCAL_PATH> (file)",
        "memories DB integrity": "ok",
        "queue DB": "<REDACTED_LOCAL_PATH> (file)",
        "queue DB integrity": "ok",
        "sqlite home": "<REDACTED_LOCAL_PATH> (dir)",
        "state DB": "<REDACTED_LOCAL_PATH> (file)",
        "state DB integrity": "ok",
        "thread history DB": "<REDACTED_LOCAL_PATH> (file)",
        "thread history DB integrity": "ok"
      },
      "remediation": null,
      "durationMs": 18082
    },
    "state.rollout_db_parity": {
      "id": "state.rollout_db_parity",
      "category": "threads",
      "status": "warning",
      "summary": "rollout files and state DB thread inventory differ",
      "details": {
        "default model provider": "openai",
        "rollout DB active files": "326",
        "rollout DB active rows": "387",
        "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=383, =4",
        "rollout DB rows": "387",
        "rollout DB scan cap reached": "false",
        "rollout DB scan errors": "0",
        "rollout DB sources": "subagent:thread_spawn=225, subagent:other=74, vscode=36, exec=31, cli=21",
        "rollout DB stale row sample": [
          "<REDACTED_SESSION_PATH>",
          "<REDACTED_SESSION_PATH>",
          "<REDACTED_SESSION_PATH>",
          "<REDACTED_SESSION_PATH>",
          "<REDACTED_SESSION_PATH>"
        ],
        "rollout DB stale rows": "61"
      },
      "issues": [
        {
          "severity": "warning",
          "cause": "state DB rows point at missing or unusable rollout files",
          "measured": "61 stale rows",
          "expected": "every state DB rollout path is a file on disk",
          "remedy": null,
          "fields": []
        }
      ],
      "remediation": null,
      "durationMs": 11623
    },
    "system.environment": {
      "id": "system.environment",
      "category": "system",
      "status": "ok",
      "summary": "OS language en-US",
      "details": {
        "EDITOR": "not set",
        "VISUAL": "not set",
        "os": "Windows 10.0.26200 (Windows 11 Professional) [64-bit]",
        "os language": "en-US",
        "os type": "Windows",
        "os version": "10.0.26200"
      },
      "remediation": null,
      "durationMs": 8
    },
    "terminal.env": {
      "id": "terminal.env",
      "category": "terminal",
      "status": "ok",
      "summary": "terminal metadata was detected",
      "details": {
        "WT_SESSION": "present",
        "color output": "enabled",
        "console input code page": "437",
        "console output code page": "437",
        "stderr console mode": "0x00000007 (VT processing: true)",
        "stderr is terminal": "true",
        "stdin is terminal": "true",
        "stdout console mode": "0x00000007 (VT processing: true)",
        "stdout is terminal": "true",
        "terminal": "Windows Terminal",
        "terminal size": "120x30"
      },
      "remediation": null,
      "durationMs": 1
    },
    "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": "cwd",
        "terminal title project value": "<REDACTED>",
        "terminal title source": "default"
      },
      "remediation": null,
      "durationMs": 1
    },
    "updates.status": {
      "id": "updates.status",
      "category": "updates",
      "status": "warning",
      "summary": "update configuration is locally consistent",
      "details": {
        "cached latest version": "0.147.0",
        "check for update on startup": "true",
        "last checked at": "2026-08-09T11:48:19.959694600Z",
        "latest version probe": "curl: (28) Operation timed out after 10265 milliseconds with 0 bytes received",
        "npm update target": "<REDACTED_LOCAL_PATH>",
        "update action": "npm install -g @openai/codex",
        "version cache": "<REDACTED_LOCAL_PATH>"
      },
      "remediation": null,
      "durationMs": 10771
    }
  }
}

What issue are you seeing?

Codex CLI does not appear to provide a way to tag or explicitly invoke a configured subagent from the prompt, even though this workflow is available in the Codex app.

In the Codex app, I can explicitly select/tag a particular subagent when I want a task delegated to that agent.

In the CLI, I can have subagents configured and Codex may decide to use them autonomously, but I cannot directly tell Codex something equivalent to:

@repo-scout inspect the authentication implementation

or:

Ask @researcher to investigate this dependency.

There is no agent autocomplete/mention UI when typing @, and I have not found another CLI syntax that lets me explicitly address one of my configured subagents.

This makes custom agents considerably less useful in CLI workflows because I often know which agent I want to handle a particular part of the task and do not want to rely on the parent agent deciding whether and how to delegate it.

What steps can reproduce the bug?

Configure one or more custom/subagents that Codex can use.
Open the Codex app and start a session.
Use the app's agent-tagging/selection functionality to explicitly direct work to a particular subagent.
Open Codex CLI with the same setup.
Start typing a prompt and attempt to explicitly reference one of those agents.
Type @ or the agent's name.
No subagent autocomplete/selection appears, and the agent cannot be explicitly addressed in the same way as in the Codex app.

For example:

@repo-scout map the parts of this repository involved in authentication.

The CLI treats this as ordinary prompt text rather than resolving repo-scout as a configured subagent.

What is the expected behavior?

Codex CLI should support explicit subagent invocation with behavior comparable to the Codex app.

Ideally, typing:

@

would show configured/available subagents, similar to other CLI autocomplete menus.

I should then be able to write something such as:

@repo-scout inspect the repository and report which files are relevant.

and have Codex explicitly run that task using the selected subagent.

It would also be useful for mentions to work inside larger orchestration prompts, for example:

@repo-scout find the relevant code, then have @reviewer check the proposed fix.

The parent agent should still be free to autonomously spawn/delegate to agents when appropriate. This request is specifically about also giving the user an explicit way to choose a subagent, as is possible in the Codex app.

Additional information

This is especially useful for workflows with specialized custom agents such as:

repository scouts
code reviewers
researchers
test/debug agents
implementation agents

Without explicit addressing, defining several specialized subagents is less predictable from the CLI because the user has to ask the main agent to delegate indirectly and hope it chooses the intended agent.

If the app and CLI share the same underlying subagent system, exposing agent mentions/autocomplete in the CLI would make the two interfaces much more consistent