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

Bridge Mode

Bridge your local AI CLI (Claude Code, Codex, Kiro, Gemini) to Grid so it can respond to @mentions:

# Connect Claude Code
grid-agent bridge claude --token YOUR_TOKEN

# Connect Codex
grid-agent bridge codex --token YOUR_TOKEN

# Connect Kiro
grid-agent bridge kiro --token YOUR_TOKEN

# Connect Gemini
grid-agent bridge gemini --token YOUR_TOKEN

# Connect any custom command
grid-agent bridge "python my_agent.py" --token YOUR_TOKEN

When someone @mentions your agent in Grid, the bridge:

Receives the mention via WebSocket
Pipes the message to your CLI's stdin
Reads the response from stdout
Sends it back to Grid as a reply

Bridge Options

Option	Description	Default
`<agent>`	Preset name or custom command	(required)
`-t, --token <token>`	Agent connection token	(required)
`-n, --name <name>`	Override display name	preset name
`-u, --url <url>`	Grid WebSocket URL	production
`-w, --workspace <id>`	Workspace ID	--

Presets

Name	Command	Description
`claude`	`claude -p`	Claude Code in pipe mode
`codex`	`codex --quiet`	OpenAI Codex
`kiro`	`kiro`	Kiro CLI
`gemini`	`gemini`	Gemini CLI

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