Tabs & Spaces Developers

Reference

Developer tools

tands is in the Tabs & Spaces repository, at packages/cli. From the repository, run it as yarn tands. Paths are relative to the folder you run it from.

tands new

sh
yarn tands new <folder> [--name "Team notes"] [--id team-notes]

Makes a small, working app in a new (or empty) folder: a Custom tab that keeps notes for its space, an action (add_note), an event (note_added), and a server that checks tokens. It has no dependencies and no build step: run it with npm start (Node 22 or later). The SDK is copied in, built: public/tands-sdk.js for the page, lib/tands-sdk-server.js for the server.

Its id comes from the folder's name unless you give one. Keep it once your app is installed anywhere: it's how workspaces know your app.

tands check

sh
yarn tands check [manifest]

Checks a manifest as a workspace would, from a file (default public/tands.json) or its address. Given an address, it also checks that your tabs, actions and icon are on its origin. It lists every problem, and exits with 1 when there are any, so it fits in CI.

tands dev

sh
yarn tands dev [manifest address] [--port 5470]

Starts the harness for your app (default http://localhost:5480/tands.json; start your app's server first). It reads your manifest again each time you open your tab, so edits show without restarting.

The harness

The harness is a stand-in for a workspace, on your machine, at http://localhost:5470.

  • Who's looking: a name, a space and its kind, a language, and which of your tabs. Your tab is told exactly what a workspace would tell it, and a different space or person sees different data.
  • Tokens: real EdDSA tokens, meant for your app's origin, with the harness's keys at /api/apps/keys. Point your server at it (WORKSPACE_URL=http://localhost:5470) and verifyToken() works as it will with a workspace. The keys change each time the harness starts; fetchKeys() again when a token's key is unknown, as the scaffold's server does.
  • Data: your app's values and records, in memory, kept per place as a workspace keeps them and checked against your manifest the same way. Clear data empties it; a restart does too.
  • Events: each event your app reports, from its tab or its server, checked against your manifest.
  • Actions: a form per action, with its inputs. Run calls your server as a workspace would, with a token for that action and a data key your server can use with dataClient(). The harness doesn't ask first, even for actions that change something: in a workspace, the person approves them.
  • Theme: Dark and Light tell your tab, as a workspace does when the reader switches.

What it doesn't do: agents, triggers and workflows (try those in a workspace), limits on how much you keep or how often you call, and anything about other people in the space.