diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 00d5b33..03f829f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,9 +7,12 @@ }, "plugins": [ { - "name": "box", + "name": "simular-box", "source": "./claude", "description": "box by Simular: a cloud computer your agent drives over MCP." } - ] + ], + "renames": { + "box": "simular-box" + } } diff --git a/README.md b/README.md index ceba78c..6751097 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Most agents need no plugin: add the MCP server `https://mcp.box.simular.ai/mcp` | Agent | Folder | Sign-in | Install | | --- | --- | --- | --- | -| Claude Code and Cowork | [`claude/`](claude/) | OAuth, once in the browser | `/plugin marketplace add simular-ai/box-plugin`, then `/plugin install box@simular-box` | +| Claude Code and Cowork | [`claude/`](claude/) | OAuth, once in the browser | `/plugin marketplace add simular-ai/box-plugin`, then `/plugin install simular-box@simular-box` | | DeepSeek Harness (dsh) | [`dsh/`](dsh/) | Personal key (`cb_...`), pasted on the plugin's page in Plugins | [dsh/README.md](dsh/README.md) | | OpenClaw | [`openclaw/`](openclaw/) | OAuth, once from the plugin's page in Settings | `openclaw plugins install @simular-ai/openclaw-box` | | Any of Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Hermes, OpenClaw, VS Code (and steps for Claude Desktop) | [`cli/`](cli/) | OAuth; personal key with `--auth key` for Hermes and OpenClaw | `npx @simular-ai/box connect` (check with `npx @simular-ai/box doctor`) | @@ -15,7 +15,7 @@ Most agents need no plugin: add the MCP server `https://mcp.box.simular.ai/mcp` ## Offload: move a coding task into your box and back -Going offline in the middle of a task? In Claude Code with the plugin, `/box:offload` hands the task to a fresh Claude Code (or Codex, Cursor) session in your box, which keeps working while you are away; `/box:back` brings its commits and its written hand-over home and merges them. Any other agent or a plain terminal uses `npx @simular-ai/box offload` and `npx @simular-ai/box back`. Setup and details: [cli/README.md](cli/README.md#offload). +Going offline in the middle of a task? In Claude Code with the plugin, `/simular-box:offload` hands the task to a fresh Claude Code (or Codex, Cursor) session in your box, which keeps working while you are away; `/simular-box:back` brings its commits and its written hand-over home and merges them. Any other agent or a plain terminal uses `npx @simular-ai/box offload` and `npx @simular-ai/box back`. Setup and details: [cli/README.md](cli/README.md#offload). ## Adding an agent @@ -23,7 +23,7 @@ Add a folder named after the agent with its own manifest, MCP config and, where ## Releasing -- `claude/`: bump `version` in `claude/.claude-plugin/plugin.json`. Claude Code doesn't auto-update third-party marketplaces: users get it with `/plugin marketplace update simular-box` and `/plugin update box@simular-box`, or with `npx @simular-ai/box connect`. +- `claude/`: bump `version` in `claude/.claude-plugin/plugin.json`. Claude Code doesn't auto-update third-party marketplaces: users get it with `/plugin marketplace update simular-box` and `/plugin update simular-box@simular-box`, or with `npx @simular-ai/box connect`. - `openclaw/`: bump `version` in `openclaw/package.json` and `openclaw/openclaw.plugin.json`, then `npm run build` and `clawhub package publish .` from `openclaw/`. - `dsh/`: bump `version` in `dsh/package.json`, then push a tag `dsh-vX.Y.Z`. The release workflow attaches `dsh-box.tgz`. - `openai/`: bump `version` in `openai/plugin.json` and `publication.release_notes`, run `openai/build-zip.sh`, upload the ZIP at platform.openai.com/plugins. diff --git a/claude/.claude-plugin/plugin.json b/claude/.claude-plugin/plugin.json index 4901979..65c895f 100644 --- a/claude/.claude-plugin/plugin.json +++ b/claude/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { - "name": "box", + "name": "simular-box", "displayName": "box by Simular", - "version": "0.2.3", + "version": "0.3.1", "description": "Give Claude a computer of its own: a cloud Linux desktop with Chrome and a shell that it drives over MCP, while your own computer stays free. You sign in once in the browser; no key to paste.", "author": { "name": "Simular", diff --git a/claude/README.md b/claude/README.md new file mode 100644 index 0000000..5ba9e90 --- /dev/null +++ b/claude/README.md @@ -0,0 +1,82 @@ +# box by Simular: plugins + +[box](https://box.simular.ai) gives your AI agent a computer of its own: a cloud Linux desktop with Chrome and a shell that it drives over MCP, while your own computer stays free. You can watch it live and take over at https://box.simular.ai/box. + +Most agents need no plugin: add the MCP server `https://mcp.box.simular.ai/mcp` and sign in once (see https://box.simular.ai/install). The [simular-ai/box-plugin](https://github.com/simular-ai/box-plugin) repository holds a package for each agent that installs box its own way. Each folder stands alone and is released through that agent's channel. This folder is the Claude Code and Cowork plugin. + +| Agent | Folder | Sign-in | Install | +| --- | --- | --- | --- | +| Claude Code and Cowork | [`claude/`](https://github.com/simular-ai/box-plugin/tree/main/claude) | OAuth, once in the browser | `/plugin marketplace add simular-ai/box-plugin`, then `/plugin install simular-box@simular-box` | +| DeepSeek Harness (dsh) | [`dsh/`](https://github.com/simular-ai/box-plugin/tree/main/dsh) | Personal key (`cb_...`), pasted on the plugin's page in Plugins | [dsh/README.md](https://github.com/simular-ai/box-plugin/blob/main/dsh/README.md) | +| OpenClaw | [`openclaw/`](https://github.com/simular-ai/box-plugin/tree/main/openclaw) | OAuth, once from the plugin's page in Settings | `openclaw plugins install @simular-ai/openclaw-box` | +| Any of Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Hermes, OpenClaw, VS Code (and steps for Claude Desktop) | [`cli/`](https://github.com/simular-ai/box-plugin/tree/main/cli) | OAuth; personal key with `--auth key` for Hermes and OpenClaw | `npx @simular-ai/box connect` (check with `npx @simular-ai/box doctor`) | +| Hermes Agent | [`hermes/`](https://github.com/simular-ai/box-plugin/tree/main/hermes) | Personal key (`cb_...`) in `MCP_BOX_API_KEY`; OAuth optional | [hermes/README.md](https://github.com/simular-ai/box-plugin/blob/main/hermes/README.md) | +| ChatGPT and Codex (OpenAI plugin directory) | [`openai/`](https://github.com/simular-ai/box-plugin/tree/main/openai) | OAuth, once in the browser | Listed by OpenAI after review; build the upload with `openai/build-zip.sh` ([openai/README.md](https://github.com/simular-ai/box-plugin/blob/main/openai/README.md)) | + +## What this plugin contains + +- **The box MCP server** (`.mcp.json`): `https://mcp.box.simular.ai/mcp`, over HTTP. You sign in once with OAuth in the browser (`/mcp`, pick `plugin:simular-box:box`, Authenticate); there is no key to paste, and the plugin stores none. +- **The `box` skill** (`skills/box/SKILL.md`): when to use the box tools and which one fits. +- **Offload and back** (`commands/offload.md`, `commands/back.md`, `skills/box-offload/SKILL.md`): `/simular-box:offload` and `/simular-box:back`, below. They are the only part of the plugin that runs a program on your computer. + +## Offload: move a coding task into your box and back + +Going offline in the middle of a task? In Claude Code with the plugin, `/simular-box:offload` hands the task to a fresh Claude Code (or Codex) session in your box, which keeps working while you are away; `/simular-box:back` brings its commits and its written hand-over home and merges them. Any other agent or a plain terminal uses `npx @simular-ai/box@1.1.0 offload` and `npx @simular-ai/box@1.1.0 back`. Setup and details: [the CLI's README](https://www.npmjs.com/package/@simular-ai/box). + +Nothing leaves your computer until you run `/simular-box:offload` yourself. + +### What `/simular-box:offload` runs + +- **One npx package, pinned to an exact version:** `npx -y @simular-ai/box@1.1.0`, the `simular-box` CLI, built and released by Simular from [simular-ai/box-cli](https://github.com/simular-ai/box-cli) and published to npm as [`@simular-ai/box`](https://www.npmjs.com/package/@simular-ai/box). The pin is exact, never a range, so what runs is the version this plugin was reviewed with. +- **Claude's steps** (from `skills/box-offload/SKILL.md`): + 1. Write a hand-over to the file `npx -y @simular-ai/box@1.1.0 offload handover-path` prints, from a fixed template: goal, decisions, files touched, next steps, commands. Secrets go in by name only, never by value. + 2. Run `npx -y @simular-ai/box@1.1.0 offload --kind claude` in your repo. The CLI does every step that follows; the skill tells Claude never to copy files or secrets itself. +- **Checks before anything is sent.** The CLI stops, and sends nothing, when the folder is not a git repo, `rsync` is missing, this repo already has an offload in progress, the box's image is too old, or the task needs macOS. It warns, and goes on only after you say yes, when you have untracked files, a `.env` file stays behind, the hand-over names secrets you have not opted in, the code reads environment variables set here but not in the box, the repo uses Git LFS or submodules, it calls local services or VPN-only hosts, or the copy is over 500 MB. +- **Sign-in:** the CLI uses your box account (`npx -y @simular-ai/box@1.1.0 login`, in the browser). Its token is kept in the macOS Keychain, or on Linux in `~/.simular-box/credentials.json` with mode 0600. + +### What gets uploaded from your repo + +| What | Details | +| --- | --- | +| Tracked files | Every file git tracks (committed, or staged with `git add`), with its uncommitted changes. | +| Git history | A `git bundle` of your branches and tags that the box does not have yet, and `.git` without its object store. | +| The hand-over | `handover.md`, written by Claude as above. | +| `env.json` | Versions of the tools the repo uses on this computer (go, rustc, node, …), its package manager, and which toolchain files and lockfiles exist. No environment variable values. | +| Secrets you opted in | Nothing, unless you opted a secret in for this repo yourself (next section). | + +What stays on your computer: + +- Untracked files, the ones git does not know about. Stage a new file with `git add` to take it. +- Git-ignored files, such as `.env` and `node_modules`. +- Git LFS contents (the box copy holds their pointers) and submodule contents (the box copy holds their commits). +- Everything outside the repo, except the secrets you opted in. + +### Where it goes + +Into your own box, the cloud computer of the box account you signed in with, at `/workspace/`. It travels over box's API (`mcp.box.simular.ai`), authenticated as you: `rsync` and `git` run over the CLI's own remote shell to your box. Nothing is sent anywhere else. `/simular-box:back` brings the box's commits and its hand-over home, and merges them only when that leaves your work intact: a fast-forward, or a clean merge applied uncommitted; otherwise the box's work goes on a branch `box/back-