@linzumi/cli 0.0.11-beta → 0.0.13-beta

package/README.md

@@ -1,288 +1,267 @@
 # Linzumi CLI
 
-Run an AI coding session on the code that is already on your computer, then
-open the editor and app preview from a shared browser workspace.
-
-Linzumi is for the common team workflow that is still too painful:
-
-- your branch is only on your laptop
-- your app only runs with your local setup, secrets, database, or devices
-- you want an AI agent to read, edit, run, and explain that code
-- you want a teammate to see the editor or preview without cloning the repo
-- you do not want to move the project into a cloud VM just to collaborate
-
-The CLI connects your machine to Kandan, Linzumi's shared browser workspace.
-Your code, terminal commands, dev servers, and editor runtime stay local. Kandan
-handles sign-in, sharing, HTTPS browser access, and permission checks.
-
-## Try It
-
-Use Chrome, Edge, Arc, Brave, or another Chromium-based browser.
-
-```bash
-npm install -g @linzumi/cli@beta
-linzumi start ~/code/my-app
-```
-
-Then in the browser:
-
 ```text
-Explain this project, open the editor, and tell me how to run it.
-```
-
-If the project has a dev server, start it locally:
-
-```bash
-npm run dev
+▓▓╗     ▓▓╗▓▓▓╗   ▓▓╗▓▓▓▓▓▓▓╗▓▓╗   ▓▓╗▓▓▓╗   ▓▓▓╗▓▓╗
+▓▓║     ▓▓║▓▓▓▓╗  ▓▓║╚══▓▓▓╔╝▓▓║   ▓▓║▓▓▓▓╗ ▓▓▓▓║▓▓║
+▓▓║     ▓▓║▓▓╔▓▓╗ ▓▓║  ▓▓▓╔╝ ▓▓║   ▓▓║▓▓╔▓▓▓▓╔▓▓║▓▓║
+▓▓║     ▓▓║▓▓║╚▓▓╗▓▓║ ▓▓▓╔╝  ▓▓║   ▓▓║▓▓║╚▓▓╔╝▓▓║▓▓║
+▓▓▓▓▓▓▓░░░░░░░░╚▓▓▓▓║▓▓▓▓▓▓▓╗╚▓▓▓▓▓▓╔╝░░░░░░░░▓▓║▓▓║
+╚═══▒▒▒@@@@@@@@▒▒═══╝╚══════╝ ╚════▒▒▒@@@@@@@@▒▒╝╚═╝
+ ▒@@@@@@@@@@@@@@@@▒             ▒@@@@@@@@@@@@@@@@▒
+@@@@@@@@@@@@@@@@@@@@@           @@@@@@@@@@@@@@@@@@@@@
+   @@@@@@@@@@@@@@@                 @@@@@@@@@@@@@@@
+          ║║                             ║║
+          ║║                             ║║
+          ║║        ()-().----.          ║║
+          ║║         \"/` ___  ;_________║║_.'
+          ║║          ` ^^   ^^          ║║
+──────────╨╨─────────────··────··────────╨╨──────────────
+          your agent, your laptop, PRs in minutes
 ```
 
-Open the forwarded preview from Kandan. You should get a normal HTTPS URL that
-you can share with an approved teammate, without exposing a raw `localhost`
-address.
-
-To pin this exact beta:
+Today, your AI coding agent has two homes, both bad.
 
-```bash
-npm install -g @linzumi/cli@0.0.11-beta
-linzumi start ~/code/my-app
-```
+It can run **alone in your terminal**, where nobody — your teammate,
+your eng lead, your future self at 2am — can see what it's doing or
+help when it gets stuck.
 
-## What You Get
+Or it can run in **someone else's sandbox VM**, where "works for the
+agent" rarely means "works on your laptop." You merge, pull, run the
+test suite, and find out at 4pm.
 
-Linzumi turns your local project into a shared coding workspace:
+Linzumi gives it a third home: **your real laptop, in a thread your
+team can watch live**. Real env vars, real branches, real dotfiles,
+real teamwork. Diffs land in chat as the agent makes them. Your
+reviewer opens a browser VS Code pointed at *your folder* and has an
+opinion before the agent's even finished. You approve from your phone
+on the way to lunch.
 
-1. Codex can inspect and edit the folder you allowed.
-2. You can open a browser editor for that local folder.
-3. Local app previews are reachable through Kandan HTTPS URLs.
-4. Approved teammates can join the editor or preview.
-5. Kandan enforces auth, sharing grants, and allowed-port policy.
+In three minutes from now you'll have it.
 
-The important part: your project does not have to leave your computer for this
-to work.
+## What you'll have in three minutes
 
-## What Runs Where
+- **An AI coding agent running on your real laptop**, in a thread
+  your team can read along with.
+- **A browser VS Code editor** pointed at the same folder, share-able
+  by link — no clone, no deploy, no "let me push a branch real
+  quick."
+- **A private support channel with the Linzumi team**, in case
+  anything goes sideways.
 
-On your computer, the CLI starts a runner. The runner can:
+Two commands. No cloud VM. Your code, your terminal, and your dev
+server stay on your laptop the whole time.
 
-- launch or connect to Codex
-- download the Kandan-approved editor runtime
-- start code-server for the folder you chose
-- connect to explicitly approved local ports
-- stream editor and preview traffic through Kandan
+## Install + start
 
-In the browser, Kandan provides:
-
-- sign-in and workspace UI
-- local-runner status
-- editor and preview links
-- sharing controls
-- HTTPS termination
-- access checks before traffic reaches your machine
-
-When docs mention `127.0.0.1` or `localhost` on the local-service hop, that
-means your computer, not the Kandan server.
-
-## Requirements
-
-Install these before running the beta:
-
-```bash
-node --version
-npm --version
-bun --version
-codex --version
-```
-
-Expected:
-
-- Node.js 20 or newer
-- npm
-- Bun 1.2 or newer
-- Codex CLI
-- Chrome, Edge, Arc, Brave, or another Chromium-based browser
-
-Safari is semi-supported for now. Use Chromium for the best editor and
-collaboration behavior.
-
-## First Run
+You'll need **Node.js 20+**, **Bun 1.2+**, the **Codex CLI**, and a
+Chromium-based browser (Chrome, Edge, Arc, or Brave). Safari mostly
+works; live collaboration is smoother in Chromium.
 
 ```bash
+npm install -g @linzumi/cli@beta
 linzumi start ~/code/my-app
 ```
 
-What happens:
-
-1. The CLI opens Kandan.
-2. You sign up or sign in.
-3. Kandan asks permission to connect this computer.
-4. The CLI stores a scoped local-runner token.
-5. The CLI checks Bun, Codex, and the Kandan editor runtime.
-6. Kandan shows the computer as connected.
+Here's what the next 30 seconds look like:
 
-The first editor launch can download a Kandan-approved runtime archive. Later
-runs reuse the verified runtime from:
+1. Your browser opens to Linzumi.
+2. Sign in (or sign up — one click).
+3. Linzumi asks if it can connect to this computer. Click allow.
+4. Your laptop appears as a runner in your workspace, and
+   `~/code/my-app` is added to your trusted-paths list automatically.
+5. Type something in chat — *"Explain this project and tell me how
+   to run it"* — and Codex picks it up on your machine.
 
-```text
-~/.linzumi/editor-runtimes
-```
+That's it. The rest of this README is detail.
 
-The production path does not use a random local `code-server` install. Kandan
-publishes a checksummed runtime manifest, and the CLI only advertises editor
-readiness after that runtime is verified locally.
+## Agent-first launch path
 
-## Good Things To Try
-
-Ask Codex to map the project:
+Copy this into an agent running in the repo you want changed:
 
 ```text
-What does this app do? Where should I start reading?
+Get me a working hello-world PR from https://linzumi.com/agents.md
 ```
 
-Ask Codex to make a small change:
-
-```text
-Find the main settings page and add a clear empty state.
-```
+That one prompt is the launch path. The canonical agent instructions are
+hosted at `https://linzumi.com/agents.md`; `https://linzumi.com/skills.md`
+stays available for compatibility. The agent will ask for your email,
+ask for the emailed code, say hello to `@sean` in the shared support
+channel, start the runner in the current folder, open Codex and the
+browser editor, then post the PR or reviewable branch.
 
-Open the editor from Kandan and inspect the changed files.
-
-Start a local dev server:
-
-```bash
-npm run dev
-```
-
-If a port is not auto-detected, restart with an explicit approved port:
+Under the hood, the npm package exposes these commands:
 
 ```bash
-linzumi start ~/code/my-app --forward-port 3000
+npx -y @linzumi/cli@latest signup --email alice@example.com --agent-name BuildBot
+npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
+npx -y @linzumi/cli@latest thread new "Hello world PR" --message "Starting now."
+npx -y @linzumi/cli@latest agent runner "$PWD" --runner-id hello-world-agent
 ```
 
-For a collaboration test, invite another user, open the same file in the local
-editor, and type in Chromium. Remote cursor labels and selections should be
-visible.
+The agent-owned runner reads `~/.linzumi/agent-token.json`, uses the
+workspace/channel scope from the approval flow, trusts only the selected
+folder by default, and listens only to the approving human unless
+`--listen-user` is explicitly passed.
 
-## Hosted Kandan
+`linzumi claim` also prints `support_channel_url`. That channel is the
+shared onboarding room for the approving human, the claimed agent identity,
+and Linzumi support. Keep repository work in task threads; use the support
+channel when signup, runner, mobile, or browser-editor setup gets stuck.
 
-For a hosted Kandan deployment, point the CLI at the hosted websocket URL:
+Once the runner is online, the agent can ask Kandan to start Codex and
+open the browser editor for the same thread and folder:
 
 ```bash
-linzumi start ~/code/my-app --kandan-url wss://<your-kandan-host>
+npx -y @linzumi/cli@latest codex start <thread_id> \
+  --runner hello-world-agent \
+  --cwd "$PWD" \
+  --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."
+
+npx -y @linzumi/cli@latest editor open <thread_id> \
+  --runner hello-world-agent \
+  --cwd "$PWD"
 ```
 
-For Render-hosted Kandan, public TLS should work without local certificate
-flags. The CLI derives the HTTPS API origin from the websocket URL for OAuth,
-runtime manifest download, and runtime archive download.
-
-For local development with a private CA:
+The launch target for this path is zero-to-hello-world-pr+editor in under
+3 minutes, measured from `signup` through PR/reviewable change link plus
+browser VS Code readiness.
+
+## What just happened
+
+You now have:
+
+- **A runner.** Your laptop, listed in the workspace, advertising the
+  folder you started in (and any others you've added to your trusted
+  list).
+- **A workspace** you can invite teammates into. They open the same
+  browser app, see the same threads, and can start their own runners
+  on their own machines.
+- **A private Linzumi support channel.** We can see this channel; we
+  **cannot** see your repo contents, your tokens, your Codex
+  transcripts, your editor session, or your other threads. Stuck?
+  Post there — we read it.
+- **A browser VS Code editor**, available on demand for any Codex
+  session, posted into the thread when ready.
+
+## Three things to try first
+
+1. **Onboard yourself to a new repo.** *"Explain this project and tell
+   me how to run it."* Codex maps the codebase before you've opened
+   a single file. Days saved on day one.
+2. **Make a real change without context-switching.** Codex edits files
+   on your disk. Watch the diff land in chat, or jump into the
+   browser editor (it's VS Code in your browser, pointed at your
+   folder) and shape it yourself.
+3. **Show a teammate something on your screen.** Open the browser
+   editor or share your local dev server through a normal HTTPS
+   link. No exposing localhost, no copy-pasting IPs, no "screenshare
+   real quick."
+
+## Working as a team
+
+This is what makes Linzumi different from running an AI coding agent
+alone in a terminal.
+
+- **Your laptops are always in sight.** Every machine you've run
+  `linzumi start` on shows up as a runner. From any channel, you can
+  see how many of your runners are reachable right now and which ones
+  are listening on that channel.
+
+- **Put Codex on the job from the channel.** Pick an available runner
+  and a trusted folder from the channel menu, type what Codex should
+  work on, hit start. Linzumi attaches a fresh Codex to that runner
+  with the folder and settings you picked.
+
+- **One Codex per thread.** Once a Codex picks up a thread, it owns
+  the thread — no second Codex can step in and trample the work. The
+  lock holds for the life of the thread.
+
+- **Browse what your team's been up to.** Open the runners dropdown
+  to see, across every device, the most recently active threads with
+  short AI-written summaries. Jump in and keep working.
+
+- **Chat with humans without waking Codex.** Start a message with `&`
+  and Codex won't see it. Side conversations live in the same thread
+  without nudging the agent.
+
+## Trusted folders — the security model
+
+Linzumi only runs Codex or opens the editor inside folders you've
+explicitly trusted. The trust list lives at `~/.linzumi/config.json`.
 
 ```bash
-KANDAN_TLS_CA_FILE=/path/to/ca.crt linzumi start ~/code/my-app \
-  --kandan-url wss://linzumi.io:4140
+linzumi paths list
+linzumi paths add ~/code/my-app
+linzumi paths remove ~/code/my-app
 ```
 
-## Tailscale Development
-
-If your browser needs to reach a local Kandan server through Tailscale:
+`linzumi start <path>` adds `<path>` to the trust list automatically
+on first use. `linzumi connect` uses the list as-is — or pass
+`--allowed-cwd <paths>` for a one-off comma-separated override.
+
+There's no credential escalation: an agent attached to a trusted
+folder can only read and write inside that folder, with the same
+privileges as your shell. Every action is auditable from the thread.
+
+## When something looks wrong
+
+- **`linzumi: command not found`** — your global npm bin folder isn't
+  on `PATH`. Run `npm prefix -g`; add the printed path's `bin` folder
+  to your shell.
+- **`bun: command not found`** — install Bun, then rerun
+  `linzumi start`. The `linzumi` binary is a node shim that delegates
+  to Bun for fast TypeScript startup.
+- **`codex: command not found`** — install the Codex CLI, or pass
+  `--codex-bin <path>` to `linzumi start`.
+- **Browser sign-in opens but never returns to the CLI.** Your browser
+  can't reach the address the CLI is listening on. Pass
+  `--oauth-callback-host <ip-or-host-your-browser-can-reach>`.
+- **Browser editor never says it's ready.** Rerun `linzumi start` and
+  watch the console for the editor download step. The very first
+  launch on a slow network can take a minute or two.
+- **Collaboration looks off in Safari.** Switch to Chromium for now.
+- **Anything else.** Post in your Linzumi support channel — we read it.
+
+## Pinning a version
 
 ```bash
-linzumi start ~/code/my-app \
-  --kandan-url ws://100.71.192.98:4162 \
-  --oauth-callback-host 100.71.192.98
+npm install -g @linzumi/cli@0.0.13-beta
+linzumi --version
 ```
 
-Use your own Tailscale IP.
+## Advanced
 
-## Commands
+Most people never need anything in this section.
 
-```bash
-linzumi
-linzumi --help
-linzumi --version
-linzumi start <folder>
-linzumi connect --help
-linzumi connect [runner options]
-linzumi auth [auth options]
-```
-
-Most people should use `linzumi start`.
+### Lower-level connect
 
-`linzumi connect` is the lower-level command for connecting to an explicit
-workspace and channel:
+`linzumi start` is what you want almost every time. The lower-level
+form is useful when you already know your workspace and channel:
 
 ```bash
 linzumi connect \
-  --kandan-url wss://serve.kandanai.com \
-  --workspace default \
-  --channel general \
+  --workspace <your-workspace> \
+  --channel <your-channel> \
   --cwd ~/code/my-app
 ```
 
-## Useful Options
-
-```bash
---kandan-url <ws-url>       Kandan websocket URL
---oauth-callback-host <ip>  Callback host reachable by your browser
---runner-id <id>            Stable id for this computer
---codex-bin <path>          Codex executable, default codex
---model <name>              Codex model metadata shown in Kandan
---reasoning-effort <value>  Codex reasoning metadata shown in Kandan
---fast                      Mark this runner as low-latency
---forward-port <ports>      Comma-separated local ports Kandan may expose
---allowed-cwd <paths>       Comma-separated roots Kandan may use
---log-file <path>           JSONL runner event log
-```
-
-`--code-server-bin` exists only as a development override. It is not the
-supported production editor path.
-
-## Troubleshooting
-
-Check the CLI version:
-
-```bash
-linzumi --version
-```
-
-Expected:
+### All the flags
 
 ```text
-linzumi 0.0.11-beta
-```
-
-If `linzumi` is not found, your global npm bin directory is not on `PATH`.
-
-If `bun` is not found, install Bun and rerun `linzumi start`.
-
-If `codex` is not found, install or configure the Codex CLI, or pass
-`--codex-bin`.
-
-If OAuth opens but does not return to the CLI, pass an
-`--oauth-callback-host` that your browser can reach.
-
-If the editor does not become ready, do not install a local code-server package
-as a workaround. The server-managed runtime must download and verify cleanly.
-Rerun the CLI and check the runner log.
-
-If collaboration behaves oddly in Safari, retry in Chromium. Safari is currently
-semi-supported.
-
-## For Kandan Release Engineers
-
-The production contract is:
-
-1. Build the server-approved editor runtime archive.
-2. Publish the manifest and archive from Kandan.
-3. Publish the CLI beta.
-4. The CLI downloads only the approved runtime archive.
-5. The CLI verifies the archive SHA before advertising editor readiness.
-
-For local package verification:
-
-```bash
-bun test
-npm pack --dry-run
+--agent-token-file <path>   Agent token cache for `linzumi agent runner`
+--oauth-callback-host <ip>  Sign-in callback host your browser can reach
+--codex-bin <path>          Codex executable, default `codex`
+--model <name>              Model requested for Codex sessions and labelled in Linzumi
+--reasoning-effort <value>  Reasoning effort requested for Codex sessions and labelled in Linzumi
+--fast                      Advertise this runner as low-latency in the workspace
+--forward-port <ports>      Comma-separated local TCP ports Linzumi may share as authenticated previews
+--allowed-cwd <paths>       Override ~/.linzumi/config.json with comma-separated trusted roots
+--log-file <path>           JSONL runner event log
 ```
 
-The npm package must include this README, `bin/linzumi.js`, and the `src`
-runtime files.
+`--runner-id`, `--auth-file`, `--code-server-bin`, `--codex-url`,
+`--launch-tui`, `--listen-user`, `--sandbox`, `--approval-policy`,
+`--stream-flush-ms`, and `--token` are also accepted; `linzumi
+--help` shows them all with brief descriptions. They exist for
+multi-runner orchestration, custom Codex deployments, and CI
+scenarios — not for everyday use.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.11-beta",
-  "description": "Connect your computer to Kandan for local Codex sessions, editors, and forwarded previews",
+  "version": "0.0.13-beta",
+  "description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {
     "linzumi": "bin/linzumi.js"