The statelode-bridge CLI

statelode-bridge is StateLode’s small command-line helper. It does three jobs, and modern interactive clients only need the first two; they connect directly to remote HTTP MCP with OAuth:

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:
Terminal window
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> --workspace <workspace-id>

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>", "workspaceId": "<id>", "endpoint": "…" }. The field is named projectId so it reads exactly like the argument agents pass to the tools. The optional workspaceId is an explicit repository choice and takes precedence over the connection default. (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 credential is required to run init — it only writes local files. For the full model of how the slug, workspace access, and IDE install scope fit together, see Workspaces, projects & tokens.

Putting it together

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