{"_id":"@absolutepraya/wt","_rev":"3-c9d0bdd55d84afa93849636c9ffd84b5","name":"@absolutepraya/wt","dist-tags":{"latest":"0.3.3"},"versions":{"0.3.1":{"name":"@absolutepraya/wt","version":"0.3.1","keywords":["git","worktree","cli","developer-tools"],"license":"MIT","_id":"@absolutepraya/wt@0.3.1","maintainers":[{"name":"absolutepraya","email":"daffaabhiprayaputra@gmail.com"}],"homepage":"https://github.com/absolutepraya/wt#readme","bugs":{"url":"https://github.com/absolutepraya/wt/issues"},"bin":{"wt":"npm/wt.cjs"},"dist":{"shasum":"a2fff12254b636a4d2c88301f850bcf678775dbd","tarball":"https://registry.npmjs.org/@absolutepraya/wt/-/wt-0.3.1.tgz","fileCount":5,"integrity":"sha512-nXxm6enaIpG4fcmroO6+5QHaxNxJN26kevXCb/gjllPEwMALRxUee9yjNh7P9out08L6virmpNg1YCm/UQ/TQA==","signatures":[{"sig":"MEQCIHfYJUZOi9IbPi6leEVOuKSYRC1DIEB0/ms91JnpWYNjAiBqQX9lETjAeTLq+nV+3oDnPleU+8squ1CkhzmES3gyTw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81013},"engines":{"node":">=18"},"gitHead":"3abb4dd4e3202f1d9e123980b2d9d7a93e1c68c6","scripts":{"check":"node --check npm/wt.cjs","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"absolutepraya","email":"daffaabhiprayaputra@gmail.com"},"repository":{"url":"git+https://github.com/absolutepraya/wt.git","type":"git"},"_npmVersion":"10.9.4","description":"Universal git worktree CLI for fast, parallel feature work","directories":{},"_nodeVersion":"22.21.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/wt_0.3.1_1788364699278_0.7021905675673172","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@absolutepraya/wt","version":"0.3.2","keywords":["git","worktree","cli","developer-tools"],"license":"MIT","_id":"@absolutepraya/wt@0.3.2","maintainers":[{"name":"absolutepraya","email":"daffaabhiprayaputra@gmail.com"}],"homepage":"https://github.com/absolutepraya/wt#readme","bugs":{"url":"https://github.com/absolutepraya/wt/issues"},"bin":{"wt":"dist/wt.cjs"},"dist":{"shasum":"1093635b263dfd1a2d11783ca9344a4d48bed0bf","tarball":"https://registry.npmjs.org/@absolutepraya/wt/-/wt-0.3.2.tgz","fileCount":4,"integrity":"sha512-WNGcMvJOSlMllok5qUo7Mq/v5JyCSKV9ABUQZOSIZfXVQ4p2lhdhSvRwo0KVwVRaaCgUo6gelKlbTBynyKzd2A==","signatures":[{"sig":"MEUCIQD4XJ/7ZI1tC6yaN/TtpEYXznrc8zLH/9Jv/n+GCGmaUQIgGGuz00yPcUSUm5FucEeLVw5QMafoHJhw0BFm2z/ElH4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@absolutepraya%2fwt@0.3.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":181865},"_from":"file:/tmp/wt-release-0.3.2-3JDdd7/absolutepraya-wt-0.3.2.tgz","engines":{"node":">=18"},"scripts":{"test":"npm run build && node scripts/run-tests.mjs","build":"node scripts/build.mjs","check":"npm run typecheck && npm run build && node --check dist/wt.cjs","smoke:npm":"npm run build && node scripts/check-npm-package.mjs","typecheck":"tsc --noEmit","pack:check":"npm run build && npm pack --dry-run","check-version":"node scripts/check-version.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:002473cc-c0ec-409f-957a-4eaf714b6c45"}},"_resolved":"/tmp/wt-release-0.3.2-3JDdd7/absolutepraya-wt-0.3.2.tgz","_integrity":"sha512-WNGcMvJOSlMllok5qUo7Mq/v5JyCSKV9ABUQZOSIZfXVQ4p2lhdhSvRwo0KVwVRaaCgUo6gelKlbTBynyKzd2A==","repository":{"url":"git+https://github.com/absolutepraya/wt.git","type":"git"},"_npmVersion":"11.5.1","description":"Universal git worktree CLI for fast, parallel feature work","directories":{},"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.13","esbuild":"^0.28.2","typescript":"^7.0.2","@iarna/toml":"^2.2.5","@types/node":"^26.4.1"},"_npmOperationalInternal":{"tmp":"tmp/wt_0.3.2_1788786540825_0.512395550052847","host":"s3://npm-registry-packages-npm-production"}},"0.3.3":{"name":"@absolutepraya/wt","version":"0.3.3","description":"Universal git worktree CLI for fast, parallel feature work","keywords":["git","worktree","cli","developer-tools"],"license":"MIT","homepage":"https://github.com/absolutepraya/wt#readme","repository":{"type":"git","url":"git+https://github.com/absolutepraya/wt.git"},"bugs":{"url":"https://github.com/absolutepraya/wt/issues"},"engines":{"node":">=18"},"bin":{"wt":"dist/wt.cjs"},"publishConfig":{"access":"public"},"scripts":{"build":"node scripts/build.mjs","typecheck":"tsc --noEmit","test":"npm run build && node scripts/run-tests.mjs","check-version":"node scripts/check-version.mjs","check":"npm run typecheck && npm run build && node --check dist/wt.cjs","pack:check":"npm run build && npm pack --dry-run","smoke:npm":"npm run build && node scripts/check-npm-package.mjs"},"devDependencies":{"@iarna/toml":"^2.2.5","@types/node":"^26.4.1","esbuild":"^0.28.2","tsx":"^4.23.13","typescript":"^7.0.2"},"_id":"@absolutepraya/wt@0.3.3","_integrity":"sha512-89ZK2elMYJ2Z88NxsEB9rIUFROUCUrrichvpJBsilkVhqRkaQob9vC8Enu78bk7nTj2m5Tm+UR14xpcB9p6dFA==","_resolved":"/tmp/wt-release-0.3.3-37SgIN/absolutepraya-wt-0.3.3.tgz","_from":"file:/tmp/wt-release-0.3.3-37SgIN/absolutepraya-wt-0.3.3.tgz","_nodeVersion":"24.20.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-89ZK2elMYJ2Z88NxsEB9rIUFROUCUrrichvpJBsilkVhqRkaQob9vC8Enu78bk7nTj2m5Tm+UR14xpcB9p6dFA==","shasum":"4a8e50ac2793f29c86b77a9ee14fd093a2449845","tarball":"https://registry.npmjs.org/@absolutepraya/wt/-/wt-0.3.3.tgz","fileCount":4,"unpackedSize":185695,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@absolutepraya%2fwt@0.3.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEfGWipmIjzxIM8L9N0KQIbxKK6B6XgErZv5kWicmz9HAiBN+O82SEJXTFymnd95I/J/xavxF581AxaVG/1H2EecaA=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:002473cc-c0ec-409f-957a-4eaf714b6c45"}},"directories":{},"maintainers":[{"name":"absolutepraya","email":"daffaabhiprayaputra@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wt_0.3.3_1788920327796_0.10960363023875752"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T15:58:19.117Z","modified":"2026-09-09T02:18:48.347Z","0.3.1":"2026-09-02T15:58:19.422Z","0.3.2":"2026-09-07T13:09:00.929Z","0.3.3":"2026-09-09T02:18:47.974Z"},"bugs":{"url":"https://github.com/absolutepraya/wt/issues"},"license":"MIT","homepage":"https://github.com/absolutepraya/wt#readme","keywords":["git","worktree","cli","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/absolutepraya/wt.git"},"description":"Universal git worktree CLI for fast, parallel feature work","maintainers":[{"name":"absolutepraya","email":"daffaabhiprayaputra@gmail.com"}],"readme":"# wt\n\n[![CI](https://github.com/absolutepraya/wt/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/absolutepraya/wt/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/%40absolutepraya%2Fwt?logo=npm)](https://www.npmjs.com/package/@absolutepraya/wt)\n[![npm downloads](https://img.shields.io/npm/dm/%40absolutepraya%2Fwt?logo=npm)](https://www.npmjs.com/package/@absolutepraya/wt)\n[![GitHub Release](https://img.shields.io/github/v/release/absolutepraya/wt?display_name=tag&sort=semver)](https://github.com/absolutepraya/wt/releases)\n[![Node.js 18+](https://img.shields.io/badge/node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)\n[![License](https://img.shields.io/github/license/absolutepraya/wt)](LICENSE)\n\nWT is an agent-first Git worktree manager for LLM agents. It lets several agents work concurrently on the same project through one unified worktree manager, regardless of which coding agent you use. Switch between Claude Code, Codex, Cursor, OpenCode, or another agent without changing the project's worktree workflow.\n\nEach agent gets a named, isolated worktree while WT handles branch creation, project setup and teardown, slot allocation, port offsets, and safe cleanup. WT also works well for human-led parallel feature work.\n\n## Why WT\n\nGit worktrees solve the one-checkout-per-branch problem. WT also gives each\nworktree repeatable setup and teardown, a reserved slot, predictable port\noffsets, and a discoverable list of managed and unmanaged worktrees. That\nkeeps several agents from competing over one checkout, one dependency setup,\nor one development port.\n\n## Install\n\nWT has one Node.js CLI and three supported distribution modes. All modes require Node.js 18 or newer and Git.\n\n### Standalone installer, macOS or Linux\n\n```bash\ncurl -fsSL https://github.com/absolutepraya/wt/releases/latest/download/install.sh | bash\n```\n\nThe release-based installer downloads the latest stable release, verifies the SHA-256 manifest and the embedded CLI version, then installs atomically. It installs:\n\n- `~/.local/bin/wt`, the executable\n- `~/.config/wt/wt.sh`, the Bash and Zsh wrapper\n- `~/.config/wt/wt.fish`, the Fish wrapper\n- `~/.config/wt/install.json`, standalone channel metadata\n\nThe installer adds managed wrapper blocks to Bash, Zsh, and Fish startup files. The executable is available immediately at `~/.local/bin/wt` even if that directory is not yet in `PATH`. Future interactive shells that source the relevant rc or config file will load the integration. Bash login shells may not source `~/.bashrc` automatically, so use your shell's normal login configuration or source the wrapper explicitly. For the current shell, add the directory to `PATH` and evaluate the shell initializer as shown below.\n\nThe installer checks the platform, Node.js, and Git before writing the\ndestination files. If Node.js or Git is missing, it stops with an actionable\nmessage and does not install a partial CLI.\n\nThe standalone installer supports macOS and Linux. Windows users should use the npm installation, which supports the CLI and shell initializer on Windows.\n\n### Global npm install\n\n```bash\nnpm install -g @absolutepraya/wt\nwt --help\n```\n\nThis puts the `wt` executable in npm's global bin directory. It does not edit Bash, Zsh, Fish, or PowerShell profiles. Use npm to update it:\n\n```bash\nnpm update -g @absolutepraya/wt\n```\n\n### Project-local npm install\n\n```bash\nnpm install -D @absolutepraya/wt\nnpx --no-install wt --help\n```\n\nThe consuming project's lockfile pins WT for agents and npm scripts. The local package does not edit shell profiles. Use npm to update it:\n\n```bash\nnpm update -D @absolutepraya/wt\n```\n\nThe global and local npm packages use the same bundled `dist/wt.cjs` artifact as the standalone release. npm installs support macOS, Linux, and Windows for the core commands.\n\n### From source\n\n```bash\ngit clone https://github.com/absolutepraya/wt ~/Documents/Projects/wt\ncd ~/Documents/Projects/wt\nnpm ci\nnpm run build\nnode dist/wt.cjs --help\n```\n\nSource checkouts are updated through Git, for example with `git pull --ff-only` after reviewing the incoming changes. `wt update` does not modify a source checkout.\n\n### Requirements and paths\n\n- Node.js 18 or newer\n- Git 2.5 or newer, with worktree support\n- macOS or Linux for the standalone installer\n- macOS, Linux, or Windows for npm installations\n\nStandalone files default to `~/.local/bin` and `~/.config/wt`. Set `PREFIX` or `WT_CONFIG_DIR` for a different standalone location. Project state is kept outside the repository at `~/.wt/<project-id>.json`, with a matching lock path. No npm package installation creates or changes a project's shell profile.\n\n## Shell integration\n\n`wt shell-init` prints the integration for the current shell. It does not edit any profile. The initializer is useful immediately after installation and when a shell uses a custom profile path.\n\n### Bash\n\n```bash\neval \"$(~/.local/bin/wt shell-init bash)\"\n```\n\nTo load it in future shells, source the generated wrapper from a profile:\n\n```bash\nsource ~/.config/wt/wt.sh\n```\n\n### Zsh\n\n```zsh\neval \"$(~/.local/bin/wt shell-init zsh)\"\n```\n\nThe Bash and Zsh initializer output is shell-compatible. A future Zsh can source the same wrapper:\n\n```zsh\nsource ~/.config/wt/wt.sh\n```\n\n### Fish\n\n```fish\n~/.local/bin/wt shell-init fish | source\n```\n\nFor future Fish shells:\n\n```fish\nsource ~/.config/wt/wt.fish\n```\n\n### PowerShell\n\n```powershell\nInvoke-Expression (& wt shell-init powershell)\n```\n\nAdd that line to the PowerShell profile yourself if it should load in future sessions. WT never edits a PowerShell profile automatically.\n\nThe shell wrapper consumes WT's `__cd__:<path>` navigation sentinel for `wt new --cd` and `wt cd`. A child process cannot change the working directory of its parent shell, so running a raw executable as a subprocess cannot navigate the calling shell. Coding agents should use `wt new` without `--cd`, then use the absolute worktree path printed by WT for subsequent commands.\n\n## Quick start\n\nIn a Git repository, create `.wt/config.toml` once if the project is not already configured:\n\n```bash\nmkdir -p .wt\ncat > .wt/config.toml <<'EOF'\nworktree_path = \".worktrees\"\nport_offset_interval = 100\nmax_slots = 9\nEOF\n\nwt new\n```\n\n## Commands\n\n```text\nwt --version, -V                print the installed WT version\nwt --help, -h                   show top-level help\n\nwt new                          create a worktree from origin/main\nwt new [name]                   choose a worktree name\nwt new -b user/feature          choose the branch name\nwt new --from feature-x         base on an existing remote branch\nwt new --no-setup               skip configured setup commands\nwt new --skip-setup             alias for --no-setup\nwt new --cd                     navigate the interactive shell after creation\n\nwt ls                           list managed and unmanaged Git worktrees\nwt list                         alias for ls\nwt cd                           print the current or main worktree path\nwt cd <name>                    print a named worktree path\n\nwt rm <name>                    run teardown and remove the worktree\nwt remove <name>                alias for rm\nwt rm <name> --force            bypass dirty, unmerged, and teardown failures\nwt rm <name> --keep-branch      remove the worktree but preserve its branch\n\nwt update                       update a standalone installation\nwt update --check               check the latest stable release for standalone installs\nwt shell-init bash              print Bash integration\nwt shell-init zsh               print Zsh integration\nwt shell-init fish              print Fish integration\nwt shell-init powershell        print PowerShell integration\n```\n\nRun `wt <command> --help` or `wt <command> -h` for command-specific usage.\n`wt new` stays in the current directory unless its shell wrapper receives\n`--cd`. `wt update` is only a self-mutating command for a standalone\ninstallation. For a standalone install, `wt update --check` checks the latest\nstable release without changing files. For npm or source installs, it does not\ncheck the release service. It only prints guidance to update through npm or\nGit. Use `npm update` for npm installations and Git for a source checkout.\n\n## Configuration\n\nConfiguration is discovered upward from the current directory at `<repo>/.wt/config.toml`:\n\n```toml\nworktree_path = \".worktrees\"\nport_offset_interval = 100\nmax_slots = 9\nname_strategy = \"cities\"              # or \"word_pairs\"\nbranch_template = \"{user}/{name}\"\ndefault_base = \"origin/main\"\n\nsetup = [\n  \"pnpm install --frozen-lockfile\",\n  \"cp .env.example .env.local\",\n  \"bash scripts/start-infra.sh\",\n]\n\nteardown = [\n  \"docker compose -p ${WT_WORKSPACE_NAME} down\",\n  \"docker network prune -f\",\n]\n```\n\n`worktree_path` must remain inside the repository. Each non-main worktree gets the first free slot from `1` through `max_slots` and a port base of `slot * port_offset_interval`. `default_base` defaults to `origin/main`. Setup and teardown arrays run in order from the worktree directory through the platform shell.\n\n### Setup and teardown environment\n\nEvery configured setup and teardown command receives these values without modifying the parent process environment:\n\n| Variable | Example | Purpose |\n| --- | --- | --- |\n| `WT_ROOT_PATH` | `/home/you/code/myrepo` | Main worktree root |\n| `WT_WORKSPACE_NAME` | `rotterdam` | Worktree name |\n| `WT_WORKSPACE_PATH` | `/home/you/code/myrepo/.worktrees/rotterdam` | Absolute worktree path |\n| `WT_BRANCH` | `you/rotterdam` | Live branch name |\n| `WT_SLOT` | `3` | Allocated slot |\n| `WT_PORT_BASE` | `300` | Slot times `port_offset_interval` |\n\nFor example, a service using port `5432` can bind to `5432 + WT_PORT_BASE` in its setup script.\n\n## State, concurrency, and safety\n\nWT stores one JSON state file per project under `~/.wt`. It records the project root and managed slot entries, including the name, branch, relative path, base ref, remote tracking state, creation time, and a generation token. State writes are validated and replaced atomically. A project lock serializes slot allocation and destructive state changes.\n\n- `wt new` fetches the configured base, allocates a slot, creates the Git worktree, persists state, and then runs setup.\n- If setup fails or is interrupted, WT rolls back the newly created worktree and branch while preserving replacement state if another operation has taken ownership.\n- `wt new` is safe to run concurrently. Slot and name allocation are protected by the project lock.\n- `wt rm` refuses to remove the worktree containing the current directory.\n- `wt rm` checks the live branch and worktree identity again after teardown, so a replacement cannot be removed accidentally.\n- Dirty worktrees and branches with unmerged commits require confirmation. `--force` bypasses those checks. `--keep-branch` removes only the worktree.\n- A worktree known to Git but not to WT appears as unmanaged in `wt ls`; remove it with Git rather than `wt rm`.\n- An empty stale lock file from the historical Python standalone CLI is migrated once to the Node directory-lock format, with the original preserved as a backup. Non-empty legacy lock files are rejected for manual inspection.\n- A stale or incompatible state entry is reported and is not silently destroyed.\n\n## Releases and updates\n\n`package.json` is the release version source of truth. CI injects that version into `dist/wt.cjs`, then uses the same bytes for npm and standalone distribution. A stable release has the tag `vX.Y.Z` and these exact assets:\n\n```text\nwt\nwt.sh\nwt.fish\ninstall.sh\nabsolutepraya-wt-X.Y.Z.tgz\nchecksums.txt\n```\n\nThe checksum manifest covers the other five assets. The installer and `wt update` accept only stable `vX.Y.Z` releases, validate the expected release URLs, verify every downloaded checksum, and check the Node shebang and embedded version before replacement. The standalone installer stages its files, runs a direct `--version` and `--help` smoke on the installed executable, and rolls back if installation or that smoke fails. `wt update` uses its existing transactional replacement behavior for the standalone executable, wrappers, and metadata, with rollback on replacement failure; it does not currently run the post-install smoke. See [docs/RELEASING.md](docs/RELEASING.md) for Trusted Publishing and release recovery.\n\n### One-time migration from Python standalone 0.3.x\n\nPython-based standalone users on the 0.3.x line should run the new installer once:\n\n```bash\ncurl -fsSL https://github.com/absolutepraya/wt/releases/latest/download/install.sh | bash\n```\n\nThe installer replaces the old standalone executable and wrappers with the Node-based release after validation. It requires Node.js 18 or newer and Git. No `WT_REF` setting is needed for ordinary installs. Start a new shell, or refresh the current shell using the shell-init examples above, then confirm with `wt --version`.\n\n## For AI coding agents\n\nThis repository ships an Agent Skill at [`skills/wt/SKILL.md`](skills/wt/SKILL.md). It teaches agents when to use WT instead of raw Git worktree commands and how to preserve project safety.\n\nInstall the skill with the [Vercel Skills CLI](https://github.com/vercel-labs/skills):\n\n```bash\nnpx skills add absolutepraya/wt --skill wt\nnpx skills add absolutepraya/wt --skill wt --global --agent codex\n```\n\nAgents should use `wt new` without `--cd`. The successful output contains the worktree path to use for subsequent commands because a child process cannot change the agent host's working directory.\n\n## Development\n\n```bash\ngit clone https://github.com/absolutepraya/wt\ncd wt\nnpm ci\nnpm test\nnpm run check\nnpm run pack:check\nnpm run smoke:npm\nbash -n install.sh\nbash scripts/check-installer.sh\ngit diff --check\n```\n\nThe CI matrix runs Node 18, 20, 22, and 24 on Ubuntu, macOS, and Windows. POSIX installer tests run on Unix runners; Windows validates the cross-platform Node package and shell initializer.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}