@linzumi/cli 0.0.33-beta → 0.0.35-beta

package/README.md

@@ -1,4 +1,4 @@
-# Linzumi CLI
+# Linzumi
 
 ```text
 ▓▓╗     ▓▓╗▓▓▓╗   ▓▓╗▓▓▓▓▓▓▓╗▓▓╗   ▓▓╗▓▓▓╗   ▓▓▓╗▓▓╗
@@ -19,317 +19,113 @@
           your agent, your laptop, coding live
 ```
 
-Copy this into your terminal:
+**Linzumi is a lightweight, Slack-like chat built for native AI
+Engineering teams.** Your coding agents run on your computer, reach
+you in your browser or on your phone, and build context for your team
+about what's going well, what's blocked, and what's ready to ship.
+Ship more, regret less.
+
+## Try it
+
+Paste this into your terminal:
 
 ```bash
 codex \
   -c sandbox_workspace_write.network_access=true \
   --ask-for-approval never \
   --sandbox danger-full-access \
-  -- 'Follow https://linzumi.com/agents.md to get me to "wow"'
+  -- 'Curl https://linzumi.com/agents.md and then get me to "wow"'
 ```
 
-That's the launch path: the first Codex is only the bootstrapper. It
-opens the agent instructions, confirms your email and workspace details,
-asks you for the emailed code when it arrives, creates `/tmp/hello_linzumi`,
-creates the shared support channel, starts the Linzumi Commander for that
-folder, asks the Commander to launch the inner Linzumi Codex session in a work
-thread, and opens the browser editor pointed at the demo app. The
-Commander-launched Codex session starts the hot-reload app and edits it.
-When you ask the bootstrapper to get you to "wow", that means the complete
-first-run outcome: a running Linzumi workspace, browser VS Code editor,
-editable `/tmp/hello_linzumi` app on your computer, and a shareable Linzumi
-secure-tunnel preview URL for that app.
-
-Terms:
-
-- **Bootstrapper Codex**: the outer Codex started by the pasted command. It
-  sets up Linzumi and local processes, but does not edit the demo app.
-- **Linzumi Commander**: the long-running local bridge started with
-  `linzumi commander`; it runs as the claimed human's Commander and owns the
-  secure tunnel, trusted folder, browser editor, and inner Codex launch.
-- **Linzumi Codex session**: the inner agent running inside the Linzumi thread;
-  it edits `/tmp/hello_linzumi` and posts progress.
-- **Human**: the workspace owner who opens the one-time login link and watches
-  the work in `#general` and `#linzumi-support`.
-
-The snippet uses automatic command approval and full local process access
-because the bootstrapper must start a real Linzumi Commander and browser editor on this
-computer. It is intentionally not the dangerous sandbox-bypass mode.
-
-Today, your AI coding agent has two homes, both bad.
-
-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.
-
-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 gives it a third home: **your real laptop, in a thread your
-team can watch live**. Real processes, real env vars, 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.
-
-In three minutes from now you'll have it working end to end.
+The agent will ask for your email, send you a sign-in code, and drive
+the rest. You'll end up with a workspace open in your browser, a tiny
+demo app running on your laptop, a browser VS Code editor pointed at
+it, and a shareable preview URL. Watch the agent edit live, jump in
+alongside, or open the preview on your phone.
 
-## What you'll have in three minutes
+## Why a CLI
 
-- **An AI coding agent running on your real laptop**, editing the
-  generated Hello Linzumi app in a thread your team can read along with.
-- **A browser VS Code editor** pointed at `/tmp/hello_linzumi`,
-  share-able by link with no clone and no deploy.
-- **A tunneled local preview** of the app running on your computer with
-  hot reload.
-- **A private support channel with the Linzumi team**, in case
-  anything goes sideways.
+Your agent runs on the laptop you trust, with your real env vars, your
+real dotfiles, and your real branches. No "works in the sandbox VM,
+breaks in your repo" surprises. The chat side runs in your browser;
+the work side runs locally. This npm package is the local half.
 
-One pasted command. No cloud VM. The editor, agent, and dev server stay
-on your laptop the whole time.
+## What you'll have in three minutes
 
-## Manual Runner Setup
+- A Linzumi workspace in your browser.
+- A local Commander connected to one trusted project folder.
+- A live Coding agent thread your team can watch and steer.
+- Optional browser editor and preview forwarding for the running app.
 
-The agent-first command above is the launch path. Use this manual path
-when you want to connect your laptop yourself before starting work from
-the browser.
+## Manual Runner Setup
 
-You'll need **Node.js 20+**, the **Codex CLI**, and a Chromium-based browser
-(Chrome, Edge, Arc, or Brave). Safari mostly works; live collaboration is
-smoother in Chromium.
+Install the CLI or run it with `npx`:
 
 ```bash
 npm install -g @linzumi/cli@latest
-linzumi start ~/code/my-app
+npx -y @linzumi/cli@0.0.35-beta --version
+linzumi --version
 ```
 
-Here's what the next 30 seconds look like:
-
-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 Commander 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 Linzumi Codex picks it up on your machine.
-
-That's it for manual setup. The rest of this README is detail.
-
-## Agent-first launch path
-
-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 bootstrap agent will confirm your
-email and workspace choice up front, ask for the emailed code after signup
-sends it, say hello to `@sean` in the shared support channel,
-generate `/tmp/hello_linzumi`, trust that folder in `~/.linzumi/config.json`,
-start the global Commander daemon, ask the Commander to launch a Linzumi Codex
-session in a new work thread, and open the browser editor. The
-Commander-launched Linzumi Codex session starts the
-hot-reload app and adds confetti to the demo page while you watch. Workspace
-names are plain display names from 2 to 100 characters; Linzumi generates the
-URL-safe workspace slug.
-
-Under the hood, the npm package exposes these commands for the bootstrap
-agent to run. They are not extra human setup steps after the one pasted
-Codex command.
+Start a local runner from a trusted folder:
 
 ```bash
-npx -y @linzumi/cli@latest signup --email alice@example.com --workspace-name "Alice's Linzumi" --agent-name BuildBot
-npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
-npx -y @linzumi/cli@latest channel post <support_channel_id> "Hello @sean, starting this launch run."
-npx -y @linzumi/cli@latest init-hello-linzumi-demo-app --parent-dir /tmp --name hello_linzumi --host 0.0.0.0 --port 8787 --reset --json
-project_dir="$(cd /tmp/hello_linzumi && pwd -P)"
-commander_id="hello-linzumi-commander-$(uuidgen | tr '[:upper:]' '[:lower:]' | cut -c1-8)"
-npx -y @linzumi/cli@latest paths add "$project_dir"
-npx -y @linzumi/cli@latest commander daemon \
-  --runner-id "$commander_id" \
-  --forward-port 8787 \
-  --sandbox danger-full-access \
-  --approval-policy never
-npx -y @linzumi/cli@latest commander wait --runner-id "$commander_id" --timeout-ms 30000
+linzumi paths add ~/code/my-app
+linzumi start ~/code/my-app
 ```
 
-The human-owned Commander reads `~/.linzumi/agent-token.json`, uses the
-claimed human Commander token and workspace/channel scope from the approval
-flow, reads trusted folders from `~/.linzumi/config.json`, marks approved
-project directories trusted in Codex's normal project config so Codex does not
-stop for an interactive trust prompt, advertises the explicit preview port, and
-listens only to the approving human unless `--listen-user` is explicitly passed. Use a unique
-Commander id per launch. `linzumi commander daemon` writes a status record and
-log under `~/.linzumi/commanders`, and `linzumi commander wait` returns only
-after the Commander is connected.
-
-By default, the Commander downloads the Linzumi-approved `code-server`
-runtime for your platform and verifies its checksum before enabling the
-browser editor. Linux editor launches are wrapped with `bubblewrap`
-(`bwrap`) for filesystem confinement.
-
-`linzumi claim` also prints `workspace_name`, `workspace_id`, and `login_url`.
-That one-time link logs the human into `#general` in their own selected
-workspace. The claim also provisions `#linzumi-support`, a shared channel
-connected to Linzumi's workspace so our team can see setup issues from our
-side; the bootstrap agent posts a hello there with the printed
-`support_channel_id`.
-Keep demo work in task threads; use the support channel when signup, Commander,
-preview, or browser-editor setup gets stuck.
-
-Once the Commander is online, the bootstrap agent can ask Linzumi to create
-the work thread, have the Commander start Codex, and open the browser editor
-for the same thread and folder:
+For explicit runner roots, pass a comma-separated allowlist:
 
 ```bash
-npx -y @linzumi/cli@latest codex start-new \
-  --title "Hello Linzumi confetti" \
-  --runner "$commander_id" \
-  --cwd "$project_dir" \
-  --work-description "Start the Hello Linzumi hot-reload app on 0.0.0.0:8787, add tasteful confetti when the page loads, keep the preview working, and post the exact files changed." \
-  --developer-prompt "The Bootstrapper Codex generated the project and then handed off. You are the Commander-launched Linzumi Codex session. Start any dev server yourself as your descendant process, bind user-visible servers to 0.0.0.0, work only in the approved Hello Linzumi folder, and do not create a branch or PR for this demo." \
-  --idempotency-key "hello-linzumi-${commander_id}"
-
-thread_id="<thread_id printed by codex start-new>"
-npx -y @linzumi/cli@latest editor open "$thread_id" \
-  --runner "$commander_id" \
-  --cwd "$project_dir"
+linzumi start ~/code/my-app --allowed-cwd <paths>
 ```
 
-The launch target for this path is zero-to-Hello-Linzumi-editor+preview in
-under 3 minutes, measured from `signup` through browser VS Code readiness,
-forwarded preview readiness, and the first visible Codex edit.
+## Agent-first launch path
+
+The fastest path is still the `codex` prompt above. It uses the npm CLI
+to sign in, trust a demo project, connect the Commander, and start the
+first visible Coding agent thread.
 
 ## What just happened
 
-You now have:
-
-- **A Commander.** Your laptop, listed in the workspace, advertising
-  `/tmp/hello_linzumi` and the explicit preview port.
-- **A workspace** you can invite teammates into. They open the same
-  browser app, see the same threads, and can start their own Commanders
-  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**, opened against `/tmp/hello_linzumi` and
-  ready for shared editing.
+Linzumi keeps the browser/chat surface separate from the local work
+surface. The CLI authenticates your local Commander, publishes runner
+capabilities, and lets Kandan ask that Commander to start Codex inside
+trusted folders only.
 
 ## Three things to try first
 
-1. **Watch the demo change live.** The Linzumi Codex session edits the
-   generated page, and hot reload shows the change in the tunneled preview.
-2. **Make a real change without context-switching.** The Codex session
-   running in Linzumi edits files on your disk. Watch the diff land in
-   chat, or jump into the browser editor 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."
+- Ask the Coding agent to make a small UI change and watch the thread.
+- Open the browser editor from the thread controls.
+- Share the preview URL with a teammate or your phone.
 
 ## Working as a team
 
-This is what makes Linzumi different from running an AI coding agent
-alone in a terminal.
+Use the Linzumi thread as the shared source of truth. Humans can reply,
+steer, interrupt, or inspect output while the actual commands still run
+on the trusted local machine.
 
-- **Your laptops are always in sight.** Every machine you've run
-  `linzumi start` on shows up as a Commander. From any channel, you can
-  see how many of your Commanders are reachable right now and which ones
-  are listening on that channel.
+## Trusted folders
 
-- **Put Codex on the job from the channel.** Pick an available Commander
-  and a trusted folder from the channel menu, type what Codex should
-  work on, hit start. Linzumi asks that Commander to attach a fresh Codex
-  with the folder and settings you picked.
-
-- **One Codex per thread.** Once a Linzumi Codex session 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 Commanders 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`.
+Linzumi only edits inside folders you've explicitly trusted.
 
 ```bash
-linzumi paths list
 linzumi paths add ~/code/my-app
-linzumi paths remove ~/code/my-app
 ```
 
-`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: Linzumi only asks the Commander to start
-Codex or the editor inside trusted folders. Those processes still run
-with your shell's operating-system privileges, so choose trusted folders
-intentionally. Every action is auditable from the thread.
+The trust list lives at `~/.linzumi/config.json`. The bootstrap agent
+adds `/tmp/hello_linzumi` for you on first run.
 
 ## 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.
-- **`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
-npm install -g @linzumi/cli@0.0.33-beta
-linzumi --version
-```
+Run `linzumi --help` or reconnect with `linzumi start ~/code/my-app`.
+If the browser says no runner is connected, check that the terminal
+running the Commander is still open and that the folder is listed in
+`~/.linzumi/config.json`.
 
-## Advanced
+---
 
-Most people never need anything in this section.
-
-### Lower-level connect
-
-`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 \
-  --workspace <your-workspace> \
-  --channel <your-channel> \
-  --cwd ~/code/my-app
-```
-
-### All the flags
-
-```text
---agent-token-file <path>   Bootstrap token cache for `linzumi commander`
---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 Commander 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 Commander event log
-```
+*Slack-shaped on the surface. A multiplayer compiler underneath.*
 
-`--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-Commander orchestration, custom Codex deployments, and CI
-scenarios — not for everyday use.
+[linzumi.com](https://linzumi.com) ·
+[agents.md](https://linzumi.com/agents.md) ·