termic.dev
Documentation menu

Spotlight

Spotlight syncs one task's changes into your main checkout so you can run and test your whole dev stack against it, without ever writing a commit onto your branch.

Worktrees are great for isolation, but sometimes you need to run your whole dev stack against a task’s changes: the dev server, the watchers, the integration tests, all the things wired to your main checkout. Spotlight does that by mirroring one task into your main checkout, without writing a commit to your branch.

What Spotlight does

Turn Spotlight on for a task and Termic keeps your main checkout in sync with that task, across three layers:

  1. Committed changes on the task’s branch.
  2. Uncommitted edits in its working tree.
  3. Untracked files, honoring .gitignore.

A background watcher re-syncs within a couple of seconds whenever files change in the spotlighted task, so the main checkout always mirrors what the agent is doing. Now your dev server (running at the main checkout, where it expects to be) sees the agent’s changes and reloads through your own watch setup.

A Termic task with Spotlight running. The bottom-right Spotlight panel lists a timestamped Synced entry naming the four files it mirrored into the main checkout, with a Stop control at its top.

A task with Spotlight active. The panel (bottom right) tracks the sync state; Run executes at the main checkout against the synced files.

No commits on your branch

Termic never writes a commit onto your branch. It checks out the task’s commit at the main checkout as a detached HEAD, so your branch ref never moves. The consequences:

  • Normal operation leaves zero commits behind.
  • A hard crash leaves only a harmless detached HEAD, which a single git checkout recovers.
  • If Termic ever finds the main checkout detached on startup, Spotlight refuses to proceed and tells you exactly how to clean up.

The live sync log

The Spotlight tab in the right panel shows a live sync log that names exactly which files moved on every pass, committed, uncommitted and untracked, so you always know the state of your main checkout.

Close-up of the Spotlight panel showing a timestamped Synced status with no changes, alongside Run and Stop buttons.

A timestamped, live sync line, with Run and Stop beside it.

Run while spotlighted

While a task is spotlighted, the Run button executes your configured run script at the main checkout, in its own tab, like any other Run. And when you switch Spotlight to a different task, Termic stops the old run and restarts it against the new target automatically, so the server you’re testing always tracks the spotlighted task.

Turning it on

Spotlight is off by default. Enable it per project in Settings → Repository → Scripts & run. Once enabled, start or stop it from a task’s menu in the sidebar, or from the Spotlight tab in the right panel.

The sidebar with a spotlighted task named "seo optimizations" marked by a Spotlight icon next to its name.

A spotlighted task is marked in the sidebar, so you always know which one is mirrored to the main checkout.

Guardrails

Spotlight has guardrails because it modifies your main checkout:

  • Worktree tasks only. Spotlight bridges an isolated worktree back to the main checkout, so it only appears for worktree tasks. It’s hidden for main checkout tasks (already at the root), multi-repo tasks, and non-git tasks, where it has nothing to mirror.
  • One task per project can be spotlighted at a time.
  • The main checkout must be on a clean branch to start.
  • Stopping fully restores the main checkout: it re-attaches your branch and removes the untracked files it copied in.
  • Reverts also run on quit, archive and delete, so you don’t end up with a spotlighted state left over.
  • Single-repo projects only, for now. Multi-repo Spotlight is a known gap.

Last reviewed: June 9, 2026