Droid SDK Documentation

Welcome to the Droid SDK documentation. The @hatchway/droid-sdk is a TypeScript SDK for Factory Droid that enables you to build AI-powered bots and applications with powerful autonomous capabilities.

What is Droid SDK?

The Droid SDK provides a programmatic interface to Factory's AI agents (Droids), allowing you to:

• Create AI-powered chatbots for Telegram, Discord, and custom platforms
• Build autonomous coding agents that can read, write, and modify code
• Implement headless AI automation for CI/CD pipelines
• Create interactive AI applications with streaming responses
• Build custom skills and tools for specialized tasks

Key Features

• Model Agnostic: Use OpenAI, Anthropic, Google, X AI, open-source or local models
• Autonomous Execution: Delegate complete tasks with configurable autonomy levels
• Streaming Support: Real-time progress via Server-Sent Events (SSE)
• Multi-Platform Bots: Built-in adapters for Telegram and Discord
• Skill System: Create reusable, specialized AI capabilities
• Runtime Management: Manage multiple concurrent droid sessions

Quick Start

Installation

npm install @hatchway/droid-sdk

Basic Usage

import { DroidSession } from '@hatchway/droid-sdk';

// Create a session
const session = new DroidSession({
  model: 'kimi-k2.5',
  reasoningEffort: 'medium',
  autonomyLevel: 'low',
  systemPrompt: 'You are a helpful coding assistant.',
});

// Send a prompt and stream events
for await (const event of session.send('Explain this codebase')) {
  switch (event.type) {
    case 'message':
      console.log('Assistant:', event.text);
      break;
    case 'tool_call':
      console.log('Tool called:', event.toolName);
      break;
    case 'tool_result':
      console.log('Tool result:', event.value);
      break;
    case 'completion':
      console.log('Done! Turns:', event.numTurns);
      break;
  }
}

// Clean up
await session.close();

Documentation Structure

droid-sdk/
├── README.md              # This file
├── api/                   # API Reference
│   ├── session.md         # DroidSession API
│   ├── bot.md             # DroidBot API
│   ├── runtime.md         # Runtime API
│   ├── skills.md          # Skills API
│   └── adapters.md        # Platform Adapters
├── guides/                # Guides & Tutorials
│   ├── getting-started.md # Getting started guide
│   ├── streaming.md       # Streaming with SSE
│   ├── bots.md            # Building bots
│   └── skills.md          # Creating custom skills
└── examples/              # Code Examples
    ├── basic.ts           # Basic usage
    ├── streaming.ts       # SSE streaming
    ├── telegram-bot.ts    # Telegram bot
    └── custom-skill.ts    # Custom skill

Core Concepts

DroidSession

The DroidSession class is the core interface for interacting with Factory Droids. It manages the connection to the Factory CLI and streams events as the AI works.

DroidBot

The DroidBot class provides a framework for building chatbots. It handles message processing, command parsing, and integrates with platform adapters.

RuntimeManager

Manages multiple concurrent droid sessions, useful for applications that need to handle multiple tasks simultaneously.

SkillsManager

Create and manage reusable skills - predefined prompts and behaviors that can be triggered by users.

Adapters

Platform-specific implementations for Telegram (built-in) and Discord (peer dependency).

Configuration

The SDK requires the Factory CLI to be installed and authenticated:

# Install Factory CLI
curl -fsSL https://app.factory.ai/cli | sh

# Authenticate
droid login

Environment Variables

# Optional: Set default model
FACTORY_DROID_MODEL=kimi-k2.5

# Optional: Set default reasoning level
FACTORY_DROID_REASONING=medium

# Optional: Set default autonomy level
FACTORY_DROID_AUTONOMY=medium

Models

Available models include:

| Model | Description | |-------|-------------| | kimi-k2.5 | Kimi's latest model (default for most tasks) | | glm-4.7 | General Language Model v4.7 (fast, cost-effective) | | claude-haiku-4-5-20251001 | Anthropic Claude Haiku (fast) | | claude-opus-4-5-20251101 | Anthropic Claude Opus (high quality) | | gpt-5.2-codex | OpenAI GPT-5.2 Codex (code focused) | | gemini-3-pro-preview | Google Gemini 3 Pro |

Autonomy Levels

Control how much the droid can do autonomously:

• Low (default): Read-only operations (search, read, analyze)
• Medium: Can modify files with confirmation
• High: Full autonomous operation

Next Steps

• Read the Getting Started Guide
• Explore the API Reference
• Check out Code Examples
• Learn about Building Bots

Support

• Factory Documentation
• Factory Discord
• GitHub Discussions

License

MIT