Skip to main content

Installation

Get the dialai library up and running in your project. This section covers the practical implementation of DIAL—for the concepts and theory, see Concepts.

Prerequisites​

  • Node.js 18+ (LTS recommended)
  • npm or pnpm or yarn
  • TypeScript 5.0+ (recommended)

Quick Install​

# Using npm
npm install dialai

# Using pnpm
pnpm add dialai

# Using yarn
yarn add dialai

Project Setup​

1. Initialize a New Project​

If you're starting fresh:

mkdir my-dial-project
cd my-dial-project
npm init -y
npm install dialai typescript @types/node tsx
npx tsc --init

2. Configure TypeScript​

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

3. Add "type": "module" to package.json​

DIAL is an ESM package:

{
  "type": "module"
}

Verify Installation​

Create a test file to verify everything works:

// src/test-install.ts
import { createSession, runSession } from "dialai";
import type { MachineDefinition } from "dialai";

const machine: MachineDefinition = {
  machineName: "test",
  initialState: "start",
  goalState: "end",
  states: {
    start: { transitions: { finish: "end" } },
    end: {},
  },
};

const session = await runSession(machine);
console.log("DIAL installed successfully!");
console.log("Session reached:", session.currentState); // "end"

Run it:

npx tsx src/test-install.ts

You should see:

DIAL installed successfully!
Session reached: end

Usage Modes​

DIAL supports two usage modes:

CLI Mode​

Run state machines from the command line:

npx dialai machine.json

Or after installation:

dialai machine.json

See Quick Start for a full example.

MCP Server Mode​

DIAL can also run as an MCP (Model Context Protocol) server, exposing its functionality as tools for AI assistants:

npx dialai --mcp

The MCP server provides tools for:

  • Running sessions from machine definitions
  • Creating and managing sessions
  • Registering specialists
  • Executing transitions and evaluating consensus

To use with Claude Desktop, add to your MCP configuration:

{
  "mcpServers": {
    "dialai": {
      "command": "npx",
      "args": ["dialai", "--mcp"]
    }
  }
}

Both modes use the same core engine and provide identical functionality.

What's Next?​

Now that DIAL is installed, you're ready to:

  1. Quick Start: Build your first state machine with AI and human specialists
  2. Learn Concepts: Understand sessions, specialists, and decision cycles
  3. Build State Machines: Model your tasks as state machines

Troubleshooting​

"Module not found" errors​

Ensure you're using a compatible Node.js version:

node --version  # Should be 18+

TypeScript compilation errors​

Make sure your tsconfig uses NodeNext module resolution:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

ESM/CJS issues​

DIAL is an ESM package. If you're in a CommonJS project, either:

  1. Add "type": "module" to your package.json, or
  2. Use dynamic imports:
const { runSession } = await import("dialai");

Need help?​

  • Check the GitHub Issues
  • Search existing discussions
  • Open a new issue with your error details