# StateLode

StateLode is a hosted, MCP-native shared task/state layer for AI coding agents.
The primary user is the LLM. Humans use the dashboard to supervise.

## Canonical URLs

- Landing: https://statelode.dev/
- Docs: https://statelode.dev/docs/
- Agent setup: https://statelode.dev/docs/agent-setup/
- Install Cursor: https://statelode.dev/docs/install/cursor/
- Install Claude Code: https://statelode.dev/docs/install/claude-code/
- Install Codex: https://statelode.dev/docs/install/codex/
- Install OpenCode: https://statelode.dev/docs/install/opencode/
- Install Windsurf: https://statelode.dev/docs/install/windsurf/
- Install Antigravity: https://statelode.dev/docs/install/antigravity/
- Bridge (stdio fallback): https://statelode.dev/docs/install/bridge/
- Workspaces, projects & tokens: https://statelode.dev/docs/concepts/projects/
- MCP tools: https://statelode.dev/docs/concepts/tools/

## Product contract

Endpoint (Streamable HTTP MCP): https://api.statelode.dev/mcp

StateLode exposes three MCP tools (no more - sprints ride on task_mutate):

- task_search: lightweight task summaries; always pass projectId. Never guess a projectId: an unknown one is never created - the unknown_project error lists the workspace's real slugs (knownProjects), so pick one of those and retry. Optional sprint filter: a sprint id, "active" (the project's active sprint), or "none" (unsprinted).
- task_get: full task body including acceptanceCriteria and updatedAt.
- task_mutate: create, update, move, comment, block, plus sprint_create, sprint_assign, sprint_activate, sprint_complete. Mutations require the last-seen updatedAt except create/comment/sprint_create. create and sprint_create are the only calls that auto-create a project: a new valid projectId slug creates the project along with the task/sprint, and the result echoes projectCreated: true.

## Workspace discovery

The server also exposes an MCP resource at statelode://workspace (application/json): the workspace this credential is bound to plus the projects it can use - { workspace: { id, name, slug }, projects: [{ slug, name }] }. Read it to discover a valid projectId instead of guessing.

## Sprints

A sprint is a named, goal-bearing group of tasks in one project, with a planned -> active -> completed lifecycle and exactly one active sprint per project. Manage them via task_mutate: sprint_create({projectId,name,goal?}); sprint_assign({id,sprintId,updatedAt}) (sprintId null removes); sprint_activate({sprintId}); sprint_complete({sprintId}). The board shows the active sprint as a priority-ordered "what's next" lane, and a returning human sees a "since you were away" digest.

## Agent install rule

Cursor, Claude Code, OpenCode, Windsurf, Antigravity connect over native HTTP MCP at https://api.statelode.dev/mcp. The default sign-in is Connect with StateLode (OAuth) - a browser consent, no token to mint, paste, or rotate; supported by Cursor, Claude Code, Codex, OpenCode, Windsurf, Antigravity. Codex uses the stdio bridge with a static token for its config-file path (OAuth is available through its desktop app UI). Use statelode-bridge only for an older or niche client that speaks stdio MCP but can't dial a remote HTTP URL.

Static tokens are for headless/CI and bridge clients. Never paste a live token into an agent's chat, and never inline one in committed config: GUI IDEs read it from a home-directory config file; terminal CLIs may reference an env var such as STATELODE_TOKEN from the shell profile.

If a human asks you to set up StateLode from zero, start with https://statelode.dev/docs/agent-setup/. Use OAuth by default; the human's only browser-only job is sign-in and approval.

Use this short, secret-free handoff prompt when the human needs to move setup into their coding agent:

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.

The agent must inspect and preserve existing config, reload or restart the client when required,
resume after the human completes OAuth, read statelode://workspace, and prepare the current
repo before declaring success. Never hand a config edit or runnable command back to the human
when the agent can perform it safely.

## Pin a repo to a project

Run "npx statelode-bridge setup" once per machine (teaches every installed IDE the StateLode workflow), then "npx statelode-bridge init <project-slug>" once per repo - it writes statelode.json plus a StateLode block in AGENTS.md, so any agent that opens the repo works the right board without guessing.