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 product help cheatsheet:

ahhelp

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.

Screenshots

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

Two different browser profiles in one window

Two real browser panes at once

Shell and browser, same window

Product apps beside the web

Help open while you browse

Apps compose with apps

Browse the web inside your terminal

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.

Still a terminal when you want one

Install

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

Build

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

What this repo includes (and what it does not)

Included	Not included
Client source under `rust/`, scripts, docs, assets	Pre-built engines or app bundles
`patches/` — full `.patch` archives + reconstruction notes	Checked-in `forks/` trees (Chromium, Ghostty, …)
`patches/release-manifest.json` — exact bases, heads, ordered patch dirs	Automatic one-command clone of Chromium (you reconstruct manually)

scripts/build.sh 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.

Prerequisites

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).

Reconstruct forks from patches (required before build)

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

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.

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.
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).

Compile client components

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

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

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

./scripts/build.sh all --release

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

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

Run

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

License

See LICENSE, NOTICE, and TRADEMARKS.md.