Astrohacker TermSurf

Astrohacker TermSurf is a desktop host with a real browser in the pane. Run ahweb, open a URL, and the page appears alongside shells and other terminal workflows.

Open a site in a browser pane:

ahweb astrohacker.com

Open the same site under a named browser profile (separate cookies and logins):

ahweb astrohacker.com --profile work

TermSurf apps are native graphical apps that run inside your terminal with real GUIs based on web technologies. Two examples ship with the product:

Open the scientific calculator:

ahcalc

Open the KeyPears client:

ahkey

This public repository contains the open source client material synced from the private Astrohacker monorepo for source releases. It includes:

• assets/ — TermSurf mark SVG and icon masters (termsurf-icon.svg, termsurf-14-*.png), plus product story screenshots under assets/screenshots/story/.
• docs/ — product docs and public legal/records.
• scripts/ — public build/install helpers and smoke scripts.
• rust/ — TermSurf client/protocol/native support code.
• patches/ — shipped fork patch archives, per-fork READMEs, and release-manifest.json (Chromium, Ghostty, Nushell, Reedline, plus historical WebKit/Gecko/Ladybird records).

Large upstream fork checkouts and build outputs are not committed here (forks/ is intentionally empty/gitignored). You reconstruct local engine and host workspaces from patches/ before a from-source build.

Product story shots from a real Astrohacker TermSurf window (multi-profile first, then composition, then solo surfaces).

This is Astrohacker TermSurf: a normal terminal window with a real Chromium browser running as a pane—same app, same window, not a separate browser you alt-tab to.

The Astrohacker Homebrew cask targets Apple silicon macOS and installs into /Applications as Astrohacker TermSurf.app:

brew tap astrohackerlabs/astrohacker
brew trust astrohackerlabs/astrohacker
brew install --cask astrohacker

To upgrade:

brew update
brew upgrade --cask astrohacker

Most people should use the Install section above. Building from this repo is for developers who want a patched engine and host from source.

scripts/build.nu only compiles workspaces that already exist under forks/. If forks/chromium/src (or Ghostty, etc.) is missing, the script skips that component — it does not download upstream or apply patches for you.

Typical host: Apple silicon macOS, with:

• Xcode (and command-line tools)
• Zig
• Rust (rustup)
• Bun (for TermSurf apps that need it)
• Chromium depot_tools and a full Chromium source checkout workflow (large disk + long first build)

brew install zig
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
curl -fsSL https://bun.sh/install | bash

Install Chromium depot_tools and follow Google’s Chromium macOS setup for fetching source (this repo does not vendor Chromium).

1. Read patches/README.md and the machine-readable pin patches/release-manifest.json (ordered patch_directories, base, expected_head / expected_tree per shipped fork).

2. For each fork you need, follow that fork’s README (clone/checkout base, create the product branch, git am the ordered archives):

   Fork	Checkout path	Docs
   Chromium (shipped engine)	forks/chromium/src	patches/chromium/README.md
   Ghostty (host / ahterm)	forks/ghostty	patches/ghostty/README.md
   Nushell	forks/nushell	patches/nushell/README.md
   Reedline	forks/reedline	patches/reedline/README.md

   WebKit / Gecko / Ladybird under patches/ are historical only — not required for a current product build.

3. Pattern (simplified; use the base SHA and archive list from the release-manifest + per-fork README, not invent paths):

   # Example shape only — replace base, branch, and archive dirs from the pin.
   cd forks/<fork>
   git checkout <base-from-release-manifest>
   git checkout -b <product-branch-name>
   git am ../../patches/<fork>/patches/<issue-dir>/*.patch
   # …apply every directory listed for that fork in order…

   Chromium’s base is an Electron Chromium tag/commit recorded in the manifest; fetch that tree with depot_tools / your usual Chromium workflow into forks/chromium/src, then apply the Chromium series the same way.

4. Confirm git rev-parse HEAD (and tree, if you verify) matches expected_head / expected_tree in release-manifest.json for that fork.

Expect a large Chromium build (many GB, often hours on first compile).

After forks are reconstructed and (for Chromium) built as needed:

scripts/build.nu chromium      # Chromium fork / ah-chromiumd path
scripts/build.nu ahweb
scripts/build.nu ahterm

Release-style local build (still requires reconstructed forks):

scripts/build.nu all --release

The host app bundle (when Ghostty/ahterm succeeds) is written to:

forks/ghostty/macos/build/Release/Astrohacker TermSurf.app

During development, launch the Ghostty-based host from the reconstructed Ghostty workspace:

cd forks/ghostty
zig build -Demit-macos-app=false
cd macos
./build.nu --configuration Debug --action build

Inside Astrohacker TermSurf, run a local ahweb and point it at a built engine (paths after a successful Chromium/ah-chromiumd build):

./rust/target/debug/ahweb \
  --browser ./forks/chromium/src/out/Default/ah-chromiumd \
  https://example.com

See LICENSE, NOTICE, and TRADEMARKS.md.