›_ Codex Issues
Codex Issues / #31247

Exact skill names should rank above fuzzy matches

Open 💬 0 comments Opened Jul 6, 2026 by turbonate

What version of Codex CLI is running?

codex-cli 0.142.5

What subscription do you have?

foundry

Which model were you using?

gpt5.5

What platform is your computer?

windows WSL Ubuntu 24.04, bare metal Ubuntu Server 24.04, and bare metal Ubuntu Server 26.04

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

bash with zellij or zellij attach from within vscode bash terminal

Codex doctor report

<redacted-user>@HX370:~/projects/<redacted-project>$ codex doctor --json
{
  "schemaVersion": 1,
  "generatedAt": "1783343276s since unix epoch",
  "overallStatus": "ok",
  "codexVersion": "0.142.5",
  "checks": {
    "app_server.status": {
      "id": "app_server.status",
      "category": "app-server",
      "status": "ok",
      "summary": "background server is not running",
      "details": {
        "control socket": "/home/<redacted-user>/.codex/app-server-control/app-server-contr
        "daemon state dir": "/home/<redacted-user>/.codex/app-server-daemon",
        "mode": "ephemeral",
        "pid file": "/home/<redacted-user>/.codex/app-server-daemon/app-server.pid (missing
        "settings": "/home/<redacted-user>/.codex/app-server-daemon/settings.json (missing)
        "status": "not running",
        "update-loop pid file": "/home/<redacted-user>/.codex/app-server-daemon/app-server-
      },
      "remediation": null,
      "durationMs": 0
    },
    "auth.credentials": {
      "id": "auth.credentials",
      "category": "auth",
      "status": "ok",
      "summary": "auth is provided by the active model provider",
      "details": {
        "auth file": "/home/<redacted-user>/.codex/auth.json",
        "auth storage mode": "File",
        "model provider requires OpenAI auth": "false",
        "provider auth env var": "AZURE_OPENAI_API_KEY (present)"
      },
      "remediation": null,
      "durationMs": 0
    },
    "config.load": {
      "id": "config.load",
      "category": "config",
      "status": "ok",
      "summary": "config loaded",
      "details": {
        "CODEX_HOME": "/home/<redacted-user>/.codex",
        "config.toml": "/home/<redacted-user>/.codex/config.toml",
        "config.toml parse": "ok",
        "cwd": "/home/<redacted-user>/projects/<redacted-project>",
        "enabled feature flags": "shell_tool, unified_exec, shell_snapshot, terminal_resiz
        "feature flag overrides": "none",
        "feature flags enabled": "33",
        "log dir": "/home/<redacted-user>/.codex/log",
        "mcp servers": "0",
        "model": "gpt-5.5",
        "model provider": "azure",
        "sqlite home": "/home/<redacted-user>/.codex"
      },
      "remediation": null,
      "durationMs": 0
    },
    "git.environment": {
      "id": "git.environment",
      "category": "git",
      "status": "ok",
      "summary": "git version 2.43.0",
      "details": {
        ".git entry": "directory",
        "PATH git #1": "/usr/bin/git",
        "PATH git #2": "/bin/git",
        "PATH git entries": "2",
        "git branch": "<redacted-branch>",
        "git build options": "git version 2.43.0; cpu: x86_64; no commit associated with t
        "git exec path": "/usr/lib/git-core",
        "git version": "git version 2.43.0",
        "repo detected": "true",
        "repo root": "/home/<redacted-user>/projects/<redacted-project>",
        "selected git": "/usr/bin/git"
      },
      "remediation": null,
      "durationMs": 122
    },
    "installation": {
      "id": "installation",
      "category": "install",
      "status": "ok",
      "summary": "installation looks consistent",
      "details": {
        "PATH codex #1": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/bin/codex",
        "current executable": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/lib/node_mo
        "install context": "npm (package /home/<redacted-user>/.nvm/versions/node/v25.9.0/l
        "managed by bun": "false",
        "managed by npm": "true",
        "managed package root": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/lib/node_
        "npm update target": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/lib/node_mod
      },
      "remediation": null,
      "durationMs": 328
    },
    "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": {
        "azure API base URL": "<redacted-url>"
        "reachability mode": "provider auth"
      },
      "remediation": null,
      "durationMs": 251
    },
    "network.websocket_reachability": {
      "id": "network.websocket_reachability",
      "category": "websocket",
      "status": "ok",
      "summary": "Responses WebSocket is not enabled for the active provider",
      "details": {
        "model provider": "azure",
        "provider name": "Azure OpenAI",
        "proxy env vars": "none",
        "supports websockets": "false",
        "wire API": "responses"
      },
      "remediation": null,
      "durationMs": 0
    },
    "runtime.provenance": {
      "id": "runtime.provenance",
      "category": "runtime",
      "status": "ok",
      "summary": "running npm on linux-x86_64",
      "details": {
        "commit": "unknown",
        "current executable": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/lib/node_mo
        "install method": "npm (package /home/<redacted-user>/.nvm/versions/node/v25.9.0/li
        "platform": "linux-x86_64",
        "version": "0.142.5"
      },
      "remediation": null,
      "durationMs": 0
    },
    "runtime.search": {
      "id": "runtime.search",
      "category": "search",
      "status": "ok",
      "summary": "search is OK (bundled)",
      "details": {
        "search command": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/lib/node_module
        "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/<redacted-user>/.codex/tmp/arg0/codex-arg0dvNu
        "execve wrapper helper": "/home/<redacted-user>/.codex/tmp/arg0/codex-arg0dvNuTq/co
        "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/<redacted-user>/.codex (dir)",
        "active rollout files": "256 files, 215650428 total bytes, 842384 average bytes",
        "archived rollout files": "0 files, 0 total bytes, 0 average bytes",
        "goals DB": "/home/<redacted-user>/.codex/goals_1.sqlite (file)",
        "goals DB integrity": "ok",
        "log DB": "/home/<redacted-user>/.codex/logs_2.sqlite (file)",
        "log DB integrity": "ok",
        "log dir": "/home/<redacted-user>/.codex/log (dir)",
        "memories DB": "/home/<redacted-user>/.codex/memories_1.sqlite (file)",
        "memories DB integrity": "ok",
        "sqlite home": "/home/<redacted-user>/.codex (dir)",
        "state DB": "/home/<redacted-user>/.codex/state_5.sqlite (file)",
        "state DB integrity": "ok"
      },
      "remediation": null,
      "durationMs": 7590
    },
    "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": "azure",
        "rollout DB active files": "256",
        "rollout DB active rows": "256",
        "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": "azure=256",
        "rollout DB rows": "256",
        "rollout DB scan cap reached": "false",
        "rollout DB scan errors": "0",
        "rollout DB sources": "subagent:thread_spawn=188, cli=68",
        "rollout DB stale rows": "0"
      },
      "remediation": null,
      "durationMs": 4298
    },
    "system.environment": {
      "id": "system.environment",
      "category": "system",
      "status": "ok",
      "summary": "OS language C",
      "details": {
        "EDITOR": "not set",
        "LANG": "C.UTF-8",
        "VISUAL": "not set",
        "os": "Ubuntu 24.4.0 (noble) [64-bit]",
        "os language": "C",
        "os type": "Ubuntu",
        "os version": "24.4.0"
      },
      "remediation": null,
      "durationMs": 17
    },
    "terminal.env": {
      "id": "terminal.env",
      "category": "terminal",
      "status": "ok",
      "summary": "terminal metadata was detected",
      "details": {
        "DISPLAY": "present",
        "WAYLAND_DISPLAY": "present",
        "WSL_DISTRO_NAME": "present",
        "WSL_INTEROP": "present",
        "WT_SESSION": "present",
        "color output": "enabled",
        "effective locale": "C.UTF-8",
        "multiplexer": "zellij 0.44.1",
        "stderr is terminal": "true",
        "stdin is terminal": "true",
        "stdout is terminal": "true",
        "terminal": "Windows Terminal",
        "terminal size": "90x52"
      },
      "remediation": null,
      "durationMs": 1068
    },
    "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": "<redacted-project>",
        "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.142.5",
        "check for update on startup": "true",
        "last checked at": "2026-07-06T10:52:41.739354518Z",
        "latest version": "0.142.5",
        "latest version status": "current version is not older",
        "npm update target": "/home/<redacted-user>/.nvm/versions/node/v25.9.0/lib/node_modules/@openai/codex",
        "update action": "npm install -g @openai/codex",
        "version cache": "/home/<redacted-user>/.codex/version.json"
      },
      "remediation": null,
      "durationMs": 321
    }
  }
}

What issue are you seeing?

Exact skill names should rank above fuzzy matches

When multiple skills match a query, an exact match (e.g. $finish) should always rank above partial/fuzzy matches such as "Finishing a Development Branch".

Current behavior:

Custom skill: $finish
Superpowers skill: Finishing a Development Branch
Typing $finish shows the Superpowers skill first.

<img width="1436" height="298" alt="Image" src="https://github.com/user-attachments/assets/d89a6abe-41ea-4288-bf61-9c39f12be007" />

Expected behavior:

Exact trigger/alias match should have highest priority.
Ranking should be:

  1. Exact trigger
  2. Exact alias
  3. Prefix match
  4. Fuzzy similarity

This makes it difficult when project specific skill keying can be hijacked by fuzzy matches for plugins.

What steps can reproduce the bug?

install Superpowers plugin
add repo skill $finish to <project>/.agents/skills/finish/SKILL.md

attempt to use skill: $finish

What is the expected behavior?

Exact trigger/alias match should have highest priority.
Ranking should be:

  1. Exact trigger
  2. Exact alias
  3. Prefix match
  4. Fuzzy similarity

Additional information

Ironically had the exact same bug in my own product that we released a fix for last month. :) Love your stuff, y'all are doing good work.

View original on GitHub ↗