Dev Watch (Symlink Watch)

What it is

Dev Watch is a feature that keeps a single dev server running while you switch between tickets. Instead of restarting npm run dev, bundle exec jekyll serve, or any other file-watching process every time you activate a different work item, the dev server stays up and automatically picks up the new code.

It works by placing symlinks in a work/ directory that point into the active worktree. Your build tool watches work/ rather than the repo root. When you switch tickets, Ticket House repoints the symlinks to the new worktree and the file watcher detects the change and hot-reloads.

How it works

1. You configure devWatch in .ticket-house.json, listing which directories to symlink and which command to run.
2. Ticket House creates a work/ directory in the repo root containing symlinks that point to directories inside the active worktree (e.g. work/src → .ticket-house/worktrees/worktree-1/src).
3. The dev process watches work/ using the build tool’s normal file watcher (Vite, webpack, Jekyll, etc.).
4. When you activate a different ticket, Ticket House removes the old symlinks and creates new ones pointing to the newly active worktree.
5. The file watcher sees the change and rebuilds / hot-reloads automatically. No restart required.

Configuration

Add a devWatch block to your .ticket-house.json:

{
  "remote": "https://your-server.example.com/projects/my-app",
  "devWatch": {
    "links": {
      "src": "src",
      "tests": "tests"
    },
    "command": "npm run dev",
    "autoStart": true,
    "workDir": "work",
    "cwd": "."
  }
}

The keys in links are the symlink names that appear in the work directory. The values are paths relative to the worktree root. In the example above, work/src would symlink to the active worktree’s src/ directory, and work/tests would symlink to its tests/ directory.

Build tool integration

Because the dev process reads from work/ instead of the repo root, you need to tell your build tool where to find source files.

Jekyll

Point Jekyll at the work/ directory for includes and data:

# _config.yml
source: work/site
exclude:
  - .ticket-house.json

Vite

Use an alias or adjust the root option:

// vite.config.js
export default {
  root: 'work/src',
}

webpack

Update the entry point and any resolve paths:

// webpack.config.js
module.exports = {
  entry: './work/src/index.js',
}

.gitignore

Add work/ to your .gitignore so the symlink directory is not committed:

work/

Example walkthrough

Here is a concrete example using a Jekyll project.

1. Project structure

my-site/
  .ticket-house.json
  _config.yml
  Gemfile
  src/          # Jekyll source (pages, layouts, includes)

2. Configure devWatch

{
  "remote": "https://your-server.example.com/projects/my-site",
  "devWatch": {
    "links": {
      "site": "src"
    },
    "command": "bundle exec jekyll serve --source work/site --livereload",
    "autoStart": true
  }
}

3. Start the workstation

npx ticket-house

When you activate ticket MS-1, Ticket House creates:

my-site/
  work/
    site -> .ticket-house/worktrees/worktree-1/src

Jekyll starts serving from work/site, which resolves through the symlink to the worktree’s src/ directory.

4. Switch to another ticket

Activate ticket MS-2. Ticket House repoints the symlink:

my-site/
  work/
    site -> .ticket-house/worktrees/worktree-2/src

Jekyll detects the file changes and rebuilds. No restart needed.

When to use Dev Watch

Dev Watch is most useful when:

• Your dev server has a slow startup (e.g. large dependency graphs, compilation steps) and you want to avoid restarting it repeatedly.
• You switch between tickets frequently and want instant feedback in the browser.
• Your build tool already supports file watching and hot-reload.

If your dev server starts quickly or you only work on one ticket at a time, you may not need Dev Watch and can simply run the dev command directly inside each worktree.