uxfront
unpack · execute · debug

Any git ref, running locally in one command

uxd turns a PR number, a branch, a commit, a URL, or a path into an isolated git worktree — dependencies installed, ports allocated, dev server up.
Get startedStar on GitHub
Terminal
uxd my-project 42 code
uxd my-project 42 run dev
uxd my-project clean --merged

Every command is the same three steps

One pipeline behind every verb. Learn it once and the whole CLI is predictable.
  • resolve the ref
    A PR number, a branch, a 40-char SHA, a URL, or a local path becomes one concrete git target. First match wins.
  • materialize the workspace
    A worktree exists, with dependencies installed, seed files copied, and ports allocated. Idempotent — and cheap when it already exists.
  • act on it
    Open an editor, run a configured command, exec, drop into a shell, diff, or sync. checkout is this pipeline with a no-op act step.

Any ref you can name

If you can point at it, uxd can run it. No cloning, no stashing, no "let me finish what I'm doing first".
  • Six kinds of ref
    PR numbers, branches, SHAs, GitHub URLs, local paths, and - for the last ref you used.
  • Paste the URL
    A GitHub PR or tree URL carries the project and the ref, so one argument is the whole command.
Six ways to name the same thing
uxd my-project 42            # pull request
uxd my-project feat/login    # branch
uxd my-project 1a2b3c…       # 40-char SHA
uxd my-project - shell       # last used ref
uxd …/pull/42 code           # straight from a URL

Isolated by construction

Three branches can run at once without fighting over a port or a node_modules.
  • A port of its own
    uxd allocates free ports, exported as $UXD_PORT and templated into your commands.
  • Setup that remembers
    cache_key globs mean installs rerun only when the lockfile actually moves.
~/.config/uxd/projects/acme-web.toml
[ports]
count = 1

[env]
PORT = "{port}"

From open to disposed

A workspace has a lifespan. uxd covers all of it, then cleans up after itself.
  • One verb per intent
    code, run, shell, exec, diff, sync — each materializes first, so there is no wrong order.
  • See the whole board
    list shows every workspace with its branch, port, age, PR state and CI mark.
  • Reclaim the disk
    clean --merged, --closed, --older-than 7d. Prints a plan, asks first, skips dirty trees.

Runs on the stack you already have

No new runtime, no daemon, no account.
  • Stock Node, plain git
    Node ≥ 18 and git ≥ 2.38. Install it with npm, pnpm, or yarn — no Bun or Deno required.
  • gh optional
    With it you get PR state, CI marks, and true PR diffs. Without it, every feature degrades gracefully.
  • One TOML per project
    Commands, env, hooks, editor, ports — versioned as text, validated in aggregate by config validate.

Materialize your first workspace

uxd setup creates the config dir, scaffolds your first project file, and prints the next command to run.
Get startedCLI reference