| name | hotspot |
| description | Use when a user wants to preview, hot-reload, swap, or sync one active Git worktree into a stable checkout with the hotspot CLI. Helps agents run a long-lived dev server from one repo folder while switching which worktree is mirrored into it. |
Hotspot
Hotspot mirrors one active Git worktree into a stable target checkout. Use it when the user wants a dev server to keep running from the target repo while agents or editors make changes in separate worktrees.
Install
Install the CLI globally:
npm install --global @aident-ai/hotspot
Confirm the binary is available:
hotspot --help
If global installation is not available, run the CLI through npm:
npx @aident-ai/hotspot --help
Commands
Check current ownership first:
hotspot status --target <target-checkout>
Start live mirroring:
hotspot activate <source-worktree> --target <target-checkout>
Switch the active source:
hotspot activate <new-source-worktree> --target <target-checkout> --replace
Stop mirroring:
hotspot deactivate --target <target-checkout>
Run one mirror pass without watching:
hotspot sync <source-worktree> --target <target-checkout>
Agent Workflow
- Confirm
<source-worktree> and <target-checkout> are Git worktrees for the same repo.
- Run
git status --short in the target checkout and avoid mixing Hotspot output with meaningful local edits unless the user explicitly wants that checkout used for previewing.
- Run
hotspot status --target <target-checkout> before activation.
- Use
--replace only when the user wants to switch the active preview source.
- Keep the dev server running from the target checkout, not from the source worktree.
- Use
hotspot deactivate --target <target-checkout> when the preview session is done.
Hotspot copies tracked files plus non-ignored untracked files from the source into the target. Ignored files such as node_modules, build output, and local env files stay in the target checkout.
