Workspaces, projects & tokens

Three different things get called “scope” when you connect StateLode. They’re independent, and mixing them up is the usual source of confusion. Here’s the whole model on one page.

The three layers

Layer	Set where	Controls
IDE install scope	Your IDE’s MCP config (global vs project)	Which IDE windows have the StateLode tools available
Workspace	Your OAuth grant or static token	Which organizations’ data you can touch — the auth boundary
Project	A projectId argument on each tool call	Which board inside that workspace gets read or written

These don’t depend on each other. A single global OAuth connection can grant several workspaces, but every tool call still selects exactly one authorized workspace and opens one RLS-scoped transaction.

One connection, explicit workspace selection

OAuth consent can grant one or more accessible workspaces and records the default you choose. Project creation uses an explicit workspace named by you first, then the repository pin, then that default. If a legacy connection grants several workspaces without a reliable default, the agent must ask; StateLode rejects silent guesses. A static token remains scoped to one workspace.

Install it once at global / user scope in your IDE (the default we recommend) and it’s available in every repo you open.

How the agent knows which project

task_search, task_get, and task_mutate each take a projectId — a short, readable project slug like statelode. The agent supplies it per call. It learns the slug one of two ways:

1. You tell it — “work on tasks in project statelode”, or
2. It reads it from the repo — which is what you should set up once, below.

If nothing tells the agent the slug, it guesses from your prompt or directory name and can guess wrong. Pin it explicitly.

A wrong guess is harmless, though: reading never creates anything. A task_search against a projectId that doesn’t exist returns an unknown_project error listing the workspace’s real slugs (knownProjects), so the agent picks a valid one on its next call. A project comes into existence only deliberately — created in the dashboard, or auto-created by the first task_mutate create (the project’s first task) against a new valid slug, which is exactly what pinning with statelode init <slug> and starting work produces. When a write does mint a project, its result carries projectCreated: true so the agent knows.

Pin a repo to a project

This uses the statelode-bridge command (Node.js required — see The statelode-bridge CLI). Run this once in the repo root:

npx statelode-bridge init <your-project-slug> --workspace <workspace-id>

(Omit the slug to derive it from the directory name.) It writes two files, both safe to commit and safe to re-run:

• statelode.json — a machine-readable marker: { "projectId": "<slug>", "workspaceId": "<id>", "endpoint": "…" }. Tooling reads this to resolve the workspace and project deterministically.
• An ## StateLode block in AGENTS.md — the file every modern coding agent (Cursor, Claude Code, Codex, Windsurf, Antigravity) already reads at startup. The block names the project slug and the task rules, so the agent scopes task_search correctly without you repeating yourself.

<!-- statelode:start -->
## StateLode

This repository's tasks live in the StateLode project `your-project-slug`.

- Before starting work, call `task_search` with `projectId: "your-project-slug"`.
- Use `task_get` for a task's full body; use `task_mutate` to claim or update it.
- Move a task: `in_progress` → `review` → `done`.
- On a `STALE_WRITE`, re-read the task and retry with the fresh `updatedAt`.
<!-- statelode:end -->

The block is delimited by those comment markers, so re-running init after a rename replaces only that section and leaves the rest of your AGENTS.md untouched. Edit the rules inside it freely — they’re yours.

The token is the one thing that must not go in either file. Keep it in your environment as STATELODE_TOKEN or your client’s secret store — see Token security.

Putting it together

1. Connect StateLode with OAuth at global scope in your IDE and select the workspaces it may access.
2. Run npx statelode-bridge setup once per machine so every IDE knows the StateLode workflow (and offers to pin un-tracked repos for you). See The statelode-bridge CLI.
3. In each repo, run npx statelode-bridge init <slug> --workspace <workspace-id> once.
4. Open any repo and ask your agent to start work — it reads AGENTS.md, finds the slug, and calls task_search against the right project automatically.