The Droid Class

The Droid class is your gateway to the Factory Droid CLI. It manages configuration, creates conversation threads, and executes AI-powered tasks.

Core Responsibilities

The Droid class handles:

• Configuration Management - Model selection, timeouts, autonomy levels
• Thread Creation - Starting new or resuming existing conversations
• One-shot Execution - Running single prompts without conversation state
• Tool Discovery - Listing available AI tools

Creating an Instance

import { Droid, MODELS } from '@activade/droid-sdk';

const droid = new Droid({
  model: MODELS.CLAUDE_SONNET,
  autonomyLevel: 'high',
  cwd: './my-project',
  timeout: 300000
});

Configuration Options

Option	Type	Default	Description
model	ModelId | string	-	AI model to use
autonomyLevel	AutonomyLevel	'default'	Level of autonomous decision-making
reasoningEffort	ReasoningEffort	-	Reasoning intensity
cwd	string	process.cwd()	Working directory for CLI operations
timeout	number	600000	Maximum execution time in ms
droidPath	string	'droid'	Path to CLI binary

Autonomy Levels

The autonomy level controls how independently the AI makes decisions:

• default - Standard behavior, asks for confirmation on risky operations
• low - More conservative, confirms most file operations
• medium - Balanced autonomy for routine tasks
• high - Maximum autonomy, executes most operations without confirmation

// High autonomy for automated workflows
const automatedDroid = new Droid({ autonomyLevel: 'high' });

// Low autonomy for careful review
const reviewDroid = new Droid({ autonomyLevel: 'low' });

Execution Patterns

One-shot Execution

Use exec() for stateless, single-prompt operations:

const result = await droid.exec('Generate a random UUID');
console.log(result.finalResponse);

Threaded Conversations

Use threads for multi-turn conversations with context:

const thread = droid.startThread();
await thread.run('Create a REST API');
await thread.run('Add authentication'); // Has context from previous turn

Best Practices

1. Reuse Droid instances - Create once, use for multiple operations
2. Match autonomy to use case - Higher for automation, lower for interactive
3. Set appropriate timeouts - Longer for complex tasks
4. Use structured output - For programmatic response handling