@svara/work3 0.4.0 → 0.5.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/README.md +51 -85
- package/dist/cli.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,20 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
**Run a fleet of Claude Code agents in parallel, each on its own branch, in its own fully set up worktree.**
|
|
6
6
|
|
|
7
|
-
[](https://www.npmjs.com/package/@svara/work3)
|
|
12
|
-
[](LICENSE)
|
|
7
|
+
[](https://github.com/svaraborut/work3/stargazers)
|
|
8
|
+
[](https://claude.com/claude-code)
|
|
9
|
+
[](https://www.npmjs.com/package/@svara/work3)
|
|
10
|
+
[](https://github.com/svaraborut/work3/blob/main/LICENSE)
|
|
13
11
|
|
|
14
|
-
<
|
|
15
|
-
|
|
16
|
-
<
|
|
12
|
+
<picture>
|
|
13
|
+
<source srcset="https://raw.githubusercontent.com/svaraborut/work3/main/docs/animation.gif" type="image/gif">
|
|
14
|
+
<img src="https://raw.githubusercontent.com/svaraborut/work3/main/docs/hero.png" alt="Six Claude Code sessions running side by side, each in its own work3 worktree" width="100%">
|
|
15
|
+
</picture>
|
|
17
16
|
|
|
18
17
|
</div>
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
Parallel agents need separate checkouts. `git worktree` gives you one, but each new worktree still needs dependencies installed, `.env` files copied, a folder name and, later, a cleanup. work3 does all of that in one command, from a config you commit once and share with your team.
|
|
21
20
|
|
|
22
21
|
**The old way**
|
|
23
22
|
|
|
@@ -27,108 +26,89 @@ cd worktrees/feat--login
|
|
|
27
26
|
bun ci
|
|
28
27
|
cp ../../.env .env
|
|
29
28
|
claude --remote-control my-app/feat/login
|
|
29
|
+
cd ../..
|
|
30
|
+
git merge --ff-only feat/login
|
|
31
|
+
git worktree remove worktrees/feat--login
|
|
32
|
+
git branch -d feat/login
|
|
30
33
|
```
|
|
31
34
|
|
|
32
35
|
**🚀 With work3**
|
|
33
36
|
|
|
34
37
|
```shell
|
|
35
38
|
work3 open feat/login
|
|
39
|
+
work3 fold feat/login -rd
|
|
36
40
|
```
|
|
37
41
|
|
|
38
|
-
##
|
|
42
|
+
## Features
|
|
39
43
|
|
|
40
|
-
- 🚀 **One command per branch** -
|
|
41
|
-
- 📦 **
|
|
42
|
-
- 📱 **
|
|
43
|
-
-
|
|
44
|
-
- 🛡️ **Safe teardown** -
|
|
45
|
-
-
|
|
44
|
+
- 🚀 **One command per branch** - worktree, setup and Claude Code in one go
|
|
45
|
+
- 📦 **Shared setup** - install and cleanup tasks committed with the repo
|
|
46
|
+
- 📱 **Remote Control** - steer every agent from your phone
|
|
47
|
+
- 🔀 **Linear history** - finished branches land fast-forward only
|
|
48
|
+
- 🛡️ **Safe teardown** - uncommitted work is never deleted
|
|
49
|
+
- 🖥️ **Cross-platform** - same tasks on Windows, macOS and Linux
|
|
50
|
+
- 🧭 **No hidden state** - git is the only source of truth
|
|
46
51
|
|
|
47
52
|
## Install
|
|
48
53
|
|
|
49
|
-
Requires [Bun](https://bun.sh) 1.2.21 or newer, git, and [Claude Code](https://claude.com/claude-code) on your `PATH
|
|
54
|
+
Requires [Bun](https://bun.sh) 1.2.21 or newer, git, and [Claude Code](https://claude.com/claude-code) on your `PATH`.
|
|
50
55
|
|
|
51
56
|
```shell
|
|
52
57
|
bun add -g @svara/work3
|
|
53
58
|
work3 --help
|
|
54
59
|
```
|
|
55
60
|
|
|
56
|
-
The package is scoped, the command is `work3`. Or run it without installing: `bunx @svara/work3 open feat/login`.
|
|
57
|
-
|
|
58
61
|
## Quick start
|
|
59
62
|
|
|
60
63
|
```shell
|
|
61
64
|
cd my-project
|
|
62
|
-
work3 init
|
|
63
|
-
work3 open feat/login
|
|
64
|
-
work3 ls
|
|
65
|
-
work3 fold feat/login -rd
|
|
66
|
-
work3 rm feat/login -d
|
|
65
|
+
work3 init # writes worktree.json and ignores /worktrees/
|
|
66
|
+
work3 open feat/login # create, set up and start claude
|
|
67
|
+
work3 ls # see all worktrees and their status
|
|
68
|
+
work3 fold feat/login -rd # fast-forward main, remove worktree and branch
|
|
69
|
+
work3 rm feat/login -d # or discard: run destroy tasks, remove worktree and branch
|
|
67
70
|
```
|
|
68
71
|
|
|
69
72
|
## Commands
|
|
70
73
|
|
|
71
|
-
### `work3 init
|
|
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.
|
|
74
|
+
### `work3 init`
|
|
79
75
|
|
|
80
|
-
|
|
76
|
+
Sets up a repository for work3 in one step. It writes a `worktree.json` with sensible defaults that you commit and share with your team, and it never overwrites a config that already exists.
|
|
81
77
|
|
|
82
|
-
|
|
78
|
+
- `--yaml` - write `worktree.yaml` instead
|
|
83
79
|
|
|
84
|
-
|
|
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 |
|
|
80
|
+
### `work3 open <branch>`
|
|
89
81
|
|
|
90
|
-
|
|
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 |
|
|
82
|
+
Takes you from a branch name to a running agent in a fully set up workspace. A new branch gets its own worktree, your setup tasks and a Claude Code session you can steer from your phone. A branch you have worked on before reopens exactly where you left it, with no setup to wait for.
|
|
94
83
|
|
|
95
|
-
|
|
84
|
+
- `--from <ref>` - start a new branch from another ref, for example `origin/main`
|
|
85
|
+
- `--no-claude` - set up the worktree without starting Claude and print its path
|
|
96
86
|
|
|
97
87
|
### `work3 list`
|
|
98
88
|
|
|
99
|
-
|
|
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]`
|
|
89
|
+
Shows every agent workspace at a glance: its branch, its folder, and whether it is `clean`, `dirty` with work not yet committed, or `missing` because its folder was deleted.
|
|
106
90
|
|
|
107
|
-
|
|
91
|
+
### `work3 remove <branch>`
|
|
108
92
|
|
|
109
|
-
|
|
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) |
|
|
93
|
+
Throws away a worktree you no longer need and runs your cleanup tasks. The branch is kept, so the commits stay available.
|
|
113
94
|
|
|
114
|
-
|
|
95
|
+
> [!TIP]
|
|
96
|
+
> Uncommitted work is never lost by accident: a worktree with changes is refused before anything is touched.
|
|
115
97
|
|
|
116
|
-
|
|
98
|
+
- `-d, --delete-branch` - delete the branch too
|
|
99
|
+
- `-f, --force` - discard uncommitted changes and push through failing cleanup tasks
|
|
117
100
|
|
|
118
|
-
|
|
101
|
+
### `work3 fold <branch>`
|
|
119
102
|
|
|
120
|
-
-
|
|
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.
|
|
103
|
+
Lands a finished branch on `main` with a clean, linear history: fast-forward only, never a merge commit, rebase or push. The files in your main checkout move forward too, ready to test or push.
|
|
123
104
|
|
|
124
|
-
|
|
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 |
|
|
105
|
+
> [!TIP]
|
|
106
|
+
> A branch with uncommitted work, or one that has fallen behind `main`, is refused with a hint to rebase it first. If cleanup fails after folding, your commits are still landed and `work3 rm <branch>` finishes the job.
|
|
130
107
|
|
|
131
|
-
|
|
108
|
+
- `--into <ref>` - land on another branch instead of `base`
|
|
109
|
+
- `-r, --remove` - remove the worktree once landed
|
|
110
|
+
- `-d, --delete-branch` - with `-r`, delete the branch too
|
|
111
|
+
- `-f, --force` - with `-r`, push through failing cleanup tasks
|
|
132
112
|
|
|
133
113
|
## Configuration
|
|
134
114
|
|
|
@@ -167,16 +147,7 @@ Tasks run one after another, inside the worktree folder, through [Bun Shell](htt
|
|
|
167
147
|
| `WORK3_PATH` | Path of the worktree |
|
|
168
148
|
| `WORK3_BRANCH` | Branch name |
|
|
169
149
|
|
|
170
|
-
|
|
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
|
|
150
|
+
## Contributing
|
|
180
151
|
|
|
181
152
|
```shell
|
|
182
153
|
git clone https://github.com/svaraborut/work3.git && cd work3
|
|
@@ -189,11 +160,6 @@ bun run typecheck
|
|
|
189
160
|
|
|
190
161
|
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
162
|
|
|
192
|
-
## Todo
|
|
193
|
-
|
|
194
|
-
- Spawn new agents from Claude
|
|
195
|
-
- Make it harness agnostic
|
|
196
|
-
|
|
197
163
|
## License
|
|
198
164
|
|
|
199
165
|
[MIT](LICENSE) © Borut Svara
|
package/dist/cli.js
CHANGED
|
@@ -3744,7 +3744,7 @@ var version = /* @__PURE__ */ defineExtension(VERSION).factory((extension, value
|
|
|
3744
3744
|
// package.json
|
|
3745
3745
|
var package_default = {
|
|
3746
3746
|
name: "@svara/work3",
|
|
3747
|
-
version: "0.
|
|
3747
|
+
version: "0.5.0",
|
|
3748
3748
|
description: "Run a fleet of Claude Code agents in parallel, each on its own branch, in its own fully set up git worktree",
|
|
3749
3749
|
keywords: [
|
|
3750
3750
|
"git",
|