@linzumi/cli 0.0.12-beta → 0.0.14-beta
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 +201 -96
- package/package.json +2 -2
- package/src/agentBootstrap.ts +806 -0
- package/src/channelSession.ts +616 -31
- package/src/channelSessionSupport.ts +54 -1
- package/src/forwardTunnel.ts +32 -7
- package/src/index.ts +293 -56
- package/src/kandanQueue.ts +11 -0
- package/src/localForwarding.ts +31 -8
- package/src/protocol.ts +15 -0
- package/src/runner.ts +21 -3
package/README.md
CHANGED
|
@@ -1,88 +1,193 @@
|
|
|
1
1
|
# Linzumi CLI
|
|
2
2
|
|
|
3
3
|
```text
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
4
|
+
▓▓╗ ▓▓╗▓▓▓╗ ▓▓╗▓▓▓▓▓▓▓╗▓▓╗ ▓▓╗▓▓▓╗ ▓▓▓╗▓▓╗
|
|
5
|
+
▓▓║ ▓▓║▓▓▓▓╗ ▓▓║╚══▓▓▓╔╝▓▓║ ▓▓║▓▓▓▓╗ ▓▓▓▓║▓▓║
|
|
6
|
+
▓▓║ ▓▓║▓▓╔▓▓╗ ▓▓║ ▓▓▓╔╝ ▓▓║ ▓▓║▓▓╔▓▓▓▓╔▓▓║▓▓║
|
|
7
|
+
▓▓║ ▓▓║▓▓║╚▓▓╗▓▓║ ▓▓▓╔╝ ▓▓║ ▓▓║▓▓║╚▓▓╔╝▓▓║▓▓║
|
|
8
|
+
▓▓▓▓▓▓▓░░░░░░░░╚▓▓▓▓║▓▓▓▓▓▓▓╗╚▓▓▓▓▓▓╔╝░░░░░░░░▓▓║▓▓║
|
|
9
|
+
╚═══▒▒▒@@@@@@@@▒▒═══╝╚══════╝ ╚════▒▒▒@@@@@@@@▒▒╝╚═╝
|
|
10
|
+
▒@@@@@@@@@@@@@@@@▒ ▒@@@@@@@@@@@@@@@@▒
|
|
11
|
+
@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@
|
|
12
|
+
@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@
|
|
13
|
+
║║ ║║
|
|
14
|
+
║║ ║║
|
|
15
|
+
║║ ()-().----. ║║
|
|
16
|
+
║║ \"/` ___ ;_________║║_.'
|
|
17
|
+
║║ ` ^^ ^^ ║║
|
|
18
|
+
──────────╨╨─────────────··────··────────╨╨──────────────
|
|
19
|
+
your agent, your laptop, PRs in minutes
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Today, your AI coding agent has two homes, both bad.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
It can run **alone in your terminal**, where nobody — your teammate,
|
|
25
|
+
your eng lead, your future self at 2am — can see what it's doing or
|
|
26
|
+
help when it gets stuck.
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
Or it can run in **someone else's sandbox VM**, where "works for the
|
|
29
|
+
agent" rarely means "works on your laptop." You merge, pull, run the
|
|
30
|
+
test suite, and find out at 4pm.
|
|
27
31
|
|
|
28
|
-
|
|
32
|
+
Linzumi gives it a third home: **your real laptop, in a thread your
|
|
33
|
+
team can watch live**. Real env vars, real branches, real dotfiles,
|
|
34
|
+
real teamwork. Diffs land in chat as the agent makes them. Your
|
|
35
|
+
reviewer opens a browser VS Code pointed at *your folder* and has an
|
|
36
|
+
opinion before the agent's even finished. You approve from your phone
|
|
37
|
+
on the way to lunch.
|
|
38
|
+
|
|
39
|
+
In three minutes from now you'll have it.
|
|
40
|
+
|
|
41
|
+
## What you'll have in three minutes
|
|
42
|
+
|
|
43
|
+
- **An AI coding agent running on your real laptop**, in a thread
|
|
44
|
+
your team can read along with.
|
|
45
|
+
- **A browser VS Code editor** pointed at the same folder, share-able
|
|
46
|
+
by link — no clone, no deploy, no "let me push a branch real
|
|
47
|
+
quick."
|
|
48
|
+
- **A private support channel with the Linzumi team**, in case
|
|
49
|
+
anything goes sideways.
|
|
50
|
+
|
|
51
|
+
Two commands. No cloud VM. Your code, your terminal, and your dev
|
|
52
|
+
server stay on your laptop the whole time.
|
|
53
|
+
|
|
54
|
+
## Install + start
|
|
55
|
+
|
|
56
|
+
You'll need **Node.js 20+**, **Bun 1.2+**, the **Codex CLI**, and a
|
|
57
|
+
Chromium-based browser (Chrome, Edge, Arc, or Brave). Safari mostly
|
|
58
|
+
works; live collaboration is smoother in Chromium.
|
|
29
59
|
|
|
30
60
|
```bash
|
|
31
|
-
npm install -g @linzumi/cli@
|
|
61
|
+
npm install -g @linzumi/cli@latest
|
|
32
62
|
linzumi start ~/code/my-app
|
|
33
63
|
```
|
|
34
64
|
|
|
35
|
-
|
|
65
|
+
Here's what the next 30 seconds look like:
|
|
36
66
|
|
|
37
67
|
1. Your browser opens to Linzumi.
|
|
38
68
|
2. Sign in (or sign up — one click).
|
|
39
69
|
3. Linzumi asks if it can connect to this computer. Click allow.
|
|
40
|
-
4. Your
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
70
|
+
4. Your laptop appears as a runner in your workspace, and
|
|
71
|
+
`~/code/my-app` is added to your trusted-paths list automatically.
|
|
72
|
+
5. Type something in chat — *"Explain this project and tell me how
|
|
73
|
+
to run it"* — and Codex picks it up on your machine.
|
|
44
74
|
|
|
45
|
-
|
|
75
|
+
That's it. The rest of this README is detail.
|
|
46
76
|
|
|
47
|
-
-
|
|
48
|
-
- **Make a real change without context-switching.** Codex edits the files on your disk. You watch the diff land in chat, or jump into the browser editor (it is VS Code, in your browser, pointed at your folder).
|
|
49
|
-
- **Show someone what is on your screen.** Open the browser editor or share your local dev server through a normal HTTPS link. No exposing `localhost` to the internet, no copy-pasting IPs.
|
|
50
|
-
- **Work with a teammate on the same code.** They join your channel, see the same threads, and can start their own Codex run on their own machine.
|
|
77
|
+
## Agent-first launch path
|
|
51
78
|
|
|
52
|
-
|
|
79
|
+
Copy this into an agent running in the repo you want changed:
|
|
53
80
|
|
|
54
|
-
|
|
81
|
+
```text
|
|
82
|
+
Get me a working hello-world PR from https://linzumi.com/agents.md
|
|
83
|
+
```
|
|
55
84
|
|
|
56
|
-
|
|
85
|
+
That one prompt is the launch path. The canonical agent instructions are
|
|
86
|
+
hosted at `https://linzumi.com/agents.md`; `https://linzumi.com/skills.md`
|
|
87
|
+
stays available for compatibility. The agent will ask for your email,
|
|
88
|
+
ask for the emailed code, say hello to `@sean` in the shared support
|
|
89
|
+
channel, start the runner in the current folder, open Codex and the
|
|
90
|
+
browser editor, then post the PR or reviewable branch.
|
|
57
91
|
|
|
58
|
-
|
|
92
|
+
Under the hood, the npm package exposes these commands:
|
|
59
93
|
|
|
60
|
-
|
|
94
|
+
```bash
|
|
95
|
+
npx -y @linzumi/cli@latest signup --email alice@example.com --agent-name BuildBot
|
|
96
|
+
npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
|
|
97
|
+
npx -y @linzumi/cli@latest thread new "Hello world PR" --message "Starting now."
|
|
98
|
+
npx -y @linzumi/cli@latest agent runner "$PWD" --runner-id hello-world-agent
|
|
99
|
+
```
|
|
61
100
|
|
|
62
|
-
-
|
|
101
|
+
The agent-owned runner reads `~/.linzumi/agent-token.json`, uses the
|
|
102
|
+
workspace/channel scope from the approval flow, trusts only the selected
|
|
103
|
+
folder by default, and listens only to the approving human unless
|
|
104
|
+
`--listen-user` is explicitly passed.
|
|
63
105
|
|
|
64
|
-
|
|
106
|
+
`linzumi claim` also prints `support_channel_url`. That channel is the
|
|
107
|
+
shared onboarding room for the approving human, the claimed agent identity,
|
|
108
|
+
and Linzumi support. Keep repository work in task threads; use the support
|
|
109
|
+
channel when signup, runner, mobile, or browser-editor setup gets stuck.
|
|
65
110
|
|
|
66
|
-
|
|
111
|
+
Once the runner is online, the agent can ask Kandan to start Codex and
|
|
112
|
+
open the browser editor for the same thread and folder:
|
|
67
113
|
|
|
68
114
|
```bash
|
|
69
|
-
|
|
70
|
-
|
|
115
|
+
npx -y @linzumi/cli@latest codex start <thread_id> \
|
|
116
|
+
--runner hello-world-agent \
|
|
117
|
+
--cwd "$PWD" \
|
|
118
|
+
--work-description "Make the smallest hello-world change, run the relevant test, open a PR or clearly labeled local-review branch, and post the link."
|
|
119
|
+
|
|
120
|
+
npx -y @linzumi/cli@latest editor open <thread_id> \
|
|
121
|
+
--runner hello-world-agent \
|
|
122
|
+
--cwd "$PWD"
|
|
71
123
|
```
|
|
72
124
|
|
|
73
|
-
|
|
125
|
+
The launch target for this path is zero-to-hello-world-pr+editor in under
|
|
126
|
+
3 minutes, measured from `signup` through PR/reviewable change link plus
|
|
127
|
+
browser VS Code readiness.
|
|
128
|
+
|
|
129
|
+
## What just happened
|
|
130
|
+
|
|
131
|
+
You now have:
|
|
132
|
+
|
|
133
|
+
- **A runner.** Your laptop, listed in the workspace, advertising the
|
|
134
|
+
folder you started in (and any others you've added to your trusted
|
|
135
|
+
list).
|
|
136
|
+
- **A workspace** you can invite teammates into. They open the same
|
|
137
|
+
browser app, see the same threads, and can start their own runners
|
|
138
|
+
on their own machines.
|
|
139
|
+
- **A private Linzumi support channel.** We can see this channel; we
|
|
140
|
+
**cannot** see your repo contents, your tokens, your Codex
|
|
141
|
+
transcripts, your editor session, or your other threads. Stuck?
|
|
142
|
+
Post there — we read it.
|
|
143
|
+
- **A browser VS Code editor**, available on demand for any Codex
|
|
144
|
+
session, posted into the thread when ready.
|
|
145
|
+
|
|
146
|
+
## Three things to try first
|
|
147
|
+
|
|
148
|
+
1. **Onboard yourself to a new repo.** *"Explain this project and tell
|
|
149
|
+
me how to run it."* Codex maps the codebase before you've opened
|
|
150
|
+
a single file. Days saved on day one.
|
|
151
|
+
2. **Make a real change without context-switching.** Codex edits files
|
|
152
|
+
on your disk. Watch the diff land in chat, or jump into the
|
|
153
|
+
browser editor (it's VS Code in your browser, pointed at your
|
|
154
|
+
folder) and shape it yourself.
|
|
155
|
+
3. **Show a teammate something on your screen.** Open the browser
|
|
156
|
+
editor or share your local dev server through a normal HTTPS
|
|
157
|
+
link. No exposing localhost, no copy-pasting IPs, no "screenshare
|
|
158
|
+
real quick."
|
|
159
|
+
|
|
160
|
+
## Working as a team
|
|
161
|
+
|
|
162
|
+
This is what makes Linzumi different from running an AI coding agent
|
|
163
|
+
alone in a terminal.
|
|
164
|
+
|
|
165
|
+
- **Your laptops are always in sight.** Every machine you've run
|
|
166
|
+
`linzumi start` on shows up as a runner. From any channel, you can
|
|
167
|
+
see how many of your runners are reachable right now and which ones
|
|
168
|
+
are listening on that channel.
|
|
169
|
+
|
|
170
|
+
- **Put Codex on the job from the channel.** Pick an available runner
|
|
171
|
+
and a trusted folder from the channel menu, type what Codex should
|
|
172
|
+
work on, hit start. Linzumi attaches a fresh Codex to that runner
|
|
173
|
+
with the folder and settings you picked.
|
|
74
174
|
|
|
75
|
-
|
|
175
|
+
- **One Codex per thread.** Once a Codex picks up a thread, it owns
|
|
176
|
+
the thread — no second Codex can step in and trample the work. The
|
|
177
|
+
lock holds for the life of the thread.
|
|
76
178
|
|
|
77
|
-
|
|
179
|
+
- **Browse what your team's been up to.** Open the runners dropdown
|
|
180
|
+
to see, across every device, the most recently active threads with
|
|
181
|
+
short AI-written summaries. Jump in and keep working.
|
|
78
182
|
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
183
|
+
- **Chat with humans without waking Codex.** Start a message with `&`
|
|
184
|
+
and Codex won't see it. Side conversations live in the same thread
|
|
185
|
+
without nudging the agent.
|
|
82
186
|
|
|
83
|
-
## Trusted folders
|
|
187
|
+
## Trusted folders — the security model
|
|
84
188
|
|
|
85
|
-
Linzumi only
|
|
189
|
+
Linzumi only runs Codex or opens the editor inside folders you've
|
|
190
|
+
explicitly trusted. The trust list lives at `~/.linzumi/config.json`.
|
|
86
191
|
|
|
87
192
|
```bash
|
|
88
193
|
linzumi paths list
|
|
@@ -90,73 +195,73 @@ linzumi paths add ~/code/my-app
|
|
|
90
195
|
linzumi paths remove ~/code/my-app
|
|
91
196
|
```
|
|
92
197
|
|
|
93
|
-
`linzumi
|
|
198
|
+
`linzumi start <path>` adds `<path>` to the trust list automatically
|
|
199
|
+
on first use. `linzumi connect` uses the list as-is — or pass
|
|
200
|
+
`--allowed-cwd <paths>` for a one-off comma-separated override.
|
|
201
|
+
|
|
202
|
+
There's no credential escalation: an agent attached to a trusted
|
|
203
|
+
folder can only read and write inside that folder, with the same
|
|
204
|
+
privileges as your shell. Every action is auditable from the thread.
|
|
205
|
+
|
|
206
|
+
## When something looks wrong
|
|
207
|
+
|
|
208
|
+
- **`linzumi: command not found`** — your global npm bin folder isn't
|
|
209
|
+
on `PATH`. Run `npm prefix -g`; add the printed path's `bin` folder
|
|
210
|
+
to your shell.
|
|
211
|
+
- **`bun: command not found`** — install Bun, then rerun
|
|
212
|
+
`linzumi start`. The `linzumi` binary is a node shim that delegates
|
|
213
|
+
to Bun for fast TypeScript startup.
|
|
214
|
+
- **`codex: command not found`** — install the Codex CLI, or pass
|
|
215
|
+
`--codex-bin <path>` to `linzumi start`.
|
|
216
|
+
- **Browser sign-in opens but never returns to the CLI.** Your browser
|
|
217
|
+
can't reach the address the CLI is listening on. Pass
|
|
218
|
+
`--oauth-callback-host <ip-or-host-your-browser-can-reach>`.
|
|
219
|
+
- **Browser editor never says it's ready.** Rerun `linzumi start` and
|
|
220
|
+
watch the console for the editor download step. The very first
|
|
221
|
+
launch on a slow network can take a minute or two.
|
|
222
|
+
- **Collaboration looks off in Safari.** Switch to Chromium for now.
|
|
223
|
+
- **Anything else.** Post in your Linzumi support channel — we read it.
|
|
224
|
+
|
|
225
|
+
## Pinning a version
|
|
94
226
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
- The Codex CLI
|
|
100
|
-
- A Chromium-based browser (Chrome, Edge, Arc, or Brave)
|
|
101
|
-
|
|
102
|
-
Safari is semi-supported. Live editing and live collaboration are smoother in Chromium.
|
|
103
|
-
|
|
104
|
-
## If something looks wrong
|
|
105
|
-
|
|
106
|
-
- **`linzumi: command not found`** — your global npm bin folder is not on `PATH`. Run `npm prefix -g` and add the `bin` folder under that path to your shell `PATH`.
|
|
107
|
-
- **`bun: command not found`** — install Bun, then rerun `linzumi start`.
|
|
108
|
-
- **`codex: command not found`** — install or configure the Codex CLI, or pass `--codex-bin <path>` to `linzumi start`.
|
|
109
|
-
- **The browser sign-in opens but never returns to the CLI** — your browser cannot reach the address the CLI is listening on. Pass `--oauth-callback-host <ip-or-host-your-browser-can-reach>`.
|
|
110
|
-
- **The browser editor never says it is ready** — rerun `linzumi start` and watch the console for the editor download step. Slow networks can make the very first launch take a minute or two.
|
|
111
|
-
- **Collaboration looks off in Safari** — switch to a Chromium browser for now.
|
|
227
|
+
```bash
|
|
228
|
+
npm install -g @linzumi/cli@0.0.14-beta
|
|
229
|
+
linzumi --version
|
|
230
|
+
```
|
|
112
231
|
|
|
113
232
|
## Advanced
|
|
114
233
|
|
|
115
234
|
Most people never need anything in this section.
|
|
116
235
|
|
|
117
|
-
### Point at a self-hosted Linzumi
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
linzumi start ~/code/my-app --kandan-url wss://your-host
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Public TLS hosts work without extra flags. For local development against a private CA, set `KANDAN_TLS_CA_FILE` to your CA bundle and pass `--kandan-url` as usual.
|
|
124
|
-
|
|
125
236
|
### Lower-level connect
|
|
126
237
|
|
|
127
|
-
`linzumi start` is what you want almost every time. The lower-level
|
|
238
|
+
`linzumi start` is what you want almost every time. The lower-level
|
|
239
|
+
form is useful when you already know your workspace and channel:
|
|
128
240
|
|
|
129
241
|
```bash
|
|
130
242
|
linzumi connect \
|
|
131
|
-
--
|
|
132
|
-
--
|
|
133
|
-
--channel general \
|
|
243
|
+
--workspace <your-workspace> \
|
|
244
|
+
--channel <your-channel> \
|
|
134
245
|
--cwd ~/code/my-app
|
|
135
246
|
```
|
|
136
247
|
|
|
137
248
|
### All the flags
|
|
138
249
|
|
|
139
250
|
```text
|
|
140
|
-
--
|
|
251
|
+
--agent-token-file <path> Agent token cache for `linzumi agent runner`
|
|
141
252
|
--oauth-callback-host <ip> Sign-in callback host your browser can reach
|
|
142
|
-
--runner-id <id> Stable id for this computer
|
|
143
253
|
--codex-bin <path> Codex executable, default `codex`
|
|
144
|
-
--model <name> Codex
|
|
145
|
-
--reasoning-effort <value> Codex
|
|
146
|
-
--fast
|
|
147
|
-
--forward-port <ports> Comma-separated local ports Linzumi may share
|
|
254
|
+
--model <name> Model requested for Codex sessions and labelled in Linzumi
|
|
255
|
+
--reasoning-effort <value> Reasoning effort requested for Codex sessions and labelled in Linzumi
|
|
256
|
+
--fast Advertise this runner as low-latency in the workspace
|
|
257
|
+
--forward-port <ports> Comma-separated local TCP ports Linzumi may share as authenticated previews
|
|
148
258
|
--allowed-cwd <paths> Override ~/.linzumi/config.json with comma-separated trusted roots
|
|
149
259
|
--log-file <path> JSONL runner event log
|
|
150
260
|
```
|
|
151
261
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
--kandan-url ws://100.71.192.98:4162 \
|
|
159
|
-
--oauth-callback-host 100.71.192.98
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Use your own Tailscale IP, not that one.
|
|
262
|
+
`--runner-id`, `--auth-file`, `--code-server-bin`, `--codex-url`,
|
|
263
|
+
`--launch-tui`, `--listen-user`, `--sandbox`, `--approval-policy`,
|
|
264
|
+
`--stream-flush-ms`, and `--token` are also accepted; `linzumi
|
|
265
|
+
--help` shows them all with brief descriptions. They exist for
|
|
266
|
+
multi-runner orchestration, custom Codex deployments, and CI
|
|
267
|
+
scenarios — not for everyday use.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linzumi/cli",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.0.14-beta",
|
|
4
|
+
"description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"linzumi": "bin/linzumi.js"
|