Elizaos

ElizaOS Expert Skill

Question Mode

If this skill was invoked with an argument (e.g., /elizaos how do I create a service? or /elizaos what changed in v2?), treat the argument as a question to answer using the knowledge in this skill and its reference files. Answer the question directly and concisely — do NOT modify any code unless the user's original message also asked for code changes. Read the relevant reference files as needed to provide accurate answers.

Architecture Overview

ElizaOS is a TypeScript framework (Node.js v23+, Bun) for autonomous AI agents. Core architecture:

ElizaOS (multi-agent manager, extends EventTarget)
  └── AgentRuntime instances (implements IAgentRuntime extends IDatabaseAdapter)
       ├── Character     — personality, knowledge, style
       ├── Plugins       — modular capability bundles
       │    ├── Actions     — what agents DO (VERB_NOUN)
       │    ├── Providers   — what agents SEE (context injection)
       │    ├── Evaluators  — what agents LEARN (post-processing)
       │    └── Services    — what agents CONNECT to (singletons)
       ├── Memory        — persistent vector DB (5 types)
       ├── Events        — 30+ async event types
       ├── Models        — provider-agnostic with priority routing
       └── Database      — Drizzle ORM + PostgreSQL/PGLite

Message Processing Pipeline

Message In → Store in Memory → Compose State (all Providers) → shouldRespond Decision
  → LLM generates thought + actions + response → Validate & Execute Actions
  → Run Evaluators → Store Response → Deliver via Client

Two processing modes: Single-Shot (one LLM call) and Multi-Step (iterative with accumulated context).

Branches & Versions (verified 2026-04-28)

| Branch | package.json | Status | Notes | |--------|---------|--------|---------| | develop (default) | 2.0.0-alpha.176 | Active alpha — this is the v2 line | 21 packages, 39 plugins, polyglot (TS+Python+Rust) | | main | 1.4.4 | Legacy v1, frozen | TypeScript-only, 17 packages | | v2-develop | 1.4.4 | Stale — identical to main, 3956 commits behind develop | Don't use; migrated into develop | | v2.0.0 | 2.0.0-alpha | Separate experimental branch | Different package set incl. computeruse/, sweagent/, daemon-style packages |

Latest published tag: v2.0.0-alpha.442 (2026-04-27). New alpha tags ship from develop continuously — install via bun i -g @elizaos/cli@alpha. There is no stable v2 release yet — all v2 work has been alpha for 13+ months.

Recommendation: For new work target the develop branch (v2 alpha) — it's where all development happens. Only fall back to main (1.4.4) if you need a frozen TypeScript-only baseline; upstream development of v1 has stopped.

Monorepo Layout — develop branch (verified)

packages/
  agent/              → Agent runtime composition layer
  app/                → Tauri desktop wrapper
  app-core/           → Shared app logic
  benchmarks/         → Perf benchmarks
  docs/               → Mintlify docs source (docs.elizaos.ai)
  elizaos/            → CLI (npm: @elizaos/cli)
  examples/           → Example agents
  homepage/           → elizaos.ai marketing site
  interop/            → Cross-language plugin interop layer
  native-plugins/     → Built-in plugins (sql, bootstrap, etc.)
  prompts/            → Standalone prompt templates
  python/             → Python runtime + SDK (pyproject.toml, uv-managed)
  rust/               → Rust runtime + SDK (Cargo.toml, builds to native + WASM)
  scenario-runner/    → Scenario testing harness
  scenario-schema/    → Scenario format schema
  schemas/            → Protobuf schemas (buf.yaml; eliza/v1/*.proto)
  shared/             → Cross-package shared utilities
  skills/             → Reusable agent skill library
  templates/          → Project templates for `elizaos create`
  typescript/         → Core TypeScript SDK (npm: @elizaos/core)
  ui/                 → React web dashboard

plugins/              → 39 first-party plugins at top level (Discord,
                        Telegram, Twitter, Solana, EVM, OpenAI, Anthropic,
                        Ollama, OpenRouter, Google, knowledge, MCP, etc.)

Key facts to internalize:

• Python and Rust SDKs are real and shipping on develop — packages/python/elizaos/ (pyproject + uv lock) and packages/rust/src/ (Cargo + WASM build via build-wasm.sh).
• Plugins are inside the monorepo at top-level plugins/, not in a separate elizaos-plugins org. The old separate-org claim is obsolete.
• Capability tiers (Basic/Extended/Autonomy) are mirrored across all 3 SDKs — AutonomyService exists in TS, Python, and Rust (verified via ENABLE_AUTONOMY symbol search).

v2.0.0 Branch (Separate Experimental)

Distinct from develop. Layout:

packages/  @schemas/ computeruse/ daemon/ docs/ elizaos/ interop/
           milaidy/ mldy/ prompts/ psyop/ python/ rust/ samantha/
           skills/ sweagent/ tui/ typescript/

Adds computeruse/ (computer-use capabilities), sweagent/ (SWE-Agent integration), tui/ (terminal UI), and several named character/agent packages (milaidy, mldy, psyop, samantha). Use only if you specifically want to track this branch.

Key v2 Capabilities (vs legacy v1.4.4 on main)

Entity Component System (replaces user system), ServiceBuilder (createService()/defineService()), formal Event system (30+ EventType enum), Task system (TaskWorker + persistent queue), multi-agent orchestration (ElizaOS class), model handler registry with priority routing, action chaining (ActionContext), working memory, x402 payment types, run tracking, capability tiers, autonomy mode, polyglot (TS/Python/Rust) runtimes with shared protobuf wire format.

For full v2 details, read [v2 Architecture](references/v2-architecture.md).

Quick Start

bun install -g @elizaos/cli@alpha   # @alpha = v2 develop line; omit for legacy v1.4.4
elizaos create my-agent              # Scaffold project
elizaos env edit-local               # Set API keys
elizaos start                        # Run (web UI at localhost:3000)
elizaos dev                          # Dev mode with hot reload

CLI Reference

| Command | Purpose | |---------|---------| | elizaos create [name] | New project/plugin/agent (--type project\|plugin\|agent\|tee) | | elizaos start | Production mode (--character , -p ) | | elizaos dev | Dev with hot reload (-b to build first) | | elizaos test | Run tests (--type component\|e2e\|all, --name ) | | elizaos deploy | Deploy to Eliza Cloud | | elizaos plugins list\|add\|remove | Manage plugins | | elizaos agent list\|start\|stop\|get\|remove\|clear-memories | Manage agents | | elizaos env list\|edit-local\|reset | Environment config | | elizaos publish | Publish plugin to registry | | elizaos update | Update CLI and packages | | elizaos monorepo | Clone elizaOS for development | | elizaos tee phala | TEE operations (Phala Cloud) |

Project Structure

my-project/
├── src/
│   ├── index.ts           # Entry: exports Project with agents
│   ├── character.ts       # Character definition
│   ├── plugins/           # Custom plugins
│   └── __tests__/         # Tests (Bun test runner)
├── .env                   # API keys (gitignored)
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── .eliza/                # Runtime data, PGLite DB

Entry Point

import { type Project, type ProjectAgent } from '@elizaos/core';
import { character } from './character';

const agent: ProjectAgent = {
  character,
  init: async (runtime) => { /* post-init logic */ },
  plugins: [],
};

const project: Project = { agents: [agent] };
export default project;

Character Configuration

const character: Character = {
  name: 'TradingBot',
  bio: ['Expert DeFi trader', 'Monitors on-chain activity 24/7'],
  username: 'defi_bot',
  adjectives: ['analytical', 'precise', 'risk-aware'],
  topics: ['DeFi', 'yield farming', 'MEV', 'liquidity'],
  style: {
    all: ['Be concise, data-driven', 'Include numbers when relevant'],
    chat: ['Ask about risk tolerance before suggesting trades'],
    post: ['Include relevant token tickers', 'Keep under 280 chars'],
  },
  messageExamples: [[
    { name: 'user', content: { text: 'Should I buy ETH?' } },
    { name: 'TradingBot', content: { text: 'ETH is at $3,200, up 4.2% today. RSI at 62. What is your time horizon?' } },
  ]],
  knowledge: ['DeFi protocol mechanics', { path: './docs/strategies.md', shared: false }],
  plugins: ['@elizaos/plugin-sql', '@elizaos/plugin-openai', '@elizaos/plugin-solana'],
  settings: {
    model: 'gpt-4o',
    secrets: { OPENAI_API_KEY: process.env.OPENAI_API_KEY },
  },
};

Database Architecture

Storage Backends

ElizaOS uses PGLite (embedded PostgreSQL in Node.js) by default. No external database required for development. For production, set POSTGRES_URL to use full PostgreSQL.

# PGLite (default — no config needed, stores at ./.eliza/.elizadb)
PGLITE_DATA_DIR=/custom/path    # Optional: override PGLite data directory

# PostgreSQL (production)
POSTGRES_URL=postgresql://user:password@host:5432/database

Adapter selection via createDatabaseAdapter():

• POSTGRES_URL set → PgDatabaseAdapter (connection pooling, SSL, retry with backoff)
• No POSTGRES_URL → PgliteDatabaseAdapter (singleton, file-based, zero config)

Both extend BaseDrizzleAdapter and implement IDatabaseAdapter.

Core Tables (auto-created by plugin-sql)

agents, memories, entities, relationships, rooms, participants, messages, embeddings, cache, logs, tasks

Embedding Dimensions

Default: 384 (NOT 1536). Defined via DIMENSION_MAP:

VECTOR_DIMS: SMALL(384), MEDIUM(512), LARGE(768), XL(1024), XXL(1536), XXXL(3072)

Plugin Schema System (Drizzle ORM)

Plugins define custom tables via Drizzle ORM and export as schema property. Migrations are fully automatic — no migration files needed.

import { pgTable, uuid, text, timestamp, jsonb } from 'drizzle-orm/pg-core';

export const myDataTable = pgTable('my_plugin_data', {
  id: uuid('id').primaryKey().defaultRandom(),
  agentId: uuid('agent_id').notNull(),
  content: text('content').notNull(),
  metadata: jsonb('metadata').default({}),
  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
});

// Plugin export
export const myPlugin: Plugin = {
  name: 'my-plugin',
  schema: { myDataTable },  // Enables auto-migration
};

Key Interfaces

Memory System

5 types: DOCUMENT, FRAGMENT, MESSAGE, DESCRIPTION, CUSTOM. Scopes: shared, private, room.

// Create memory
await runtime.createMemory({ type: MemoryType.DOCUMENT, content: { text: 'User prefers ETH' },
  metadata: { confidence: 0.9 }, roomId, entityId });

// Semantic search (vector similarity)
const results = await runtime.searchMemories({ type: MemoryType.DOCUMENT,
  query: 'user token preferences', limit: 10, threshold: 0.7 });

Model Types & Priority Routing

TEXT_SMALL, TEXT_LARGE, TEXT_COMPLETION, TEXT_REASONING_SMALL, TEXT_REASONING_LARGE,
TEXT_EMBEDDING, TEXT_TOKENIZER_ENCODE/DECODE, IMAGE, IMAGE_DESCRIPTION,
TRANSCRIPTION, TEXT_TO_SPEECH, AUDIO, VIDEO, OBJECT_SMALL, OBJECT_LARGE, RESEARCH

Usage: await runtime.useModel(ModelType.TEXT_LARGE, { prompt, temperature: 0.7 })

Model registration uses priority-based routing — higher priority wins.

Event Types (30+)

World: WORLDJOINED/CONNECTED/LEFT | Entity: ENTITYJOINED/LEFT/UPDATED Room: ROOMJOINED/LEFT | Message: MESSAGERECEIVED/SENT/DELETED Voice: VOICEMESSAGERECEIVED/SENT | Run: RUNSTARTED/ENDED/TIMEOUT Action: ACTIONSTARTED/COMPLETED | Evaluator: EVALUATORSTARTED/COMPLETED Model: MODELUSED | Embedding: EMBEDDINGGENERATION* | Control: CONTROLMESSAGE Form: FORMFIELD_CONFIRMED/CANCELLED

Service Types

transcription, video, browser, pdf, aws_s3, web_search, email, tee, task,
wallet, lp_pool, token_data, message_service, message, post, unknown

ServiceTypeRegistry is extensible via TypeScript module augmentation.

@elizaos/core API Quick Reference (v2 alpha — develop branch)

These are the exact type signatures for the current alpha. Use these when writing plugins.

Handler Signature

type Handler = (
  runtime: IAgentRuntime,
  message: Memory,
  state?: State,                    // OPTIONAL — State | undefined
  options?: HandlerOptions,
  callback?: HandlerCallback,
  responses?: Memory[]
) => Promise;

Action

interface Action {
  name: string;
  description: string;
  similes?: string[];
  examples?: ActionExample[][];
  validate(runtime: IAgentRuntime, message: Memory, state?: State): Promise;
  handler: Handler;  // Returns Promise
}

interface ActionResult { success: boolean; text?: string; error?: string;
  values?: Record; data?: Record; }

Provider

interface Provider {
  name: string;
  description?: string;
  dynamic?: boolean;
  position?: number;
  private?: boolean;
  get(runtime: IAgentRuntime, message: Memory, state?: State): Promise;
}

interface ProviderResult {
  text?: string;
  values?: Record;
  data?: Record;
}

Evaluator

interface Evaluator {
  name: string;
  description: string;
  similes?: string[];
  alwaysRun?: boolean;
  examples?: EvaluatorExample[];     // MUST include, at least empty []
  validate(runtime: IAgentRuntime, message: Memory, state?: State): Promise;
  handler: Handler;
}

Service

abstract class Service {
  runtime!: IAgentRuntime;
  static serviceType: string;         // e.g. "MY_SERVICE" — a string constant
  capabilityDescription?: string;     // Describe what this service does
  static start(runtime: IAgentRuntime): Promise;
  stop?(): Promise;
}

CRITICAL: Do NOT name a property config in Service subclasses — it conflicts with Service.config?: Metadata in the base class. Use paymentConfig, serviceConfig, etc.

Plugin registration: services: [MyServiceClass] — pass the class, NOT new MyServiceClass().

Runtime

runtime.getSetting(key: string): string | boolean | number | null;  // Cast with String(val)
runtime.logger.info(obj: Record, msg: string);     // Pino-style: object first, string second
runtime.logger.warn(msg: string);                                    // Or just string
runtime.useModel(ModelType.TEXT_SMALL, { prompt: '...' }): Promise;
runtime.getService(serviceType: string): T | null;

Plugin

interface Plugin {
  name: string;
  description?: string;
  priority?: number;            // Lower = loads first (plugin-sql uses 0)
  dependencies?: string[];
  init?(config: Record, runtime: IAgentRuntime): Promise;
  actions?: Action[];
  providers?: Provider[];
  evaluators?: Evaluator[];
  services?: (typeof Service)[];  // Pass CLASSES, not instances
  routes?: Route[];
  events?: Record;
  schema?: Record;  // Drizzle ORM tables for auto-migration
}

Bootstrap Plugin (Required)

Capability Tiers (v2)

Basic (default): Providers: actions, actionState, attachments, capabilities, character, entities, evaluators, providers, recentMessages, time, world. Actions: REPLY, IGNORE, NONE. Services: TaskService, EmbeddingGenerationService.

Extended (opt-in via ENABLEEXTENDEDCAPABILITIES): +Providers: choice, contacts, facts, followUps, knowledge, relationships, role, settings. +Actions: addContact, choice, followRoom, generateImage, muteRoom, sendMessage, updateContact, updateRole, updateSettings, etc. +Evaluators: reflection, relationshipExtraction.

Autonomy (opt-in via ENABLE_AUTONOMY): +Providers: adminChat, autonomyStatus. +Actions: sendToAdmin. +Services: AutonomyService.

Background Tasks

const wor

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ItachiDevv](https://github.com/ItachiDevv)
- **Source:** [ItachiDevv/elizaos-skill](https://github.com/ItachiDevv/elizaos-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.