{"id":"beam","repo":"maxwell-01/paseo-beam","url":"https://github.com/maxwell-01/paseo-beam","name":"beam","description":"Beam a Paseo workspace's working tree into your one running dev environment; beam out safely restores your checkout.","categories":["git","productivity","automation"],"platforms":[],"caveats":["Only one beam can be active at a time; beam out before beaming another workspace.","Overwrites your main checkout's working tree while active, then restores it on beam out.","The workspace and its main checkout must be worktrees of the same git repo."],"images":["https://github.com/user-attachments/assets/bc223cb5-37dc-47c3-b929-d502be01520b"],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":false,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-14T21:51:49.574Z","addedAt":"2026-09-14T21:09:21+01:00","version":"0.1.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-14T21:50:51.523Z","commit":"178fb37f3e7dccc5af5a6309c1fe0e4c0b46dbdb"},"paseoVersionRequirement":">=0.8.0","manifest":{"id":"beam","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-14T20:18:07Z"},"owner":{"login":"maxwell-01","avatarUrl":"https://avatars.githubusercontent.com/u/45392468?v=4"},"installNotesHtml":"<pre><code class=\"language-bash\">paseo plugin install /absolute/path/to/paseo-beam\npaseo plugin ls\n</code></pre>\n<p>Then open a workspace and either click the <strong>Beam</strong> (⚡) button in the workspace header, or open the\n<strong>Beam</strong> panel (or run <strong>Open Beam</strong> from the command center), and beam in.</p>","readmeText":"# Beam\n\n<img width=\"1283\" height=\"288\" alt=\"image\" src=\"https://github.com/user-attachments/assets/bc223cb5-37dc-47c3-b929-d502be01520b\" />\n\n\nA [Paseo](https://paseo.sh) plugin that continuously mirrors a workspace's entire working tree\nonto your local main checkout on disk, so an already-running dev environment with live-reload\nshows the workspace's changes without you switching branches there.\n\nRequires **Paseo 0.8 or newer**.\n\nSimilar to Conductor's Spotlight feature.\n\n## What it does\n\nWhile a beam is active, Beam watches the workspace directory and, on every change, overwrites your\nmain checkout to match the workspace's current working tree:\n\n- **Beam in** — snapshots main's exact current state (branch, `HEAD`, index, and full working tree\n  including uncommitted, staged, and untracked files), then starts a file watcher on the workspace\n  and runs an immediate sync. Each sync moves main's branch to the workspace's `HEAD` and rewrites\n  main's tracked working tree and index to a snapshot of the workspace's full working tree.\n- **Beam out** — stops the watcher and **restores main to exactly its pre-beam state** — branch,\n  working tree, index, and untracked files all come back as if nothing ever happened.\n\nThe mirror is the **full working tree**, including uncommitted and untracked files, not just\ncommitted changes. `.gitignore` is respected, so ignored files (for example `.env`, `node_modules`)\nare **not** copied from the workspace, and main's own ignored files **survive** each sync. This is\nintentional: your running stack keeps its local environment.\n\nSyncs are mtime-stable: only files that actually differ are rewritten, so the dev server's watcher\nonly reacts to real changes.\n\nBeam appears in three places:\n\n- a **Beam** header button (a ⚡ icon) in each workspace's header, next to the GitHub / \"Update from\n  main\" controls — the primary control. It is the normal color when off and turns **yellow** while\n  this workspace is beaming, with a tooltip that reflects the current state, and one click to beam in\n  or out;\n- a **Beam** workspace panel — toggle, status, and a live activity log of each sync;\n- an **Open Beam** command-center item.\n\n## Install\n\n```bash\npaseo plugin install /absolute/path/to/paseo-beam\npaseo plugin ls\n```\n\nThen open a workspace and either click the **Beam** (⚡) button in the workspace header, or open the\n**Beam** panel (or run **Open Beam** from the command center), and beam in.\n\n## Reversible — your main checkout is safe\n\nBeam is **reversible**. Beaming in is safe even when main has uncommitted, staged, or untracked\nwork: before the first sync, Beam captures main's complete state as a git object snapshot stored\nunder `refs/beam/original` (a real commit chain in the object store — **not** `git stash`, which is\nleft untouched). Beaming out restores main's branch pointer, working tree, index, and untracked\nfiles to exactly that snapshot, so it is as if the beam never happened, and it deletes the temporary\nref. Beaming in on a dirty main is therefore fine.\n\nIgnored files (for example `.env`, `node_modules`) are never captured, never mirrored, and never\ntouched during beam-in, sync, or beam-out.\n\n## Notes and limitations\n\n- **One beam at a time, machine-wide.** Beam tracks the single active mirror through a home pointer\n  file (`~/.paseo-beam-active.json`) plus a per-checkout state file\n  (`<mainPath>/.git/beam-state.json`). Beaming a second workspace — even onto a different checkout —\n  while one is already active is rejected; beam out first.\n- **Ignored during watch:** any path segment named `.git`, `node_modules`, or `.context`, and any\n  filename containing `.tmp.`.\n- **Crash caveat.** If Paseo or your machine stops while a beam is active, main stays mirrored until\n  you beam out (which performs the restore). The snapshot survives under `refs/beam/original` even if\n  the state file is lost, because that ref is a 3-commit chain: the snapshot commit's tree is main's\n  full pre-beam working tree, its parent commit's tree is the pre-beam index, and its grandparent is\n  the pre-beam `HEAD`. Restore by hand with:\n  ```bash\n  git -C <mainPath> read-tree --reset -u refs/beam/original^{tree}\n  git -C <mainPath> reset --soft refs/beam/original^^\n  git -C <mainPath> read-tree refs/beam/original^^{tree}\n  git -C <mainPath> update-ref -d refs/beam/original\n  ```\n  A plain `git -C <mainPath> reset --hard refs/beam/original` only gets the working-tree *contents*\n  right — it leaves the branch pointed at the synthetic `beam: pre-beam snapshot` commit instead of\n  your real pre-beam `HEAD`, and it collapses whatever was staged vs. unstaged into one committed\n  state. Use the four commands above to reproduce the pre-beam state exactly.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\n```\n"}