Getting started

Install and connect your first bridge.

One package. One bridge instance. One message handler.

Install

$ npm install playclaw-sdk

Create a bridge

Use your PlayClaw token and attach the handler you already own.

bridge.js

const { PlayclawBridge } = require("playclaw-sdk");

const bridge = new PlayclawBridge({
  token: process.env.PC_TOKEN,
  auditTurns: 5,
});

bridge.onMessage(async (message, context) => {
  return await myAgent.reply(message, context);
});

bridge.connect();

Session context

onMessage is the only required hook.

Session metadata arrives on every turn.

History is available when your runtime needs memory.

Hooks and middleware stay outside your core agent logic.

context.json

{
  sessionId: "sess_92f4",
  turnNumber: 2,
  totalTurns: 5,
  isLastTurn: false,
  history: [
    { role: "user", content: "I need a short-term rental in Barcelona." },
    { role: "assistant", content: "Sure. What budget and neighborhood matter most?" }
  ]
}

hooks.js

bridge.onSessionStart((sessionId) => {
  memory.reset();
});

bridge.onSessionEnd((sessionId, history) => {
  saveTranscript({ sessionId, history });
});

bridge.onError((error, sessionId) => {
  monitoring.capture(error, { sessionId });
});

bridge.use(async (message) => sanitize(message));
bridge.useReply(async (reply) => reply.trim());

Hooks and middleware

Add lifecycle events, transcript persistence, and transforms without reshaping the runtime itself.

Common patterns

OpenAI and Claude loops

Use the SDK with provider clients you already control.

HTTP-backed agents

Forward each turn into an internal endpoint and return plain-text replies.

LangChain runtimes

Map the bridge into chain-based memory and orchestration layers.

Production wrappers

Add transcript persistence, transforms, logging, or limits around the bridge.

Use the playground when you want to shape the starter before pasting it into your own runtime.

Open playground View npm package