# Linzumi ```text ▓▓╗ ▓▓╗▓▓▓╗ ▓▓╗▓▓▓▓▓▓▓╗▓▓╗ ▓▓╗▓▓▓╗ ▓▓▓╗▓▓╗ ▓▓║ ▓▓║▓▓▓▓╗ ▓▓║╚══▓▓▓╔╝▓▓║ ▓▓║▓▓▓▓╗ ▓▓▓▓║▓▓║ ▓▓║ ▓▓║▓▓╔▓▓╗ ▓▓║ ▓▓▓╔╝ ▓▓║ ▓▓║▓▓╔▓▓▓▓╔▓▓║▓▓║ ▓▓║ ▓▓║▓▓║╚▓▓╗▓▓║ ▓▓▓╔╝ ▓▓║ ▓▓║▓▓║╚▓▓╔╝▓▓║▓▓║ ▓▓▓▓▓▓▓░░░░░░░░╚▓▓▓▓║▓▓▓▓▓▓▓╗╚▓▓▓▓▓▓╔╝░░░░░░░░▓▓║▓▓║ ╚═══▒▒▒@@@@@@@@▒▒═══╝╚══════╝ ╚════▒▒▒@@@@@@@@▒▒╝╚═╝ ▒@@@@@@@@@@@@@@@@▒ ▒@@@@@@@@@@@@@@@@▒ @@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@ ║║ ║║ ║║ ║║ ║║ ()-().----. ║║ ║║ \"/` ___ ;_________║║_.' ║║ ` ^^ ^^ ║║ ──────────╨╨─────────────··────··────────╨╨────────────── secure mission control for all your agents on your computers ``` **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 npx -y @linzumi/cli@latest signup ``` Linzumi will ask for your email, send you a sign-in code, help you pick the repos where Codex may work, start useful first tasks, and open Mission Control in your browser with the work already running. ## Why a CLI 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. ## What you'll have in three minutes - 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. ## Manual Runner Setup Install the CLI or run it with `npx`: ```bash npm install -g @linzumi/cli@latest npx -y @linzumi/cli@latest signup npx -y @linzumi/cli@1.0.179 --version linzumi --version ``` Start a local runner from a trusted folder: ```bash linzumi paths add ~/code/my-app linzumi start ~/code/my-app ``` For explicit runner roots, pass a comma-separated allowlist: ```bash linzumi start ~/code/my-app --allowed-cwd ``` For non-production Linzumi servers, `connect` accepts either API URL flag: ```bash linzumi connect --linzumi-url ws://127.0.0.1:4140 --workspace default --allow-port-forwarding-by-default ``` ## Headless / remote runner auth (device flow) The default `connect` flow opens a browser on the runner machine and waits for an OAuth callback on `localhost`. That cannot work on a headless box - a VPS, a Windows/SSH session, or any machine with no browser or no loopback callback. For those, use `--auth-mode device`: the runner prints a short user code plus a verification URL, and you approve it from a browser already logged in to Linzumi on any other machine (e.g. your laptop). ```bash linzumi connect --workspace --auth-mode device --api-url wss://serve.linzumi.com ``` The runner prints: ``` Authorize this computer: Code: 5PYP8PC2 Open: https://serve.linzumi.com/api/v2/local-codex-runner/device ``` 1. On any machine where you are signed in to Linzumi, open the `Open:` URL. 2. Enter the 8-character `Code:` and approve. 3. The runner long-polls, receives a scoped token, and connects - no browser or loopback callback needed on the runner itself. The verification URL targets the same server you pass via `--api-url` / `--linzumi-url` (defaulting to `wss://serve.linzumi.com`), so the link you open always points at the server the runner connected to. The code expires in 10 minutes; re-run `connect` to get a fresh one. ## Agent-first launch path The fastest path is the `npx -y @linzumi/cli@latest signup` command above. It signs you in, lets you trust local projects, connects the Commander, and starts the first visible Coding agent threads. ## What just happened Linzumi keeps the browser/chat surface separate from the local work surface. The CLI authenticates your local Commander, publishes runner capabilities, and lets Linzumi ask that Commander to start Codex inside trusted folders only. ## MCP for coding agents Commander-started Codex sessions are preconfigured with a local MCP server named `linzumi`. It lets the agent use the same approved local-runner auth to read the scoped Linzumi message, thread, or channel context, and to send a bounded DM to the Commander owner when configured. Manual MCP commands are available for other MCP-compatible agents: ```bash linzumi mcp doctor --api-url https://serve.linzumi.com --workspace --channel linzumi mcp config --api-url https://serve.linzumi.com --format codex linzumi mcp config --api-url https://serve.linzumi.com --format claude-code linzumi mcp server --api-url https://serve.linzumi.com ``` The shipped tools are `linzumi_get_message`, `linzumi_get_thread`, `linzumi_get_channel`, and `linzumi_dm_owner`. ## Three things to try first - 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 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. ## Trusted folders Linzumi only edits inside folders you've explicitly trusted. ```bash linzumi paths add ~/code/my-app ``` The trust list lives at `~/.linzumi/config.json`. The bootstrap agent adds `/tmp/hello_linzumi` for you on first run. For `linzumi connect`, the selected `--cwd` is also trusted for that runner process. ## Git safety snapshots Before an agent turn runs in a git workspace with uncommitted changes, the runner saves a safety snapshot: dirty tracked state as a dangling `git stash create` commit (pinned under `refs/linzumi/safety/`, never touching your working tree) plus copies of untracked, non-ignored files under `~/.linzumi/safety-snapshots/` (up to 200MB per snapshot; oversized files are skipped loudly). A clean tree costs one `git status` and stores nothing. Snapshots are pruned after 72 hours or beyond the newest 50. If a turn discards work you wanted, recover it: ```bash linzumi safety-snapshots list linzumi safety-snapshots restore --to ./recovered ``` Restore materializes the snapshot into a new directory and never overwrites current files; the listed stash commit also works directly with `git stash apply `. Default ON; set `LINZUMI_GIT_SAFETY_SNAPSHOTS=0` to disable. ## When something looks wrong 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`. --- *Slack-shaped on the surface. A multiplayer compiler underneath.* [linzumi.com](https://linzumi.com) · [agents.md](https://linzumi.com/agents.md) ·