@svara/work3 0.0.0-stage → 0.0.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.
- package/LICENSE +21 -0
- package/README.md +196 -2
- package/dist/cli.js +9320 -0
- 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,197 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
[](https://github.com/svaraborut/work3/stargazers)
|
|
8
|
+
[](https://bun.sh)
|
|
9
|
+
[](https://www.typescriptlang.org)
|
|
10
|
+
[](https://claude.com/claude-code)
|
|
11
|
+
[](https://www.npmjs.com/package/work3)
|
|
12
|
+
[](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 work3
|
|
53
|
+
work3 --help
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Or run it without installing: `bunx 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
|
+
## Todo
|
|
191
|
+
|
|
192
|
+
- Spawn new agents from Claude
|
|
193
|
+
- Make it harness agnostic
|
|
194
|
+
|
|
195
|
+
## License
|
|
196
|
+
|
|
197
|
+
[MIT](LICENSE) © Borut Svara
|