Introduction

uxd — unpack, execute, debug — materializes any git ref of a configured project into an isolated, runnable local workspace with one command.

AI coding agents produce branches and pull requests faster than anyone can read them. Reading a diff tells you what changed; it does not tell you whether the app still works. uxd closes that gap: it turns a ref — a PR number, a branch, a commit, a URL, or a local path — into a ready-to-run git worktree, so you can start the app, click through the UI, and poke at the change instead of reviewing blind.

uxd my-project 42 code        # PR #42 → worktree → open in editor
uxd my-project 42 run dev     # same workspace → install deps → start dev server
uxd my-project clean --merged # dispose of workspaces whose PRs merged

The one pipeline

Every workspace command is the same three steps:

resolve(ref) → materialize(workspace) → act(command)

Resolve turns a ref into a concrete git target. Materialize ensures a worktree exists for that target, with dependencies installed, seed files copied, and ports allocated — idempotent, and cheap when the workspace already exists. Act does the thing you asked for: open an editor, run a configured command, exec an arbitrary command, drop into a shell, diff, or sync.

checkout is the pipeline with a no-op act step. Every other verb is a thin wrapper over it. Learn the pipeline once and the whole CLI follows.

What you get

Where to go next

• New here? Install uxd, then follow the quick start.
• Want the model in your head? Read how it works and refs.
• Have a task in mind? Start with the guides.
• Looking up a flag? Go straight to the CLI reference.