File watcher not detecting Claude Code edits with `--watch` flag

[delphos-mike]

Describe the bug

Issue Description

When running marimo edit --watch notebook.py, the file watcher does not detect file modifications made by Claude Code's Edit tool. This affects the Claude Code integration workflow promoted in the marimo blog post.

Environment

• OS: macOS (Darwin 25.0.0)
• marimo version: 0.16.5
• Python: 3.13.7
• Package manager: uv
• watchdog: 6.0.0 (installed)
• Claude Code: 2.0.15

Will you submit a PR?

• Yes

Environment

{
  "marimo": "0.16.5",
  "editable": false,
  "location": "/Users/mike/workspace/tools_and_scripts/notebooks/.venv/lib/python3.13/site-packages/marimo",
  "OS": "Darwin",
  "OS Version": "25.0.0",
  "Processor": "arm",
  "Python Version": "3.13.7",
  "Locale": "en_US",
  "Binaries": {
    "Browser": "141.0.7390.77",
    "Node": "v24.7.0"
  },
  "Dependencies": {
    "click": "8.1.8",
    "docutils": "0.22.2",
    "itsdangerous": "2.2.0",
    "jedi": "0.19.2",
    "markdown": "3.9",
    "narwhals": "2.8.0",
    "packaging": "24.2",
    "psutil": "7.0.0",
    "pygments": "2.19.1",
    "pymdown-extensions": "10.16.1",
    "pyyaml": "6.0.2",
    "starlette": "0.46.2",
    "tomlkit": "0.13.3",
    "typing-extensions": "4.13.2",
    "uvicorn": "0.34.2",
    "websockets": "15.0.1"
  },
  "Optional Dependencies": {
    "altair": "5.5.0",
    "duckdb": "1.2.2",
    "nbformat": "5.10.4",
    "openai": "1.78.0",
    "pandas": "2.2.2",
    "polars": "1.34.0",
    "pyarrow": "20.0.0",
    "loro": "1.8.1",
    "python-lsp-server": "1.13.1",
    "ruff": "0.14.0",
    "sqlglot": "26.16.4"
  },
  "Experimental Flags": {
    "sql_linter": false,
    "external_agents": true,
    "rtc_v2": false
  }
}```

</details>


### Code to reproduce

## Reproduction Steps

1. **Setup environment**:
```bash
cd ~/workspace/notebooks
uv init
uv add marimo watchdog

2. Create a simple marimo notebook (test.py):

import marimo

__generated_with = "0.16.5"
app = marimo.App()

@app.cell
def _():
    import marimo as mo
    return (mo,)

@app.cell(hide_code=True)
def _(mo):
    mo.md(r"""## Test Plot - Version 1""")
    return

if __name__ == "__main__":
    app.run()

3. Start marimo with watch mode:

uv run marimo edit test.py --watch

4. Edit the file using Claude Code's Edit tool, changing the markdown text:

mo.md(r"""## Test Plot - Version 2""")  # Changed from "Version 1"

Expected: The marimo UI should detect the file change and mark cells as stale/autorun.

Actual: No change detected. The UI still shows "Version 1".

5. Workaround - manually touch the file:

touch test.py

Result: Now marimo detects the change and updates the UI.

Additional Findings

Config Issue

The marimo UI settings don't properly update the config file. We had to manually edit ~/.config/marimo/marimo.toml:

[runtime]
watcher_on_save = "autorun"  # Changed from "lazy" via manual edit

Changing this setting in the UI (User Settings > Runtime > Watcher on save) did not update the TOML file until we manually edited it.

What Works vs. What Doesn't

Works:

• Manually editing the file in a text editor (triggers file watcher)
• Running touch filename.py after Claude Code edits (forces file system event)
• Editing cells directly in marimo UI

Doesn't Work:

• Claude Code's Edit tool file modifications (no file system event detected)

Root Cause Analysis

The issue appears to be that Claude Code's file write operations don't emit file system events that watchdog can detect. This could be due to:

• Atomic write operations (write to temp file, then rename)
• Specific system calls that bypass normal file monitoring
• File descriptor reuse without proper close/reopen

The touch command forces a file system event (updates mtime) that watchdog successfully detects.

Suggested Fixes

1. Add polling fallback: When watchdog doesn't detect changes within expected intervals, fall back to periodic polling
2. Document the workaround: Add note about touch requirement when using Claude Code
3. Investigate alternative watch methods: Some file watchers support multiple monitoring strategies
4. Add diagnostic logging: Help users identify when file watching isn't working as expected

Impact

This significantly affects the Claude Code + marimo integration workflow that marimo is actively promoting. Users must manually run touch after every Claude Code edit, which breaks the seamless experience shown in demos.

Workaround

For now, users can work around this by:

1. Configure watcher_on_save = "autorun" in marimo config
2. After Claude Code makes edits, run: touch path/to/notebook.py
3. Cells will automatically re-execute

This is better than restarting marimo, but not ideal.

[mscolnick]

@delphos-mike - can you try without watchdog? it might be a newer version that we are not compatible with

[mscolnick]

I figured it out. We watch for file modifications with watchdog, but Claude Code will actually create a new file and then move the file to the existing one (and deleting the old one). I should be able to put a fix up today

[mscolnick]

Closed by #6798