Added support for live updates to skills and AGENTS by etraut-openai · Pull Request #9985 · openai/codex

etraut-openai · 2026-01-27T08:07:40Z

Overview

Add a centralized FileWatcher in codex-core (using notify) that watches:

AGENTS.md / AGENTS.override.md and project AGENTS search dirs
Skill roots from the config layer stack (recursive)

Send AgentsChanged and SkillsChanged events when relevant file system changes are detected

On SkillsChanged:

Invalidate the skills cache immediately in ThreadManager
Emit EventMsg::SkillsUpdateAvailable to active sessions
Broadcast a new app-server notification: skills/list/updated

On AgentsChanged:

Set a per-session agents_changed flag scoped to relevant watch dirs
On the next user turn, recompute skills + user instructions and inject an updated UserInstructions item into the event stream

Wire the watcher through ThreadManager -> Codex::spawn -> SessionServices, including sub-agent sessions.

Add SkillsListUpdatedNotification to the app-server protocol and gate broadcast until after initialize.

Testing

I did a bunch of manual testing of both AGENTS and skills updates. They work surprisingly well. Skill addition and removal are both handled seamlessly in both the UI and in the behavior of the agent on the next turn. Changes to skill details were picked up and followed on the next turn. Additions and modifications to AGENTS.md were followed well. The only failure that I found was when I deleted a major block of instructions from AGENTS.md. In that case, the model still followed those instructions from the older AGENTS.md because it was still in the context window.

Add a centralized FileWatcher in codex-core (using notify) that watches: * AGENTS.md / AGENTS.override.md and project AGENTS search dirs * Skill roots from the config layer stack (recursive) Send `AgentsChanged` and `SkillsChanged` events when relevant file system changes are detected On `SkillsChanged`: * Invalidate the skills cache immediately in ThreadManager * Emit EventMsg::SkillsUpdateAvailable to active sessions * Broadcast a new app-server notification: skills/list/updated On `AgentsChanged`: * Set a per-session agents_changed flag scoped to relevant watch dirs * On the next user turn, recompute skills + user instructions and inject an updated UserInstructions item into the event stream Wire the watcher through ThreadManager -> Codex::spawn -> SessionServices, including sub-agent sessions. Refactor project_doc discovery to expose project_doc_search_dirs for shared watch-dir computation. Add SkillsListUpdatedNotification to the app-server protocol and gate broadcast until after initialize. Testing: I did a bunch of manual testing of both AGENTS and skills updates. They work surprisingly well. Skill addition and removal are both handled seamlessly in both the UI and in the behavior of the agent on the next turn. Changes to skill details were picked up and followed on the next turn. Additions and modifications to AGENTS.md were followed well. The only failure that I found was when I deleted a major block of instructions from AGENTS.md. In that case, the model still followed those instructions from the older AGENTS.md because it was still in the context window.

xl-openai

Thanks for making this change! The skills part LGTM!

pakrym-oai · 2026-01-27T23:01:45Z

codex-rs/core/src/codex.rs

            );
        }
        let state = SessionState::new(session_configuration.clone());
+        let agents_watch_dirs = Self::build_agents_watch_dirs(&config);


Aren't agents.md cwd-specific? Can we create the watcher only once for the entire session?

This function is taking cwd into consideration. It builds a list of all directories from the cwd up to the root of the repo and watches for changes in those directories. This mirrors the same logic used when enumerating the AGENTS files.

pakrym-oai · 2026-01-27T23:04:04Z

codex-rs/core/src/codex.rs

+        let enabled_skills = skills_outcome.enabled_skills();
+        let user_instructions = get_user_instructions(&config, Some(&enabled_skills)).await;
+        let mut state = self.state.lock().await;
+        state.session_configuration.user_instructions = user_instructions.clone();


Should we let the model know which file names changed instead? And let it decide which ones it cares about?

The current logic can inadvertently create huge messages and flood the context. We've seen very large skills + agents combinations.

If we inject the entire thing for every change we'll exhaust the context in no time.

I don't think it will work to only tell it which file names changed. We need to update the names and summaries of the skills. Both the name and summary are bounded in size (64 characters and 512 characters, respectively). We are not including the full skill file here.

We do include the full agents contents. I agree that's a concern in terms of size. But I don't see a way around that. We don't initially tell the model the file paths of the AGENTS files; we simply read the contents of all of these files, concatenate them, and then truncate to 32K. If we were to later tell it about file paths, it would have no way of correlating those paths with the original AGENTS text. I suppose we could modify the way we handle AGENTS, but that's a pretty big change and would probably be OOD for the model. Let me know if you have any other suggestions.

Note that we're reinjecting only on turn boundaries. This acts as a "debounce" mechanism in the case where multiple file changes occur in quick succession. But I understand your concern about potential storms of file watcher events. Since we deliver a SkillsListUpdatedNotification app server notification each time, it could swap an app server client. I've added an additional one-second throttling/debounce mechanism.

pakrym-oai

Needs tests.

I think re-injecting full Agents.md and skills is too much of a risk/context bloat. We should consider only injecting updated file names for both skills and agents along with some short prompt and letting the model decide.

I'd also prefer if we had a very aggressive throttle on file change events. If there is any bug in file_watcher it'll flood the session (some editors perform save operations that cause multiple file notifications, rename, create, delete etc).

And we should consider shipping this behind a feature first.

…nd agents

# Conflicts: # codex-rs/core/config.schema.json

etraut-openai · 2026-01-29T01:36:12Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8b6f27de5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

codex-rs/core/src/file_watcher.rs

codex-rs/core/src/codex.rs

etraut-openai · 2026-01-29T01:54:11Z

codex review

etraut-openai · 2026-01-29T06:18:43Z

@pakrym-oai, I've made the following changes since the last review:

Added experimental feature flags live_agents_reload and live_skills_reload; they default to false for now
Added an "event coalescer" mechanism for file watcher events that limits them to one per second
Added integration tests
Added support for fallback filenames (a config option that allows users to specify alternative names for AGENTS.md)
Modified AGENTS.md for this repo to remove instructions about updating docs, since docs are no longer stored in this repo

I didn't make changes to the injection strategy (see responses above). Let me know if you have other thoughts here.

codex-rs/cloud-requirements/src/lib.rs

pakrym-oai · 2026-02-01T23:48:11Z

codex-rs/core/src/rollout/truncation.rs

+
+        // Filter out synthetic user-instructions messages so truncation counts
+        // only real user turns.
+        items.retain(|item| match item {


Why did we start needing this?

This is required for some of the existing tests to accommodate the new skills & AGENTS injection.

codex-rs/core/src/skills/manager.rs

# Conflicts: # codex-rs/app-server/src/message_processor.rs # codex-rs/cloud-requirements/src/lib.rs # codex-rs/core/src/codex.rs

# Conflicts: # codex-rs/app-server/src/message_processor.rs

# Conflicts: # codex-rs/core/Cargo.toml # codex-rs/core/src/codex.rs

Add a centralized FileWatcher in codex-core (using notify) that watches skill roots from the config layer stack (recursive) Send `SkillsChanged` events when relevant file system changes are detected On `SkillsChanged`: * Invalidate the skills cache immediately in ThreadManager * Emit EventMsg::SkillsUpdateAvailable to active sessions * Broadcast a new app-server notification: skills/list/updated Add SkillsListUpdatedNotification to the app-server protocol and gate broadcast until after initialize. This change does not inject new events into the event stream. That means the agent will not know about new skills, so it won't be able to implicitly invoke new skills. It also won't know about changes to existing skills, so if it has already read the contents of a modified skill, it will not honor the new behavior. I plan to address these limitations in a follow-on PR modeled after #9985. Injection of new skills (and AGENTS) was deemed to risky at this point, hence the need to split the feature into two stages. Testing: * In addition to automated tests, I did manual testing to confirm that newly-created skills, deleted skills, and renamed skills are reflected in the TUI skill picker menu. Also confirmed that modifications to behaviors for explicitly-invoked skills are honored.

Add a centralized FileWatcher in codex-core (using notify) that watches skill roots from the config layer stack (recursive) Send `SkillsChanged` events when relevant file system changes are detected On `SkillsChanged`: * Invalidate the skills cache immediately in ThreadManager * Emit EventMsg::SkillsUpdateAvailable to active sessions ~~* Broadcast a new app-server notification: SkillsListUpdatedNotification~~ This change does not inject new items into the event stream. That means the agent will not know about new skills, so it won't be able to implicitly invoke new skills. It also won't know about changes to existing skills, so if it has already read the contents of a modified skill, it will not honor the new behavior. This change also does not detect modifications to AGENTS.md. I plan to address these limitations in a follow-on PR modeled after #9985. Injection of new skills and AGENTS was deemed to risky, hence the need to split the feature into two stages. The changes in this PR were designed to easily accommodate the second stage once we have some other foundational changes in place. Testing: In addition to automated tests, I did manual testing to confirm that newly-created skills, deleted skills, and renamed skills are reflected in the TUI skill picker menu. Also confirmed that modifications to behaviors for explicitly-invoked skills are honored. --------- Co-authored-by: Xin Lin <xl@openai.com>

etraut-openai added 7 commits January 27, 2026 00:07

Changed from strong to weak reference to prevent shutdown.

f780842

Improved comments

7d97287

Fixed broken test

0dc71b2

Fixed test

60991e7

Test fix

cc5c6d1

Fix test

45d258f

xl-openai reviewed Jan 27, 2026

View reviewed changes

pakrym-oai reviewed Jan 27, 2026

View reviewed changes

pakrym-oai requested changes Jan 27, 2026

View reviewed changes

etraut-openai added 4 commits January 28, 2026 15:22

Merge origin/main

a95f4e7

Added separate experimental feature flags for live update of skills a…

dad3af9

…nd agents

Added integration test

57f9c9f

Merge remote-tracking branch 'origin/main' into etraut/live_skill_update

c8b6f27

# Conflicts: # codex-rs/core/config.schema.json

Aesthetic improvements

40a223e

chatgpt-codex-connector bot reviewed Jan 29, 2026

View reviewed changes

codex-rs/core/src/file_watcher.rs Outdated Show resolved Hide resolved

codex-rs/core/src/codex.rs Show resolved Hide resolved

Add support for fallback filenames

f3100c7

Added throttling for file watcher events

41e1d66

etraut-openai requested a review from pakrym-oai January 29, 2026 06:18

This comment was marked as off-topic.

Sign in to view

etraut-openai added 3 commits January 30, 2026 09:33

Merge origin/main into etraut/live_skill_update

d79761f

Merge remote-tracking branch 'origin/main' into etraut/live_skill_update

1c62e54

Fixed merge issue

1925449

pakrym-oai reviewed Feb 1, 2026

View reviewed changes

codex-rs/cloud-requirements/src/lib.rs Outdated Show resolved Hide resolved

pakrym-oai reviewed Feb 1, 2026

View reviewed changes

codex-rs/core/src/skills/manager.rs Outdated Show resolved Hide resolved

etraut-openai added 5 commits February 1, 2026 20:52

Merge remote-tracking branch 'origin/main' into etraut/live_skill_update

74323b6

# Conflicts: # codex-rs/app-server/src/message_processor.rs # codex-rs/cloud-requirements/src/lib.rs # codex-rs/core/src/codex.rs

Code review feedback

fca6982

Fix lint

d0ce01d

Merge remote-tracking branch 'origin/main' into etraut/live_skill_update

e91f6ff

# Conflicts: # codex-rs/app-server/src/message_processor.rs

Merge remote-tracking branch 'origin/main' into etraut/live_skill_update

c070d14

# Conflicts: # codex-rs/core/Cargo.toml # codex-rs/core/src/codex.rs

etraut-openai mentioned this pull request Feb 3, 2026

Added support for live updates to skills #10478

Merged

leoshimo-oai mentioned this pull request Feb 3, 2026

feat(app-server, skills): add a way for clients to specify additional dirs for skills #10527

Closed

Conversation

etraut-openai commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Testing

Uh oh!

xl-openai left a comment

Choose a reason for hiding this comment

Uh oh!

pakrym-oai Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

etraut-openai Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

pakrym-oai Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

pakrym-oai Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

etraut-openai Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

etraut-openai Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pakrym-oai left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

etraut-openai commented Jan 29, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

etraut-openai commented Jan 29, 2026

Uh oh!

etraut-openai commented Jan 29, 2026

Uh oh!

This comment was marked as off-topic.

Uh oh!

pakrym-oai Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

etraut-openai Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

etraut-openai commented Jan 27, 2026 •

edited

Loading

etraut-openai Jan 28, 2026 •

edited

Loading

pakrym-oai left a comment •

edited

Loading