Install¶

gald3r is a single compiled binary (gald3r_core, implemented in Go) that runs the same way on Windows, macOS, and Linux. This page covers every supported install path, in the order you should try them.

Which path should I use?¶

You are...	Use
Trying gald3r for the first time, don't want to build anything	Signed binary and per-OS installers
A contributor, or want the latest unreleased code	From source with Go
Already have `gald3r` installed and want to upgrade	`gald3r install update` (see Upgrading)
Setting up a whole new machine for team use	From source, then `gald3r onboard`

1. Signed binary and per-OS installers (recommended — works today)¶

Every release attaches signed Windows/Linux/macOS binaries and per-OS installers to a GitHub Release on Gald3r-Labs/gald3r_core, with every asset linked directly from the release page (and always available at releases/latest/download/<asset>).

macOS — `.pkg` installer (recommended)¶

Download gald3r-macos-arm64.pkg from the release page.
Double-click it, follow the installer prompts. Installs to /usr/local/bin/gald3r.
Open a new terminal and run gald3r --version.

The .pkg and the binary inside it are both signed as Gald3r Labs LLC and notarized by Apple (the container with a Developer ID Installer certificate, the binary with Developer ID Application) — and the .pkg's notarization ticket is stapled on, so it installs clean with no security prompts, online or offline.

Prefer the bare binary instead? Download gald3r-macos-arm64 (no .pkg suffix) + its .sha256 sidecar, verify the checksum, chmod +x, and place it on your PATH yourself.

Linux — install tarball¶

curl -LO https://github.com/Gald3r-Labs/gald3r_core/releases/latest/download/gald3r-linux-x86_64.tar.gz
tar xzf gald3r-linux-x86_64.tar.gz
cd gald3r-*-linux-x86_64
./install.sh          # ~/.local/bin, or /usr/local/bin if run with sudo
gald3r --version

install.sh verifies the bundled gald3r.sha256 before installing and refuses (loudly) if it doesn't match. Run ./uninstall.sh from the same extracted directory to remove it later.

Prefer the bare binary, a .deb, or an Arch Linux PKGBUILD instead? .deb and AUR package definitions exist in this repo but are not yet wired into the release CI matrix — the tarball above is the fully automated path today; see packaging/deb/README.md / packaging/aur/README.md for the manual build.

Windows¶

gald3r install update

install update downloads the latest signed release for your OS from Gald3r-Labs/gald3r_core, verifies its SHA-256 checksum, and replaces whatever gald3r currently resolves to on PATH. The Windows binary is Authenticode-signed as Gald3r Labs LLC via Azure Trusted Signing. A Windows .msi installer (WiX-built, also Authenticode-signed as Gald3r Labs LLC, so SmartScreen shows the publisher instead of "Unknown") is also published for environments that require the Windows Installer service instead of an ad hoc .exe — the .msi installs both gald3r.exe and gald3rw.exe onto the same PATH entry in one step.

On Windows, gald3r install update likewise refreshes both release assets (gald3r-windows-x86_64.exe → gald3r.exe, and gald3rw-windows-x86_64.exe → gald3rw.exe) in one fail-closed transaction. If either binary is locked by a running process (commonly gald3rw.exe held open by a Windows MCP server), the update aborts with a clear message naming the locked file and rolls back any partial replace. If Windows prevents that rollback too, gald3r fails loudly, retains the .bak-* backup, and gives the exact manual-recovery command instead of falsely reporting a consistent pair. POSIX stays single-binary.

Bootstrapping the very first gald3r (before you have one on PATH to run install update with) is the .pkg/tarball/.msi install above, or — on any OS — a plain download-and-run of the OS-appropriate bare-binary asset from the release's GitHub page.

2. From source (Go) — for contributors¶

Users should install the signed binaries above. This path exists for people contributing to gald3r_core itself — the source repository is private, so building from source requires being granted access first. If you just want to use gald3r, you do not need this section at all.

gald3r is implemented as a Go monorepo (gald3r.ai/cli and its supporting modules). A small Python layer remains for build/release tooling and this documentation site, but the CLI itself is a native Go binary you build with the standard Go toolchain.

Prerequisites¶

Access granted to the private source repository (request it from the team)
Go 1.26+ (see go.work for the exact toolchain version this repo pins)
Git
uv, only if you also want to build this documentation site or run the Python-based release tooling

Build the CLI¶

git clone <the private source repository URL you were granted access to>
cd gald3r_core
go build -o bin/gald3r ./gald3r_cli/cmd/gald3r
./bin/gald3r --version

On Windows, build bin/gald3r.exe the same way; go build produces a native binary with no Python runtime dependency. A fresh, unstamped build reports its honest development version rather than a real release number:

> go build -o bin/gald3r.exe ./gald3r_cli/cmd/gald3r
> ./bin/gald3r.exe --version
gald3r version 0.0.1-dev
  schema/rel version: 3.0.0
  build: <commit> (<timestamp>) [+dirty]

The signed release binaries (above) stamp a real version number at build time; a local from-source build intentionally does not claim one it hasn't earned.

Make `gald3r` reachable from any project¶

Building only puts the binary at the output path you gave go build. To run gald3r from a project of your own (not the source checkout itself), pick one:

Add that output directory to your PATH, then restart your terminal/IDE fully — a process already running when you edit PATH won't see the change.
Invoke the binary by its full path from inside your own project directory.
Run everything through gald3r ... from inside the source checkout and pass --dir <path> (or a verb's own --root/--project-root flag, where one exists) to target a different project.

Building this documentation site¶

The docs site (this one) is built with MkDocs, kept in an opt-in Python extra so a routine Go build stays fast and dependency-free:

uv sync --extra docs
uv run mkdocs build --strict

3. Per-platform IDE integration (CRASH overlay)¶

Once gald3r itself is installed, gald3r setup (or gald3r onboard) scaffolds .gald3r/ in your project. Separately, gald3r platform install writes ONE platform's IDE overlay (commands/skills/agents/rules — the CRASH files an IDE like Claude Code, Cursor, or Copilot actually reads) into your project:

gald3r platform list                 # see the full supported platform roster
gald3r platform install claude       # writes .claude/ into the current directory
gald3r platform install cursor       # writes .cursor/ into the current directory

Real output, run against a scratch project:

> gald3r platform install claude --into .
platform install claude: wrote 633 file(s) into <path>
  + release marker: .claude/.gald3r_overlay.json
  + version stamp: .claude/.gald3r-overlay-version.json

gald3r platform verify checks an installed platform tree is complete; gald3r platform parity diffs your installed overlay against the canonical generator output.

Once installed, see platform-usage.md for what to actually do with that overlay — the /g-/@g- command layer, skills, rules, hooks, and agents you now have available inside your IDE, plus a per-platform quick-start matrix.

gald3r setup/gald3r onboard do NOT install a platform overlay by default. Those two verbs only ever scaffold .gald3r/ — no .claude//.cursor//etc., no wired settings.json — unless you ask. Pass the same opt-in, repeatable --platform NAME flag to either verb to also run the exact install path above in the same command:

gald3r setup --platform claude              # scaffold .gald3r/ AND write .claude/
gald3r onboard --platform claude --platform cursor   # both, in one command

Omit --platform and both verbs print a hint (no IDE overlay installed -- run: gald3r platform install <platform> --into .) instead of leaving you with an unwired project and no indication anything is missing.

Hook wiring: `.claude/settings.json` vs. `.cursor/hooks.json`¶

Installing an overlay copies every hook script (.claude/hooks/*.py) in either case, but each IDE has its own separate file that actually registers those scripts against lifecycle events — copying the scripts alone does nothing until that registration file points at them. platform install writes both in one step, per platform:

Platform	Hook scripts land in	Registered via
Claude Code	`.claude/hooks/*.py`	`.claude/settings.json`'s top-level `"hooks"` key
Cursor	`.cursor/hooks/*.py`	`.cursor/hooks.json`

The .claude/settings.json merge is non-destructive. If a settings.json already exists at the target (your own mcpServers, permissions, env, or other top-level keys), platform install claude writes/updates only the "hooks" key and leaves everything else byte-for-byte untouched. A fresh install (no pre-existing file) creates settings.json containing only the "hooks" key — it never invents mcpServers or permissions you didn't already have.

If you ever see hook scripts sitting in .claude/hooks/ that don't seem to be firing, check that .claude/settings.json actually has a populated "hooks" key; re-running gald3r platform install claude --into . repairs it without touching your other settings.

Upgrading an existing install¶

gald3r install update    # replace the PATH binary with the latest signed release
gald3r version-check     # find out if a newer gald3r is available -- works offline

Stop the local fleet before replacing files¶

Before an update, especially on Windows where a running MCP server can lock gald3r.exe/gald3rw.exe, inspect the persistent gald3r fleet and then request its cooperative shutdown:

gald3r shutdown --dry-run
gald3r shutdown --wait 30
gald3r install update

shutdown identifies executable shims and resident MCP, Valkyrie, and autopilot processes from their executable path and command line. It never targets the command's own shell-parent chain. The command waits only for the bounded --wait period and exits nonzero if a process remains; use gald3r shutdown --force only after reviewing that report, because force termination can discard in-flight work.

version-check reports honestly either way — it does not require network access to run, and tells you if it couldn't reach anything rather than silently assuming you're current.

Confirm the install is healthy¶

gald3r doctor

See the quickstart for full real output of this command and what each line means, and Troubleshooting if anything comes back FAIL instead of OK/WARN.

Windows note — two executables ship on PATH: the release installs BOTH gald3r.exe (console subsystem — terminals, scripts, agent shells; always prints and returns a real exit code, even from a console-less PowerShell host) and gald3rw.exe (GUI-subsystem attach — Windows MCP launch configs stamped at install time, and any other console-less-parented spawn that must never flash a console window). Type gald3r, not gald3rw, in a terminal or script. gald3r doctor reports a windows_dual_exe row when the two binaries report different --version strings. If a gald3r command ever returns instantly with no output at all, see Troubleshooting → "Windows: gald3r returns instantly with no output".