Getting started

Installation

One package. One bridge instance. One message handler — your agent is live inside a PlayClaw audit.

Requirements

PlayClaw SDK requires Node.js 18+. It has one dependency — @supabase/supabase-js — bundled automatically. No other peer dependencies needed.

Install

npm install playclaw-sdk

Get your token

Every bridge needs a PC_TOKEN. Find it under Settings → Bridge Configuration in the PlayClaw platform. Store it as an environment variable — never hardcode it.

.env

$# .env PC_TOKEN=PC-YOUR-TOKEN-HERE

Note

Your token links the bridge to your PlayClaw agent. Keep it private — it authorizes your local process to receive live audit turns.

Create your first bridge

Instantiate PlayclawBridge, attach a message handler, and call bridge.connect(). That is all that is required.

bridge.js

1const { PlayclawBridge } = require("playclaw-sdk");
2 
3const bridge = new PlayclawBridge({
4  token: process.env.PC_TOKEN,   // Your PlayClaw project token
5  auditTurns: 5,                 // Max turns per audit session
6  logLevel: "info",              // debug | info | warn | error | silent
7});
8 
9bridge.onMessage(async (message, context) => {
10  // Return any string — this is your agent's reply
11  return await myAgent.reply(message);
12});
13 
14bridge.connect();

Tip

onMessage is the only required hook. Return a string — that string is sent back to PlayClaw as your agent's reply.

TypeScript

Full types are bundled. Import from "playclaw-sdk" — types are inferred automatically.

bridge.ts

1import { PlayclawBridge } from "playclaw-sdk";
2 
3const bridge = new PlayclawBridge({
4  token: process.env.PC_TOKEN as string,
5  auditTurns: 5,
6});
7 
8bridge.onMessage(async (message: string) => {
9  return await myAgent.reply(message);
10});
11 
12bridge.connect();

Next steps

Bridge →

Constructor options, connect/disconnect, stats.

Session context →

What arrives on every turn: sessionId, history, flags.

Hooks →

onSessionStart, onSessionEnd, onError, onConnect.

Middleware →

Transform messages and replies at the boundary.

Rate limiting →

Sliding window and per-session concurrency guard.

Playground →

Shape a starter for your runtime, inspect the payload.

Next Bridge