Add self-update support with background checks

README.md

@@ -108,6 +108,20 @@ git push origin main
 git push --tags
 ```
 
+## Auto-update
+
+Prebuilt binaries check for updates automatically on startup and download new versions in the background. The update is applied on the next startup.
+
+```bash
+# manually check for updates
+loop update
+
+# same thing (alias)
+loop upgrade
+```
+
+When running from source (`bun src/loop.ts`), auto-update is disabled — use `git pull` instead.
+
 ## Options
 
 - `-a, --agent <claude|codex>`: agent to run (default: `codex`)

src/loop.ts

@@ -1,9 +1,16 @@
 #!/usr/bin/env bun
 import { cliDeps } from "./loop/deps";
+import { updateDeps } from "./loop/update-deps";
 
 const TMUX_DETACH_HINT = "[loop] detach with Ctrl-b d";
 
 export const runCli = async (argv: string[]): Promise<void> => {
+  await updateDeps.applyStagedUpdateOnStartup();
+  if (await updateDeps.handleManualUpdateCommand(argv)) {
+    return;
+  }
+  updateDeps.startAutoUpdateCheck();
+
   if (process.env.TMUX) {
     console.log(TMUX_DETACH_HINT);
   }

src/loop/args.ts

@@ -3,6 +3,7 @@ import {
   DEFAULT_CODEX_MODEL,
   DEFAULT_DONE_SIGNAL,
   HELP,
+  LOOP_VERSION,
   VALUE_FLAGS,
 } from "./constants";
 import type { Agent, Format, Options, ReviewMode, ValueFlag } from "./types";
@@ -100,6 +101,11 @@ const consumeArg = (
 ): { nextIndex: number; stop: boolean } => {
   const arg = argv[index];
 
+  if (arg === "-v" || arg === "--version") {
+    console.log(`loop v${LOOP_VERSION}`);
+    process.exit(0);
+  }
+
   if (arg === "-h" || arg === "--help") {
     console.log(HELP);
     process.exit(0);

src/loop/constants.ts

@@ -1,15 +1,19 @@
+import pkg from "../../package.json";
 import type { ValueFlag } from "./types";
 
 export const DEFAULT_DONE_SIGNAL = "<promise>DONE</promise>";
 export const DEFAULT_CODEX_MODEL = "gpt-5.3-codex";
 export const DEFAULT_CLAUDE_MODEL = "opus";
+export const LOOP_VERSION = pkg.version;
 
 export const HELP = `
-loop - meta agent loop runner
+loop - v${LOOP_VERSION} - meta agent loop runner
 
 Usage:
   loop                              Open live panel for running claude/codex instances
   loop [options] [prompt]
+  loop update                       Check for updates and stage if available
+  loop upgrade                      Alias for update
 
 Options:
   -a, --agent <claude|codex>        Agent CLI to run (default: codex)
@@ -21,7 +25,12 @@ Options:
   --review [claude|codex|claudex]   Review on done (default: claudex)
   --tmux                            Run in a detached tmux session (name: repo-loop-X)
   --worktree                        Create and run in a fresh git worktree (name: repo-loop-X)
+  -v, --version                     Show loop version
   -h, --help                        Show this help
+
+Auto-update:
+  Updates are checked automatically on startup and applied on the next run.
+  Use "loop update" to manually check and stage an update.
 `.trim();
 
 export const REVIEW_PASS = "<review>PASS</review>";

src/loop/update-deps.ts

@@ -0,0 +1,11 @@
+import {
+  applyStagedUpdateOnStartup,
+  handleManualUpdateCommand,
+  startAutoUpdateCheck,
+} from "./update";
+
+export const updateDeps = {
+  applyStagedUpdateOnStartup,
+  handleManualUpdateCommand,
+  startAutoUpdateCheck,
+};