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

​
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

Work on the fundamental elizaOS engine:

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

​
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

​
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!