### Setup Project Dependencies

Source: https://github.com/electric-sql/electric/blob/main/examples/burn/README.md

Install and configure the project dependencies within the example directory.

```sh
cd examples/burn
mix setup
```

--------------------------------

### Install and Run Web App

Source: https://github.com/electric-sql/electric/blob/main/examples/agents-walkthrough/README.md

Install dependencies and start the development server for the web application.

```sh
pnpm install
pnpm dev
```

--------------------------------

### Install Go Client

Source: https://github.com/electric-sql/electric/blob/main/website/docs/streams/clients/other.md

Install the Go client library for Durable Streams using go get.

```bash
go get github.com/durable-streams/durable-streams/packages/client-go
```

--------------------------------

### Configure and Run Agents Playground

Source: https://github.com/electric-sql/electric/blob/main/examples/agents-playground/README.md

Navigate to the playground directory, copy the environment example, add your Anthropic API key, install dependencies, and start the development server.

```bash
cd examples/agents-playground
cp .env.example .env            # add your ANTHROPIC_API_KEY
pnpm install
pnpm dev
```

--------------------------------

### Start Dev Server

Source: https://github.com/electric-sql/electric/blob/main/examples/yjs/README.md

Initiate the development server for the Yjs example.

```shell
pnpm dev:server
```

--------------------------------

### Start Electric Agents Components Independently

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/quickstart.md

Manually start the runtime server and the built-in agents if you need more control than the 'quickstart' command provides.

```sh
npx electric-ax agents start          # runtime server + UI (background, Docker)
npx electric-ax agents start-builtin  # built-in Horton and worker (foreground)
```

--------------------------------

### Start Client App

Source: https://github.com/electric-sql/electric/blob/main/examples/yjs/README.md

Run the command to start the client application for the Yjs example.

```shell
pnpm dev:client
```

--------------------------------

### Run Example - Entity and UI Servers

Source: https://github.com/electric-sql/electric/blob/main/examples/deep-survey/README.md

Start the entity server and the Vite UI dev server in separate terminals to run the example. The UI will be available at http://localhost:5175.

```bash
# Terminal 1 — entity server (registers the orchestrator with the agents server)
pnpm run dev:server
```

```bash
# Terminal 2 — Vite UI dev server
pnpm run dev:ui
```

--------------------------------

### Start Electric Agents Quickstart

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/quickstart.md

Initiates the Electric Agents runtime, Postgres, Electric, and the built-in Horton assistant. The runtime server is accessible at http://localhost:4437.

```sh
npx electric-ax agents quickstart
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/electric-sql/electric/blob/main/examples/tanstack/README.md

Return to the specific example directory after building the workspace.

```shell
cd examples/tanstack
```

--------------------------------

### Set Up Shell Completions

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/reference/cli.md

Configures shell completions for the Electric CLI. Without arguments, it shows setup instructions. Use `install` to auto-install.

```bash
electric agents completion            # Show setup instructions
```

```bash
electric agents completion install    # Auto-install into your shell init file
```

--------------------------------

### Install Dependencies and Run Backend

Source: https://github.com/electric-sql/electric/blob/main/examples/tanstack-db-web-starter/AGENTS.md

Commands to install project dependencies, start the backend services using Docker Compose, apply database migrations, and run the development server.

```sh
pnpm install    # install deps
pnpm backend:up # run backend services using docker compose
pnpm migrate    # apply migrations
pnpm dev        # run dev server
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/electric-sql/electric/blob/main/examples/todo-app/README.md

Return to the specific directory for the Todo app example.

```shell
cd examples/todo-app
```

--------------------------------

### Quick Start: Initialize YjsProvider

Source: https://github.com/electric-sql/electric/blob/main/website/docs/streams/integrations/yjs.md

Initialize the YjsProvider to sync a Yjs document. This example shows basic setup with a document, awareness, and server URL. The provider connects automatically and handles snapshot discovery and live updates.

```typescript
import { YjsProvider } from "@durable-streams/y-durable-streams"
import * as Y from "yjs"
import { Awareness } from "y-protocols/awareness"

const doc = new Y.Doc()
const awareness = new Awareness(doc)

const provider = new YjsProvider({
  doc,
  baseUrl: "http://localhost:4438/v1/yjs/my-service",
  docId: "my-document",
  awareness,
})

provider.on("synced", (synced) => {
  console.log("Synced:", synced)
})
```

--------------------------------

### Configure and Run the Chat Application

Source: https://github.com/electric-sql/electric/blob/main/examples/agents-chat-starter/README.md

After starting the infrastructure, copy the environment file, install dependencies, and run the development server. Ensure your Anthropic API key is added to the .env file.

```bash
cp .env.example .env            # add your ANTHROPIC_API_KEY
pnpm install && pnpm dev        # open http://localhost:5175
```

--------------------------------

### Start Backend Services with Docker Compose

Source: https://github.com/electric-sql/electric/blob/main/examples/encryption/README.md

Starts the backend services for the encryption example using Docker Compose. Ensure Docker is running.

```shell
pnpm backend:up
```

--------------------------------

### Configure and Run Playground

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/examples/playground.md

Navigate to the playground directory, copy the environment configuration, install dependencies, and start the development server. The app server runs on port 3000.

```bash
cd examples/agents-playground
cp .env.example .env
pnpm install
pnpm dev
```

--------------------------------

### Start Postgres and Electric with Docker

Source: https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-04-09-building-ai-apps-on-sync.md

Start the Postgres and Electric services using Docker Compose. This command assumes Docker is installed and configured.

```sh
docker compose up -d
```

--------------------------------

### Electric Agents Development Quick Start

Source: https://github.com/electric-sql/electric/blob/main/AGENTS.md

Provides shell commands for building and starting the Electric Agents development environment, including Docker setup and process management. Assumes necessary API keys are set in .env.

```sh
./scripts/dev.sh build       # install + build typescript-client, agents-runtime,
                             # agents-mcp, agents-server, agents
./scripts/dev.sh start       # docker + 5 dev processes; Ctrl-C stops everything
./scripts/dev.sh start --with-agents   # also spawn built-in agents (Horton + Worker)
./scripts/dev.sh desktop     # run the Electron desktop app (in a separate terminal,
                             # against an already-running stack)
./scripts/dev.sh stop        # stop processes + docker compose down
./scripts/dev.sh teardown    # also remove Postgres volume + .streams-data/
```

--------------------------------

### Install the experimental client

Source: https://github.com/electric-sql/electric/blob/main/packages/experimental/README.md

Install the package via NPM.

```sh
npm i @electric-sql/experimental
```

--------------------------------

### Start Docker Desktop

Source: https://github.com/electric-sql/electric/blob/main/AGENTS.md

Ensure Docker Desktop is running before proceeding with the integration test setup.

```sh
open -a Docker   # macOS
```

--------------------------------

### Quick Start: Create and Run an Assistant Entity

Source: https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/README.md

This example demonstrates setting up a simple durable chat assistant entity. It initializes the status state, configures an agent, and sets up an HTTP server to handle webhook requests for the runtime.

```typescript
import http from 'node:http'
import { z } from 'zod'
import { createRuntimeHandler, defineEntity } from '@electric-ax/agents-runtime'

defineEntity(`assistant`, {
  description: `Simple durable chat assistant`,

  state: {
    status: {
      schema: z.object({
        key: z.string(),
        value: z.enum([`idle`, `working`]),
      }),
      type: `status`,
      primaryKey: `key`,
    },
  },

  async handler(ctx) {
    if (!ctx.db.collections.status.get(`current`)) {
      ctx.db.actions.status_insert({
        row: { key: `current`, value: `idle` },
      })
    }

    ctx.useAgent({
      systemPrompt: `You are a helpful assistant.`,
      model: `claude-sonnet-4-5-20250929`,
      tools: [...ctx.electricTools],
    })

    await ctx.agent.run()
  },
})

const runtime = createRuntimeHandler({
  baseUrl: `http://127.0.0.1:4437`,
  serveEndpoint: `http://127.0.0.1:3000/webhook`,
})

await runtime.registerTypes()

const server = http.createServer(async (req, res) => {
  if (req.url === `/webhook` && req.method === `POST`) {
    await runtime.onEnter(req, res)
    return
  }

  res.writeHead(404)
  res.end()
})

server.listen(3000, `127.0.0.1`)

```

--------------------------------

### Run Hono Dev Server

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/walkthrough.md

Navigates into the created Hono project directory and starts the development server. This is used to verify the initial app setup.

```bash
cd walkthrough
pnpm dev
```

--------------------------------

### Start the backend sync service

Source: https://github.com/electric-sql/electric/blob/main/packages/experimental/README.md

Prepare and start the sync service in the backend directory.

```shell
cd ../sync-service
mix deps.get
mix stop_dev && mix compile && mix start_dev && ies -S mix
```

--------------------------------

### Navigate to Redis Example Directory

Source: https://github.com/electric-sql/electric/blob/main/examples/redis/README.md

Change directory to the specific Redis example folder.

```shell
cd examples/redis
```

--------------------------------

### Install durable-streams

Source: https://github.com/electric-sql/electric/blob/main/website/docs/streams/clients/python.md

Install the library using pip or uv.

```bash
pip install durable-streams
```

```bash
uv add durable-streams
```

--------------------------------

### Install Dependencies

Source: https://github.com/electric-sql/electric/blob/main/examples/tanstack-db-expo-starter/README.md

Command to install all required project dependencies.

```bash
pnpm i
```

--------------------------------

### Install PHP Client

Source: https://github.com/electric-sql/electric/blob/main/website/docs/streams/clients/other.md

Install the Durable Streams PHP client using Composer.

```bash
composer require durable-streams/client
```

--------------------------------

### Server Health Check Endpoint

Source: https://github.com/electric-sql/electric/blob/main/packages/agents-mobile/PLAN.md

Example of the HTTP GET request used to validate the agents server URL during the first-run setup.

```http
GET /_electric/health
```

--------------------------------

### Initialize Project

Source: https://github.com/electric-sql/electric/blob/main/examples/tanstack-db-expo-starter/README.md

Commands to scaffold a new project from the official starter template.

```bash
npx gitpick electric-sql/electric/tree/main/examples/tanstack-db-expo-starter my-tanstack-db-expo-project
cd my-tanstack-db-expo-project
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/electric-sql/electric/blob/main/examples/proxy-auth/README.md

Change the current working directory to the proxy-auth example folder.

```shell
cd examples/proxy-auth
```

--------------------------------

### Basic Agent Setup and Execution

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/usage/configuring-the-agent.md

Demonstrates how to initialize an agent with a system prompt, model, and tools, and then execute it. Ensure `ctx.useAgent` is called before `ctx.agent.run`.

```typescript
async handler(ctx) {
  ctx.useAgent({
    systemPrompt: 'You are a helpful assistant.',
    model: 'claude-sonnet-4-5-20250929',
    tools: [...ctx.electricTools],
  })
  await ctx.agent.run()
}
```

--------------------------------

### Start Caddy Server

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/walkthrough.md

Command to start the Caddy server in the background. Ensure Caddy is installed and trusted first.

```sh
caddy start
```

--------------------------------

### Build the package

Source: https://github.com/electric-sql/electric/blob/main/packages/experimental/README.md

Navigate to the client directory and build the package.

```shell
cd packages/typescript-client
pnpm build
```

--------------------------------

### Live Request Example

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/guides/client-development.md

Example of a GET request to the Electric API in live mode. Ensure your request timeout exceeds the server timeout.

```http
GET /v1/shape?table=items&handle=38083685-1729874417404&offset=27344208_0&cursor=1674440&live=true
```

--------------------------------

### Navigate to React Example Directory

Source: https://github.com/electric-sql/electric/blob/main/examples/react/README.md

Change the current directory to the React example folder.

```shell
cd examples/react
```

--------------------------------

### Get ShapeStream with Production API Proxy

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/integrations/react.md

Use getShapeStream to get or create a ShapeStream from the global cache. This example shows the production pattern using an API proxy.

```tsx
const itemsStream = getShapeStream<Item>({
  url: `http://localhost:3001/api/items`,
})
```

--------------------------------

### Start Development Servers

Source: https://github.com/electric-sql/electric/blob/main/examples/tanstack-db-expo-starter/README.md

Commands to launch the development and API servers.

```bash
pnpm start
```

```bash
pnpm api
```

--------------------------------

### Start Development Postgres Database

Source: https://github.com/electric-sql/electric/blob/main/README.md

Start a Docker Compose setup for the development Postgres database, configured for logical replication. This is a prerequisite for running sync service tests.

```sh
cd packages/sync-service
mix start_dev
```

--------------------------------

### Start Infrastructure with Electric Agents CLI

Source: https://github.com/electric-sql/electric/blob/main/examples/agents-playground/README.md

Use the `electric-ax agents start` command to initiate the necessary infrastructure, including Postgres, Electric, and the Agent Server.

```bash
npx electric-ax agents start
```

--------------------------------

### Complete CLI Workflow Example

Source: https://github.com/electric-sql/electric/blob/main/website/docs/streams/cli.md

Demonstrates a full session using the CLI to create, write to, read from, and delete a JSON stream. Assumes a server is running on localhost:4437.

```bash
export STREAM_URL=http://localhost:4437/v1/stream

# Create a JSON stream
durable-stream create chat --json

# In another terminal, start following the stream
durable-stream read chat

# Back in the first terminal, write messages
durable-stream write chat '{"user": "alice", "text": "Hello!"}' --json
durable-stream write chat '{"user": "bob", "text": "Hi there!"}' --json

# Pipe data in
echo '{"user": "alice", "text": "How are you?"}' | durable-stream write chat --json

# Clean up
durable-stream delete chat
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/electric-sql/electric/blob/main/README.md

Install project dependencies using asdf for toolchain management and pnpm for Node.js packages. This step is required before running tests or starting development services.

```sh
asdf install
pnpm install
```

--------------------------------

### Manage Backend Services

Source: https://github.com/electric-sql/electric/blob/main/examples/proxy-auth/README.md

Commands to start or stop the Docker Compose backend services for the example.

```shell
pnpm backend:up
```

```shell
pnpm backend:down
```

--------------------------------

### Get Shape with Production API Proxy

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/integrations/react.md

Use getShape to get or create a Shape from the global cache. This example demonstrates the production pattern using an API proxy, helping to avoid materializing multiple shapes for the same stream.

```tsx
const itemsShape = getShape<Item>({
  url: `http://localhost:3001/api/items`,
})
```

--------------------------------

### TanStack DB Web Starter Example

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/stacks.md

This example demonstrates an end-to-end TypeScript stack for web development using TanStack DB, Electric, Drizzle, TanStack Start, and tRPC. It's suitable for building reactive, local-first client-side applications.

```typescript
import { defineConfig } from "@tanstack/start/router";

export default defineConfig({
  // ...
});

```

--------------------------------

### Quickstart Electric Agents with Anthropic API Key

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/reference/cli.md

Initiates the coordinator server, displays onboarding commands, and runs the built-in agents runtime. An Anthropic API key is required for the built-in Horton server.

```bash
electric agents quickstart --anthropic-api-key sk-ant-...
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/electric-sql/electric/blob/main/examples/linearlite-read-only/README.md

Return to the specific directory for the Linearlite Read Only example after completing the monorepo-wide build.

```shell
cd examples/linearlite-read-only
```

--------------------------------

### Construct Shape URL

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/guides/client-development.md

Encode a shape definition into a GET /v1/shape URL. This example shows how to request all rows from the 'items' table.

```http
GET /v1/shape?table=items
```

--------------------------------

### Start ElectricSQL with Postgres

Source: https://github.com/electric-sql/electric/blob/main/website/blog/posts/2024-01-24-electricsql-v0.9-released.md

Launch the Electric service with an integrated Postgres database.

```sh
npx electric-sql start --with-postgres
```

--------------------------------

### Monorepo Development Setup

Source: https://github.com/electric-sql/electric/blob/main/packages/start/README.md

Commands to install dependencies and build packages within the Electric monorepo. Useful for developers working on the package itself.

```bash
# From the monorepo root
pnpm install   # Install all workspace dependencies
pnpm build     # Build all packages
```

```bash
# From packages/quickstart
pnpm build     # Compile TypeScript
pnpm dev       # Build and test locally
```

--------------------------------

### Start Electric App with CLI

Source: https://github.com/electric-sql/electric/blob/main/AGENTS.md

Initialize and deploy an Electric Cloud application using the ElectricSQL CLI.

```sh
npx @electric-sql/start my-app
pnpm claim && pnpm deploy
```

--------------------------------

### Start Backing Services

Source: https://github.com/electric-sql/electric/blob/main/docs/agents-development.md

Use this command to start the necessary backing services like Postgres, Electric, and Jaeger for development.

```sh
docker compose -f packages/agents-server/docker-compose.dev.yml up -d
```

--------------------------------

### Setup Project Dependencies

Source: https://github.com/electric-sql/electric/blob/main/examples/gatekeeper-auth/api/README.md

Installs and sets up project dependencies using the Mix build tool. This is a standard first step for Elixir projects.

```shell
mix setup
```

--------------------------------

### Watch a Stream Live with SSE

Source: https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-12-23-durable-streams-0.1.0.md

Connect to a stream using Server-Sent Events (SSE) to receive real-time updates. Start with offset -1 to get all messages.

```bash
curl -N http://localhost:4437/v1/stream/my-first-stream?offset=-1&live=sse
```

--------------------------------

### Create Python Project Structure

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/guides/client-development.md

Set up a new directory and initialize it as a Python package. This is the first step in creating a client application.

```shell
mkdir example-client
cd example-client
touch __init__.py
```

--------------------------------

### Python Test Client Setup

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/guides/client-development.md

Sets up a test file for running the client. Imports necessary modules and initializes the Shape client for testing purposes.

```python
import multiprocessing
import unittest

from client import Shape

class TestClient(unittest.TestCase):
    def test_shape_sync(self):
        parent_conn, child_conn = multiprocessing.Pipe()

        shape = Shape(table='items')
```

--------------------------------

### Run Built-in Agents Entrypoint

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/usage/embedded-builtins.md

Use `runBuiltinAgentsEntrypoint()` for a simplified setup that reads environment variables, creates a `BuiltinAgentsServer`, and starts it. This is the default behavior for the `electric-agents` package binary.

```typescript
import {
  resolveBuiltinAgentsEntrypointOptions,
  runBuiltinAgentsEntrypoint,
} from "@electric-ax/agents"

const options = resolveBuiltinAgentsEntrypointOptions(process.env)
const { server, url } = await runBuiltinAgentsEntrypoint()

console.log(options.agentServerUrl, url)
await server.stop()
```

--------------------------------

### Run Electric with Docker Compose

Source: https://github.com/electric-sql/electric/blob/main/README.md

This command starts the Electric SQL service using Docker Compose. Ensure you have Docker installed and the docker-compose.yml file present in the current directory.

```sh
docker compose -f .support/docker-compose.yml up
```

--------------------------------

### Spawning a Worker with Tools

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/entities/agents/worker.md

Example of using the `spawn_worker` tool to create a new worker agent. Specifies the system prompt, available tools, and an initial message to start the worker.

```typescript
spawn_worker({
  systemPrompt:
    "You are a focused researcher. Find the three most-cited papers on X and return their titles, authors, and DOIs as a markdown table.",
  tools: ["brave_search", "fetch_url"],
  initialMessage: "Begin research now.",
})
```

--------------------------------

### Basic Agent Usage

Source: https://github.com/electric-sql/electric/blob/main/website/docs/agents/usage/configuring-the-agent.md

Demonstrates how to initialize an agent with a system prompt, model, and tools, and then execute it.

```APIDOC
## Basic usage

```ts
async handler(ctx) {
  ctx.useAgent({
    systemPrompt: 'You are a helpful assistant.',
    model: 'claude-sonnet-4-5-20250929',
    tools: [...ctx.electricTools],
  })
  await ctx.agent.run()
}
```

`useAgent` returns an `AgentHandle` and also sets `ctx.agent`. Both references are equivalent.
```

--------------------------------

### Cloudflare Worker Auth Example

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/integrations/cloudflare.md

Use a Cloudflare Worker to validate an Authorization token before proxying requests to Electric. This protects access to data shapes and enforces GET requests.

```typescript
export default {
  async fetch(request): Promise<Response> {
    const ELECTRIC_URL = 'https://my-electric.example.com'

    const headers = request.headers
    const authHeader = request.headers.get('Authorization')
    const isValid = (header) => {
      /* ... e.g.: verify JWT ... */
    }
    if (!isValid(authHeader)) {
      return new Response('Forbidden', { status: 403 })
    }

    if (request.method != `GET`) {
      return new Response('Method Not Allowed', { status: 405 })
    }

    const url = new URL(request.url)
    const shapeUrl = `${ELECTRIC_URL}${url.pathname}${url.search}`
    const clonedHeaders = new Headers(new Request(request).headers)

    return await fetch(shapeUrl, {
      headers: clonedHeaders,
      cf: { cacheEverything: true },
    })
  },
} satisfies ExportedHandler
```

--------------------------------

### Clone AI Chat Demo Repository

Source: https://github.com/electric-sql/electric/blob/main/website/blog/posts/2025-04-09-building-ai-apps-on-sync.md

Clone the Electric AI Chat demo repository to get started. Ensure you have Node, pnpm, Docker, and an OpenAI API key.

```sh
git clone https://github.com/electric-sql/electric-ai-chat.git
cd electric-ai-chat
```

--------------------------------

### Install Electric React client

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/llms/_quickstart_redux.md

Navigate to the React app directory and install the @electric-sql/react package.

```sh
cd react-app
npm install @electric-sql/react
```

--------------------------------

### Start Electric App (Cloud)

Source: https://github.com/electric-sql/electric/blob/main/website/docs/sync/quickstart.md

Use this command to create a new Electric app using the starter script for cloud deployment.

```shell
npx @electric-sql/start my-electric-app
```

--------------------------------

### Expo Project Setup - Phase 1

Source: https://github.com/electric-sql/electric/blob/main/packages/agents-mobile/PLAN.md

Notes on setting up the Expo project for the mobile application, including package installation and configuration checks. Ensure Expo doctor passes.

```bash
pnpm dlx expo-doctor
```