# @super-hands/connect

Connect the coding agents on this machine to your team's
[Superhands](https://app.superhands.ai) MCP server, in one command.

Superhands generates the command for you, with a short-lived setup code on
the end of it:

```
npx -y @super-hands/connect@latest --code shsetup_…
```

The client exchanges that code for the credential over one request to your
deployment and writes the credential into the clients below. The code is
worth nothing twenty minutes later; the token it becomes never appears in the
command, the prompt you pasted it from, or your shell history. A command
written by hand around a token from the Agents page still works:
`SUPERHANDS_MCP_TOKEN="…" npx -y @super-hands/connect@latest`.

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.

## Using Superhands in the chat that connected it

A client reads its MCP servers when a chat starts, so the chat that ran the
connect command does not have the Superhands tools. It does not need a new
chat to carry on. The same tools are reachable through this command, with the
connection the install just saved:

```
npx -y @super-hands/connect@latest tools
npx -y @super-hands/connect@latest call superhands_request_guidance --args '{"contractVersion":2,"requestId":"r1","taskId":"t1","kind":"work","intent":"Set up our design system from our website"}'
```

`tools` lists every tool with the arguments it takes. `call` runs one and
prints its answer. The arguments are one JSON object after `--args`, or in a
file after `--args-file`. For a long value, `--text body=./colour.md` puts a
file's text at that argument, and `--base64 base64=./logo.svg` puts a file's
bytes there. `--cursor`, `--claude` or `--codex` picks whose saved connection
to use; with none it uses the first it finds.

From the next new chat the tools are in the client's own list, and this is not
needed.

## What it does

- **Cursor** — merges the `superhands` server into `~/.cursor/mcp.json`.
  Every other server in the file is preserved; a file that does not parse is
  left untouched. Restart Cursor and enable the server under Settings → MCP.
- **Claude Code** — registers the server through Claude Code's own CLI
  (`claude mcp add`, user scope). A new `claude` session connects on start.
- **Codex** — appends the `superhands` block to `~/.codex/config.toml`, and
  only when no such block is there. Both the app and the CLI read that file.
  Install and update also add a marked instruction to Codex’s global
  `AGENTS.md` (or its active override). It directs new chats to request team
  guidance when work matches the connected design system’s advertised scope, unless the
  user opts out. Uninstall removes the installer’s block.
- **The skill** — writes `skills/superhands/SKILL.md` under each connected
  client's own directory. It routes UI work through the team's guidance and
  carries no credential.

With no flags it connects every client it finds; `--cursor`, `--claude` or
`--codex` narrow it to one. Re-running it later to pick up a newer skill needs
no credential — see `update`, below.

## Updating it

```
npx -y @super-hands/connect@latest update
```

Brings the skill on an already-connected machine up to whatever this build
ships. It takes **no token**: it reads the endpoint and the credential back out
of the configs the install wrote, so there is nothing to fetch from Superhands
and nothing new is minted. It touches no MCP entry — the entry is how the
credential was found, so it is already right.

A client counts as connected when its own config names the `superhands` server;
anything else is skipped, and a machine with no Superhands entry at all is told
to install first rather than half-connected. An installed skill at the same
version or newer is left alone, so your own edits survive an update and the run
says which files it left as they were. The same `--cursor` / `--claude` /
`--codex` flags narrow it to one client.

## Removing it

```
npx -y @super-hands/connect@latest uninstall
```

The exact inverse, in this order: it reads every Superhands credential on the
machine out of the configs, hands each one back to the deployment that issued
it, and only then removes the entries and the skill files. The other way round
would delete the only copy of the credential needed to tell the server
anything.

It removes only what this tool wrote — one key out of `~/.cursor/mcp.json`,
its own block out of `~/.codex/config.toml`, and the Claude Code entry through
`claude mcp remove`. Everything else in those files stays. Running it twice, or
on a machine that was never connected, does nothing and says so; a machine that
cannot reach the internet is still cleaned locally, with a warning that the
credential is still live. The same `--cursor` / `--claude` / `--codex` flags
remove one client and leave the rest.

## What it does not do

It reads no repository, runs none of your code, and uploads nothing but the
setup code it was given, once, to the deployment that issued it. The one
secret it then holds is the token that came back, and it is written only into
the client configs above. The token can be revoked at any time from the
Superhands Agents page.

This file is generated from
[`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhands/blob/main/lib/connect-client-entry.ts)
in the Superhands repository — the published bytes are that commit's, and are
not minified.
