@cniska/agent-worktree 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoffer Niska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# agent-worktree
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Task worktrees for coding agents: one checkout per task, set up and torn down by the project's own commands
+
+[![CI](https://img.shields.io/github/actions/workflow/status/cniska/agent-worktree/check.yml?branch=main&style=flat&label=ci)](https://github.com/cniska/agent-worktree/actions/workflows/check.yml) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat)](LICENSE)
+
+agent-worktree never works out what a checkout needs: `agent-worktree install` writes the setup and teardown commands and the port count the project gives it into hooks, and agent-worktree runs those.
+
+- `agent-worktree create <name>` makes a git worktree outside the repository, on a new branch cut from `origin`'s default branch as `origin` has it now, runs the project's setup hook in it, and prints its path in its result.
+- `agent-worktree remove <name>` runs the project's teardown hook, removes the worktree, and once its remote's default branch has the branch, deletes it locally and on that remote: its upstream or, with none, the branch of the same name on `origin`, other than `origin`'s default branch. When the remote branch holds a commit the branch lacks, it keeps both copies.
+- The `cniska-worktree` Claude Code plugin sends Claude Code's own worktrees through the same commands.
+
+## Install
+
+Install the `agent-worktree` command for macOS on Apple silicon or Linux on x64 through one of these channels.
+
+With the release's installer:
+
+```bash
+curl -fsSL https://github.com/cniska/agent-worktree/releases/latest/download/install.sh | sh
+```
+
+With Homebrew:
+
+```bash
+brew install cniska/tap/agent-worktree
+```
+
+With npm:
+
+```bash
+npm install -g @cniska/agent-worktree
+```
+
+With Bun:
+
+```bash
+bun add -g @cniska/agent-worktree
+```
+
+The curl line installs `~/.local/bin/agent-worktree` and, when that directory is not on your `PATH`, adds it to `~/.zshrc` for zsh or to an existing `~/.bashrc` or `~/.bash_profile` for bash, and otherwise asks you to add it. Each channel updates the way it installed: `brew upgrade agent-worktree`, `npm update -g @cniska/agent-worktree`, `bun update -g @cniska/agent-worktree`, or the curl line run again.
+
+Then install the Claude Code plugin:
+
+```bash
+claude plugin install cniska-worktree@cniska
+```
+
+## Why
+
+Two agents in one checkout overwrite each other's files, so parallel work needs a checkout per task. A bare `git worktree add` gives one that is not ready to work in, and whatever it started outside its directory, such as a database, is left running when the work is done.
+
+Claude Code makes worktrees of its own, for EnterWorktree and for subagents, without the project's setup, and repoints git's `core.hooksPath` when it does, so a `post-checkout` hook cannot do the setup either. agent-worktree owns the whole lifecycle: it creates the worktree, runs the setup, records whether it finished, and runs the teardown before the worktree goes.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `agent-worktree install [--local] [--setup <command>] [--teardown <command>] [--ports <n>]` | Write the project's hooks |
+| `agent-worktree create [--from <ref>] <name>` | Create the worktree, run setup, print the path |
+| `agent-worktree remove [--force] <name>` | Run teardown, remove the worktree and settle its branch |
+| `agent-worktree prune` | Tear down gone worktrees and remove those whose branch landed |
+| `agent-worktree ls [--full]` | Count the worktrees in each state and list them; also what `agent-worktree` alone prints |
+| `agent-worktree path <name>` | Print the worktree's path |
+
+Each command prints its result, or its error, as one [TOON](https://toonformat.dev) document. [Commands](docs/commands.md) lists every command and its output, where `create` cuts a branch and how `remove` settles one.
+
+## Docs
+
+- [Project contract](docs/contract.md): the hooks a project installs, keeping them in your clone, where worktrees live, ports, and running the hooks without the CLI.
+- [Commands](docs/commands.md): every command, its output and its branch rules.
+- [Claude Code plugin](docs/plugin.md): what the plugin does and what it needs.
+- [Development](docs/development.md): setup, checks, layout and rules, for working on this repo.
+- [Releasing](docs/releasing.md): the release workflow, the owner's one-time setup and each release's steps.
+
+## Related
+
+agent-worktree works on its own in any agent workflow, and is one of the optional add-ons to [agent-skills](https://github.com/cniska/agent-skills), engineering skills for coding agents. The other add-ons:
+
+- [agent-task](https://github.com/cniska/agent-task): task tracking for coding agents, the tasks running, in review and waiting to run
+- [agent-record](https://github.com/cniska/agent-record): a session record for coding agents, every past session queryable and joined to its commits
+- [agent-gates](https://github.com/cniska/agent-gates): commit gates for coding agents, git hooks and CI checks that refuse a bad commit

package/bin/agent-worktree

@@ -0,0 +1,60 @@
+#!/bin/sh
+set -u
+
+builds='darwin-arm64 linux-x64'
+name=agent-worktree
+scope=@cniska
+
+quoted() {
+  printf '"%s"' "$(printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+}
+
+refuse() {
+  printf 'command: %s\nok: false\nerror:\n  kind: refusal\n  code: %s\n  message: %s\n  meta:\n  resolve: %s\n' \
+    "$name" "$1" "$(quoted "$2")" "$(quoted "$3")" >&2
+  exit 1
+}
+
+self=$0
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case $link in
+    /*) self=$link ;;
+    *) self=$(dirname "$self")/$link ;;
+  esac
+done
+bin=$(cd "$(dirname "$self")" && pwd -P)
+
+case $(uname -s) in
+  Darwin) os=darwin ;;
+  Linux) os=linux ;;
+  *) os=$(uname -s) ;;
+esac
+case $(uname -m) in
+  arm64 | aarch64) cpu=arm64 ;;
+  x86_64) cpu=x64 ;;
+  *) cpu=$(uname -m) ;;
+esac
+target=$os-$cpu
+
+case " $builds " in
+  *" $target "*) ;;
+  *) refuse no_build_for_platform \
+    "$name ships no build for $target, only $(printf '%s' "$builds" | sed 's/ / and /g')" \
+    "build $name from source with Bun, as its docs/development.md says" ;;
+esac
+
+package=$scope/$name-$target
+binary=
+for dir in "$bin/../node_modules/$package" "$bin/../../$name-$target"; do
+  if [ -e "$dir/$name" ]; then
+    binary=$dir/$name
+    break
+  fi
+done
+[ -n "$binary" ] || refuse platform_package_missing \
+  "$package is not installed beside $scope/$name" \
+  "reinstall $scope/$name with optional dependencies enabled"
+[ -x "$binary" ] || refuse binary_not_executable "$binary is not executable" "reinstall $scope/$name"
+
+exec "$binary" "$@"

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@cniska/agent-worktree",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Task worktrees for coding agents: one checkout per task, set up and torn down by the project's own commands.",
+  "license": "MIT",
+  "homepage": "https://github.com/cniska/agent-worktree",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cniska/agent-worktree.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cniska/agent-worktree/issues"
+  },
+  "keywords": [
+    "agent",
+    "claude-code",
+    "git",
+    "worktree",
+    "cli"
+  ],
+  "bin": {
+    "agent-worktree": "bin/agent-worktree"
+  },
+  "files": [
+    "bin/agent-worktree"
+  ],
+  "optionalDependencies": {
+    "@cniska/agent-worktree-darwin-arm64": "0.2.0",
+    "@cniska/agent-worktree-linux-x64": "0.2.0"
+  }
+}