@cniska/agent-worktree 0.0.0-stage → 0.1.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,56 @@
-# 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.
+- `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, when it was pushed with an upstream, on that remote. When the upstream 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
+
+agent-worktree runs on [Bun](https://bun.sh), which [mise](https://mise.jdx.dev) installs for it. With mise installed:
+
+```bash
+git clone https://github.com/cniska/agent-worktree.git
+cd agent-worktree
+mise trust && mise install
+```
+
+`mise install` installs Bun and the dependencies. In the clone, never in a worktree, it puts `agent-worktree` in `~/.bun/bin` with `bun link`, so removing a worktree never leaves the command pointing at a deleted checkout. Add that directory to your `PATH` if it is not there yet.
+
+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` | One line per worktree |
+| `agent-worktree path <name>` | Print the worktree's path |
+
+[Commands](docs/commands.md) lists every command, 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.

package/bin/agent-worktree

@@ -0,0 +1,55 @@
+#!/bin/sh
+set -u
+
+builds='darwin-arm64 linux-x64'
+name=agent-worktree
+scope=@cniska
+
+refuse() {
+  printf '%s: %s\n  %s\n' "$name" "$1" "$2" >&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 \
+    "$name ships no build for $target, only $(printf '%s' "$builds" | sed 's/ / and /g')" \
+    "build $name from source with Bun, as its README 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 \
+  "$package is not installed beside $scope/$name" \
+  "reinstall $scope/$name with optional dependencies enabled"
+[ -x "$binary" ] || refuse "$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.1.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.1.0",
+    "@cniska/agent-worktree-linux-x64": "0.1.0"
+  }
+}