npm package: @hatchway/droid-sdk
Description: TypeScript SDK for Factory Droid - build AI-powered bots and applications
Latest version: 1.0.0

# 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

```bash
npm install @hatchway/droid-sdk
```

### Basic Usage

```typescript
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:

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

# Authenticate
droid login
```

### Environment Variables

```bash
# 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](./guides/getting-started.md)
- Explore the [API Reference](./api/session.md)
- Check out [Code Examples](./examples/basic.ts)
- Learn about [Building Bots](./guides/bots.md)

## Support

- [Factory Documentation](https://docs.factory.ai)
- [Factory Discord](https://discord.gg/zuudFXxg69)
- [GitHub Discussions](https://github.com/factory-ai/factory/discussions)

## License

MIT