Watch Mode

hx’s watch mode automatically runs commands when source files change, enabling rapid development iteration.

Overview

Watch mode monitors your source files and triggers rebuilds, tests, or other commands automatically when you save changes.

hx watch build

Basic Usage

Watch and Build

hx watch build

Rebuilds automatically when any .hs file changes.

Watch and Test

hx watch test

Re-runs tests on every save.

Watch and Run

hx watch run

Rebuilds and restarts the application.

Watch and Check

hx watch check

Type-checks without full compilation (faster feedback).

Watched Files

By default, hx watches:

In directories:

• src/
• app/
• lib/
• test/
• bench/

Options

Clear Terminal

Clear the screen before each run:

hx watch build --clear

Debounce

Control how long to wait after changes settle:

# Wait 500ms after last change
hx watch build --debounce 500

Default is 300ms.

Custom Patterns

Watch additional files:

hx watch build --include "config/**/*.yaml"

Exclude files:

hx watch build --exclude "generated/**"

Polling Mode

Use polling instead of filesystem events (useful for network drives):

hx watch build --poll

Configuration

Configure watch behavior in hx.toml:

[watch]
# Clear terminal on each run
clear = true

# Debounce delay (ms)
debounce = 300

# Additional patterns to watch
include = ["config/**"]

# Patterns to exclude
exclude = [
  "dist-newstyle/**",
  ".git/**",
  "*.tmp"
]

Workflows

Test-Driven Development

hx watch test

1. Write a failing test
2. Save → tests run automatically
3. Write implementation
4. Save → tests run again
5. See green tests
6. Repeat

REPL-Like Development

hx watch run

1. Make changes to your application
2. Save → app rebuilds and restarts
3. See results immediately

Type-First Development

hx watch check

Faster feedback than full builds:

1. Write function signatures
2. Save → type errors shown
3. Fill in implementations
4. Save → type check again

Combined Workflows

Run checks, then tests if they pass:

# Using shell
watch -n 1 'hx check && hx test --match "fast"'

Keyboard Controls

While in watch mode:

Performance Tips

Use Check for Fast Feedback

hx watch check is faster than hx watch build:

# Faster - type check only
hx watch check

# Slower - full compilation
hx watch build

Exclude Generated Files

[watch]
exclude = ["generated/**", "dist-newstyle/**"]

Adjust Debounce

Lower debounce for faster response:

[watch]
debounce = 100

Higher debounce to batch rapid changes:

[watch]
debounce = 500

Focus on Changed Areas

Run specific tests:

hx watch test -- --match "Parser"

Integration with Editors

VS Code

HLS provides real-time feedback. Use watch mode for tests:

1. Open integrated terminal
2. Run hx watch test
3. Keep terminal visible while editing

Vim/Neovim

Split terminal workflow:

:split | terminal hx watch test

Or with tmux:

tmux split-window -h "hx watch test"

Emacs

(defun hx-watch-test ()
  (interactive)
  (async-shell-command "hx watch test"))

Troubleshooting

Changes Not Detected

Try polling mode:

hx watch build --poll

Check watched directories:

hx watch build --verbose

Too Many Rebuilds

Increase debounce:

hx watch build --debounce 500

Exclude noisy directories:

[watch]
exclude = ["logs/**", "tmp/**"]

High CPU Usage

On some systems, filesystem watching can be intensive. Solutions:

1. Use polling with longer intervals:

   hx watch build --poll

2. Reduce watched directories

Platform Notes

Linux

Uses inotify. May need to increase watch limit:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

macOS

Uses FSEvents. Generally works well.

Windows

Uses ReadDirectoryChangesW. May have issues with network drives—use --poll if needed.

See Also

• hx build — Build command
• hx test — Test command
• hx check — Type check command