Astrohacker TermSurf
Astrohacker TermSurf is a desktop host with a real browser in the pane. Run
roamari, open a URL, and the page appears alongside shells and other terminal
workflows.
Open a site in a browser pane:
roamari astrohacker.com
Open the same site under a named browser profile (separate cookies and logins):
roamari 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
This public repository contains the open source client material synced from the
private Astrohacker monorepo for source releases. It includes:
assets/ — the canonical TermSurf mark (termsurf.svg) and its generated
termsurf-<theme>-<size>.<format>/dock projections, 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
Docs beside the web
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 trust astrohackerlabs/astrohacker
brew tap astrohackerlabs/astrohacker
brew install --cask termsurf
To upgrade:
brew update
brew upgrade --cask termsurf
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 code/, 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.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.
Prerequisites
Typical host: Apple silicon macOS, with:
- Xcode (and command-line tools)
- Zig, at the version Ghostty's
forks/ghostty/build.zig.zon names in
minimum_zig_version (same major.minor). Homebrew's plain zig tracks the
newest release and may not match, so install the versioned keg-only formula.
scripts/build.nu finds it, or stops and prints the exact
brew install zig@<major>.<minor> command.
- Rust (
rustup)
- Bun (for TermSurf apps that need it)
- Chromium
depot_tools and a full Chromium source checkout workflow
(large disk + long first build)
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):
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):
# Run from the repository root after provisioning the fork and recorded base.
let entry = (open patches/release-manifest.json | get forks | where name == ghostty | first)
let root = $env.PWD
let files = ($entry.patch_directories | each {|dir|
glob ($root | path join $dir '*.patch') | sort
} | flatten)
git -C $entry.checkout switch -c $entry.branch $entry.base
if not ($files | is-empty) { git -C $entry.checkout am ...$files }
Chromium’s base is an Electron Chromium tag/commit recorded in the
manifest; fetch that tree with / your usual Chromium workflow
into , then apply the Chromium series the same way.
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.nu chromium # Chromium fork / roamari-chromiumd path
scripts/build.nu roamari
scripts/build.nu ahterm
Release-style local build (still requires reconstructed forks):
scripts/build.nu termsurf --release
The host app bundle (when the Ghostty/ahterm build component 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
^(nu ../../scripts/lib/zig-toolchain.nu) build -Demit-macos-app=false
cd macos
./build.nu --configuration Debug --action build
Inside Astrohacker TermSurf, run a local roamari and point it at a built
engine (paths after a successful Chromium/roamari-chromiumd build):
./target/debug/roamari \
--browser ./forks/chromium/src/out/Default/roamari-chromiumd \
https://example.com
License
See LICENSE, NOTICE, and TRADEMARKS.md.
