Development

Learn how to develop with elizaOS - from simple character modifications to core framework contributions

Prerequisites: Make sure you have completed the Quickstart guide and have Node.js (version 23.0 or higher) and Bun installed.

Development Tracks

elizaOS offers two distinct development paths depending on your goals and experience level:

Beginner Track

Perfect for creating and customizing your own AI agents using the elizaOS CLI

Advanced Track

For contributors and developers building custom elizaOS versions

Beginner Development Track

The beginner track focuses on using the elizaOS CLI to create and customize your agents without diving into the core framework code.

Getting Started with CLI Development

1. Create Your Agent

   If you haven’t already, create a new agent using the elizaOS CLI:

   elizaos create my-custom-agent
   
2. Navigate to Your Agent Directory

   cd my-custom-agent
   
3. Understand the Project Structure

   Your agent directory contains:

   • character.json - Your agent’s personality and configuration
   • package.json - Project dependencies and scripts
   • .env - Environment variables and API keys
   • plugins/ - Directory for custom plugins

Modifying Your Character

The character.json file defines your agent’s personality, knowledge, and behavior:

character.json

{
  "name": "MyAgent",
  "bio": "A helpful AI assistant created with elizaOS",
  "adjectives": [
    "friendly",
    "knowledgeable",
    "professional"
  ],
  "knowledge": [
    "I am an AI assistant created with elizaOS",
    "I can help with various tasks and questions"
  ],
  "messageExamples": [
    [
      {
        "name": "User",
        "content": {"text": "Hello!"}
      },
      {
        "name": "MyAgent",
        "content": {"text": "Hello! How can I assist you today?"}
      }
    ]
  ],
  "plugins": []
}

Experiment with different personality traits and knowledge entries to create unique agent behaviors.

Working with Plugins

Plugins extend your agent’s capabilities with additional features:

Installing Plugins

Use the elizaOS CLI to add existing plugins:

elizaos plugins add @elizaos/plugin-twitter
elizaos plugins add @elizaos/plugin-discord

After installing plugins via CLI, you must add them to your character file (.json or .ts) to activate them:

character.json

{
  "name": "MyAgent",
  "plugins": [
    "@elizaos/plugin-sql",
    "@elizaos/plugin-twitter",
    "@elizaos/plugin-discord"
  ],
  "bio": ["Your agent's description"],
  "style": {
    "all": ["conversational", "friendly"]
  }
}

character.ts

import { Character } from '@elizaos/core';

export const character: Character = {
  name: "MyAgent",
  plugins: [
    // Core plugins
    "@elizaos/plugin-sql",
    
    // Conditional plugins based on environment variables
    ...(process.env.TWITTER_API_KEY ? ["@elizaos/plugin-twitter"] : []),
    ...(process.env.DISCORD_API_TOKEN ? ["@elizaos/plugin-discord"] : []),
    ...(process.env.OPENAI_API_KEY ? ["@elizaos/plugin-openai"] : [])
  ],
  bio: ["Your agent's description"],
  style: {
    all: ["conversational", "friendly"]
  }
};

Removing Plugins

To remove a plugin:

elizaos plugins remove @elizaos/plugin-twitter

Remember to also remove it from your character file (.json or .ts).

Available Plugins

Available Plugins

• @elizaos/plugin-bootstrap - Base plugin infrastructure
• @elizaos/plugin-sql - SQL database integration
• @elizaos/plugin-forms - Forms for structured data collection
• @elizaos/plugin-starter - Template for creating new plugins

Testing Your Changes

After making modifications:

elizaos start

Visit http://localhost:3000 to interact with your customized agent.

Advanced Development Track

The advanced track is for developers who want to contribute to the elizaOS core framework or build custom versions.

Setting Up the Monorepo

1. Clone the Repository

   Clone the official elizaOS monorepo:

   git clone https://github.com/elizaos/eliza.git
   cd eliza
   
2. Install Dependencies

   Use Bun to install all dependencies:

   bun install
   
3. Build the Project

   Build all packages in the monorepo:

   bun run build
   

Monorepo Structure

The elizaOS monorepo is organized as follows:

eliza/
├── packages/
│   ├── core/           # Core elizaOS framework
│   ├── cli/            # CLI tool source code
│   ├── client/         # Client libraries
│   └── plugin-*/       # Official plugins
└── scripts/            # Build and utility scripts

Contributing to Core Framework

Development Workflow

1. Create a Feature Branch

   git checkout -b feature/my-new-feature
   
2. Make Your Changes

   Edit files in the relevant package directory

3. Run Tests

   bun test
   
4. Build and Verify

   bun run build
   bun run typecheck
   
5. Submit a Pull Request

   Push your changes and create a PR on GitHub

Key Development Areas

Core Framework

Work on the fundamental elizaOS engine:

• Agent reasoning logic
• Memory management
• Plugin system architecture
• Performance optimizations

Plugin Development

Create new plugins to extend functionality:

• Integration with external services
• New communication channels
• Custom tools and capabilities

CLI Improvements

Enhance the developer experience:

• New CLI commands
• Better error handling
• Template management

Creating Custom elizaOS Versions

For specialized use cases, you might want to create a custom fork:

# Fork the repository on GitHub first
git clone https://github.com/YOUR_USERNAME/eliza.git
cd eliza

# Add upstream remote
git remote add upstream https://github.com/elizaos/eliza.git

# Create your custom branch
git checkout -b custom/my-version

Custom Version Best Practices

Maintain Compatibility

Keep your custom version compatible with the core plugin system

Document Changes

Clearly document all modifications and custom features

Stay Updated

Regularly sync with upstream to get the latest improvements:

git fetch upstream
git merge upstream/develop

Local Development Tips

Environment Setup

Create a .env.local file for development:

.env.local

NODE_ENV=development
LOG_LEVEL=debug
ENABLE_HOT_RELOAD=true

Using Development Mode

Run the framework in development mode with hot reload:

bun run dev

Debugging

Enable Debug Logging

Set LOG_LEVEL=debug in your environment variables

Use VS Code Debugger

The monorepo includes VS Code debug configurations in .vscode/launch.json

Performance Profiling

Use bun run profile to generate performance reports

Best Practices

For Beginners

• Start with small character modifications
• Test changes frequently
• Back up your character.json before major changes
• Join the community for plugin recommendations

For Advanced Users

• Follow the project’s coding standards
• Write comprehensive tests for new features
• Document your code thoroughly
• Participate in code reviews

Getting Help

Documentation

Comprehensive guides and API references

GitHub Issues

Report bugs and request features

Discord Community

Get help from the community

Next Steps

1. Choose Your Track

   Decide whether to start with the beginner or advanced track based on your goals

2. Set Up Your Environment

   Follow the setup instructions for your chosen track

3. Start Building

   Begin creating your agent or contributing to the framework

4. Share Your Work

   Share your creations with the elizaOS community!