@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.
Files changed (3) hide show
  1. package/README.md +51 -85
  2. package/dist/cli.js +1 -1
  3. 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
- [![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)
7
+ [![GitHub stars](https://img.shields.io/github/stars/svaraborut/work3?style=for-the-badge&logo=github&logoColor=white&label=stars&labelColor=18181b&color=3f3f46)](https://github.com/svaraborut/work3/stargazers)
8
+ [![Claude Code](https://img.shields.io/badge/remote%20control-d97757?style=for-the-badge&logo=claude&logoColor=white&label=claude%20code&labelColor=18181b)](https://claude.com/claude-code)
9
+ [![npm](https://img.shields.io/npm/v/@svara/work3?style=for-the-badge&logo=npm&logoColor=white&label=npm&labelColor=18181b&color=cb3837)](https://www.npmjs.com/package/@svara/work3)
10
+ [![License: MIT](https://img.shields.io/github/license/svaraborut/work3?style=for-the-badge&label=license&labelColor=18181b&color=3f3f46)](https://github.com/svaraborut/work3/blob/main/LICENSE)
13
11
 
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>
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
- 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.
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
- ## Why work3
42
+ ## Features
39
43
 
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.
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` (unless you always pass `--no-claude`).
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 # 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
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 [--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.
74
+ ### `work3 init`
79
75
 
80
- ### `work3 open <branch> [--from <ref>] [--no-claude]`
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
- Alias: `create`. Creates the worktree if needed, then starts `claude --remote-control <repo>/<branch>` inside it.
78
+ - `--yaml` - write `worktree.yaml` instead
83
79
 
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 |
80
+ ### `work3 open <branch>`
89
81
 
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 |
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
- If an `initialize` task fails, work3 stops, keeps the worktree for inspection and does not start Claude.
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
- 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]`
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
- Alias: `rm`. Runs `destroy` tasks, then removes the worktree.
91
+ ### `work3 remove <branch>`
108
92
 
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) |
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
- work3 refuses to remove the worktree you are currently in, and refuses dirty worktrees before any destroy task runs.
95
+ > [!TIP]
96
+ > Uncommitted work is never lost by accident: a worktree with changes is refused before anything is touched.
115
97
 
116
- ### `work3 fold <branch> [--into <ref>] [-r] [-f] [-d]`
98
+ - `-d, --delete-branch` - delete the branch too
99
+ - `-f, --force` - discard uncommitted changes and push through failing cleanup tasks
117
100
 
118
- Lands a finished branch on `base` by fast-forward only: no merge commits, no rebases, no pushes.
101
+ ### `work3 fold <branch>`
119
102
 
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.
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
- | 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 |
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
- If removal fails after a successful fold, the fold is kept and `work3 rm <branch>` retries the cleanup.
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
- ### 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
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.4.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",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@svara/work3",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Run a fleet of Claude Code agents in parallel, each on its own branch, in its own fully set up git worktree",
5
5
  "keywords": [
6
6
  "git",