@svara/work3 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +198 -2
  3. package/dist/cli.js +9320 -0
  4. package/package.json +52 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Borut Svara
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,199 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- 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.
3
+ # Work3 CLI
4
+
5
+ **Run a fleet of Claude Code agents in parallel, each on its own branch, in its own fully set up worktree.**
6
+
7
+ [![GitHub stars](https://img.shields.io/github/stars/svaraborut/work3?style=flat&logo=github)](https://github.com/svaraborut/work3/stargazers)
8
+ [![Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun&logoColor=black)](https://bun.sh)
9
+ [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
10
+ [![Claude Code](https://img.shields.io/badge/Claude%20Code-Remote%20Control-d97757?logo=claude&logoColor=white)](https://claude.com/claude-code)
11
+ [![npm](https://img.shields.io/npm/v/@svara/work3?logo=npm)](https://www.npmjs.com/package/@svara/work3)
12
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
13
+
14
+ <img src="docs/hero.png" alt="Six Claude Code sessions running side by side, each in its own work3 worktree" width="100%">
15
+
16
+ <sub>Six agents, six branches, zero collisions. One `work3 open` each.</sub>
17
+
18
+ </div>
19
+
20
+ Your one-stop solution to manage worktrees in your agentic projects. Two agents in the same checkout overwrite each other's files. Plain `git worktree` fixes that, then leaves you reinstalling dependencies, copying `.env` files, inventing folder names and cleaning up stale trees by hand, for every branch, every day. work3 turns all of it into one command, configured once per repository and shared with your whole team.
21
+
22
+ **The old way**
23
+
24
+ ```shell
25
+ git worktree add -b feat/login worktrees/feat--login main
26
+ cd worktrees/feat--login
27
+ bun ci
28
+ cp ../../.env .env
29
+ claude --remote-control my-app/feat/login
30
+ ```
31
+
32
+ **🚀 With work3**
33
+
34
+ ```shell
35
+ work3 open feat/login
36
+ ```
37
+
38
+ ## Why work3
39
+
40
+ - 🚀 **One command per branch** - `work3 open <branch>` creates the worktree, runs your setup and drops you into Claude Code, or reopens it if it already exists.
41
+ - 📦 **Setup that lives in the repo** - `initialize` and `destroy` tasks in `worktree.json` install dependencies, copy secrets and clean up, the same for everyone on the team.
42
+ - 📱 **Steer every agent from your phone** - each session starts with Claude Code Remote Control, named `<repo>/<branch>` so parallel sessions stay distinguishable.
43
+ - 🖥️ **Cross-platform tasks** - commands run through Bun Shell, so `cp $WORK3_ROOT/.env .env` works on Windows, macOS and Linux alike.
44
+ - 🛡️ **Safe teardown** - `work3 rm` refuses to delete uncommitted work and never runs destroy tasks on a worktree it will not remove.
45
+ - 🧭 **No hidden state** - git is the only source of truth, and every command works from the main checkout or from inside any worktree.
46
+
47
+ ## Install
48
+
49
+ Requires [Bun](https://bun.sh) 1.2.21 or newer, git, and [Claude Code](https://claude.com/claude-code) on your `PATH` (unless you always pass `--no-claude`).
50
+
51
+ ```shell
52
+ bun add -g @svara/work3
53
+ work3 --help
54
+ ```
55
+
56
+ The package is scoped, the command is `work3`. Or run it without installing: `bunx @svara/work3 open feat/login`.
57
+
58
+ ## Quick start
59
+
60
+ ```shell
61
+ cd my-project
62
+ work3 init # writes worktree.json and ignores /worktrees/
63
+ work3 open feat/login # create, set up and start claude
64
+ work3 ls # see all worktrees and their status
65
+ work3 fold feat/login -rd # fast-forward main, remove worktree and branch
66
+ work3 rm feat/login -d # or discard: run destroy tasks, remove worktree and branch
67
+ ```
68
+
69
+ ## Commands
70
+
71
+ ### `work3 init [--yaml]`
72
+
73
+ Creates the config in the root of the current repository.
74
+
75
+ - Writes `worktree.json`, or `worktree.yaml` with `--yaml`.
76
+ - Sets `base` to `main` if that branch exists, otherwise to the current branch.
77
+ - Adds `/worktrees/` to `.gitignore` unless it is already ignored.
78
+ - Refuses to run if a config file already exists.
79
+
80
+ ### `work3 open <branch> [--from <ref>] [--no-claude]`
81
+
82
+ Alias: `create`. Creates the worktree if needed, then starts `claude --remote-control <repo>/<branch>` inside it.
83
+
84
+ | Situation | Behaviour |
85
+ |---|---|
86
+ | Worktree already exists | Reopened as is, `initialize` tasks are not run again |
87
+ | Branch exists, no worktree | Branch is checked out in a new worktree, `--from` is ignored |
88
+ | Branch does not exist | Branch is created from `--from`, or from `base` in the config |
89
+
90
+ | Flag | Description |
91
+ |---|---|
92
+ | `--from <ref>` | Base ref for a new branch, overrides `base` (for example `origin/main`) |
93
+ | `--no-claude` | Skip launching Claude and print the worktree path instead |
94
+
95
+ If an `initialize` task fails, work3 stops, keeps the worktree for inspection and does not start Claude.
96
+
97
+ ### `work3 list`
98
+
99
+ Alias: `ls`. Lists worktrees under `location` with their branch, status and path.
100
+
101
+ - `clean` - no changes.
102
+ - `dirty` - uncommitted or untracked files.
103
+ - `missing` - registered in git but the folder is gone.
104
+
105
+ ### `work3 remove <branch> [-f] [-d]`
106
+
107
+ Alias: `rm`. Runs `destroy` tasks, then removes the worktree.
108
+
109
+ | Flag | Description |
110
+ |---|---|
111
+ | `-f, --force` | Remove even with uncommitted or untracked changes, continue past failing destroy tasks, force-delete the branch |
112
+ | `-d, --delete-branch` | Also delete the branch (kept by default) |
113
+
114
+ work3 refuses to remove the worktree you are currently in, and refuses dirty worktrees before any destroy task runs.
115
+
116
+ ### `work3 fold <branch> [--into <ref>] [-r] [-f] [-d]`
117
+
118
+ Lands a finished branch on `base` by fast-forward only: no merge commits, no rebases, no pushes.
119
+
120
+ - Refuses if the worktree has uncommitted or untracked changes, so no work is left behind.
121
+ - Refuses if the branch is not a fast-forward of the target, and tells you to rebase it inside the worktree.
122
+ - If the target is checked out (usually in the main checkout), its files are updated too.
123
+
124
+ | Flag | Description |
125
+ |---|---|
126
+ | `--into <ref>` | Target branch, overrides `base` |
127
+ | `-r, --remove` | Remove the worktree after folding, same as `work3 remove` |
128
+ | `-f, --force` | With `-r`: continue past failing destroy tasks |
129
+ | `-d, --delete-branch` | With `-r`: also delete the folded branch |
130
+
131
+ If removal fails after a successful fold, the fold is kept and `work3 rm <branch>` retries the cleanup.
132
+
133
+ ## Configuration
134
+
135
+ work3 reads its config from the root of the main checkout, looking for `worktree.json`, `worktree.yaml` or `worktree.yml`. If more than one exists, work3 warns and uses the first. Commit the config so the whole team shares the same augmented workflow.
136
+
137
+ ```json
138
+ {
139
+ "location": "worktrees",
140
+ "base": "main",
141
+ "initialize": [
142
+ { "name": "install", "cmd": "bun ci" },
143
+ { "name": "env", "cmd": "cp $WORK3_ROOT/.env .env" }
144
+ ],
145
+ "destroy": [
146
+ { "name": "cleanup", "cmd": "echo removing $WORK3_BRANCH" }
147
+ ]
148
+ }
149
+ ```
150
+
151
+ | Key | Type | Default | Description |
152
+ |---|---|---|---|
153
+ | `location` | string | `"worktrees"` | Folder for worktrees, relative to the repository root |
154
+ | `base` | string | `"main"` | Ref new branches start from, overridable with `--from` |
155
+ | `initialize` | task[] | `[]` | Tasks run once, right after a worktree is created |
156
+ | `destroy` | task[] | `[]` | Tasks run before a worktree is removed |
157
+
158
+ Each task is `{ "name"?: string, "cmd": string }`. `name` is shown in the output, `cmd` is shown when `name` is missing.
159
+
160
+ ### Tasks
161
+
162
+ Tasks run one after another, inside the worktree folder, through [Bun Shell](https://bun.sh/docs/runtime/shell). Built-ins such as `cp`, `rm`, `mkdir` and `echo` behave the same on every OS. These environment variables are available in addition to your own:
163
+
164
+ | Variable | Value |
165
+ |---|---|
166
+ | `WORK3_ROOT` | Path of the main checkout |
167
+ | `WORK3_PATH` | Path of the worktree |
168
+ | `WORK3_BRANCH` | Branch name |
169
+
170
+ ### Folder names
171
+
172
+ Worktree folders are named after the branch with `/` and `\` replaced by `--`, so `feat/login` lives in `worktrees/feat--login`.
173
+
174
+ ## Good to know
175
+
176
+ - work3 never fetches. `base: "main"` means your local `main`, use `--from origin/main` for the remote one.
177
+ - Tools in the main checkout (tsc, eslint, test runners, IDE indexers) may scan `worktrees/`. Exclude it in their configs if they do, or move `location` outside the repository, for example `"../my-project.worktrees"`.
178
+
179
+ ## Development
180
+
181
+ ```shell
182
+ git clone https://github.com/svaraborut/work3.git && cd work3
183
+ bun install
184
+ bun run build && bun link # puts your local build on PATH as work3
185
+ bun run dev -- --help # run from source without building
186
+ bun test
187
+ bun run typecheck
188
+ ```
189
+
190
+ Releases are automatic and follow [Conventional Commits](https://www.conventionalcommits.org): `!` or `BREAKING CHANGE:` bumps the major, anything else the minor. Pushing to `main` tags `vX.Y.Z`, publishes to npm as `latest` and creates a GitHub release with the changelog, pushing to `stage` publishes a `X.Y.Z-rcN` release candidate under the `rc` tag (`bun add -g @svara/work3@rc`).
191
+
192
+ ## Todo
193
+
194
+ - Spawn new agents from Claude
195
+ - Make it harness agnostic
196
+
197
+ ## License
198
+
199
+ [MIT](LICENSE) © Borut Svara