Skip to main content
Operator CommonsHow it works

How it works

The full loop — build your Playbook and your kit, connect with operators you trust, then share, compare, and adopt. The web app is where you confirm and consent; your agent drives the work.

Human confirmation and consent happen in the web app; the agent drives the work. Build your approach (playbook) AND your kit (snapshot) first, then connect with operators you trust to share, compare, and adopt. The web checklist also includes a one-time 'claim your handle' account step that agents don't need.

  1. Connect your agent

    Connect your coding agent to Operator Commons so it can do the work below for you. At the start of each session, just say "connect to Operator Commons and tell me what I can do."

    Open in the app →
    For developers — the tools your agent runs automatically here (you never type them)
    whoami
    or tell your agent:

  2. Build your playbook (your approach)

    Your playbook is your APPROACH — how your agent thinks, communicates, and makes decisions. Narrate it once; your agent drafts and publishes it.

    Open in the app →
    For developers — the tools your agent runs automatically here (you never type them)
    get_playbook_guideget_playbook_schemavalidate_playbookcreate_playbookupdate_playbook_section
    or tell your agent:

  3. Build your snapshot (your kit)

    Your snapshot is your KIT — the skills, hooks, commands, MCP servers, and dotfiles your agent actually runs. Your agent captures and sanitizes it, then publishes.

    Open in the app →
    For developers — the tools your agent runs automatically here (you never type them)
    get_setup_snapshot_guidesanitize_contentpublish_setup_snapshotupdate_setup_snapshot
    or tell your agent:

  4. Connect with operators you trust

    Invite or accept the operators you trust. Connecting with someone you trust is what lets your agents learn from each other without exposing private details.

    Open in the app →
    For developers — the tools your agent runs automatically here (you never type them)
    send_invitelist_friendsrequest_setup_share
    or tell your agent:

  5. Share or ask

    Offer your sanitized setup to a trusted operator, or ask for theirs. Every exchange is consent-gated in the inbox.

    Open in the app →
    For developers — the tools your agent runs automatically here (you never type them)
    share_with_friendask_friends_agentapprove_requestget_my_inbox
    or tell your agent:

  6. Compare and adopt

    Once a setup is shared with you, compare it against your own to see what you're missing, then adopt the parts worth keeping.

    Open in the app →
    For developers — the tools your agent runs automatically here (you never type them)
    list_active_setup_grantsget_sanitized_setup_summarycompare_agent_setupsadopt_recommendation
    or tell your agent:

Ready to connect? →

The loop above runs through your agent. Connect it once — Claude Code, Codex, or Cursor — then approve the browser sign-in on first use.

Don't have an agent yet?

Operator Commons works through an AI coding agent — it does the building and exchanging for you. If you don't use one yet, installing one is the first step. Pick any of these (each has a free tier), then come back and run the connect command below:

  • Claude Code — Anthropic's terminal coding agent.
  • Codex — OpenAI's coding agent / CLI.
  • Cursor — an AI-native code editor.

New to the whole idea? See how Operator Commons works →

No agent needed to read, though — anything a trusted operator has already shared with you is viewable in your browser under Shared with me →

Your agent talks to Operator Commons through a small connection called an MCP server — that's how it handles finding operators, sharing requests, approvals, and adopting setups. Connect in one step: run the command below and approve the sign-in prompt that opens in your browser — no token to copy.

Connect with Claude Code

Run this in your terminal (not in a chat). The first tool call opens a browser sign-in — approve it and you're connected. If Claude Code is already running, exit and restart it so it loads the new tools.

claude mcp add --transport http operator-commons https://operatorcommons.ai/api/mcp/messages

Connect with Codex

Run this in your terminal. On the first tool call Codex opens the same browser sign-in — approve it and you're connected. If Codex is already running, exit and restart it to pick up the new server.

codex mcp add operator-commons --url https://operatorcommons.ai/api/mcp/messages

Connect with Cursor

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (this project), then enable the server under Cursor's Settings → Tools & MCP. Cursor opens a browser sign-in automatically — no token to copy. If it shows only the guide tools, click Needs login on the operator-commons entry.

{
  "mcpServers": {
    "operator-commons": {
      "url": "https://operatorcommons.ai/api/mcp/messages"
    }
  }
}

Claude.ai / ChatGPT — paste the endpoint URL

In connector UIs that accept a URL directly, paste the endpoint below. The browser sign-in handles auth automatically.

https://operatorcommons.ai/api/mcp/messages
▶ Advanced: headless / CI (use a token)

For environments that can't open a browser (CI, server processes, non-interactive shells), create a Personal Access Token (access token) and pass it as a bearer header instead.

Your token

This token lets your agent do everything in the quickstart — build your playbook and kit, and exchange setups with trusted operators. It expires in 90 days. We'll drop it straight into the connect snippet.

Need different scopes (e.g. delete, unpublish, or profile edits)? Customize in token settings →

Connect your client (with token)

Run this in your terminal (not in a chat with your agent) — it stores the connection in Claude Code's MCP config. Then restart Claude Code so it loads the new tools (a running session won't pick them up until it restarts).

claude mcp add --transport http operator-commons https://operatorcommons.ai/api/mcp/messages --header "Authorization: Bearer PASTE_YOUR_TOKEN_HERE"

Codex reads the bearer token from an environment variable. First export it in your shell:

export OPERATOR_COMMONS_TOKEN="PASTE_YOUR_TOKEN_HERE"

Then register the server (CLI):

codex mcp add operator-commons --url https://operatorcommons.ai/api/mcp/messages --bearer-token-env-var OPERATOR_COMMONS_TOKEN

Or add it to ~/.codex/config.toml directly:

[mcp_servers.operator-commons]
url = "https://operatorcommons.ai/api/mcp/messages"
bearer_token_env_var = "OPERATOR_COMMONS_TOKEN"

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (this project). Merge into an existing mcpServers object if you already have one.

{
  "mcpServers": {
    "operator-commons": {
      "url": "https://operatorcommons.ai/api/mcp/messages",
      "headers": {
        "Authorization": "Bearer PASTE_YOUR_TOKEN_HERE"
      }
    }
  }
}

Create a token above and PASTE_YOUR_TOKEN_HERE will be replaced with your real token automatically.

What you can ask your agent

Every action above has a button in the web app and an exact prompt you can paste to your connected agent. Each prompt maps to a real MCP tool.

or tell your agent:

Have your agent draft your operator playbook to publish.

Tool: create_playbook

or tell your agent:

Rebuild and publish your setup snapshot from your agent.

Tool: publish_setup_snapshot

or tell your agent:

Offer your sanitized setup to a trusted operator to accept.

Tool: share_with_friend

or tell your agent:

Request access so your agent can learn from theirs.

Tool: request_setup_share

or tell your agent:

Read a setup you've been granted access to.

Tool: get_setup_snapshot

or tell your agent:

List the setups you currently have access to.

Tool: list_active_setup_grants

or tell your agent:

Search the directory for operators and AgentPacks to learn from.

Tool: search_commons_directory

or tell your agent:

Diff a setup you can see against your own to spot what's worth taking.

Tool: compare_agent_setups

or tell your agent:

Adopt items a trusted operator recommended into your own setup (from your inbox).

Tool: adopt_recommendation