sp00ky Logo
Github|...

AI Coding Agents

Sp00ky ships first-class support for AI coding agents (Claude, Cursor, Windsurf, etc.). Drop an agent into a sp00ky-backed project and it learns the framework, your schema, and the safe edit loop without prompt engineering.

How it works

Three artifacts give an agent everything it needs:

  1. AGENTS.md — a project-rooted guide tailored to your schema. Generated by spky agents init.
  2. Per-package guides shipped inside @spooky-sync/* tarballs. Always available via node_modules/@spooky-sync/<pkg>/AGENTS.md.
  3. A devtools MCP server that exposes the running app’s live state (active queries, schema, auth) and lets the agent execute SurrealQL against it.

Agents that follow the AGENTS.md convention discover the project guide automatically. Cursor’s .cursorrules, Claude Code’s CLAUDE.md, and Aider’s repo-level rules all read it as fallback.

Generate AGENTS.md

Run once per project:

Bash 
spky agents init

This parses your .surql schema, finds every CRDT field and parent relationship, and writes an AGENTS.md at the project root with:

  • The sp00ky mental model (schema → codegen → reactive hooks → SSP → SurrealDB)
  • Your tables, marked with @crdt and @parent annotations
  • Common gotchas (record-ID format, useCrdtField vs useQuery, debounced writes)
  • The agent feedback loop (spky generate → spky doctor)
  • A list of available cookbook recipes

Re-run after schema changes to refresh the table list:

Bash 
spky agents init --force

Per-package guides

Every @spooky-sync/* package ships an AGENTS.md documenting its public API surface. Once installed, an agent can enumerate them:

Bash 
find node_modules/@spooky-sync -name AGENTS.md

You’ll find guides for core (sync engine), client-solid (useDb, useQuery, useCrdtField), query-builder (DSL), cli (spky subcommands), devtools-mcp (live introspection), and ssp-wasm (browser stream processor).

Cookbook recipes

spky scaffold emits framework-level patterns parameterized by your schema. Run with no arguments to list available recipes:

Bash 
spky scaffold list

Render a recipe to stdout:

Bash 
spky scaffold live-list --table thread
Bash 
spky scaffold optimistic-mutation --table thread
Bash 
spky scaffold crdt-text-field --table thread --field content

Or write directly to a file:

Bash 
spky scaffold live-list --table thread --out src/components/ThreadList.tsx

Agents typically pipe spky scaffold output into a file edit, then the project’s AGENTS.md tells them to run spky doctor to verify the result.

Live introspection via MCP

The devtools MCP server gives agents direct access to a running sp00ky app’s local cache, active live queries, auth state, and event history — plus it can execute SurrealQL against either the local replica or the remote DB.

Wire it into your agent’s MCP configuration:

JSON 
{
  "mcpServers": {
    "spooky-devtools": {
      "command": "npx",
      "args": ["-y", "@spooky-sync/devtools-mcp"]
    }
  }
}

The server connects to the Sp00ky DevTools browser extension (when an app tab is open) or directly to a SurrealDB instance via SURREAL_URL / SURREAL_USER / SURREAL_PASS.

Tools an agent gets

ToolWhat it does
describe_schemaStitched schema view: tables, columns, types, plus @crdt / @parent annotations when the extension is connected
lint_queryValidate SurrealQL without executing — runs EXPLAIN and reports parse errors with line/column
run_queryExecute SurrealQL against local or remote
list_tables, get_table_dataRead-only schema and data inspection
update_table_row, delete_table_rowDirect mutations (bypass the local mutation queue)
get_active_queries, get_events, get_auth_stateInspect the running tab’s live state
Note

Mutations through MCP go straight to SurrealDB and don’t enter the local queue. Use them for fixtures and debugging; for in-app behavior, drive mutations through your UI.

Generated docs in schema.gen.ts

Every regenerated schema.gen.ts carries JSDoc on each table and column. Tables list their relationships and a useQuery example; columns marked @crdt get a “use useCrdtField and { debounced: true }” hint inline; @parent columns get a “auto-populated server-side, do not write” hint.

Both your IDE’s hover-docs and an agent’s read of the file pick this up automatically. Nothing to wire up.

The feedback loop

The standard pattern an agent should follow after any schema edit:

  1. Edit schema.surql
  2. spky generate — refresh schema.gen.ts
  3. spky doctor --json — confirm nothing else drifted (codegen freshness, migration state, config validity)
  4. Make code edits using the typed schema.gen.ts
  5. Re-run spky doctor to double-check

AGENTS.md documents this loop verbatim so the agent doesn’t have to re-derive it.