docker-watch-mode-2025 — Claude Code skill: Docker Compose hot reload
docker-watch-mode-2025 sets up Compose watch rules so source edits land in the running container, while dependency manifests trigger a rebuild.
MIT 166 installs ★ 66 updated 2026-06-18
npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a claude-codeWhat docker-watch-mode-2025 does
The skill covers Compose watch rules: which directory gets sync, what to hand to rebuild, when sync+restart is the right call. It walks through a six-step procedure, lists the actions, and closes with a troubleshooting checklist for edits that never reach the container.
The YAML sample pairs sync on ./frontend/src with ignore patterns for node_modules/, .git/ and dist/, plus a rebuild rule for ./frontend/package.json. You start it with docker compose up --watch. Keep ignore rules narrow — dependency folders, build output, caches and secrets stay out of the sync.
Get the app running with plain docker compose up first. Adding watch rules to a service that never started cleanly leaves you nothing to debug. Hot reload also needs a watcher inside the container: Compose copies files over, the runtime has to pick them up. When watch rules meet service dependencies, profiles or volumes, the skill suggests using compose-patterns-2025 alongside.
What it helps with
- move a frontend service to hot reload without a bind mount over the whole project
- keep source sync apart from rebuilds on dependency changes
- exclude
node_modulesand build output from watched paths - trace why a file edit never lands in the container
- pick between
sync+restartand plainsyncfor config files
Example prompts for the agent
- Set up
watchfor thefrontendservice:syncon./frontend/srcandrebuildonpackage.json. - Edits to
src/App.tsxnever reach the container — walk the watch troubleshooting checklist. - Add
ignorepatterns fornode_modules/,.git/anddist/to the sync rule.
How to install docker-watch-mode-2025
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a claude-code2Manually: put the files in place
~/.claude/skills/docker-watch-mode-2025/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/docker-watch-mode-2025/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a codex2Manually: put the files in place
.agents/skills/docker-watch-mode-2025/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a cursor2Manually: put the files in place
.cursor/skills/docker-watch-mode-2025/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/azure-to-docker-master/skills/docker-watch-mode-20252Manually: put the files in place
.github/skills/docker-watch-mode-2025/SKILL.md1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a gemini-cli2Platform CLI
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/azure-to-docker-master/skills/docker-watch-mode-2025Manually: put the files in place
.devin/skills/docker-watch-mode-2025/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about docker-watch-mode-2025
How do I install docker-watch-mode-2025 in Claude Code?
Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill docker-watch-mode-2025 -a claude-code. The skill file ends up at ~/.claude/skills/docker-watch-mode-2025/SKILL.md.
What does docker-watch-mode-2025 do?
It explains the three watch actions in Compose: sync for frameworks that reload files themselves, rebuild for compiled languages and dependency changes, sync+restart for configs read only at process start.
Does Compose watch replace nodemon or cargo-watch?
No, unless your app watches files on its own. Watch only delivers changed files into the container, the restart happens inside the runtime, so without a watcher there hot reload will not fire.
Source text
SKILL.md · MIT
---
name: docker-watch-mode-2025
description: |
Docker Compose Watch mode for hot reload during local development (2025 GA).
PROACTIVELY activate for: (1) docker compose watch setup, (2) watch action types (sync, rebuild, sync+restart, sync+exec), (3) configuring path filters and ignore patterns, (4) hot-reload for Node/Python/Go/Rust apps in Compose, (5) sync-only vs rebuild trade-offs, (6) using watch with profiles, (7) debugging watch mode (verbose logs), (8) integrating watch with bind mounts, (9) Compose watch vs nodemon/air/cargo-watch.
Provides: watch action reference, per-language hot-reload examples, path filter patterns, and troubleshooting steps.
---
# Docker Compose Watch Mode (2025 GA)
Docker Compose Watch enables automatic hot reload during local development by synchronizing file changes instantly without manual container restarts.
## Three Watch Actions
### 1. sync - Hot Reload
For frameworks with hot reload (React, Next.js, Node.js, Flask).
Copies changed files directly into running container.
### 2. rebuild - Compilation
For compiled languages (Go, Rust, Java) or dependency changes.
Rebuilds image and recreates container when files change.
### 3. sync+restart - Config Changes
For configuration files requiring restart.
Syncs files and restarts container.
## Core Procedure
1. Confirm the app already starts with `docker compose up` before adding watch rules.
2. Prefer `sync` for source directories when the runtime already reloads files.
3. Use `rebuild` for dependency manifests, Dockerfiles, compiled artifacts, or base-image changes.
4. Use `sync+restart` for configuration files that are read only at process startup.
5. Add narrow `ignore` rules for dependency folders, build outputs, VCS folders, caches, secrets, and generated files.
6. Run `docker compose up --watch` and verify both fast source edits and dependency changes.
## Usage
```yaml
services:
frontend:
build: ./frontend
develop:
watch:
- action: sync
path: ./frontend/src
target: /app/src
ignore: [node_modules/, .git/, dist/]
- action: rebuild
path: ./frontend/package.json
```
Start with: `docker compose up --watch`.
## Troubleshooting Checklist
- Change not detected: verify the watched path is relative to the Compose file and not excluded by `ignore`.
- Hot reload not firing: confirm the application inside the container has its own watcher enabled.
- Container restarts too often: split source `sync` from manifest `rebuild` rules.
- File ownership issues: prefer named volumes for dependency directories and sync only application code.
- Slow sync: narrow watched paths and exclude build outputs or large generated folders.
## References
Use `docker compose watch --help` and Docker's Compose Watch documentation for the current action set and CLI flags. Pair this skill with `compose-patterns-2025` when watch rules interact with service dependencies, profiles, networks, or volumes.
## Benefits
- Better performance than broad bind mounts
- Fewer host/container file permission issues
- Intelligent syncing with rebuild capability
- Works across supported Docker Desktop and Compose platforms
© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace