Repository navigation
Description
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_capabilitiesfor driver"codex"callscodex_capabilitiesfor that workspace cwd (capabilities.rs:61–88). (measured)codex_capabilitiesprepares["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_capabilitiestheninitializes, notifiesinitialized, optionally callsplugin/installed, and requestsskills/listwith{"cwds":[cwd],"forceReload":true}(:201–240). (measured)- Existing coverage (
codex_skill_catalog_includes_plugin_installsand neighbors in the same file, from:362) checks catalog contents against a fake binary. It does not assert process reuse or countinitialize/ 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
--versionprobe 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, includingcodex_skill_catalog_includes_plugin_installs) uses a fakecodexbinary that counts process starts andinitializecalls. Two skill-catalog reads, or reads for two cwds, start one app-server and oneinitialize, 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 typecheckif 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
- (inferred) Reuse key: executable + effective
CODEX_HOME, or also user/environment? Different homes must not share a process. - (inferred) Should a user-initiated reload keep
forceReload: trueon the reused server, and should background/cache refreshes omit it? - (inferred) Idle lifetime: close after the current inventory batch, or keep a short-lived process for later reads in the same server session?
- (guess) Can one
skills/listcall pass severalcwdsat 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
--versionprobes 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
getProviderCapabilitieson 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
mubeda commentedon Nov 18, 2026
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
codex app-serverin 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.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.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.