@juiceboxcreative/loop 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.
- package/LICENSE +21 -0
- package/README.md +454 -2
- package/bin/cli.mjs +14 -0
- package/dist/THIRD-PARTY-LICENSES.md.gz +0 -0
- package/dist/_chunks/libs/@clack/core.mjs +679 -0
- package/dist/_chunks/libs/@clack/prompts.mjs +250 -0
- package/dist/_chunks/rolldown-runtime.mjs +22 -0
- package/dist/cli.d.mts +1 -0
- package/dist/cli.mjs +3723 -0
- package/package.json +57 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Juicebox Creative
|
|
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,455 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @juiceboxcreative/loop
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Hand local work to the Loop fleet.
|
|
4
|
+
`loop` turns the repository and branch you are sitting in into a Loop task that a fleet machine picks up, so an agent session can stop and the remaining work keeps moving.
|
|
5
|
+
|
|
6
|
+
## Install and sign in
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npx @juiceboxcreative/loop@latest login
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
This opens Loop in your browser.
|
|
13
|
+
Loop mints a CLI token and sends it with a cross-origin POST to a listener on `127.0.0.1`, so the token never appears in a URL or a terminal.
|
|
14
|
+
The listener accepts only the Loop web origin you opened and only a state value it generated for this login.
|
|
15
|
+
On a headless shell, use `loop login --paste`: open the printed URL (`/cli/connect?paste=1`) in any browser and paste the token it shows once.
|
|
16
|
+
The token's expiry is stored when Loop sends it and left null in paste mode.
|
|
17
|
+
|
|
18
|
+
Add `--env dev` to sign in to the dev environment instead.
|
|
19
|
+
Both environments can be signed in at the same time.
|
|
20
|
+
|
|
21
|
+
## Commands
|
|
22
|
+
|
|
23
|
+
| Command | What it does |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `loop login [--api-url URL] [--web-url URL] [--paste]` | Sign in through the browser and store a token |
|
|
26
|
+
| `loop handoff [WORDS...] [--title T] [--brief FILE \| -] [--skill SLUG]... [--attach FILE]... [--plan \| --no-plan] [--process SLUG] [--hotfix] [--engine auto] [--model ID] [-s] [--type code] [--no-run] [--include-wip \| --no-wip] [--json]` | Create a task for the current repository and branch |
|
|
27
|
+
| `loop add [WORDS...] [same flags]` | Capture a task in Backlog without running it (same as `handoff --no-run`) |
|
|
28
|
+
| `loop task create --project SLUG [WORDS...] [same flags]` | Create a task without git context |
|
|
29
|
+
| `loop status [KEY] [--json]` | Show a task: status, engine and model, run outcome, pull request links and any open question (defaults to the last task you created) |
|
|
30
|
+
| `loop open [KEY] [--json]` | Print a task's URL and open it in the browser. With `--json`, or without a terminal, it only prints the URL (`{"url":...}` for `--json`) |
|
|
31
|
+
| `loop checkout [KEY] [--repo OWNER/NAME] [--json]` | Fetch the task's pull request branch from `origin` and check it out |
|
|
32
|
+
| `loop ls [--all] [--mine] [--json]` | List your open tasks for the current repository, or every repository with `--all`. `--mine` is the default and is accepted so scripts can say it |
|
|
33
|
+
| `loop wait [KEY] [--timeout MINUTES] [--json]` | Block until the task needs you or is final, then exit with a matching code |
|
|
34
|
+
| `loop session [KEY] [--json]` | Watch and drive a run in the terminal (needs a terminal; use `--json` otherwise) |
|
|
35
|
+
| `loop approve [KEY] [--json]` | Approve the plan so the code run starts (for tasks created with `--plan`) |
|
|
36
|
+
| `loop models [--json]` | List the models Loop accepts for `--model` |
|
|
37
|
+
| `loop doctor [--json]` | Check sign-in, token expiry, project, branch and version in one screen |
|
|
38
|
+
| `loop completion zsh\|bash` | Print a shell completion script |
|
|
39
|
+
|
|
40
|
+
Every command accepts `--env dev`.
|
|
41
|
+
|
|
42
|
+
### How `loop handoff` picks the project
|
|
43
|
+
|
|
44
|
+
1. Reads the `origin` remote (`git@github.com:owner/name.git`, `https://github.com/owner/name`, `ssh://git@github.com/owner/name`), the current branch, the HEAD sha and whether the tree is dirty.
|
|
45
|
+
2. Asks Loop for projects linked to `owner/name`.
|
|
46
|
+
No match exits 3.
|
|
47
|
+
Several matches prompt once and remember the answer in `repos.json`.
|
|
48
|
+
With `--json` or no terminal and no remembered answer, it exits 3 naming the candidate slugs and suggests `loop task create --project <slug>`.
|
|
49
|
+
3. Sets the task's base branch, the branch the pull request targets, to the one your work derives from, with or without local work (see [The base branch](#the-base-branch)).
|
|
50
|
+
When local work is sent (see [Local work travels](#local-work-travels)), the run starts from the pushed `loop/wip-*` branch and the pull request still targets that base branch.
|
|
51
|
+
4. Resolves each `--skill` slug to a Loop skill and attaches it.
|
|
52
|
+
5. Creates the task, prints the key and URL, and records it in `last.json` for `loop status` and `loop open`.
|
|
53
|
+
|
|
54
|
+
The brief becomes the task description.
|
|
55
|
+
Without `--title`, the first content line of the brief is the title.
|
|
56
|
+
Nothing is written into your repository.
|
|
57
|
+
|
|
58
|
+
### The base branch
|
|
59
|
+
|
|
60
|
+
`loop handoff` and `loop add` always send the base branch your work derives from, so an unpushed branch cut from `develop` does not fall back to the project default (often `master`).
|
|
61
|
+
If your current branch is on `origin`, it is the base, whether or not local work travels with the task, exactly as before.
|
|
62
|
+
The first rule that finds a branch on `origin` wins:
|
|
63
|
+
|
|
64
|
+
1. Your current branch, when it is on `origin`.
|
|
65
|
+
2. The `origin` branch your current branch tracks (`@{upstream}`).
|
|
66
|
+
Branch names match exactly, so a local `fix` is not on `origin` just because `cj/fix` is.
|
|
67
|
+
The list of `origin` branches comes from one `git ls-remote --heads origin`, or from the remote-tracking refs you already have when origin cannot be reached.
|
|
68
|
+
Then `base_warning` says "Could not reach origin; the base was chosen from your last fetch.", and so does the `loop doctor` Branch line (as a warning).
|
|
69
|
+
3. The nearest of the project's configured branches that exist on `origin` (`dev_branch`, `base_branch`, `uat_branch`, `test_branch`, `production_branch`): the one with the smallest distance from `HEAD`, which is the commits only on `origin/X` plus the commits only on `HEAD` (`git rev-list --left-right --count origin/X...HEAD`).
|
|
70
|
+
A hotfix cut from the tip of master picks master, and a branch off develop picks develop.
|
|
71
|
+
A tie goes to the earlier in that list, so production is chosen only when it is strictly nearest.
|
|
72
|
+
A branch that is on `origin` but not in your clone is fetched on its own first (one remote-tracking ref, nothing else).
|
|
73
|
+
In a shallow clone the distance cannot be measured, so no base is sent and the warning says to run `git fetch --unshallow`.
|
|
74
|
+
If a project branch is on `origin` but cannot be fetched, the warning says the base "could not be checked (fetch failed)".
|
|
75
|
+
4. None, with a warning that names the project default: Loop uses the project default.
|
|
76
|
+
|
|
77
|
+
The output carries `base_branch` (or `null`) and `base_source` (`current`, `upstream`, `nearest` or `none`), and a person sees `Base branch: ...`.
|
|
78
|
+
`loop task create` has no git context and sends none.
|
|
79
|
+
|
|
80
|
+
### The brief
|
|
81
|
+
|
|
82
|
+
The brief comes from the first of these that is present:
|
|
83
|
+
|
|
84
|
+
1. `--brief <file>`.
|
|
85
|
+
2. Standard input, with `--brief -`.
|
|
86
|
+
3. The words after the command, as in `loop handoff "build the campaign landing page"` or `loop task create --project site "Write the FAQ"`.
|
|
87
|
+
|
|
88
|
+
### Capture without running
|
|
89
|
+
|
|
90
|
+
`loop add "Fix the footer links"` creates the task in Backlog and does not start a run.
|
|
91
|
+
It is the same as `loop handoff --no-run`, and it is git-aware in the same way.
|
|
92
|
+
|
|
93
|
+
### Local work travels
|
|
94
|
+
|
|
95
|
+
`loop handoff` and `loop add` look for uncommitted changes (tracked and untracked, `.gitignore` respected) and for commits that are not on `origin`.
|
|
96
|
+
|
|
97
|
+
| Situation | What happens |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| Nothing to send | `wip` is `none` |
|
|
100
|
+
| Terminal, no flag | Asks once whether to send it |
|
|
101
|
+
| `--include-wip` | Sends it without asking, and fails (exit 1, no task) if it cannot be sent |
|
|
102
|
+
| `--no-wip` | Does not send it. Using it with `--include-wip` is an error |
|
|
103
|
+
| `--json` or no terminal, no flag | Does not ask and sends committed and pushed work only. The output says `"wip": "not_sent"` and why |
|
|
104
|
+
|
|
105
|
+
Secret detection is best effort: it matches file names and private-key headers, so look at what is in your working tree before you say yes, and the confirm prompt says so.
|
|
106
|
+
Local work over 50 MB gets a warning (in the prompt, and in `wip_reason` for `--json` and scripts) that lists the three largest files.
|
|
107
|
+
Sending builds a commit of your working tree and pushes it to `origin` as `loop/wip-<id>`.
|
|
108
|
+
The task then starts from that branch, and its pull request still targets your base branch (see [The base branch](#the-base-branch)).
|
|
109
|
+
The key steps, which leave your branch, index, working tree and stash exactly as they were:
|
|
110
|
+
|
|
111
|
+
1. Copy your index file to a temporary one (`GIT_INDEX_FILE` in a temp directory), then `git add -A` into the copy.
|
|
112
|
+
The copy keeps `skip-worktree` and `assume-unchanged` bits, so files you hid locally stay out.
|
|
113
|
+
Your real index is only read.
|
|
114
|
+
2. `git write-tree` and `git commit-tree -p HEAD` make the commit.
|
|
115
|
+
No branch moves and nothing is checked out.
|
|
116
|
+
3. `git push origin <sha>:refs/heads/loop/wip-<id>`.
|
|
117
|
+
When the tree is clean and only commits are unpushed, `HEAD` itself is pushed.
|
|
118
|
+
|
|
119
|
+
Git also adds a remote-tracking ref `origin/loop/wip-<id>` to your clone, as it does for any push.
|
|
120
|
+
If the push fails, the CLI stops with the error and creates no task.
|
|
121
|
+
If Loop rejects the create call (401 or 4xx), the CLI deletes the pushed `loop/wip-<id>` branch from `origin` (best effort) and reports the original error.
|
|
122
|
+
After a 5xx or a dropped connection the task may exist, so the branch stays and the error says so: `The task may have been created; check loop ls. Your work is on loop/wip-<id>.`
|
|
123
|
+
Ctrl-C at a prompt cancels the command: nothing is pushed and no task is created.
|
|
124
|
+
Status checks run with `GIT_OPTIONAL_LOCKS=0`, so they never take `index.lock` or rewrite your index.
|
|
125
|
+
Loop checks that the branch exists at that commit on the project's repository, and rejects the task if it does not.
|
|
126
|
+
|
|
127
|
+
Files that look like secrets (`.env`, `.env.*` except `.env.example` and `.env.sample`, `*.pem`, `*.key`, `id_rsa*`, `id_dsa*`, `id_ecdsa*`, `id_ed25519*`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `*.kdbx`, `*.tfvars`, `*.tfstate`, `.npmrc`, `.netrc`, `.pypirc`, `.htpasswd`, `.git-credentials`, `service-account*.json`, `*credentials*.json`, `.aws/credentials`, `.docker/config.json`, `secrets.yml`, `secrets.yaml`, `*.secret`) and any file whose content holds a `-----BEGIN ... PRIVATE KEY-----` header, whatever it is called are listed and left out of the pushed commit unless you confirm in a terminal.
|
|
128
|
+
The names and the key-header check run again on exactly what is about to be pushed (from the temporary index, after the prompt), so a file created or edited after you answered is still caught.
|
|
129
|
+
The checks read blobs through two `git cat-file` processes however many files change (a few seconds for thousands of files), and a symlink replaced by a key file is scanned too.
|
|
130
|
+
Files over 2 MB are not read for the content check, and `wp-config.php` is not treated as a secret because edits to it are often legitimate.
|
|
131
|
+
With `--include-wip` and no terminal, or in `--json` mode, they are left out and reported in `wip_excluded`.
|
|
132
|
+
A secret-looking file that is already in an unpushed commit cannot be left out, so without a terminal confirmation nothing is sent (an error with `--include-wip`, otherwise `not_sent`).
|
|
133
|
+
A private key inside an unpushed commit is stricter, because history cannot be edited: every version added or changed by those commits is scanned (when `origin` has been fetched, same 2 MB cap, so a key that a later commit removed still counts).
|
|
134
|
+
A hit cannot be overridden.
|
|
135
|
+
`--include-wip` fails with exit 1 and no task, naming the file and commit.
|
|
136
|
+
In a terminal the CLI says so and asks only `Create the task without your local work?`: `y` creates it without the local work, and `n` or Ctrl-C exits 1 with no task.
|
|
137
|
+
Rewrite or drop those commits, or push without them, then run it again.
|
|
138
|
+
|
|
139
|
+
When `origin` has no remote-tracking refs (a fresh `git remote add`, never fetched), every commit would look unpushed.
|
|
140
|
+
The CLI then checks only uncommitted changes and says `origin has not been fetched, so unpushed commits were not checked; run git fetch first for a full check.` in the output (`wip_reason` in JSON).
|
|
141
|
+
|
|
142
|
+
### Cleaning up `loop/wip-*` branches
|
|
143
|
+
|
|
144
|
+
A `loop/wip-<id>` branch stays on `origin` while its task may still need it, and the CLI never deletes it after a successful create.
|
|
145
|
+
Once the task's pull request is merged or closed, delete the branch yourself: `git push origin --delete loop/wip-a1b2c3`.
|
|
146
|
+
`loop ls` shows which of your tasks are still open, so you know which branches are safe to remove.
|
|
147
|
+
(The CLI itself removes the branch only when Loop clearly rejected the create call.)
|
|
148
|
+
|
|
149
|
+
### Bring the result back
|
|
150
|
+
|
|
151
|
+
`loop checkout [KEY]` fetches the task's pull request head branch from `origin` and checks it out, tracking `origin/<branch>`.
|
|
152
|
+
An existing local branch of the same name is fast-forwarded when it can be.
|
|
153
|
+
|
|
154
|
+
- It refuses when tracked files have uncommitted changes, and tells you to commit or stash them yourself.
|
|
155
|
+
- Several pull requests are narrowed first: `--repo`, then the repository of your `origin`, then open ones over closed or merged.
|
|
156
|
+
Only a remaining tie asks in a terminal.
|
|
157
|
+
Without a terminal it errors, and asks for `--repo owner/name` when the tie spans repositories.
|
|
158
|
+
- Older pull request rows can lack the repository or head branch.
|
|
159
|
+
The repository and number then come from the pull request URL.
|
|
160
|
+
With no head branch, `refs/pull/<n>/head` is fetched into a local branch `loop/pr-<n>`.
|
|
161
|
+
- A pull request in a different repository from your `origin` is an error that names that repository.
|
|
162
|
+
Run it from a clone of that repository.
|
|
163
|
+
|
|
164
|
+
`loop ls` prints your open tasks (anything not `done`) for the current repository as key, title, status, engine and age.
|
|
165
|
+
`--all` lists every repository.
|
|
166
|
+
The index filters by owner, open status and project (`owner=me`, `open=1`, `project_id`), and the projects are every Loop project linked to this repository (`project_id=1,2`), so `loop ls` never prompts.
|
|
167
|
+
The same checks run in the CLI too, so an API that ignores a filter still gives the right answer.
|
|
168
|
+
If the index returns its cap of 200 rows, a warning goes to stderr, and JSON has `"truncated": true`.
|
|
169
|
+
|
|
170
|
+
### Wait for a task
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
loop wait LOOP-321 --timeout 30 --json
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
`loop wait [KEY]` polls the task every 5 seconds, backing off to every 30 seconds, until it needs a person or is final.
|
|
177
|
+
It waits without limit unless `--timeout <minutes>` is given.
|
|
178
|
+
Network failures and 5xx answers are retried up to three times in a row with the same backoff, never sleeping past `--timeout`, before the command fails.
|
|
179
|
+
If the API is still failing when `--timeout` runs out, the result is a timeout (exit 5) with the last known task, or the same object with `"status":null`, `"outcome":null`, `"pull_requests":[]`, `"question":null` and `"timed_out":true` when no poll ever succeeded.
|
|
180
|
+
|
|
181
|
+
| Task state | Exit code |
|
|
182
|
+
| --- | --- |
|
|
183
|
+
| `done` or `in_review` | 0 |
|
|
184
|
+
| Clarity question, an open question card, or `waiting_for_user` | 2 |
|
|
185
|
+
| In the Backlog (`todo`), not approved, never run | 2, with `question` "KEY is in the Backlog and not set to run. Approve it in Loop or run loop handoff." |
|
|
186
|
+
| `stuck`, failed or cancelled | 4 |
|
|
187
|
+
| Timed out | 5 |
|
|
188
|
+
|
|
189
|
+
`--json` prints one object: `key`, `status`, `outcome` (`failure_cause`, `next_step` or `null`), `pull_requests` (URLs), `question` (or `null`) and `timed_out`.
|
|
190
|
+
|
|
191
|
+
### Attach files
|
|
192
|
+
|
|
193
|
+
`--attach FILE` (repeatable) uploads a file to the task after it is created, on `handoff`, `add` and `task create`.
|
|
194
|
+
Every file is checked before anything is created, so a missing, empty or oversized file, or a type Loop refuses, fails the command with no task and no pushed branch.
|
|
195
|
+
The limits are Loop's defaults: 25 MB a file and 100 files a task.
|
|
196
|
+
Loop refuses executable types (`.exe`, `.sh`, `.dmg` and the like) and any `application/octet-stream` or `application/x-*` type, and it works the type out from the file's content first and its extension second.
|
|
197
|
+
The CLI does the same, so `.sql`, `.tar`, `.rar`, `.pem`, `.php` and other extensions that map to those types are refused locally (a `.tgz` that is really gzip, or a script with a `#!` line, is accepted, as it is by Loop).
|
|
198
|
+
A file with an unknown extension goes up as `text/plain` when it reads as text.
|
|
199
|
+
A binary file the CLI cannot identify is refused: zip it, or attach it in Loop.
|
|
200
|
+
|
|
201
|
+
For each file the CLI asks Loop for an upload slot (`POST /api/v2/tasks/{id}/attachments/presign`), sends the bytes (`PUT` to the URL it returns, with your token only when that URL is on the Loop API host) and confirms it (`POST /api/v2/tasks/{id}/attachments`).
|
|
202
|
+
A run reads its attachments when it starts, so with files the task is created without running, the files go up, and then the run is started with the same approval that create-and-run uses.
|
|
203
|
+
If an upload fails, the task already exists: the error names the file, the task and its URL, says how to finish (add the rest and choose Approve and run there), and the run is not started.
|
|
204
|
+
With `--json` the error object also carries `id`, `key` and `url`.
|
|
205
|
+
The output lists `attachments` (`id`, `filename`, `content_type`, `size_bytes`) in human and JSON modes.
|
|
206
|
+
|
|
207
|
+
### Plan first, approve, process and hotfix
|
|
208
|
+
|
|
209
|
+
`--plan` sets plan first: Loop writes a plan before any code, and waits.
|
|
210
|
+
`--no-plan` sends plan first as false, so Loop goes straight to work and never offers the plan choice (and an agent never gets that exit 2).
|
|
211
|
+
Using both is an error.
|
|
212
|
+
Read it in the Session or on the task, then run `loop approve [KEY]` to start the code run.
|
|
213
|
+
`loop approve` exits 1 with a clear message when no plan is waiting.
|
|
214
|
+
|
|
215
|
+
`--process SLUG|NAME` runs the task through a process from Loop's catalogue.
|
|
216
|
+
It matches the process key first and then its name, ignoring case.
|
|
217
|
+
An unknown or ambiguous value fails before anything is created and lists the options.
|
|
218
|
+
|
|
219
|
+
`--hotfix` marks an urgent production fix, which targets the project's production branch.
|
|
220
|
+
Loop decides who may and which projects can: its refusal (for example "Only someone who may approve this task can change Hotfix.") is shown as the error.
|
|
221
|
+
|
|
222
|
+
### Doctor
|
|
223
|
+
|
|
224
|
+
`loop doctor` prints one line per check, each ok, warn or fail, and exits 1 if any fail:
|
|
225
|
+
|
|
226
|
+
| Check | Fails when | Warns when |
|
|
227
|
+
| --- | --- | --- |
|
|
228
|
+
| Signed in (`GET /api/me`) | Not signed in, the token is rejected, or Loop is unreachable | |
|
|
229
|
+
| Token expiry | Expired | Under 14 days left (a pasted token has no recorded expiry and shows as ok) |
|
|
230
|
+
| Project | No Loop project is linked to this repository | Several are linked and none is remembered |
|
|
231
|
+
| Branch | | The branch is not on `origin`, or HEAD is detached. The line also says which base branch a hand-off would use |
|
|
232
|
+
| Version | | A newer version is published, or the latest could not be checked (with `LOOP_NO_UPDATE_CHECK=1` no request is made and it shows as ok, not checked) |
|
|
233
|
+
|
|
234
|
+
It never prompts and never prints the token.
|
|
235
|
+
It never writes either, so the base it reports comes from your local copy of `origin`; a handoff also fetches a project branch you have never fetched, so run `git fetch` if doctor says the project default.
|
|
236
|
+
Outside a git repository the project and branch lines are left out.
|
|
237
|
+
`--json` prints `{"ok":true,"checks":[{"name","status","message"}]}`.
|
|
238
|
+
|
|
239
|
+
### Update notice and completion
|
|
240
|
+
|
|
241
|
+
At most once a day, `loop` asks npm for the latest published version (one request to `registry.npmjs.org`, nothing about you in it) and prints one line on stderr when yours is older.
|
|
242
|
+
It stays silent when stdout or stderr is not a terminal, with `--json`, in CI, and on any failure, including the package not being published yet.
|
|
243
|
+
The check time and result are cached in `update.json` in the config directory.
|
|
244
|
+
It also stays silent when the command failed (a non-zero exit).
|
|
245
|
+
The check starts when the command starts and runs beside it.
|
|
246
|
+
After the command, `loop` waits at most 200 ms for it; if it is not done, the check is cancelled, not recorded, and tried again next time, so it never holds your shell.
|
|
247
|
+
Set `LOOP_NO_UPDATE_CHECK=1` to turn it off.
|
|
248
|
+
|
|
249
|
+
`eval "$(loop completion zsh)"` (or `bash`) in your shell profile completes commands and flags.
|
|
250
|
+
The script is built from the same command and flag tables the parser and `--help` use.
|
|
251
|
+
|
|
252
|
+
### Engine and model
|
|
253
|
+
|
|
254
|
+
`--engine` takes `auto`, `claude-code`, `codex` or `opencode` (Open Models in Loop).
|
|
255
|
+
`--model` applies only to Open Models.
|
|
256
|
+
It takes a short name (`kimi-k3`) or Loop's full id, and sends the full id.
|
|
257
|
+
`--model` on its own implies `--engine opencode`, so `loop handoff --model kimi-k3 "..."` is enough.
|
|
258
|
+
`--model` with `--engine claude-code` or `codex` is an error, and so is a model Loop does not accept.
|
|
259
|
+
`loop models` lists the accepted models, and the error for an unknown model lists them too.
|
|
260
|
+
|
|
261
|
+
### Questions from Loop before a run
|
|
262
|
+
|
|
263
|
+
When Loop's brief check asks a question, `loop handoff` and `loop task create` show it in a terminal and take your answer there.
|
|
264
|
+
Loop may ask a follow-up, and the loop repeats until the task is approved.
|
|
265
|
+
Type `/approve` to run the task as it is when Loop allows that.
|
|
266
|
+
The answer approves and starts the task, and the command prints the result.
|
|
267
|
+
With `--json`, or when input is not a terminal, nothing is asked: the question comes back in the output and the command exits 2.
|
|
268
|
+
|
|
269
|
+
Loop may instead ask "Approve a plan first?" for code work that looks complex.
|
|
270
|
+
That is a choice, not free text: in a terminal you pick "Plan first, then run" or "Run without a plan", and the answer goes to `POST /api/v2/tasks/{id}/plan-choice`.
|
|
271
|
+
The same choice is offered in `loop session` (type 1 or 2) and after `--attach`.
|
|
272
|
+
The `clarity` object in the output has `kind`: `question` for the brief check, `plan_choice` for this one (which also carries `helper` and `needs_plan`, and has no `question_key`).
|
|
273
|
+
Create with `--plan` or `--no-plan` to answer it up front.
|
|
274
|
+
|
|
275
|
+
### Watch and drive a run: `loop session`
|
|
276
|
+
|
|
277
|
+
`loop session [KEY]` is a terminal view of the Session in the web app's task panel.
|
|
278
|
+
Without a key it opens the last task you created.
|
|
279
|
+
Add `-s` (`--attach-session`) to `loop handoff`, `loop add` or `loop task create` to open it straight after the task is created.
|
|
280
|
+
Without `-s`, a task that runs ends with `Follow it: loop session KEY`, and a task that does not run (`add`, `--no-run`) ends with `Talk to it: loop session KEY`, because Loop Assistant still answers.
|
|
281
|
+
The interactive Session and `-s` need a terminal (stdin and stdout both TTYs).
|
|
282
|
+
Otherwise they exit 1 and point to `loop session --json KEY`, and `-s` refuses before it creates anything.
|
|
283
|
+
|
|
284
|
+
It shows the history first, then new replies, steps, status changes, questions and the pull request link.
|
|
285
|
+
While the run is live it reads the task every 2 seconds, and the messages and steps every 4 seconds, unless the last read found something new, a status changed or you just acted (then every 2 seconds).
|
|
286
|
+
When idle it reads everything every 10 seconds.
|
|
287
|
+
If Loop answers 429 or 408, or sends `Retry-After` (seconds or a date, at most 60 s), the Session and `loop wait` retry after that long, and never past `--timeout`.
|
|
288
|
+
A run that ended Failed or Cancelled shows its outcome and next step, like `--json`; `loop checkout` is offered only when there is a pull request.
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
$ loop session LOOP-321
|
|
292
|
+
Session for LOOP-321: Add the login page
|
|
293
|
+
Status: Running
|
|
294
|
+
you: Add the login page
|
|
295
|
+
agent: Cloning the repository
|
|
296
|
+
- Clone repo (completed)
|
|
297
|
+
> use the existing form component
|
|
298
|
+
Sent, waiting for the agent to pick it up.
|
|
299
|
+
Proposal: Steer the live run on LOOP-321
|
|
300
|
+
"Use the existing form component"
|
|
301
|
+
Confirm this steer? (y/n)
|
|
302
|
+
> y
|
|
303
|
+
Sent, waiting for the agent to pick it up.
|
|
304
|
+
Delivered.
|
|
305
|
+
Status: Running -> Ready for review
|
|
306
|
+
Pull request: https://github.com/acme/site/pull/9
|
|
307
|
+
Run ended: Ready for review
|
|
308
|
+
Bring it back: loop checkout LOOP-321
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
What you can type:
|
|
312
|
+
|
|
313
|
+
| Input | Effect |
|
|
314
|
+
| --- | --- |
|
|
315
|
+
| A line | Sent to Loop Assistant, with Loop's delivery result in plain words |
|
|
316
|
+
| `y` or `n` after a proposal | Confirms or drops a steer. Nothing reaches the agent until you confirm |
|
|
317
|
+
| A number on a decision card | Answers it (`1,3` on a choose-several card) |
|
|
318
|
+
| A one-time code on a code card | Answered masked. It is never echoed, printed or kept in history |
|
|
319
|
+
| An answer to a clarity question | Answered through Loop's brief check. `/approve` runs it as it is |
|
|
320
|
+
| `continue` | Sent as a message; on a finished run it starts a new run |
|
|
321
|
+
| `/steer TEXT` | Sends TEXT straight to the live run, as `Steer the agent: TEXT`, so Loop Assistant does not answer it as a question. Only while a run is running or waiting for you; otherwise it says `No run is live...` and sends nothing. If Loop Assistant still took it as a question (a lookup word such as show, open, latest, status or check), it says so: rephrase it |
|
|
322
|
+
| `/cancel` | Stops the current run after you confirm |
|
|
323
|
+
| `/approve` with no question open | Prints `Nothing to approve.` and sends nothing (approve a written plan with `loop approve KEY`) |
|
|
324
|
+
| `/open` | Opens the task in the browser |
|
|
325
|
+
| `/quit` or Ctrl+C | Leaves without cancelling, and prints `loop session KEY` to come back |
|
|
326
|
+
|
|
327
|
+
Internal notes are marked `[internal]`.
|
|
328
|
+
A message handed straight to the live run prints `Sent, waiting for the agent to pick it up.`, and `Delivered.` follows once, when the agent replies or starts a step after the time your message was saved.
|
|
329
|
+
When the run ends, the Session prints the outcome, the pull request links and `loop checkout KEY`, then stays open for follow-up messages.
|
|
330
|
+
A written plan is the exception: the API parks it as Stuck, but nothing failed, so the status line reads `Plan ready` and the Session prints `The plan is ready. Run loop approve KEY.` instead of `Run ended: Stuck`.
|
|
331
|
+
`loop session --json` keeps the API's `stuck` status in its entries.
|
|
332
|
+
|
|
333
|
+
### JSON output
|
|
334
|
+
|
|
335
|
+
`--json` on `handoff`, `add`, `task create`, `status`, `checkout`, `ls`, `wait`, `approve`, `doctor` and `models` prints a single JSON object on stdout and nothing else:
|
|
336
|
+
|
|
337
|
+
```json
|
|
338
|
+
{"id":321,"key":"LOOP-321","status":"ready","project":"loop-cli","url":"https://loop.juicebox.agency/tasks/321","dispatched":true,"queued":false,"dispatch_error":null,"clarity":null,"wip":"sent","wip_branch":"loop/wip-a1b2c3","wip_sha":"0123456789abcdef0123456789abcdef01234567","wip_excluded":[".env"],"wip_reason":null}
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
`wip` is `none`, `sent` or `not_sent`.
|
|
342
|
+
`wip_reason` explains `not_sent` and carries the unfetched-origin note.
|
|
343
|
+
`handoff` and `add` carry the `wip_*` fields; `task create` does not.
|
|
344
|
+
Every create also carries `engine` (`auto` unless one was chosen or the API reports one) and `model` (or `null`).
|
|
345
|
+
In a terminal it prints `Engine: ...` and, unless `-s` was given, `Follow it: loop session KEY` (`Talk to it: ...` for a task that does not run).
|
|
346
|
+
|
|
347
|
+
`loop status --json` is one object: `id`, `key`, `status`, `title`, `project`, `url`, `engine`, `model`, `outcome` (`failure_cause`, `next_step` or `null`), `pull_requests` (URLs) and `question` (or `null`), built from task detail with the same wording as `loop wait`.
|
|
348
|
+
`loop open --json` prints `{"url":"..."}`.
|
|
349
|
+
|
|
350
|
+
Errors in JSON mode are `{"error":"..."}`.
|
|
351
|
+
`--json` is read before the arguments are parsed, so an unknown flag, an unknown command or a missing sign-in also answers with one error object on stdout.
|
|
352
|
+
`-s` cannot be combined with `--json`.
|
|
353
|
+
|
|
354
|
+
`loop models --json` prints `{"models":[{"engine":"opencode","id":"...","label":"...","short_name":"..."}]}`.
|
|
355
|
+
|
|
356
|
+
`loop session --json` is the one exception to "one object".
|
|
357
|
+
It prints JSON Lines on stdout, one object per Session entry, never asks anything, and ends when the run ends or needs an answer:
|
|
358
|
+
|
|
359
|
+
```json
|
|
360
|
+
{"type":"status","status":"in_progress","previous":null}
|
|
361
|
+
{"type":"message","id":1,"role":"user","visibility":"public","body":"Add the login page","created_at":"...","machine_task_id":null,"artifacts":[]}
|
|
362
|
+
{"type":"step","machine_task_id":"...","index":0,"label":"Clone repo","status":"completed","timestamp":"..."}
|
|
363
|
+
{"type":"card","id":"...","kind":"choose_one","title":"Which database?","body":null,"options":[{"id":"a","label":"Postgres"}],"expires_at":null}
|
|
364
|
+
{"type":"clarity","kind":"question","question":"Which page?","question_key":"...","can_approve_anyway":false}
|
|
365
|
+
{"type":"pull_request","url":"https://github.com/acme/site/pull/9","status":"open"}
|
|
366
|
+
{"type":"end","status":"in_review","outcome":null,"pull_requests":["https://github.com/acme/site/pull/9"]}
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
A step that updates in place is printed again with its new status.
|
|
370
|
+
The command ends with the `end` entry, using the same state rules and exit codes as `loop wait`:
|
|
371
|
+
|
|
372
|
+
| Task state | Exit code | `end` entry |
|
|
373
|
+
| --- | --- | --- |
|
|
374
|
+
| Ready for review or Done | 0 | No `reason` |
|
|
375
|
+
| Stuck, failed or cancelled | 4 | No `reason` |
|
|
376
|
+
| Needs an answer | 2 | `reason` is `clarity` (a clarity question or the plan-first offer), `card` (an open question card), `waiting_for_user`, `backlog` (in Backlog and not set to run) or `plan` (a written plan waits for `loop approve KEY`) |
|
|
377
|
+
|
|
378
|
+
The question or card itself is printed as a `clarity` or `card` entry just before `end`.
|
|
379
|
+
A `clarity` entry with `kind` `plan_choice` is the plan-first offer: it carries `helper` and `needs_plan`, and a person answers it in the interactive Session with 1 or 2.
|
|
380
|
+
Interactive `loop session` is unchanged: it stays open until you leave.
|
|
381
|
+
|
|
382
|
+
## Troubleshooting
|
|
383
|
+
|
|
384
|
+
`--json` and a missing terminal stop git and credential helpers from prompting (`GIT_TERMINAL_PROMPT=0`), and make ssh fail fast on a passphrase-protected key (`GIT_SSH_COMMAND='ssh -o BatchMode=yes'`) with a readable error.
|
|
385
|
+
Your own `GIT_SSH_COMMAND`, `GIT_SSH` or `core.sshCommand` is never overridden.
|
|
386
|
+
If an `ssh` remote fails that way in a script or agent, add your key to an ssh agent (`ssh-add`) first.
|
|
387
|
+
|
|
388
|
+
Git commands that talk to origin (`ls-remote`, `fetch`, `push`) give up after 120 seconds with an error that names the command; a push that times out creates no task.
|
|
389
|
+
Every request to Loop gives up after 30 seconds, and `loop wait --timeout` never starts a request that could outlast its deadline.
|
|
390
|
+
A stalled request is treated like a network failure: `loop wait` and the Session retry it.
|
|
391
|
+
A create is never retried: if Loop does not answer, the error says the task may have been created, so check `loop ls`.
|
|
392
|
+
File uploads wait 60 seconds plus 10 seconds per MB, at most 10 minutes.
|
|
393
|
+
|
|
394
|
+
## Exit codes
|
|
395
|
+
|
|
396
|
+
| Code | Meaning |
|
|
397
|
+
| --- | --- |
|
|
398
|
+
| 0 | Created, or the command succeeded (`loop wait`: done or in review; `loop session`: left or the run ended) |
|
|
399
|
+
| 1 | Error, including `Run loop login` when the token is missing or expired. Also `loop approve` when the plan was approved but the run could not start (`dispatch_error`), as for an answered clarity question |
|
|
400
|
+
| 2 | Needs an answer. Created but Loop returned a clarity question that was not answered (always in `--json`). `loop wait`: a clarity question, an open question card, a waiting run, a ready plan (`loop approve KEY`), or a Backlog task that is not set to run. `loop session --json`: the same states as `loop wait`, with the `end` entry's `reason` |
|
|
401
|
+
| 3 | No Loop project is linked to this repository |
|
|
402
|
+
| 4 | The run is stuck, failed or cancelled (`loop wait` and `loop session --json`). A ready plan is the one Stuck state that is not a failure: it exits 2 |
|
|
403
|
+
| 5 | `loop wait` timed out |
|
|
404
|
+
|
|
405
|
+
## Where credentials live
|
|
406
|
+
|
|
407
|
+
`$XDG_CONFIG_HOME/loop/`, or `~/.config/loop/` when that variable is unset.
|
|
408
|
+
|
|
409
|
+
| File | Contents |
|
|
410
|
+
| --- | --- |
|
|
411
|
+
| `credentials.json` | `{ api_url, web_url, token, expires_at }`, written with mode 600 |
|
|
412
|
+
| `repos.json` | `owner/name` to the remembered project id |
|
|
413
|
+
| `last.json` | The last task you created |
|
|
414
|
+
| `update.json` | When the version check last ran and what it found |
|
|
415
|
+
|
|
416
|
+
Dev environment files carry a `.dev` suffix, for example `credentials.dev.json`.
|
|
417
|
+
Tokens can be revoked in Loop under Settings, API.
|
|
418
|
+
The CLI never prints the token.
|
|
419
|
+
|
|
420
|
+
## The `/loop-handoff` skill
|
|
421
|
+
|
|
422
|
+
The companion skill in the private `JuiceboxCreative/skills` repository lets a Claude Code or Codex session hand its own remaining work to Loop.
|
|
423
|
+
It does the CLI steps in this order:
|
|
424
|
+
|
|
425
|
+
1. `loop doctor --json` checks that you are signed in, the repository is linked to a project and the branch state.
|
|
426
|
+
2. It reports uncommitted and unpushed work and asks whether to send it, then passes `--include-wip` or `--no-wip` itself.
|
|
427
|
+
Its shell has no terminal, so the CLI never has to ask.
|
|
428
|
+
3. It writes a brief with five fixed headings (Goal, Done so far, Decisions made, Remaining work, Acceptance criteria) to a file outside the repository and shows it for confirmation.
|
|
429
|
+
4. After your yes it runs `loop handoff --brief FILE --json`, with `--include-wip` or `--no-wip`, and any `--model`, `--plan` or `--no-plan` you asked for.
|
|
430
|
+
The skill's approval hook needs a brief file, never stdin (`--brief -`), so it can check the file is the one you approved.
|
|
431
|
+
5. It prints the task URL and offers `loop session KEY` and `loop checkout KEY` for you to run yourself.
|
|
432
|
+
It never opens the interactive Session, which needs a terminal.
|
|
433
|
+
|
|
434
|
+
Install it with:
|
|
435
|
+
|
|
436
|
+
```bash
|
|
437
|
+
npx @juiceboxcreative/skills@latest add JuiceboxCreative/skills --skill loop-handoff -g
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
## Development
|
|
441
|
+
|
|
442
|
+
```bash
|
|
443
|
+
pnpm install
|
|
444
|
+
pnpm dev --help # run from source
|
|
445
|
+
pnpm lint # eslint, zero warnings
|
|
446
|
+
pnpm format:check # prettier
|
|
447
|
+
pnpm type-check # tsc
|
|
448
|
+
pnpm test # vitest, fixtures only, no live API
|
|
449
|
+
pnpm build # obuild -> dist/cli.mjs
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
Work branches from `develop` and pull requests target `develop`.
|
|
453
|
+
A release is a pull request from `develop` into `master`, which needs CJ's approval.
|
|
454
|
+
Releases publish from the `v*` tag workflow, without npm provenance, because npm cannot attach provenance to a package built in a private repository.
|
|
455
|
+
After the release pull request merges, bump `package.json` on `master` if it was not already bumped, tag `vX.Y.Z`, and push the tag.
|
package/bin/cli.mjs
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import module from 'node:module';
|
|
4
|
+
|
|
5
|
+
// https://nodejs.org/api/module.html#module-compile-cache
|
|
6
|
+
if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
|
|
7
|
+
try {
|
|
8
|
+
module.enableCompileCache();
|
|
9
|
+
} catch {
|
|
10
|
+
// Ignore errors
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
await import('../dist/cli.mjs');
|
|
Binary file
|