@super-hands/connect 0.1.18 → 0.1.19

package/README.md

@@ -21,6 +21,33 @@ It connects to `https://app.superhands.ai/api/mcp` unless `SUPERHANDS_MCP_URL`
 says otherwise — a command from a preview or local deployment carries that
 variable too.
 
+## Starting without an account
+
+If you have never used Superhands, you do not need a setup code, a browser or
+an account. This command works on its own:
+
+```
+npx -y @super-hands/connect@latest start --claude
+```
+
+It creates a Superhands team for this machine, with the baseline Instructions
+already in it, mints the credential, and writes the configs and the skill just
+as an install does. Nobody owns the team yet: after your agent's first
+Superhands tool call, its reply carries a link you can open to claim the team
+whenever you want it in the app. `--cursor` and `--codex` do the same for those
+clients; with no client flag it connects every client it finds.
+
+Because this makes a team, it refuses to run twice by accident: on a machine
+that already holds a Superhands credential it stops and tells you to use
+`update`, or `install` with a setup code, instead. Pass `--new` if you really
+do want a separate team.
+
+The homepage adds one more thing to this command — `--code shwatch_…`. That is
+a **watch handle**, not a credential and not a setup code. It buys exactly one
+thing: the page you copied the command from can show your agent arriving and
+list its first few calls. The team you get is identical without it, and every
+run carrying the same handle lands on one team rather than making several.
+
 ## What it does
 
 - **Cursor** — merges the `superhands` server into `~/.cursor/mcp.json`.

package/client.mjs

@@ -332,6 +332,12 @@ function connectReportUrl(endpoint) {
 function connectExchangeUrl(endpoint) {
   return `${connectReportUrl(endpoint)}/exchange`;
 }
+function connectStartUrl(endpoint) {
+  return `${connectReportUrl(endpoint)}/start`;
+}
+function appOrigin(endpoint) {
+  return endpoint.replace(/\/api\/mcp\/?$/, "") || endpoint;
+}
 function takeCodeArgument(argv) {
   const rest = [];
   let code = null;
@@ -382,6 +388,36 @@ async function exchangeSetupCode(args) {
     `Superhands answered ${response.status} to the setup code. Try again in a moment, or get a fresh command from Superhands.`
   );
 }
+async function startTeam(args) {
+  let response;
+  try {
+    response = await fetch(connectStartUrl(args.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(args.code ? { code: args.code } : {}),
+      signal: AbortSignal.timeout(1e4)
+    });
+  } catch {
+    return stop(
+      `Superhands at ${args.endpoint} could not be reached. Nothing was created. Check the connection and run this command again.`
+    );
+  }
+  const body = await response.json().catch(() => null);
+  if (response.ok && body?.ok && typeof body.token === "string" && body.token) {
+    return body.token;
+  }
+  if (response.status === 429) {
+    return stop(
+      `Superhands has started too many teams from this network in the last hour. Nothing was created. Try again later, or create an account at ${appOrigin(args.endpoint)} and use the connect command from Setup.`
+    );
+  }
+  if (response.status === 401) {
+    return stop(
+      `that watch code has expired or is not one Superhands issued. Run the same command without ${CONNECT_CODE_FLAG} \u2014 you get the same team, the homepage just will not show it arriving.`
+    );
+  }
+  return stop("Superhands could not start a team just now. Nothing was created \u2014 try again in a moment.");
+}
 async function reportSkillVersion(args) {
   try {
     await fetch(connectReportUrl(args.endpoint), {
@@ -486,15 +522,62 @@ async function main() {
   const command = argv.find((arg) => !arg.startsWith("--")) ?? "install";
   if (command === "uninstall") return uninstall(flags);
   if (command === "update") return update(flags);
+  if (command === "start") return start(flags, code);
   if (command !== "install") {
     stop(
-      `unknown command "${command}". This tool takes "install" (the default), "update" or "uninstall".`
+      `unknown command "${command}". This tool takes "install" (the default), "start", "update" or "uninstall".`
     );
   }
   return install(flags, code);
 }
+function chosenEndpoint() {
+  return process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+}
+async function start(flags, code) {
+  const endpoint = chosenEndpoint();
+  if (code === "") {
+    stop(
+      `${CONNECT_CODE_FLAG} needs the watch code after it. Copy the whole command from the Superhands homepage and run it unchanged, or drop ${CONNECT_CODE_FLAG} entirely \u2014 the command works without it.`
+    );
+  }
+  const existing = existingConnections(endpoint);
+  if (!code && existing.length > 0 && !flags.has("--new")) {
+    stop(
+      `this machine is already connected to Superhands at ${endpoint}. Run \`update\` to refresh it, add the client flag to \`install\` with a setup code from your Agents page to connect another client to the same team, or pass --new to start a separate team.`
+    );
+  }
+  const token = await startTeam({ endpoint, code });
+  await connectWithToken(flags, token, endpoint);
+  if (existing.length === 0) {
+    say(
+      "A Superhands team was created for this machine, with the baseline Instructions already in it. Nobody owns it yet: your agent's first answer after calling a Superhands tool carries the link to claim it."
+    );
+  }
+}
+function existingConnections(endpoint) {
+  const found = [];
+  let cursorText = null;
+  try {
+    cursorText = readFileSync(join(homedir(), ".cursor", "mcp.json"), "utf8");
+  } catch {
+    cursorText = null;
+  }
+  const cursor = cursorConnection(cursorText);
+  if (cursor) found.push(cursor);
+  const claude = claudeRegistration().connection;
+  if (claude) found.push(claude);
+  let codexText = "";
+  try {
+    codexText = readFileSync(join(homedir(), ".codex", "config.toml"), "utf8");
+  } catch {
+    codexText = "";
+  }
+  const codex = codexConnection(codexText);
+  if (codex) found.push(codex);
+  return found.filter((connection) => connection.endpoint === endpoint);
+}
 async function install(flags, code) {
-  const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+  const endpoint = chosenEndpoint();
   if (code === "") {
     stop(
       `${CONNECT_CODE_FLAG} needs the setup code after it. Copy the whole command from Superhands and run it unchanged.`
@@ -503,9 +586,12 @@ async function install(flags, code) {
   const token = code ? await exchangeSetupCode({ endpoint, code }) : process.env[CONNECT_TOKEN_ENV]?.trim();
   if (!token) {
     stop(
-      `this command needs a setup code after ${CONNECT_CODE_FLAG}, or ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands and run it unchanged.`
+      `this command needs a setup code after ${CONNECT_CODE_FLAG}, or ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands and run it unchanged. If you have no Superhands account yet, run \`start\` instead \u2014 it needs nothing.`
     );
   }
+  return connectWithToken(flags, token, endpoint);
+}
+async function connectWithToken(flags, token, endpoint) {
   const wanted = chosenClients(flags);
   let connected = 0;
   let attempted = 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.18",
-  "description": "Connect the coding agents on this machine to your team's Superhands MCP server, refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
+  "version": "0.1.19",
+  "description": "Connect the coding agents on this machine to your team's Superhands MCP server — with `start`, from a machine that has no Superhands account at all. Refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"
   },