Agent setup

Give this prompt to your agent

Paste this into the coding agent you want to connect. The prompt contains no token or other secret.

Set up StateLode in this coding environment.
Read and follow https://statelode.dev/docs/agent-setup/
First tell me which client and which surface you are running in — for example a terminal CLI or a desktop app. Ask me if you cannot tell from the environment, and do not guess: for some clients the surface changes the config and the sign-in step.
Do every setup step you can yourself. Do not ask me to edit config files, run commands you can run, or paste secrets into chat.
Pause only for browser sign-in or OAuth consent, a client restart you cannot safely perform yourself, or a genuinely ambiguous client, surface, or project choice. Give me one exact action, wait for me to finish it, then continue.
Finish only after you verify the MCP connection, discover the workspace and projects, and make the current repo ready to use StateLode.

That is the primary setup path. The agent should inspect and preserve your existing config, write the correct client-specific entry, start OAuth, and verify the finished connection. You should touch a config file or terminal only when the agent cannot access that surface.

You only do what the agent cannot

• Complete browser sign-in, workspace selection, and OAuth consent.
• Restart or reload the current coding client when restarting would terminate the agent that is guiding you.
• Resolve a project choice only when the repository identity or existing workspace projects are genuinely ambiguous.
• Handle a static token directly in a secret store or config only when you deliberately choose the headless or CI fallback. Never paste it into chat.

Agent contract

From here onward, you are the coding agent. The human may not know where MCP config files live, which format your client expects, or which setup command belongs in which directory. Do not hand that work back to them.

Your job is to configure StateLode, verify that the connection works, and then use the claim-first workflow. The human signs in and approves OAuth in the browser, and restarts the current client only when you cannot safely do that from inside the running session.

Step 0: identify the client AND the surface

Do this before you read anything else on this page, and before you touch a single file.

1. Which client: Cursor, Claude Code, Codex, OpenCode, Windsurf, or Antigravity.
2. Which surface: a terminal CLI, or a desktop app.

State both back to the human in one line before changing anything. If the environment does not make it obvious, ask. Do not guess and do not silently assume the CLI — a human who is told “I’ll set up the CLI” when they are sitting in a desktop app will either be confused or follow steps that cannot work.

Why the surface matters, concretely:

Client	Does the surface change the setup?
Claude Code	No. The CLI and the desktop app share ~/.claude.json and one OS credential store. Configure and sign in once; both surfaces get it. Say this out loud rather than leaving the human wondering whether to repeat it.
Codex	Yes — completely. The desktop app uses the hosted HTTP endpoint with OAuth. The CLI is stdio-only and needs the bridge. Getting this wrong means writing a config the client cannot use.
Cursor, OpenCode, Windsurf, Antigravity	No meaningful split today; one config path each.

Beware a third kind of surface: a chat app that merely shares a brand name with a coding client, such as the Claude app / claude.ai versus Claude Code. Those are different products with different, account-level connector systems. See the rule below.

Never send a human to a connector UI for a locally-added server

When you add StateLode by writing a local config file or running a client CLI command, the server exists on that machine. It will not appear in any account-level “Connectors” or “MCP” settings screen, because those lists are populated by the vendor’s server-side integrations, not by your local config.

So: do not tell the human to “open Settings → Connectors and find statelode, then connect”. For a locally-added server there is nothing there to find, no error explaining the absence, and the human is simply stuck. This has happened in real setups.

Authenticate with the client’s own command instead. For Claude Code that is:

claude mcp login statelode

Only direct a human to a connector UI when you deliberately configured that account-level connector yourself.

Before you edit anything

1. Complete Step 0 above: client and surface are known and stated.
2. Prefer OAuth. Do not ask the human to paste a statelode_live_... token into chat.
3. Configure StateLode at global or user scope so it is available in every repo on this machine.
4. After MCP connects, run npx statelode-bridge setup once per machine. This installs agent rule files only — it is not the MCP connection. Never reach for the stdio bridge as the transport when your client speaks HTTP natively.
5. In this repo, run npx statelode-bridge init <project-slug> once to pin the repo to a StateLode project.

If you do not know the project slug, connect first and read statelode://workspace. Match the repo’s existing pin, Git remote, package metadata, and folder identity to an existing project. If no project matches, derive a stable slug from the repository, create that project deliberately with the first real setup task, and pin the repo. Ask the human only when the identity is genuinely ambiguous or project creation is denied.

Human-only steps

• Sign in to StateLode in the browser.
• Approve the OAuth request when the MCP client opens the browser.
• Choose the workspace if the OAuth screen asks.
• Restart or reload the current client only when you cannot safely do it yourself; give one exact action and wait for the human to return with “continue setup”.
• Paste a static token only if they explicitly chose the headless, CI, or legacy-bridge fallback.

Everything else is agent work.

Agent steps

• Identify the client and its surface, state both to the human, and ask when it is not obvious.
• Inspect the effective config, then preserve and merge the correct global/user MCP entry.
• Add the StateLode server with OAuth as the default authentication path.
• Trigger OAuth and clearly hand off only the browser consent step.
• Restart or reload the MCP client when required; after a human restart, continue setup rather than declaring success from the config write alone.
• Run npx statelode-bridge setup once per machine — agent rule files only, not the transport.
• Read statelode://workspace, resolve or deliberately create the current repo’s project, and run npx statelode-bridge init <project-slug> when its pin is missing or stale.
• Verify with task_search against the pinned project.
• Confirm the dashboard shows the connection or latest activity.

MCP endpoint

Use the hosted Streamable HTTP endpoint:

https://api.statelode.dev/mcp

OAuth config should not include an Authorization header. The client should discover the protected-resource metadata, open the browser, and store the OAuth credential itself.

Client configs

Cursor

Open or create the global config:

~/.cursor/mcp.json

Use this OAuth config:

{
  "mcpServers": {
    "statelode": {
      "url": "https://api.statelode.dev/mcp"
    }
  }
}

Then open Cursor settings for Tools & MCP, choose the StateLode login/connect action, and let the human approve the browser flow.

Claude Code

This section covers both the claude CLI and the Claude Code desktop app. They share ~/.claude.json and one credential store, so you configure and authenticate once and both surfaces get it. Do not repeat setup per surface. (Connectors in the separate Claude app / claude.ai are account-level and out of scope here.)

Prefer the CLI because it writes the user-scoped config correctly:

claude mcp add --scope user --transport http statelode https://api.statelode.dev/mcp

That command only writes the server entry — it does not authenticate. Run the sign-in yourself; it is a plain command, not an interactive dialog, so this is your job, not the human’s:

claude mcp login statelode

The human’s only part is browser consent. Then verify:

claude mcp list

statelode must read ✔ Connected. Do not treat the mcp add write as completion — a server entry with no credential reports “Needs authentication” forever, and restarting does not fix it. If the desktop app was already running, ask the human to restart it and return with “continue setup”.

Use /mcp → Authenticate only as a fallback in an interactive terminal session; you cannot drive that picker yourself, and it is unreachable from the desktop app. Do not add --header unless the human explicitly chooses the static-token fallback.

Never tell the human to find statelode in the Claude app’s MCP or Connectors settings. A server added with claude mcp add is local and does not appear there; that screen lists only account-level claude.ai connectors. Run claude mcp login statelode instead.

Codex

Confirm the surface before writing anything — this is the one client where it changes everything. The desktop app speaks HTTP and does OAuth; the CLI is stdio-only and needs the bridge. A config written for the wrong surface simply will not load.

For the Codex desktop app, use the custom MCP UI with Streamable HTTP:

https://api.statelode.dev/mcp

For the Codex CLI, MCP config is stdio-only today. Open or create:

~/.codex/config.toml

If the human explicitly chooses the static-token bridge fallback, add:

[mcp_servers.statelode]
command = "npx"
args = ["statelode-bridge", "--token", "paste-token-here"]

Do not ask the human to paste that token into chat. Ask them to paste it directly into the config file or use the desktop app OAuth path instead.

OpenCode

Open the global config:

~/.config/opencode/opencode.json

Use this OAuth config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "statelode": {
      "type": "remote",
      "url": "https://api.statelode.dev/mcp",
      "enabled": true,
      "oauth": {}
    }
  }
}

Then run:

opencode mcp auth statelode

After the human finishes browser consent, completely exit and restart OpenCode. The running OpenCode process does not reliably discover a newly written global MCP entry. If restarting would terminate this conversation, tell the human exactly how to restart, ask them to return with “continue setup”, and resume with:

opencode mcp list

Do not treat a successful config edit or OAuth callback as completion; statelode must appear in the resolved server list after restart.

Windsurf

Open or create:

~/.codeium/windsurf/mcp_config.json

Use serverUrl, not url:

{
  "mcpServers": {
    "statelode": {
      "serverUrl": "https://api.statelode.dev/mcp"
    }
  }
}

Fully quit and reopen Windsurf, then let the human approve the sign-in from the MCP panel.

Antigravity

Open or create:

~/.gemini/config/mcp_config.json

Use serverUrl, not url:

{
  "mcpServers": {
    "statelode": {
      "serverUrl": "https://api.statelode.dev/mcp"
    }
  }
}

Refresh the MCP store and let the human approve the sign-in.

Machine setup

After the MCP server is configured, run this once on the machine:

npx statelode-bridge setup

This installs StateLode’s global agent workflow rules where supported. It does not require a token and it does not pin a repo to a project.

Repo setup

From the repo root, run:

npx statelode-bridge init <project-slug>

This writes the project pin and agent instructions into the repo. It is safe to run yourself after the human confirms the slug. If no slug was provided and the folder name is generic, ask before running it.

Verify

1. Restart or reload the MCP client if required, then confirm statelode is loaded.
2. Read statelode://workspace and inspect this repo’s statelode.json and agent guide files.
3. Call task_search with the pinned projectId.
4. If task_search reports an unknown project, use the known project list in the error. When this is a genuinely new repo, deliberately create the derived project with its first real setup task, then rerun init with that slug; never create a project from a typo.
5. Confirm the StateLode dashboard shows the connection or activity.

After connect

Use StateLode as the task source of truth:

• Read statelode://workspace first to learn the accountable human Supervisor, inherited advisory responsibility role, scope-derived capabilities, member directory, and valid projects.
• Start with task_search.
• Use task_get before mutation so you have the latest updatedAt.
• Use the responsibility role as collaboration guidance: Team leads coordinate, Contributors implement and collaborate, and Observers primarily monitor and advise.
• Do not treat responsibility as a permission boundary. Workspace membership and credential scopes determine which tasks and mutations are available.
• On STALE_WRITE, use the fresh task in the error payload and retry with its updatedAt.

Do not add tools. StateLode exposes three MCP tools: task_search, task_get, and task_mutate.