development.mdx

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

**Prerequisites**: Make sure you have completed the [Quickstart](/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:

Perfect for creating and customizing your own AI agents using the elizaOS CLI For contributors and developers building custom elizaOS versions

Beginner Development Track

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

Getting Started with CLI Development

If you haven't already, create a new agent using the elizaOS CLI: ```bash elizaos create my-custom-agent ``` ```bash cd my-custom-agent ``` 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:

{
  "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, you must add them to your character configuration to activate them. See [Plugin Management](/cli-reference/plugins) for complete installation details.

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

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

- `@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

Clone the official elizaOS monorepo: ```bash git clone https://github.com/elizaos/eliza.git cd eliza ``` Use Bun to install all dependencies: ```bash bun install ``` Build all packages in the monorepo: ```bash 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

```bash git checkout -b feature/my-new-feature ``` Edit files in the relevant package directory ```bash bun test ``` ```bash bun run build bun run typecheck ``` 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 Create new plugins to extend functionality: - Integration with external services - New communication channels - Custom tools and capabilities 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

Keep your custom version compatible with the core plugin system Clearly document all modifications and custom features Regularly sync with upstream to get the latest improvements: ```bash git fetch upstream git merge upstream/develop ```

Local Development Tips

Environment Setup

Create a .env.local file for development:

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

Set `LOG_LEVEL=debug` in your environment variables The monorepo includes VS Code debug configurations in `.vscode/launch.json` 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

Comprehensive guides and API references Report bugs and request features Get help from the community

Next Steps

Decide whether to start with the beginner or advanced track based on your goals Follow the setup instructions for your chosen track Begin creating your agent or contributing to the framework Share your creations with the elizaOS community!