SDK

The Honeybee SDK provides typed clients, Zod contracts, telemetry reporting, and integration types for building on the Honeybee platform.

Install

npm install @honeybee-ai/hivemind-sdk

Subpath exports

The SDK uses subpath exports for tree-shaking:

Import	What
@honeybee-ai/hivemind-sdk	Platform client (createPlatformClient)
@honeybee-ai/hivemind-sdk/contracts	Zod schemas for all API types
@honeybee-ai/hivemind-sdk/integrations	Tool types: ToolResult, ToolDef, ToolEntry, PluginContext, IncubatorPlugin
@honeybee-ai/hivemind-sdk/telemetry	TelemetryReporter, createTelemetryFromEnv
@honeybee-ai/hivemind-sdk/config	Config loader (.wglrc, env vars, precedence)

Platform client

import { createPlatformClient } from '@honeybee-ai/hivemind-sdk';

const client = createPlatformClient({ profile: 'default' });

// Hive management
const hives = await client.listHives();
const hive = await client.createHive({ name: 'my-project' });
await client.startHive(hive.id);
await client.stopHive(hive.id);
await client.deleteHive(hive.id);

// Secrets
await client.setSecret({ provider: 'cerebras', key: 'csk-...' });
const secrets = await client.listSecrets();
await client.deleteSecret('cerebras');

// Marketplace
const results = await client.searchMarketplace('code review');
await client.installProtocol('code-review');

Contracts (Zod schemas)

Type-safe API contracts for all Honeybee entities:

import {
  HiveSchema,
  AgentSchema,
  ProtocolSchema,
  SecretSchema,
  TelemetryEventSchema,
} from '@honeybee-ai/hivemind-sdk/contracts';

// Validate API responses
const hive = HiveSchema.parse(apiResponse);

// TypeScript types
type Hive = z.infer<typeof HiveSchema>;
type Agent = z.infer<typeof AgentSchema>;

Integration types

Types for building incubator plugins and tools:

import type {
  ToolResult,
  ToolDef,
  ToolEntry,
  PluginContext,
  IncubatorPlugin,
} from '@honeybee-ai/hivemind-sdk/integrations';

// Build a plugin
const plugin: IncubatorPlugin = {
  name: 'my-plugin',
  getToolEntries(ctx: PluginContext): ToolEntry[] {
    return [{
      name: 'my_tool',
      description: 'Does something',
      parameters: { type: 'object', properties: {} },
      handler: async (args): Promise<ToolResult> => {
        return { result: 'done' };
      },
    }];
  },
};

Telemetry reporter

import { createTelemetryFromEnv } from '@honeybee-ai/hivemind-sdk/telemetry';

// Reads TELEMETRY_ENDPOINT + TELEMETRY_API_KEY from env
// Falls back to local-only JSONL if not set
const reporter = createTelemetryFromEnv('my-project');

// Record events (fire-and-forget, never throws)
reporter.record({
  type: 'llm_call',
  model: 'claude-sonnet',
  promptTokens: 500,
  completionTokens: 200,
  latencyMs: 1500,
});

// Get aggregated snapshot (for dashboards)
const snapshot = reporter.getSnapshot();

// Flush on shutdown
await reporter.flush();

Config loader

import { loadConfig, loadGlobalConfig } from '@honeybee-ai/hivemind-sdk/config';

// Load project config (.wglrc in closest ancestor)
const config = loadConfig();

// Load global config (~/.wglrc)
const global = loadGlobalConfig();

// Access values
const serverUrl = config.get('server');
const activeProfile = global.activeProfile || 'personal';