Install and Update

Install & Update

A tool that is hard to install never gets adopted, and a tool that silently goes stale loses the trust that made it useful. Both the first install and every update are designed to be one command, with the surprising-failure modes engineered out.

One-command install

curl -fsSL https://cdn.jsdelivr.net/npm/dreamcontext/install.sh | sh

install.sh ships inside the npm tarball and is served through the jsdelivr CDN. That detail matters: the CDN serves the published package, so the installer works even when the source repo is private — no GitHub access, no auth, no clone. The script is deliberately conservative:

• POSIX sh, not bash — runs on the default shell everywhere.
• Node ≥ 18 gate. Checks the version up front and exits with a clear message rather than failing halfway.
• No sudo, no eval, no nested remote pipe. Nothing in the script escalates privileges or pipes a second remote payload into a shell. You can read the whole thing before running it.
• Idempotent and non-TTY safe. Re-running it is harmless, and it works in CI or any non-interactive shell.
• Install-or-update by detection. If _dream_context/ already exists, the script updates in place; otherwise it does a fresh install. The same one-liner is both your install and your upgrade path.

Two things to update

There are two distinct artifacts, and conflating them is the usual source of "I updated but nothing changed":

1. The CLI binary — installed globally via npm. dreamcontext upgrade runs npm install -g dreamcontext@latest. dreamcontext upgrade --check prints current: X latest: Y and exits without installing.
2. The project's installed files — the skill, agents, and hooks copied into .claude/ or .agents/ at install time. These are per-project snapshots; upgrading the global CLI does not retroactively rewrite them. dreamcontext update refreshes them to match the newly-installed CLI, preserving your own non-managed content.

So a full update is dreamcontext upgrade (get the new CLI) followed by dreamcontext update (propagate it into this project) — or just re-run the curl … | sh one-liner, which does both.

The in-session update nudge

The hard constraint: tell the user about a new version without ever slowing session start. Session start is the hot path — it runs on every single session, and the whole point of dreamcontext is that the agent wakes up instantly with context already loaded. A blocking network call there would defeat the product.

The design separates the two concerns:

• The SessionStart snapshot reads a cached result only. buildNudge() looks at _dream_context/state/.version-check.json and, if a newer version is recorded, prepends a single-line nudge to the agent's context. It never makes a network call. If there is no cache, there is no nudge — session start is never blocked or slowed.
• The actual npm lookup runs off the hot path. The single network call fires from the UserPromptSubmit hook, at most once every 24 hours, and writes the result to the cache for the snapshot to read next time. It is wrapped in try/catch and fails silent — if npm is unreachable, nothing breaks and no error surfaces.
• Fully opt-out. Set DREAMCONTEXT_VERSION_CHECK=0 and no check ever runs.

One related fix shipped alongside this: the CLI version string used to be hardcoded (.version('0.1.0')), which drifted from package.json. It now reads from the manifest via dreamcontextVersion(), so --version, the nudge comparison, and the published package can never disagree.

---

Part of the dreamcontext deep dive — Home · README