hayeah/gobin

gobin

gobin is for the "I want to hack on this" workflow. Every install creates a go build shim that rebuilds from source on each run. Edit the source and the next run picks up your changes.

Binaries are installed to ~/.gobin/shims.

If you just need a binary, use go install. gobin is for when you care about the source.

TL;DR

• gobin install ./cli/foo once from the main checkout of the repo. The shim then go builds from that source on every invocation, so any subsequent edits, pulls, or merges to main are picked up automatically — no reinstall needed.
• Never gobin install from a worktree — the shim embeds the source path, so you'd be repointing the global binary at a feature branch and breaking every other process that uses it. See "Never gobin install from a worktree" below.
• Inside a worktree, use go run ./cli/foo (one-off) or go build -o /tmp/foo-test ./cli/foo (throwaway) to test your changes without touching the global shim.

Install

uv tool install -e .

Commands

gobin install <path-or-url>

Creates a go build shim. Reinstalling an existing name overwrites the shim.

# Install from a local package directory
gobin install ./cli/mytool

# Install from an absolute path
gobin install /Users/me/github.com/hayeah/foopkg/cli/foocmd

# Install from a GitHub package path (clones repo if not present)
gobin install github.com/hayeah/foopkg/cli/foocmd

# Install repo root as a package
gobin install github.com/hayeah/foopkg

# Override the binary name
gobin install github.com/hayeah/foopkg/cli/foocmd --name foo

# Pass build flags to go build (everything after -- is forwarded)
gobin install github.com/hayeah/foopkg/cli/foocmd -- -tags integration

# Full clone instead of treeless partial clone (needed for git history or worktrees)
gobin install github.com/hayeah/foopkg/cli/foocmd --full

gobin rm <name>

Removes the shim and its cached binary.

gobin rm foocmd

gobin ls

Lists all gobin-managed shims. Reads the embedded metadata comment from each shim — no registry file needed.

gobin ls
# foocmd  github.com/hayeah/foopkg/cli/foocmd
# bar     /Users/me/projects/bar/cmd/bar

GOBIN_CACHE

By default every shim invocation rebuilds from source. Set GOBIN_CACHE to any non-empty value to skip the build and reuse the cached binary:

GOBIN_CACHE=1 foocmd --help   # fast: skips go build
foocmd --help                  # slow: rebuilds first

If the cached binary does not exist yet, the build runs regardless of GOBIN_CACHE.

Directory layout

~/.gobin/
  shims/    ← add this to PATH
  bins/     ← compiled binaries (written by shims)
  repos/    ← cloned repos (default; see GOBIN_REPOS / GITHUB_REPOS)

Clone behavior

Remote GitHub paths are cloned via git-quick-clone (treeless partial clone by default). Use --full for a complete clone.

Clone root resolution (first set wins):

| Priority | Source | Example result | |----------|--------|----------------| | 1 | $GOBIN_REPOS | $GOBIN_REPOS/github.com/user/repo | | 2 | $GITHUB_REPOS | $GITHUB_REPOS/github.com/user/repo | | 3 | default | ~/.gobin/repos/github.com/user/repo |

Set GITHUB_REPOS=~ to reuse your normal dev layout (~/github.com/user/repo).

If the repo already exists locally, it is reused as-is — no re-clone or pull.

Never gobin install from a worktree

The shim embeds an absolute path to the source dir at install time. If you run gobin install ./cli/foo from inside <repo>/.worktrees/<slug>/, the shim now rebuilds from that worktree on every invocation — until you reinstall from somewhere else. This silently breaks any other process that depends on the same binary, including sibling agents working in parallel branches and the parent shell that spawned them.

Concretely: a feature branch's worktree usually lacks the latest changes from main (or has in-progress changes that aren't ready for callers). Pointing the global shim at a worktree means every foocmd call across the system sees that branch's view until the install is reverted. Caught live three times in one boss-loop session: a sibling agent merged a new subcommand to main, the boss session tried to use it, and got "unknown command" because the shim was still pointing at an older worktree.

Rule: gobin shims always point at the main checkout. Never reinstall from a worktree.

When you need to test a binary from inside a worktree (e.g. you've made changes you want to exercise without polluting the global shim), use go run explicitly:

# inside <repo>/.worktrees/<slug>
go run ./cli/foo --help                # one-off invocation
go build -o /tmp/foo-test ./cli/foo    # local binary, doesn't touch ~/.gobin
/tmp/foo-test --help

If the shim is already pointing at the main checkout, you don't need to do anything after a merge — the next invocation rebuilds from main automatically. Reinstall is only needed to repoint the shim, e.g. to recover from an earlier gobin install that mistakenly ran inside a worktree. In that recovery case: cd to the main checkout and gobin install ./cli/foo to point the shim back at main.

Quirks

• gobin ls only shows shims that contain the # gobin: comment. Plain shell scripts in ~/.gobin/shims/ not created by gobin are silently ignored.
• The binary name defaults to the last path segment of the package path (same as go install). Use --name to override.
• gobin never updates an existing clone. To get the latest code, cd into the repo and git pull yourself.
• Shim paths embed the absolute local path at install time. If you move the repo, reinstall the shim. (See "Never gobin install from a worktree" above for why this matters.)