The statelode-bridge CLI

statelode-bridge is StateLode’s small command-line helper. It does three jobs, and most people only need the first two:

Command	When you run it	What it does
statelode-bridge setup	Once per machine	Teaches every installed IDE how to use StateLode (a global rule).
statelode-bridge init	Once per repo	Pins the repo to a StateLode project so agents read the right board.
statelode-bridge (no subcommand)	Only for stdio-only clients	Acts as a stdio↔HTTP transport.

Connecting a modern IDE (Cursor, Claude Code, Codex, Windsurf, Antigravity) to the hosted MCP endpoint is separate — follow that agent’s install guide. setup and init are how you make the connection useful across machines and repos.

Prerequisite: Node.js

statelode-bridge runs on Node.js 20 or newer. Check what you have:

node --version

If that prints v20 or higher you’re set. If not, install Node from nodejs.org (or your version manager) first.

Get the command

You have two options — pick one:

# Option A — run it on demand, nothing installed (recommended)
npx statelode-bridge <command>

# Option B — install it globally, then call it directly
npm install -g statelode-bridge
statelode-bridge <command>

npx downloads and runs the latest published version each time, so you never have a stale copy. The examples below use the npx form; drop the npx prefix if you installed globally.

If a copied command misbehaves, your document may have rewritten -- as an en-dash. Sanitize smart punctuation before running:

pbpaste | tr "–—" "--"

statelode-bridge setup

Configure every IDE once. Run this once per machine. It writes a short, conservative StateLode rule into the global instruction file of each IDE you actually have installed, so every agent treats StateLode consistently without you teaching each project from scratch:

npx statelode-bridge setup

What it touches (and only if that IDE is installed):

IDE	Where the rule goes
Claude Code	~/.claude/CLAUDE.md
Codex	~/.codex/AGENTS.md
Windsurf	~/.codeium/windsurf/memories/global_rules.md
Cursor, VS Code (Copilot)	Printed for you to paste into app settings (they keep global rules in settings, not a file)

The rule is marker-aware and ask-first by design:

• In a repo with a statelode.json, the agent uses that project automatically.
• In a repo without one, the agent never guesses or auto-creates a project. It offers, once, to pin the repo (statelode-bridge init) and only proceeds if you agree.

It’s safe to re-run — it upserts a single delimited block and never clobbers your existing rules. Preview without writing anything:

npx statelode-bridge setup --dry-run

After setup, pin individual repos with init (next).

statelode-bridge init

Pin a repo to a project. Run this once in each repo you want StateLode to manage:

npx statelode-bridge init <project-slug>

Omit the slug to derive it from the directory name (on a re-run it reuses the pin already in statelode.json). Re-running is also how you refresh: npx statelode-bridge@latest init rewrites the guide blocks with the latest agent rules and keeps the existing pin — use @latest so npx doesn’t serve a cached older bridge. It writes two things, both safe to commit and safe to re-run:

• statelode.json — a machine-readable marker { "projectId": "<slug>", "endpoint": "…" }. The field is named projectId so it reads exactly like the argument agents pass to the tools. (Older pins used project; re-running init migrates them.)
• An ## StateLode block in both AGENTS.md and CLAUDE.md — Codex and Cursor read AGENTS.md; Claude Code reads CLAUDE.md. Writing both means every agent scopes task_search to this project at session start.

No token is required to run init — it only writes local files. For the full model of how the slug, your workspace token, and IDE install scope fit together, see Workspaces, projects & tokens.

Putting it together

1. Connect your IDE to the hosted endpoint using its install guide.
2. Run npx statelode-bridge setup once per machine.
3. Run npx statelode-bridge init <slug> once per repo.
4. Open any pinned repo and ask your agent to start work — it reads the slug and calls task_search against the right project.