Statewave IDE Companion (VS Code / Cursor)

Makes Statewave aware of your workspace, project structure, docs, run-commands, git state, and diagnostics, then lets Copilot / Cursor read that memory back through the existing Statewave MCP server.

Part of the Statewave Connectors ecosystem. Editor-independent logic lives in @statewavedev/ide-core.

Install

Published for VS Code, Cursor, and other VS Code–based editors — the extension registers the MCP server for you, so there's no mcp.json to hand-edit.

• VS Code — Install from the Visual Studio Marketplace
• Cursor · Windsurf · VSCodium — Install from Open VSX
• Any editor — open the Extensions panel and search "Statewave IDE Companion" (publisher statewavedev).

You'll still need a Statewave server for the extension to talk to — see below.

Connect your Statewave server

One command — spin up the server + admin + DB (Docker required), zero config files to write:

npx @statewavedev/connectors-cli quickstart

That starts the stack on the defaults the plugin already expects (http://localhost:8100), so the moment it's up the extension is connected — nothing else to set. Stop it later with the same command plus --down.

statewave.apiKey can stay empty for local dev. The plugin handles MCP wiring itself, so you don't need any of the CLI's other commands.

services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: statewave
      POSTGRES_PASSWORD: statewave
      POSTGRES_DB: statewave
    volumes:
      - statewave-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U statewave"]
      interval: 2s
      timeout: 5s
      retries: 10

  api:                                       # the Statewave server
    image: statewavedev/statewave:${STATEWAVE_VERSION:-latest}
    ports:
      - "${STATEWAVE_API_HOST_PORT:-8100}:8100"   # matches statewave.url default
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_DEBUG: "true"                # local dev: accepts any X-API-Key
    depends_on:
      db:
        condition: service_healthy

  admin:                                     # operator console (browse subjects/episodes/memories)
    image: statewavedev/statewave-admin:${STATEWAVE_ADMIN_VERSION:-latest}
    ports:
      - "${STATEWAVE_ADMIN_HOST_PORT:-8080}:8080"
    environment:
      STATEWAVE_API_URL: http://api:8100
      STATEWAVE_API_KEY: ${STATEWAVE_API_KEY:-dev-local-placeholder}
      ADMIN_AUTH_DISABLED: "true"            # local dev only
      NODE_ENV: production
    depends_on:
      api:
        condition: service_started

volumes:
  statewave-pgdata:

docker compose -f statewave.docker-compose.yml up -d
curl http://localhost:8100/healthz     # server health
open  http://localhost:8080            # admin console

The plugin never reads your Copilot/Cursor/Claude chat

There is no transcript access and no interception. On its own the extension observes only:

• the workspace file tree (classified, ignore-filtered)
• README / docs / ADR / RFC / decision documents (+ git history, code structure)
• declared run-commands — package.json scripts, Makefile targets, pyproject.toml script tables (the command names + lines only — never source bodies, lockfiles, or env files)
• git branch + remote (parsed from .git/, no git spawned)
• editor diagnostics (messages + locations only — never source code)
• files you save (only when you turn on statewave.autoIndex)

Conversational facts ("my favorite color is red") enter memory only because, with statewave.assistantInstructions: read-write (default), we write a no-secret rules file telling the assistant to call the public statewave_ingest_episode MCP tool when you state a durable fact. That is the model taking a visible, approvable action — not the plugin scraping chat. Set read-only (consult only) or off.

Safety model

• No ingestion on install or activation. Activation registers commands and nothing else.
• Preview-first. Every command previews episodes in the Statewave IDE Companion output channel; sending is a separate, explicit button press.
• statewave.autoIndex is off by default. It is the only switch that lets the file watcher send anything without a button press, and you turn it on yourself.
• Redaction on by default (statewave.redaction.enabled) — email / phone / API-key shapes are scrubbed before anything leaves the editor.
• Auto-wiring keeps secrets out of the repo. MCP config is written only to home-dir / editor-storage files (or in-memory for Copilot); the API key never lands in version control. Agent-instruction files carry no secrets and are meant to be committed.
• No telemetry. No phone-home. The only network call is to your configured statewave.url.

Commands

Settings

statewave.url, statewave.apiKey, statewave.subjectStrategy, statewave.subject (override), statewave.autoIndex, statewave.includeGlobs, statewave.excludeGlobs, statewave.redaction.enabled, statewave.compileAfterIngest, statewave.mcp.autoWire, statewave.mcp.clients, statewave.assistantInstructions, statewave.github.* (opt-in GitHub history connector), statewave.forge.* (opt-in GitLab / Bitbucket / Gitea / Azure DevOps / GitHub Enterprise history connector). See docs/vscode-extension.md.

Develop / package

pnpm install
pnpm --filter @statewavedev/ide-core build
pnpm --filter statewave-ide-companion build      # esbuild → dist/extension.cjs
# F5 in VS Code (Run Extension) loads it in an Extension Development Host.
# Or build a VSIX:
pnpm --filter statewave-ide-companion package
# Full release gate (build+lint+typecheck+test+package+leak-scan):
pnpm --filter statewave-ide-companion preview-release

The package is named statewave-ide-companion (a marketplace-valid id statewavedev.statewave-ide-companion) rather than a scoped npm name, because the VS Code extension manifest is its package.json and the marketplace rejects / in name. It is private and never published to npm; changesets ignore it automatically.

More

• CHANGELOG.md · PRIVACY.md · SECURITY.md · TROUBLESHOOTING.md
• Run Statewave: Diagnose for an actionable health report; Statewave: Open Project Understanding for a provenance-backed live summary.

Status

Available as a preview. See CHANGELOG.md for the per-release history.

License

Apache-2.0.