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 token	Which organization’s 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 install + a single workspace token can read and write every project in that workspace — the agent just names the project on each call.

One token covers the whole workspace

A StateLode token authenticates to a workspace, not a project. You do not need a separate token per project. One token, minted once, works for every project in the workspace and carries its own scopes (tasks:read, tasks:write) and audit trail.

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>

(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: { "project": "<slug>", "endpoint": "…" }. Tooling reads this to resolve the 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. Mint one workspace token; install StateLode at global scope in your IDE.
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> 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.