›_ Codex Issues
Codex Issues / #39805

Codex TUI harness not finding skills when searching ~/.codex

Open 💬 2 comments Opened Aug 20, 2026 by jvasile

What version of Codex CLI is running?

codex-cli 0.149.0

What subscription do you have?

The $20 one, whatever that is

Which model were you using?

5.6-luna

What platform is your computer?

Linux 7.1.3+deb14-amd64 x86_64 unknown

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

wez

Codex doctor report

{
  "schemaVersion": 1,
  "generatedAt": "1787263793s since unix epoch",
  "overallStatus": "warning",
  "codexVersion": "0.149.0",
  "checks": {
    "app_server.status": {
      "id": "app_server.status",
      "category": "app-server",
      "status": "ok",
      "summary": "background server is not running",
      "details": {
        "control socket": "/home/james/.codex/app-server-control/app-server-control.sock",
        "daemon state dir": "/home/james/.codex/app-server-daemon",
        "mode": "ephemeral",
        "pid file": "/home/james/.codex/app-server-daemon/app-server.pid (missing)",
        "settings": "/home/james/.codex/app-server-daemon/settings.json (missing)",
        "status": "not running",
        "update-loop pid file": "/home/james/.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/james/.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/james/.codex",
        "config.toml": "/home/james/.codex/config.toml",
        "config.toml parse": "ok",
        "cwd": "/home/james/src/niri-jv",
        "enabled feature flags": "shell_tool, view_image, unified_exec, shell_snapshot, code_mode_host, terminal_resize_reflow, sqlite, hooks, enable_request_compression, unbounded_connection_retries, multi_agent, apps, tool_search_always_defer_mcp_tools, tool_suggest, plugins, in_app_browser, in_app_chat, in_app_dictation, in_app_updates, browser_use, browser_use_full_cdp_access, browser_use_external, computer_use, remote_plugin, plugin_sharing, image_generation, resize_all_images, item_ids, skill_mcp_dependency_install, skill_search, mentions_v2, steer, guardian_approval, goals, collaboration_modes, tool_call_mcp_elicitation, auth_elicitation, personality, fast_mode, tui_app_server, remote_compaction_v2, workspace_dependencies",
        "feature flag overrides": "none",
        "feature flags enabled": "42",
        "log dir": "/home/james/.codex/log",
        "mcp servers": "0",
        "model": "gpt-5.6-luna",
        "model provider": "openai",
        "sqlite home": "/home/james/.codex"
      },
      "remediation": null,
      "durationMs": 0
    },
    "git.environment": {
      "id": "git.environment",
      "category": "git",
      "status": "ok",
      "summary": "git version 2.53.0",
      "details": {
        ".git entry": "directory",
        "PATH git #1": "/usr/bin/git",
        "PATH git #2": "/bin/git",
        "PATH git entries": "2",
        "git build options": "git version 2.53.0; cpu: x86_64; no commit associated with this build; sizeof-long: 8; sizeof-size_t: 8; shell-path: /bin/sh; rust: disabled; gettext: enabled; libcurl: 8.19.0-rc3; zlib: 1.3.1; 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.53.0",
        "repo detected": "true",
        "repo root": "/home/james/src/niri-jv",
        "selected git": "/usr/bin/git"
      },
      "remediation": null,
      "durationMs": 100
    },
    "installation": {
      "id": "installation",
      "category": "install",
      "status": "ok",
      "summary": "installation looks consistent",
      "details": {
        "PATH codex #1": "/home/james/.local/bin/codex",
        "PATH codex #2": "/home/james/.local/bin/codex",
        "PATH codex entries": "2",
        "current executable": "/home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/bin/codex",
        "install context": "standalone (unix, package /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl, bin /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/bin, resources /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/codex-resources, path /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/codex-path)",
        "managed by bun": "false",
        "managed by npm": "false",
        "managed by pnpm": "false",
        "managed package root": "not set"
      },
      "remediation": null,
      "durationMs": 2
    },
    "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": {
        "managed proxy": "not configured",
        "proxy env vars": "none",
        "respect system proxy": "disabled"
      },
      "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 inference URL": "https://chatgpt.com/backend-api/<redacted> reachable (HTTP 405)",
        "reachability mode": "ChatGPT auth"
      },
      "remediation": null,
      "durationMs": 195
    },
    "network.websocket_reachability": {
      "id": "network.websocket_reachability",
      "category": "websocket",
      "status": "ok",
      "summary": "Responses WebSocket handshake succeeded",
      "details": {
        "DNS": "2 IPv4, 2 IPv6, first IPv6",
        "auth mode": "chatgpt",
        "connect timeout": "15000 ms",
        "endpoint": "wss://chatgpt.com/backend-api/<redacted>",
        "handshake result": "HTTP 101 Switching Protocols",
        "model provider": "openai",
        "provider name": "OpenAI",
        "proxy env vars": "none",
        "reasoning header": "false",
        "server model present": "false",
        "supports websockets": "true",
        "wire API": "responses"
      },
      "remediation": null,
      "durationMs": 825
    },
    "runtime.provenance": {
      "id": "runtime.provenance",
      "category": "runtime",
      "status": "ok",
      "summary": "running standalone on linux-x86_64",
      "details": {
        "commit": "unknown",
        "current executable": "/home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/bin/codex",
        "install method": "standalone (unix, package /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl, bin /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/bin, resources /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/codex-resources, path /home/james/.codex/packages/standalone/releases/0.149.0-x86_64-unknown-linux-musl/codex-path)",
        "platform": "linux-x86_64",
        "version": "0.149.0"
      },
      "remediation": null,
      "durationMs": 0
    },
    "runtime.search": {
      "id": "runtime.search",
      "category": "search",
      "status": "ok",
      "summary": "search is OK (bundled)",
      "details": {
        "search command": "/home/james/.codex/packages/standalone/releases/0.149.0-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/james/.codex/tmp/arg0/codex-arg0uBylSV/codex-linux-sandbox",
        "execve wrapper helper": "/home/james/.codex/tmp/arg0/codex-arg0uBylSV/codex-execve-wrapper",
        "filesystem sandbox": "restricted",
        "network sandbox": "restricted"
      },
      "remediation": null,
      "durationMs": 0
    },
    "security.endpoint": {
      "id": "security.endpoint",
      "category": "security",
      "status": "ok",
      "summary": "endpoint protection is not inspected on this platform",
      "details": {
        "endpoint products": "not inspected on this platform"
      },
      "remediation": null,
      "durationMs": 0
    },
    "state.paths": {
      "id": "state.paths",
      "category": "state",
      "status": "ok",
      "summary": "state paths and databases are inspectable",
      "details": {
        "CODEX_HOME": "/home/james/.codex (dir)",
        "active rollout files": "72 files, 145046499 total bytes, 2014534 average bytes",
        "archived rollout files": "0 files, 0 total bytes, 0 average bytes",
        "goals DB": "/home/james/.codex/goals_1.sqlite (file)",
        "goals DB integrity": "ok",
        "log DB": "/home/james/.codex/logs_2.sqlite (file)",
        "log DB integrity": "ok",
        "log dir": "/home/james/.codex/log (dir)",
        "memories DB": "/home/james/.codex/memories_1.sqlite (file)",
        "memories DB integrity": "ok",
        "queue DB": "/home/james/.codex/queue_1.sqlite (file)",
        "queue DB integrity": "ok",
        "sqlite home": "/home/james/.codex (dir)",
        "standalone release cache": "8 entries in /home/james/.codex/packages/standalone/releases",
        "state DB": "/home/james/.codex/state_5.sqlite (file)",
        "state DB integrity": "ok",
        "thread history DB": "/home/james/.codex/thread_history_1.sqlite (file)",
        "thread history DB integrity": "ok"
      },
      "remediation": null,
      "durationMs": 1352
    },
    "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": "72",
        "rollout DB active rows": "73",
        "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=73",
        "rollout DB rows": "73",
        "rollout DB scan cap reached": "false",
        "rollout DB scan errors": "0",
        "rollout DB sources": "cli=73",
        "rollout DB stale row sample": "/home/james/.codex/sessions/2026/08/10/rollout-2026-08-10T17-06-43-019fed7f-cdb1-70b1-90dc-145386cf5017.jsonl",
        "rollout DB stale rows": "1"
      },
      "issues": [
        {
          "severity": "warning",
          "cause": "state DB rows point at missing or unusable rollout files",
          "measured": "1 stale rows",
          "expected": "every state DB rollout path is a file on disk",
          "remedy": null,
          "fields": []
        }
      ],
      "remediation": null,
      "durationMs": 191
    },
    "system.disk": {
      "id": "system.disk",
      "category": "disk",
      "status": "ok",
      "summary": "sufficient free disk space (111.4 GiB)",
      "details": {
        "CODEX_HOME available": "111.4 GiB",
        "failure threshold": "1.0 GiB",
        "warning threshold": "5.0 GiB",
        "worktree available": "111.4 GiB"
      },
      "remediation": null,
      "durationMs": 0
    },
    "system.environment": {
      "id": "system.environment",
      "category": "system",
      "status": "ok",
      "summary": "OS language en-US",
      "details": {
        "EDITOR": "set",
        "LANG": "en_US.UTF-8",
        "VISUAL": "not set",
        "os": "Debian n/a (forky) [64-bit]",
        "os language": "en-US",
        "os type": "Debian",
        "os version": "n/a"
      },
      "remediation": null,
      "durationMs": 24
    },
    "terminal.env": {
      "id": "terminal.env",
      "category": "terminal",
      "status": "warning",
      "summary": "height 17 rows - content may scroll off (recommended >=24)",
      "details": {
        "COLORTERM": "truecolor",
        "DISPLAY": "present",
        "TERM": "xterm-256color",
        "TERM_PROGRAM": "WezTerm",
        "WAYLAND_DISPLAY": "present",
        "color output": "enabled",
        "effective locale": "en_US.UTF-8",
        "multiplexer": "tmux 3.7b",
        "stderr is terminal": "true",
        "stdin is terminal": "true",
        "stdout is terminal": "true",
        "terminal": "WezTerm",
        "terminal size": "80x17",
        "terminal version": "20240203-110809-5046fc22",
        "tmux allow-passthrough": "all",
        "tmux client termname": "xterm-256color",
        "tmux client termtype": "WezTerm 20240203-110809-5046fc22",
        "tmux extended-keys": "off",
        "tmux focus-events": "on",
        "tmux set-clipboard": "on",
        "tmux xterm-keys": "on"
      },
      "issues": [
        {
          "severity": "warning",
          "cause": "height 17 rows - content may scroll off (recommended >=24)",
          "measured": "80 x 17",
          "expected": ">= 24 rows",
          "remedy": "resize the window to at least 24 rows",
          "fields": [
            "terminal size"
          ]
        }
      ],
      "remediation": null,
      "durationMs": 62
    },
    "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": "niri-jv",
        "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.148.0",
        "check for update on startup": "true",
        "last checked at": "2026-08-20T16:03:58.714840903Z",
        "latest version": "0.149.0",
        "latest version status": "current version is not older",
        "update action": "standalone installer",
        "version cache": "/home/james/.codex/version.json"
      },
      "remediation": null,
      "durationMs": 172
    }
  }
}

What issue are you seeing?

Codex harness doesn't load my skill and so the llm never gets a chance to invoke it. When asked, it said:

› Is ~/.codex/skills/foo not where I am supposed to put a skill?


• Yes, James. ~/.codex/skills/foo/SKILL.md is the expected location for a user-installed skill when ~/.codex is CODEX_HOME. A symlink there is also valid if it resolves to the actual skill directory.


› And you just didn't look there?


• Correct. I failed to inspect ~/.codex/skills/jbug even though it was the expected location. That was my error.

Skill discovery not being deterministic is just... I don't even know what to say. Anyway, switching back to Claude because I actually need the skills to work.

What steps can reproduce the bug?

Add ~/.codex/skills/foo/SKILL.md and then do a task that triggers that skill. Watch in horror as codex blindly tries to imagine for itself what it should be doing. Stop the task and ask it what is happening. Have the above-reproduced discussion.

This happened twice in a row while using codex. Non-deterministic skill discovery is just absurd. But having it fail twice in a row puts this tool in the category of unusable.

What is the expected behavior?

Load skills. Use them as appropriate. I get that skill invocation is going to be driven by the model, but if you can't walk a dir tree without LLM prompting, the LLM never gets the chance to fire on the skill. I cannot see any reason why this part of the harness would be subject to LLM interpretation.

Additional information

_No response_

View original on GitHub ↗

2 Comments

jvasile · 7 days ago

In this example, btw, foo is a symlink to a dir. That makes this related to #31592, which concerns the SKILL.md file itself being a symlink. But in this case, SKILL.md is a regular file. It is the containing dir that is the symlink.

tsuvic · 7 days ago

Reproduced the symlink case in isolation on codex-cli 0.149.0 (release binary, macOS arm64) — a symlinked skill directory IS discovered and rendered there.

Setup (isolated CODEX_HOME, no other skills): $CODEX_HOME/skills/linkedskill → symlink to a directory containing a regular SKILL.md, plus a plain-directory control skill beside it. After one codex exec turn, both skills appear in the available-skills catalog inside the turn instructions, e.g.:

- linkedskill: <description> (file: /private/tmp/.../skills/linkedskill/SKILL.md)

(the discovery path is canonicalized — /tmp → /private/tmp on macOS — but the entry is present).

Source, identical at rust-v0.149.0 and current main (@67b2c8c): directory symlinks are followed for user/repo/admin skill roots; only the system scope ignores them —

let directory_symlinks = match skill_root.scope {
    SkillScope::User | SkillScope::Repo | SkillScope::Admin => DirectorySymlinkPolicy::Follow,
    SkillScope::System => DirectorySymlinkPolicy::Ignore,
};

(codex-rs/ext/skills/src/loader/host.rs:160–163; behavior test follows_directory_symlinks_except_for_system_scope, host_tests.rs:679). ~/.codex/skills is user scope, so a symlinked directory there should be eligible on Linux as well — there is no OS-specific branch in this policy.

If the skill still doesn't surface in a task, the next divider is discovery vs. rendering: the catalog that reaches the prompt is budgeted and selector-driven (include_instructions, max_context_tokens, shadow selection — codex-rs/ext/skills/src/config.rs:4–15), so a skill can be discovered yet omitted from a given turn's context. Checking whether it shows up in the TUI's skills list (which reflects skills/list, i.e. discovery) would separate the two. (Hypothesis for this part; the symlink-following itself is verified above.)