Skip to content

Codex: each skill catalog read starts a fresh app-server #385

Closed as not planned

Description

@mubeda

Problem / summary

(measured) Every Codex skill-catalog read starts, initializes, and then stops a fresh codex app-server process, including skills/list with forceReload: true. There is no reuse across workspaces or repeated reads.

(guess) That spawn/initialize cost is likely a large share of skill-list latency. T3 Code measured a drop from 1,657 ms to 138 ms median for four workspaces after reusing one app-server. That number is T3's, not a BibCode measurement. No timing was taken here.

(measured) Diagnosis is static only, at the SHA below. No app, test, or provider process was run.

Current behavior

(measured) Verified at be03142dcd9f14378d4357d83ad65d2cf5af513a (origin/main as of 15 November 2026, 19:21 America/Buenos_Aires, merge of PR #379). Every path:line below refers to this SHA.

  • discover_capabilities for driver "codex" calls codex_capabilities for that workspace cwd (capabilities.rs:61–88). (measured)
  • codex_capabilities prepares ["app-server"], spawns a supervised process, opens a JSON-RPC connection, and on completion closes the connection and stops the child (:162–198). (measured)
  • read_codex_capabilities then initializes, notifies initialized, optionally calls plugin/installed, and requests skills/list with {"cwds":[cwd],"forceReload":true} (:201–240). (measured)
  • Existing coverage (codex_skill_catalog_includes_plugin_installs and neighbors in the same file, from :362) checks catalog contents against a fake binary. It does not assert process reuse or count initialize / spawn. (measured)
  • Nothing in this inventory path keeps an app-server around for a later cwd or a later read. (measured)

Proposed fix

(inferred) Keep one supervised Codex app-server for skill catalog reads (keyed by executable plus effective CODEX_HOME, or an equivalent identity) and reuse it for later skills/list calls, including other workspaces. Continue to honor cancellation, the existing probe timeout, and profiler-safe shutdown (process::supervised / stop before teardown). Do not leave an orphaned app-server after inventory is cancelled or the server shuts down.

forceReload policy is an open question: reuse should not serve a stale catalog when the user asked to reload, and it should not pay a full process start when a live server can answer.

Goals and non-goals

Goals:

  • Repeated Codex skill-catalog reads, including reads for several workspaces, reuse one app-server instead of spawning one process per read.
  • Catalog contents, plugin-install discovery, cancellation, and timeout errors stay correct.
  • The reused process is supervised and is stopped on shutdown, timeout, and cancel.

Non-goals:

  • Changing Cursor's filesystem skill walk (#229, closed).
  • Changing startup --version probe concurrency (#318, closed).
  • Changing which skills appear in the picker (#298, closed).
  • Reusing a chat session's Codex app-server, or keeping a process forever with no idle teardown.
  • A promised latency number. Any speed-up should be measured on BibCode after the change; T3's 12× figure is not a target.

Acceptance criteria

P0:

  • A hermetic test (extend apps/server/src/production/provider_inventory/capabilities.rs, including codex_skill_catalog_includes_plugin_installs) uses a fake codex binary that counts process starts and initialize calls. Two skill-catalog reads, or reads for two cwds, start one app-server and one initialize, and both catalogs are returned correctly.
  • Cancellation and timeout still stop the child and do not leak a process. Existing catalog, plugin-install, and incomplete-catalog cases still pass.
  • cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, and the focused Rust tests pass. vp check / vp run typecheck if any non-Rust surface changes.

P1:

  • An idle reused server is shut down (a short idle timeout is fine) and a later read may start a new one. Server shutdown and profiler teardown still stop it.
  • A failed or exited reused server is discarded; the next read starts a fresh one instead of stalling.
  • Profiler coverage line in the delivery report (spawn, reuse, and stop). Skill names and catalog payloads never reach profiler records or logs.
  • Testing runbooks are reviewed and remain accurate or are updated.

P2:

  • Optional before/after timing of two or more workspace skill reads, recorded in the PR, with no required speed-up factor.

Open questions

  1. (inferred) Reuse key: executable + effective CODEX_HOME, or also user/environment? Different homes must not share a process.
  2. (inferred) Should a user-initiated reload keep forceReload: true on the reused server, and should background/cache refreshes omit it?
  3. (inferred) Idle lifetime: close after the current inventory batch, or keep a short-lived process for later reads in the same server session?
  4. (guess) Can one skills/list call pass several cwds at once on the app-server BibCode targets, or must each cwd be requested separately on the shared connection?

Duplicate check

Searched open and closed issues (titles and body search for "app-server", "skill discovery", "skill catalog", "Codex skill", forceReload, skills/list, probe/inventory).

  • Related, not a duplicate: #229 (closed) bounded the Cursor on-disk skill walk.
  • Related, not a duplicate: #318 (closed) made startup --version probes concurrent.
  • Related, not a duplicate: #298 (closed) included plugin-installed Codex skills in the picker; it did not reuse the app-server.
  • Related, not a duplicate: #107 (closed) was a slow first getProviderCapabilities on cache miss.
  • #163 (closed) was about unused Codex retries/compaction APIs, not skill-list process reuse.
  • No open or closed issue asks to reuse one Codex app-server for skill catalog reads.

Reference

Similar change in T3 Code: pingdotgg/t3code#33972 (reuse one Codex app-server for skill reads). The 1,657 ms → 138 ms median for four workspaces is T3's claimed measurement, not a BibCode result.

Activity

  1. added
    enhancementRequested improvement or new capability.
    needs-triageIssue needs maintainer review and initial categorization.
    on Nov 16, 2026
  2. mubeda commented on Nov 18, 2026

    @mubeda
    OwnerAuthor

    Closing as not planned. Two implementations were written and reviewed; both failed on the same point, and the point is in the proposal, not the code.

    Why reuse is not safe here

    1. Where the kept server runs. Today each read launches codex app-server in the workspace. A shared server cannot do that: inside one workspace it holds that worktree open (and blocks its removal on Windows), and outside it a launcher that picks the Codex installation or home from the working directory (a version-manager shim, a wrapper script) starts a different Codex than the fresh launch did.
    2. State the process reads once. A running app-server keeps the signed-in account, the installed-plugin snapshot, the resolved home and the executable it was started from. BiBCode cannot see those change from outside: a keyring sign-in, a plugin disabled from another client, a retargeted home or an updated binary all leave a kept server answering with the old state. Review traced a path where the previous account's skills are returned after a switch. A file stamp closes some of these cases and none of the class.
    3. Benefit not measured. The issue's latency figure comes from another project. Nothing was measured on BiBCode, and reads are already cached per workspace with a background refresh, so the fresh launch is paid on a cache miss only.

    The repository's priority order puts correctness above convenience, and the change had grown from size:S to about 1,700 lines without reaching a state that returns the same catalog as today in every case.

    What was kept (in the batch pull request, both defects exist on main):

    • JsonRpcConnection::close() now always releases the writer task and the stdin pipe when the app-server has already died.
    • A failed background capability refresh no longer writes the provider's error text, which can name skills, to the log.

    If this comes back: measure a cache-miss read on BiBCode first. A version worth trying keeps a server only for the length of one inventory batch, in which nothing above can change, and that needs a caller that reads several workspaces at once.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementRequested improvement or new capability.needs-triageIssue needs maintainer review and initial categorization.size:S

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions