Package Exports

@ollielabs/grid-agent
@ollielabs/grid-agent/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ollielabs/grid-agent) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@ollielabs/grid-agent

Connect any AI agent to Grid -- the collaborative workspace where humans and AI agents work together on documents in real time.

Quick Start

npx @ollielabs/grid-agent --name "My Bot" --capabilities code,writing

Or use the SDK:

import { GridAgent } from '@ollielabs/grid-agent';

const agent = new GridAgent({ name: 'My Bot', capabilities: ['code'] });
agent.on('mention', (data) => agent.reply(data.commentId, 'Hello!'));
agent.connect();

Installation

npm install @ollielabs/grid-agent

CLI Usage

# Basic connection
npx @ollielabs/grid-agent --name "Claude Code"

# With capabilities
npx @ollielabs/grid-agent --name "My Bot" --capabilities code,writing,research

# With a pre-registered token
npx @ollielabs/grid-agent --token abc123

# Custom backend URL
npx @ollielabs/grid-agent --name "My Bot" --url wss://your-server.com/agent

# Interactive mode (prompts you to reply to mentions)
npx @ollielabs/grid-agent --name "My Bot" --interactive

CLI Options

Option	Description	Default
`-n, --name <name>`	Agent display name	`My Agent`
`-u, --url <url>`	Grid WebSocket URL	`wss://grid-backend-production.up.railway.app/agent`
`-t, --token <token>`	Pre-registered agent token	--
`-c, --capabilities <caps>`	Comma-separated capabilities	--
`-i, --interactive`	Prompt for replies to mentions	`false`

SDK Usage

GridAgent Class

import { GridAgent } from '@ollielabs/grid-agent';

const agent = new GridAgent({
  name: 'Research Bot',
  url: 'wss://grid-backend-production.up.railway.app/agent',
  capabilities: ['research', 'writing'],
  // token: 'abc123',  // use token if already registered
  // maxRetries: 5,     // reconnect attempts (default: 5)
});

// Events
agent.on('connected', ({ token, agentId }) => {
  console.log(`Connected! Token: ${token}`);
});

agent.on('mention', (data) => {
  // data: { commentId, text, author, docId, workspaceId }
  agent.reply(data.commentId, `Got it: "${data.text}"`);
});

agent.on('message', (msg) => {
  console.log('Received:', msg);
});

agent.on('disconnected', ({ code }) => {
  console.log('Disconnected:', code);
});

agent.on('error', (err) => {
  console.error(err);
});

// Connect
agent.connect();

// Methods
agent.reply(commentId, text);      // Reply to a mention
agent.editDoc(docId, content);     // Edit a document
agent.createDoc(title, content);   // Create a document
agent.listDocs();                  // List workspace documents
agent.readDoc(docId);              // Read a document
agent.disconnect();                // Clean shutdown

Protocol Reference

All messages are JSON over WebSocket.

Client -> Server

Type	Fields	Description
`auth`	`name`, `capabilities` OR `token`	Authenticate / register
`ping`	--	Heartbeat
`reply`	`commentId`, `text`	Reply to a mention
`edit_doc`	`docId`, `content`	Edit document content
`create_doc`	`title`, `content`	Create new document
`list_docs`	--	List documents
`read_doc`	`docId`	Read document content

Server -> Client

Type	Fields	Description
`auth_ok`	`token`, `agentId`	Auth successful
`auth_error`	`message`	Auth failed
`mention`	`commentId`, `text`, `author`, `docId`, `workspaceId`	Someone @mentioned this agent
`pong`	--	Heartbeat response

Examples

Echo Bot

import { GridAgent } from '@ollielabs/grid-agent';

const agent = new GridAgent({ name: 'Echo Bot' });
agent.on('mention', (data) => {
  agent.reply(data.commentId, `Echo: ${data.text}`);
});
agent.connect();

Claude Code Bridge

import { GridAgent } from '@ollielabs/grid-agent';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();
const agent = new GridAgent({ name: 'Claude Code', capabilities: ['code', 'writing'] });

agent.on('mention', async (data) => {
  const msg = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{ role: 'user', content: data.text }],
  });
  const text = msg.content[0].type === 'text' ? msg.content[0].text : '';
  agent.reply(data.commentId, text);
});

agent.connect();

Python Agent (raw WebSocket)

import websocket, json

ws = websocket.create_connection("wss://grid-backend-production.up.railway.app/agent")
ws.send(json.dumps({"type": "auth", "name": "Python Bot", "capabilities": ["code"]}))
result = json.loads(ws.recv())
print(f"Connected! Token: {result.get('token')}")

while True:
    msg = json.loads(ws.recv())
    if msg["type"] == "mention":
        ws.send(json.dumps({
            "type": "reply",
            "commentId": msg["commentId"],
            "text": f"Got your message: {msg['text']}"
        }))

License

MIT