halo DocsGitHub

Getting started

Install

Homebrew

Builds from source and needs Xcode 16+. Homebrew loads code only from taps you trust, so trust the halo formula once (Tap Trust):

brew tap bfpimentel/tap
brew trust --formula bfpimentel/tap/halo   # Homebrew 6+: third-party taps need explicit trust
brew install halo

Nix

The flake installs the prebuilt universal binary of the latest release, wrapped to use nixpkgs' esbuild. Add it as an input:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  halo = {
    url = "github:bfpimentel/halo";
    inputs.nixpkgs.follows = "nixpkgs";
  };
};

Then enable it in one of the modules. Each installs halo and runs halo start at login.

nix-darwin:

darwinConfigurations.my-mac = nix-darwin.lib.darwinSystem {
  modules = [
    halo.darwinModules.default
    { services.halo.enable = true; }
  ];
};

home-manager:

{ inputs, ... }:
{
  imports = [ inputs.halo.homeManagerModules.default ];
  services.halo.enable = true;
}
Option Default Does
services.halo.enable false Install halo and add the launchd agent
services.halo.package the flake's default package The halo build to run
services.halo.configDir null ($XDG_CONFIG_HOME/halo) Passed to halo start --config
nix-darwin home-manager
launchd label org.nixos.halo org.nix-community.home.halo
Agent output halo log only also ~/Library/Logs/halo.log

The agent restarts only after a crash, so halo quit keeps it stopped. Start it again with launchctl kickstart gui/$(id -u)/<label>, or run halo start yourself.

Without the modules:

nix run github:bfpimentel/halo -- start              # try it
nix profile install github:bfpimentel/halo           # install, no agent

or environment.systemPackages = [ halo.packages.${pkgs.system}.default ]; (home.packages in home-manager).

Update with nix flake update halo and rebuild: each release pins itself in the flake.

Create a config

halo init

Creates ~/.config/halo/main.tsx and a tsconfig.json that gives your editor halo's types. main.tsx default-exports a component; everything it renders is on screen.

Run

halo start

The starter widget: a clock in the corner

Edits under the config folder reload on save. A build error keeps the previous version running and shows a panel in the corner; runtime errors show there too, with your file and line. Full output: halo log.

Start at login

Next