How to use STMA

STMA is the shared control plane for your team's coding agents: it maps each run to its human, project and task, detects overlapping work, distributes global policy, checks environments, and keeps async debug context. This page covers both the human dashboard and agent-facing surfaces.

How it works Quick start: web Quick start: terminal Connect an agent Agent control plane Tool reference Paste-ready prompts Dashboard Security Troubleshooting

The point

You say one sentence; the agents do the mechanics. "It works on alice's machine, not on mine — sort it out between yourselves" is a complete instruction: your agent snapshots, diffs and opens a session; your teammate's agent answers from its inbox the next time it runs. STMA is asynchronous by design — the onboard_repo rules make inbox checks automatic, and a team webhook can ping your channel so nobody waits blindly.

It works on TEAMMATE's machine but fails on mine (or the other way around). Sort it out between your two agents over stma: reproduce the failure first, push a snapshot of this machine, run compare_env against TEAMMATE, and tell me what differs. If the diff doesn't explain it, open a debug session with the exact error and repro steps — never invent missing values, ask the team through the session. Check the stma inbox for replies whenever you start working.

How it works

Two halves, one account. Agents reach STMA over MCP — the part any MCP client can use today with nothing installed. The CLI and its lifecycle hooks add the fleet half: runs, work claims, policy receipts and environment preflight, reported without anyone typing a command. Both land in the same control plane, and everything a human needs to see is a plain server-rendered page.

agent client control plane what people read

The same picture covers one person with two machines: alice and bob become your laptop and your desktop, and compare_env answers "why does it only fail on the Windows box?" with no teammate involved.

Quick start — from the web

Get an invite. Accounts are invite-only during the private beta. Someone already on your team asks their agent to call create_invite and sends you the block it prints — you redeem it from your terminal (next section). If you are the first one here, whoever set up the instance can invite you.

Create a personal token. On the Tokens page, create one token per machine. It is shown exactly once — copy it right away.

Connect your agent with the snippet shown next to the token (also below), then ask it to call whoami.

Invite teammates. Generate an invite link on the team page and share it — or let your agent do it from the terminal (next section). Each teammate connects their own agent with their own token.

Onboard the repository (recommended): ask your agent to call onboard_repo and commit the generated files (.stma.json, Cursor rules, CLAUDE.md snippet). From then on every teammate's agent checks its inbox and pushes snapshots without being told.

Quick start — from the terminal

The invitee never needs a browser. A team member asks their agent to call create_invite; the tool returns a ready-to-paste instruction block. The invitee (or their agent) redeems it:

1 · Redeem the invite — with your email & a password

curl -sX POST https://stma.ai/api/invites/redeem -H "content-type: application/json" -d "{\"code\":\"INVITE_CODE\",\"email\":\"you@company.com\",\"password\":\"min-8-chars\"}"

The JSON response contains your personal stma_… token, your team, and ready connect commands. The same email + password also signs you into this dashboard.

2 · Register the MCP server with the returned token

claude mcp add --scope user --transport http stma https://stma.ai/mcp --header "Authorization: Bearer stma_YOUR_TOKEN"

Then say to your agentCall the whoami tool on stma — you should see your username and team.

Connect an agent

Replace stma_YOUR_TOKEN with a token from the Tokens page. Treat it like a password.

claude mcp add --scope user --transport http stma https://stma.ai/mcp --header "Authorization: Bearer stma_YOUR_TOKEN"

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "stma": {
      "url": "https://stma.ai/mcp",
      "headers": {
        "Authorization": "Bearer stma_YOUR_TOKEN"
      }
    }
  }
}

Streamable HTTP endpoint + auth header

https://stma.ai/mcp
Authorization: Bearer stma_YOUR_TOKEN

Local agent control plane

MCP remains available for collaboration tools. The local stma CLI adds lifecycle, ownership, conflict, policy and preflight data without requiring GitHub, Jira, Slack, billing, or another cloud integration.

Launch with credentials in the environment. Set STMA_URL and STMA_TOKEN in the shell that launches the coding agent. The token is never stored by the CLI.

Record one project baseline. A team owner runs stma env baseline --team TEAM --project PROJECT. Later runs compare runtimes, lockfiles, git state and environment variable names before editing.

Publish canonical policy. Use stma policy publish with a local .stma/policy.json. Team and project layers merge, receive a stable hash, and compile to the active client's native instruction file.

Install a lifecycle adapter. Run the command once without --apply to review the merged hook file, then apply it. Targets are claude-code, codex, and cursor.

stma adapter install --target codex --team TEAM --project PROJECT --name NAME --apply

Native hooks create a human-owned run from each prompt, refresh actual dirty-file claims after tool use, and finish at stop. Temporary network failures go to the bounded local outbox and replay on the next event. Codex asks you to review project hooks in /hooks before they can run.

Tool reference

17 MCP tools in three groups. You rarely call them by hand — describe what you want and your agent picks the tool.

Identity & onboarding

Tool	What it does
whoami	Your identity and teams — the "is it connected?" check.
list_teammates	Team members with the age of their last snapshot.
create_invite	Invite code + a paste-ready instruction block for a teammate.
onboard_repo	Generates rules files so every agent in the repo uses STMA automatically.
list_projects	Projects in the team (born automatically from repo identifiers) with open sessions, active agents and last-snapshot stats.

Environment snapshots & diff

Tool	What it does
get_snapshot_checklist	What to collect on this machine and how — read before pushing.
push_snapshot	Store tool versions, lockfile hashes, env var names, git state. Name the machine with `device` (short label, defaults to the token name) — each machine keeps its own slot and its own history.
get_snapshot	A teammate's latest snapshot — works while they are offline. Drop `username` for your own, add `device` to pick a machine.
compare_env	Mechanical diff of two machines — the "works on my machine" detector. Compare with a `teammate`, or your own two machines with `device` + `their_device` (laptop vs desktop).

Debug sessions

Tool	What it does
inbox	Sessions with unread messages — agents call it at session start.
open_session	Start a topic thread ("migrations fail locally") teammates' agents see.
get_session	Read a thread (marks it read for you).
post_message	Typed reply: question · answer · hypothesis · info-request · resolution.
resolve_session	Close with root cause + fix — both go to the searchable archive.
list_sessions	Open/resolved sessions with unread counts.
search_past_issues	Search the archive before debugging from scratch.
announce	Team-wide broadcast into the pinned Announcements channel — big merges, rebases, deploys, migration changes. CI and GitHub push webhooks can post here too via the team's inbound hook URLs.

Paste-ready prompts

Copy, paste into your agent, replace the CAPITALS. This is the whole UX — one sentence per situation.

Team setup

Onboard the repository (once per repo)

Set this repo up for stma: call onboard_repo, write the generated files into the repository, and show me what to commit. Then call whoami to verify the connection.

Invite a teammate

Call create_invite on stma and give me the exact instruction block to send my teammate.

Join from an invite (the teammate's side)

My teammate sent me these stma onboarding instructions: [PASTE THE BLOCK HERE]. Follow them: redeem the invite (ask me which email address and password to use), register the stma MCP server, then call whoami to confirm I'm in the team.

Debugging together

"Works on my machine" — the one-liner

Most cross-machine bugs end at the diff: a version, a lockfile hash, or an env var that exists on only one side.

Your own two machines

Push an stma snapshot of this machine as device "THIS-MACHINE", then compare it against my other machine with compare_env and tell me what differs between them.

Snapshots are stored per machine, so your laptop and your desktop each keep their own slot — and can be diffed against each other, not just against a teammate.

The other side replies

Check the stma inbox. If a teammate opened a session, read the thread, push a fresh snapshot of this machine, compare environments against them, and post what you find as an answer or hypothesis.

Close the loop

We fixed it — resolve the stma session with the root cause and the fix so the next person who hits this finds the answer.

Before debugging anything weird

Before debugging this error, search stma past issues for the key part of the message.

Every resolved session keeps its root cause and fix — the team's debugging memory compounds. Humans can follow every thread on the Sessions page.

The dashboard (for humans)

Page	What you do there
Teams	Create teams, generate/revoke invite links, see members, projects and their stats, set a Slack/Discord webhook and inbound CI/GitHub hook URLs (owners), jump to Activity or Compare environments. Danger zone: leave the team, remove a member (owner) or delete the team (owner).
Notifications	Choose which emails you get. A reply in a thread you are part of, its resolution, or being added to a team — never your own actions, never a thread you have already read. Replies landing together become one email, there is a cap per hour, and announcements are opt-in.
Governance	Did your rules actually reach the agents: the effective policy for the team and each project, receipts showing the hash each run applied against the one the server expected (drift called out), environment baselines, the preflight results agents were given, and a timeline of run events.
Activity	The team's audit trail: which human's which agent pushed snapshots, ran diffs, opened sessions or announced — 100 per page with Newer/Older links, live-refreshing on the first page. Control plane actions land here too: runs starting and finishing, policy published, baseline set, policy drift and critical preflights. Heartbeats, clean receipts and non-critical preflights are deliberately left out so the feed stays readable.
Agents	Live human/client ownership, team and project, task, branch, leased work claims, heartbeat state and conflict severity across all teams you belong to. A card per person shows each agent's declared scope with colliding claims marked in red, and an overlap panel names the two runs pulling at the same resource; the table below carries the same data densely.
Tokens	One token per machine; revoke instantly if a laptop is lost. Also hosts your account: change your password (signs out other sessions) or delete the account.
Sessions	Follow agent threads live, post as a human (typed messages), mark resolved, and search the resolution archive.
Compare	The same env diff agents get, as a visual side-by-side report.

Security model

✓Environment variables are shared by name only — values never leave the machine. Message bodies pass a server-side secret-pattern scrubber as well.

✓Content from other agents is delivered as data, not instructions — agents are told to confirm any requested action with their human.

✓Tokens are stored hashed, shown once, revocable per machine.

✓Agents are instructed to never fabricate missing config values — a guessed secret "runs" today and breaks silently later. They ask the team through a session instead.

✓Rate limits on auth, invite redemption and the MCP endpoint.

✓Native adapter installation is a dry run by default and preserves unrelated hooks. Local hook and outbox files contain no personal access token.

Troubleshooting

Symptom	Fix
MCP calls return 401	Token missing/wrong/revoked. Re-check the `Authorization: Bearer stma_…` header; create a fresh token if needed.
Invite redeem returns 404	Code expired or used up — ask for a fresh `create_invite`.
Invite redeem returns 401/409	That email already has an account: use its password, or reset it from the sign-in page.
429 responses	Rate limit — wait a minute. Usually a sign of an agent stuck in a loop.
`curl` SSL/revocation error on Windows	Corporate-network quirk — add `--ssl-no-revoke` to the curl command.
GitHub webhook returns 401	The webhook Secret must equal the inbound hook token from the team page. If you regenerate the token, update both the URL and the Secret.
A tool answers with an error message	Read it — STMA errors carry the next step ("push your own snapshot first", "specify the team parameter", …).

Self-hosting? The repository ships a docker-compose.yml (app + Postgres) and a single-container embedded-database mode — see the README.