statelode-bridge

statelode-bridge installs StateLode's agent workflow rules and repository pins. Its transport mode lets older or genuinely stdio-only MCP runtimes reach StateLode's hosted Streamable HTTP endpoint.

Interactive clients that support remote HTTP MCP — including current Claude Code, Codex, Cursor, OpenCode, Windsurf, and Antigravity releases — should connect directly with OAuth. They do not need the bridge transport or a static token.

For a headless or stdio-only compatibility runtime, keep the machine credential in the environment rather than in command arguments or checked-in config:

STATELODE_TOKEN=statelode_live_... npx statelode-bridge

The bridge forwards newline-delimited JSON-RPC from stdio to POST /mcp, keeps the Mcp-Session-Id header in sync, and relays GET /mcp server-sent events back to stdio as JSON-RPC notifications.

Teaching agents to use StateLode

Different IDEs auto-load different instruction files, so the bridge writes the StateLode rules where each agent will actually see them. There are two commands.

setup — once per machine

npx statelode-bridge setup        # add --dry-run to preview

Installs a global StateLode protocol into each installed IDE's global instruction file — ~/.claude/CLAUDE.md (Claude Code), ~/.codex/AGENTS.md (Codex), ~/.codeium/windsurf/memories/global_rules.md (Windsurf) — and prints a block to paste into the IDEs that keep global rules in app settings (Cursor → User Rules; VS Code → Copilot instructions). It only touches IDEs that are installed, and upserts a delimited block so it never clobbers your existing rules.

After setup, any agent:

• uses a repo's StateLode project when the repo has a statelode.json, and
• offers to set one up (with your permission) when it doesn't — so you don't have to initialize every project up front.

init — pin one repo to a project

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

Writes statelode.json (the marker that maps this repo to a StateLode project) and a ## StateLode block into every IDE's repo guide file so the project is in context even without the global setup:

--workspace is recommended for users with more than one accessible workspace. It records the explicit repository workspace in statelode.json, so agents use it before the OAuth connection default. To switch an existing pin, rerun with the new id and --force.

| File | IDE | | --- | --- | | AGENTS.md | Codex, Cursor | | CLAUDE.md | Claude Code | | .github/copilot-instructions.md | VS Code (Copilot) | | .cursor/rules/statelode.mdc | Cursor (project rule, alwaysApply) |

Re-running is the refresh path: npx statelode-bridge@latest init rewrites every guide block with the latest rules (we add agent hints over time) and keeps this repo's existing pin — no need to pass the slug again. Use @latest so npx doesn't serve a cached older bridge. For the global block, re-run setup the same way. --no-agents writes only the marker.

Static credentials are for headless/CI and compatibility runtimes only. Keep one in STATELODE_TOKEN or a secret store — never in statelode.json, guide files, command arguments, or chat.