feat: watch mode

[stefanoamorelli]

closes: #565

---

This PR introduces a watch mode feature that enables Codex to passively monitor the code base for AI triggering comments (default is: // CODEX: <instruction>). When a trigger comment is detected Codex will grab the surrounding context, filename, and execute the instruction.

In the video below we open nvim on the right, and codex on the left with --watch flag enabled:

video.mp4

What

Customizable AI Trigger Detection

• Default pattern matches comments like // CODEX: fix this bug
• Fully customizable regex pattern support via config.json:

 {
   "watchMode": {
     "triggerPattern": "/(?:\\/\\/|#)\\s*AI:(TODO|FIXME)\\s+(.*)/i"
   }
 }

• Supports advanced patterns like // AI:TODO fix this function for integration with task management workflows

Automatic context extraction

This mode automatically injects the context around the trigger comment and relative file in the prompt;

Comprehensive Comment Style Support

Works with various single-line comment formats across programming languages:

• Double slash comments (JavaScript, TypeScript, Java, C++, etc.)
• Hash comments (Python, Ruby, Shell scripts, YAML, etc.)
• Double dash comments (SQL, Haskell, Lua)
• Semicolon comments (Lisp, Clojure, Assembly)
• Single quote comments (VB, VBA)
• Percent comments (LaTeX, Matlab, Erlang)
• REM comments (Batch files)

Efficient file monitoring

Uses chokidar for performant file watching with intelligent filtering

Why

This feature reduces workflow disruptions by enabling Codex interoperability in any editor.

How

# Start Codex CLI with watch mode enabled
codex --watch

Then in any code file, add comments with your preferred trigger pattern:

Default pattern (// CODEX: fix this)

  def add_numbers(a, b):
      # This function should add two numbers but has a bug
      // CODEX: Fix this test
      return a - b  # This is wrong, should be addition

Task-based pattern (with custom config)

With pattern: /(?:\\/\\/|#)\\s*AI:(TODO|FIXME)\\s+(.*)/i

  function getData() {
      // AI:TODO Add error handling for network failures
      return fetch('/api/data').then(res => res.json());
  }

Custom keyword pattern (with custom config)

With pattern: /(?:\\/\\/|#)\\s*(.*)\\s*codex[!?]/i

  // Optimize this algorithm. codex!
  function slowSort(arr) {
      // inefficient implementation
  }

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[stefanoamorelli]

I have read the CLA Document and I hereby sign the CLA

[stefanoamorelli]

Hey @tibo-openai, just pushed a minor change. Let me know your feedback - happy to help with anything!

[lostmygithubaccount]

any chance this could make it in? it'd be huge for my workflows w/ codex

[eric-humane]

I would suggest we have a much more specific and possibly incorrect syntax wise (how does this work on all languages?) way of triggering this, and does it watch folders? if so -- maybe using watchman is the better idea.

I worry that valid comments which are so broad (or could be written as a joke even) could be bad. but like:

%codex "fix this", "o3"
fun test(input: String) -> String

%codex "fix this", "o3"
def test(input: str) str:

could be a better idea -- and not tied syntactically

[lostmygithubaccount]

I think the general idea is that you write the comment in whatever language you're working on, and it's indexing on "AI!" (I didn't author this/might be misunderstanding the concern -- I don't have very strong opinions on the syntax personally)

so # whatever, AI! in Python and such and // whatever, AI! in C and such. and you want the thing it's watching for to be at the end of the line (so an exclamation feels sorta natural, as you also don't want it on "AI" in general) so it doesn't start working until you've written the comment. codex! at the end would also seem fine to me

[stefanoamorelli]

+1 @lostmygithubaccount that is exactly the idea! I'm already using this daily and it's a game changer, at least for my workflow. aider follows the same approach.

As per the suffix, I could tweak it with codex or alternatives.

@eric-humane I see your point about a "custom" format for the trigger, although I'm not convinced because it breaks the syntax of the files I'm working on. IMHO having a custom suffix in normal comments, ie. AI!, makes it natural and is difficult to accidentally trigger it. But of course I'm happy to re-evaluate based on your input and the consensus!

Regarding watchman, thanks for the suggestion, how does it compare to chokidar and why would you suggest one over the other?

[eric-humane]

@eric-humane I see your point about a "custom" format for the trigger, although I'm not convinced because it breaks the syntax of the files I'm working on. IMHO having a custom suffix in normal comments, ie. AI!, makes it natural and is difficult to accidentally trigger it. But of course I'm happy to re-evaluate based on your input and the consensus!

and I agree with yours, but maybe the trigger isn't natural to you. but seeing it as // Made by AI! is not unusual in codebases I've seen. How does it know when to stop? But that is also me viewing it through the lens of a static tool.

Regarding watchman, thanks for the suggestion, how does it compare to chokidar and why would you suggest one over the other?

Ex-react / react-native engineer, it's just what I am used to lol.

o3 analysis: https://chatgpt.com/share/680c7bb3-5ab8-8004-bd0f-1bc7dd754351

[agustif]

I imagine something like TODO comment nomenclature but adding an AI:TODO spin to it
AI:TODO
AI:FIXME
AI:HACK(DO NOT FIX)

etc

[stefanoamorelli]

Thanks all for sharing your thoughts!

I've given some love to this PR that now supports defining a custom trigger regular expression in the config.json, meaning @eric-humane you can specify your own trigger (even syntactically incorrect), and @agustif, similarly, you could tweak the trigger to your preference:

// AI:TODO Add error handling for network failures

with this config:

"/(?:\\/\\/|#)\\s*AI:(TODO|FIXME)\\s+(.*)/i"

TLDR: The default trigger remains // fix this AI!, but developers can customize the trigger using a RegEx pattern to suit their preferences.

What do you think?

[eric-humane]

Thanks all for sharing your thoughts!

I've given some love to this PR that now supports defining a custom trigger regular expression in the config.json, meaning @eric-humane you can specify your own trigger (even syntactically incorrect), and @agustif, similarly, you could tweak the trigger to your preference:

// AI:TODO Add error handling for network failures

with this config:

"/(?:\\/\\/|#)\\s*AI:(TODO|FIXME)\\s+(.*)/i"

TLDR: The default trigger remains // fix this AI!, but developers can customize the trigger using a RegEx pattern to suit their preferences.

What do you think?

I still think using an open ended default trigger isn't a great idea, but like @agustif suggestion as a default. Because // fix this AI! shows up in some of my internal repos and semantically means something different -- i.e. fix this model. maybe not unusual.

// AI:TODO
// AI:FIXME

similarly:

// CODEX: add types to the args

is extremely clear :P

[stefanoamorelli]

Thanks for your input!

similarly:
// CODEX: add types to the args
is extremely clear :P

I've updated the default pattern to // CODEX: <instruction>. Still supporting the customization of the trigger to whatever the developer prefers according to their needs.

Do you have any further feedback for the first version of this enhancement?

cc. @eric-humane @agustif @lostmygithubaccount @tibo-openai