Run Terrarium in a real repository.

Install the Mac app

Get the signed app from Downloads, open the disk image, and drag Terrarium to Applications. Open it and choose your repository folder. The standalone Mac app includes its runtime; no separate Node installation is needed. Use Switch Project… in the top-left menu or menu bar icon near the clock to open another repository.

Mac, Windows, and npm 0.0.24 include whole-file reading, commit-linked HTML snapshots, worktree navigation, and the local review watchlist. The desktop apps also show startup progress and offer project switching in the top-left menu.

Install the Windows preview

Download the signed Windows 0.0.24 installer from Downloads. Run it for your Windows user account, open Terrarium, and choose a repository. The x64 installer includes its runtime; no separate Node installation is needed. Use Switch Project… in the top-left menu or system tray to open another repository. If you have used Terrarium before, it may reopen your last project instead of showing a folder picker.

Automated Windows installation, launch, repository watch, and restart checks passed. Personal-PC testing of 0.0.23 confirmed launch and project switching. That first launch took about a minute; reopening was quick. Broader physical-PC checks are still pending for this release. SmartScreen may warn about an unrecognized app; the expected publisher is GRAINWORK LLC.

The first launch can take longer while Terrarium prepares the repository. The startup screen shows the current step and elapsed time. Reopening is usually quicker; please report a startup that never completes.

The expected publisher is GRAINWORK LLC. In the downloaded file's Properties, check Digital Signatures and confirm Windows reports a valid signature. You can compare the SHA-256 checksum with the one on the download page using PowerShell:

Stop if the signature is invalid, the publisher differs, or the checksum does not match. A new release may show “Windows protected your PC” even with a valid signature. Signing verifies the publisher; SmartScreen also considers download reputation. Select More info to check the publisher, then decide whether to proceed. You do not need to turn off Microsoft Defender. Please report installation problems, including your Windows version and the exact message.

Install from the terminal

Requires Node 22.12 or newer. Python 3.9 or newer adds structural detail for Python files. @latest selects the current public npm release and --yes accepts npm's install question. The command starts a verified background watch, opens a tokenized localhost URL, and returns your prompt after readiness. Add --no-open when you only want the printed URL. Use the exact stop command Terrarium prints when you are finished.

Useful commands

npx --yes terrarium-watch@latest start .

Install without a confirmation prompt, start a verified background watch, and return the terminal after readiness.

npx terrarium-watch@latest .

Watch this repository until Control-C.

npx terrarium-watch@latest doctor .

Read the repository, agent-store, watch, version, and privacy status without writing or contacting an external service.

npx --yes terrarium-watch@latest review . --base HEAD --markdown

Print a Markdown handoff for the current Git changes.

npx terrarium-watch@latest open

Reopen an already-running local interface.

npx terrarium-watch@latest replay file.jsonl

Replay a saved session.

npx terrarium-watch@latest init-hooks .

Opt in to lower-latency Claude Code hooks.

npx terrarium-watch@latest tail --live

Stream raw events for inspection.

What you should see in the first minute

The map should fill with the repository's files right away. Keep Terrarium open, then use Claude Code or Codex in the same repository and ask it to read a file. The activity should appear with that file as its target. If the agent edits the file, Terrarium marks the reported action and the change confirmed on disk separately. The review-first queue then ranks up to five confirmed files and explains each priority.

Review priority is not a failure prediction. A fallback risklabel means the detailed receipts were unavailable for that file. Apartial map label means the repository exceeds the current mapping boundary; Terrarium shows the exact mapped count and proven lower bound instead of implying complete coverage.

If the real repository stays quiet, confirm that Terrarium and the agent are using the same repository. Run npx terrarium-watch tail --live to see whether Terrarium is receiving agent events.

Update

For the Mac app, quit Terrarium, download the current disk image, and replace Terrarium in Applications. Your local recordings stay in place. For Windows, quit Terrarium and run the current signed installer from Downloads for the same Windows user account. The following commands update the terminal edition.

Stop an existing watch with its printed stop command first, then run this to start the latest release from npm. Starting again without stopping can reopen the watch that is already running. Your recordings under ~/.terrarium stay where they are.

To install or upgrade the global command, use npm install --global terrarium-watch@latest, then terrarium start .. A fresh npm install terrarium-watch selects the latest npm release. Plain npm install in an existing project respects its dependency ranges and lockfile; use npm install terrarium-watch@latestto upgrade that project's dependency.

The in-product guide → check npm for updates action checks only when you ask. It reports versions without installing anything; normal watch startup does not contact npm.

Review the work, including changes you missed

Review first ranks up to five confirmed files and shows why each surfaced. Choose review current changes to scan the whole Git working tree against local HEAD, including edits made before you started Terrarium. The scan is read-only and does not fetch or run your project's code.

To carry that review into a handoff, run npx --yes terrarium-watch@latest review . --base HEAD --markdown. The report includes changed file paths, review priorities, and available receipt summaries. It leaves out source contents and raw agent transcripts. Read the output before sharing it; Terrarium does not send it for you.

Return after the page has been away for more than five minutes and while you were away summarizes recorded changes with up to three review targets. History opens the local archive and replay controls. Missing historical risk receipts are labeled as missing, rather than inferred from today's code.

Move between projects

Click the repository and branch in the top line to choose another existing checkout or open a verified running watch. Recent projects mentioned in local Codex or Claude transcripts can appear too; choose start watch to open one. Terrarium does not change branches, start discovered projects automatically, or treat an old agent report as proof that the agent is still running.

Connect your Mac and PC

Open connected → set up on each installation. Exchange the public pairing offers, compare the complete fingerprints, then choose which projects that installation may share. You can exchange encrypted state files manually or start a bridge through a folder you already synchronize between the machines.

Each sender applies its project boundary before encryption. The connected panel groups imported state by the local names you give paired installations, shows its age, and provides bridge status, stop, and revocation controls. Terrarium does not synchronize your Git checkout, open a network relay, or claim that an agent in imported state is still running. Your chosen folder-sync service transfers the encrypted files and may see filenames, sizes, and timing.

Let agents read the same evidence

Add Terrarium's local MCP server to Codex or Claude Code to expose the same reported activity shown in the interface. Observation is read-only. An agent can request an encrypted message for another reported agent, but it stays in the owner-local inbox until you approve it. The recipient must deliberately pull it; Terrarium does not inject prompts, launch agents, or claim delivery.

What Terrarium reads

Terrarium reads the repository you point it at. It also scans ~/.claude/projects and ~/.codex, then filters events to that repository. Agent transcripts can contain your prompts and the agent's reasoning verbatim.

Recordings are written to ~/.terrarium/sessions. They can include absolute paths, agent quotes, and source-like labels, so treat them as sensitive. To remove a recording, delete only its selected JSONL file under ~/.terrarium/sessions. Revoke any hosted replay links separately before a full reset. Deleting all of ~/.terrariumalso removes the device key, share ledger, and proofs needed to revoke links from this computer; it does not delete hosted copies.

Language support

TypeScript, JavaScript, and Python receive full symbol-level anatomy today. Other files still appear as cells on the map, without structural detail.

Save a snapshot

Choose save snapshot in the map controls to download the visible stage as a branded PNG. Terrarium makes the image in your browser and does not upload it. The footer omits the repository name, but file labels can still appear, so review the image before sharing it.

Mac 0.0.24 can also save a static map image as HTML with the checkout's commit ID, observation time, and clean, dirty, or unknown working-tree state. A supported repository origin adds a commit link that reveals the repository address. Other origins keep the full commit ID without a link. HTML export requires a connected live map with a readable commit; replays and repositories without a commit can save PNG. Review before sharing: private or unpushed commits may not open for recipients, and uncommitted work is not included in the linked commit. Saving HTML does not upload it. Both HTML and PNG snapshots are available in 0.0.24.