Evolving Agents

README

# OpenClaw Orchestrator

> **Note:** These agents haven't been fully tested yet, so they may not install or run perfectly out of the box. If you run into any issues, feel free to open a new issue!

## Self-Evolving AI Agents

This project implements **self-evolving AI agents** inspired by the [Darwin Gödel Machine](https://sakana.ai/dgm/). Unlike traditional AI systems that are static after training, these agents can:

- **Read and modify their own code** - Improve their SKILL.md, AGENTS.md, and operational instructions
- **Evaluate improvements empirically** - Test changes on actual tasks before committing
- **Evolve through open-ended exploration** - Build a growing archive of agent variants with full lineage tracking

### Key Features

| Feature | Description |
|---------|-------------|
| **Self-Modification** | Agents can propose and implement improvements to their own code |
| **Empirical Evaluation** | Changes are tested on real tasks, not just hypothesized |
| **Agent Archive** | All variants are stored with metrics and lineage (stepping stones preserved) |
| **Evolutionary Tree** | Full history of improvements and branching paths |

### How It Works

1. Agent identifies an improvement opportunity
2. Proposes specific changes with rationale
3. Tests changes on sample tasks
4. Measures performance improvement
5. Archives successful variant with lineage
6. Future improvements can branch from any archived variant

This approach mirrors natural evolution - keeping "stepping stone" variants that may not be the best individually but can lead to breakthrough improvements through parallel exploration.

---

## What is OpenClaw?

OpenClaw is an AI agent framework that lets you create and manage AI agents with specialized skills. Think of it as having a team of AI assistants - each with their own expertise - working together to help you build software, research topics, write content, and solve problems.

## Why Use This Starter Kit?

If you're new to OpenClaw, this repository gives you:

- **A ready-made agent team** - No need to configure agents from scratch
- **Best practices** - Pre-configured with proven patterns for multi-agent workflows
- **Examples to learn from** - See how agents can delegate and collaborate
- **Quick start** - Copy, run, and start building with AI agents immediately

## Meet Your Agent Team

The Orchestrator coordinates five specialized agents:

| Agent | What They Do | Example Request |
|-------|--------------|----------------|
| **coder** | Writes code, implements features, refactors | "Write a Python function to validate email addresses" |
| **researcher** | Finds information, investigates topics | "What are the best practices for REST API design?" |
| **writer** | Creates documentation, drafts content | "Write a README for my new project" |
| **qa** | Reviews code, runs tests, catches bugs | "Review this code for security issues" |
| **debugger** | Diagnoses problems, fixes errors | "Why is my app crashing here?" |
| **security** | Scans for passwords, secrets, API keys | "Check my code for exposed API keys" |

### How It Works

When you send a request to the Orchestrator, it analyzes what you need and automatically delegates to the right agent(s). You don't need to know which agent does what - just describe your problem and let the Orchestrator handle the rest.

## Quick Start

### Prerequisites

- [OpenClaw installed](https://github.com/anomalyco/opencode) on your machine
- Access to an LLM API (OpenAI, Anthropic, Ollama, etc.)

### Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/cbuntingde/openclaw-starter-agents.git
   cd openclaw-starter-agents
   ```

2. Run the setup script:
   ```bash
   ./setup.sh
   ```

3. Start the gateway:
   ```bash
   openclaw gateway --workspace $(pwd)
   ```

4. Say hello! Try sending:
   ```
   Hello! What can you help me with?
   ```

## Structure

This starter kit uses two directory structures:

### Local Workspace (created by OpenClaw)

```
~/.openclaw/
├── workspace/                      # Main orchestrator agent
│   ├── skills/
│   │   └── delegate-agent/
│   ├── memory/
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── USER.md
│   ├── IDENTITY.md
│   ├── HEARTBEAT.md
│   ├── MEMORY.md
│   ├── TOOLS.md
│   └── openclaw.json
├── workspace-coder/              # Coder sub-agent
├── workspace-researcher/         # Researcher sub-agent
├── workspace-writer/            # Writer sub-agent
├── workspace-qa/                # QA sub-agent
├── workspace-debugger/          # Debugger sub-agent
└── workspace-security/          # Security sub-agent
```

### Project Structure

```
openclaw-starter-agents/
├── agents/                    # Your team of AI agents
│   ├── coder/                 # Software development expert
│   │   ├── AGENTS.md         # Role, workflows
│   │   ├── IDENTITY.md        # Name, emoji
│   │   ├── SKILL.md          # Capabilities, tool permissions
│   │   ├── SOUL.md           # Personality, boundaries
│   │   └── USER.md           # User profile template
│   ├── debugger/             # Troubleshooting expert
│   ├── qa/                   # Quality assurance expert
│   ├── researcher/           # Research and investigation expert
│   ├── security/             # Secret detection specialist
│   └── writer/               # Content creation expert
├── skills/
│   ├── delegate-agent/       # Tool for routing tasks to agents
│   └── evolver/             # Self-evolution capability
├── archive/                 # Agent variant archive with lineage
│   ├── agents/              # Stored agent variants
│   └── lineage.json         # Evolutionary tree
├── memory/                  # Where the agent remembers things
├── AGENTS.md                 # Instructions for the Orchestrator
├── SOUL.md                   # The Orchestrator's personality
├── USER.md                   # Your profile and preferences
├── IDENTITY.md               # Agent identity
├── HEARTBEAT.md              # Periodic reminders
├── MEMORY.md                 # Long-term memory
├── TOOLS.md                  # Tool conventions
└── openclaw.json             # Configuration
```

## Usage Examples

### Getting Help with Code

```
Can you write me a function that calculates factorial?
```

The Orchestrator will delegate to the `coder` agent, which will write the function for you.

### Researching a Topic

```
What's the best way to handle authentication in a React app?
```

The Orchestrator delegates to `researcher` to find current best practices.

### Writing Documentation

```
Can you write a README for my API project?
```

The Orchestrator delegates to `writer` to create documentation.

### Code Review

```
Can you review this code for bugs?
```

The Orchestrator delegates to `qa` to review and test.

### Fixing Problems

```
My app keeps crashing when I upload a file. Can you help?
```

The Orchestrator delegates to `debugger` to diagnose the issue.

## Customization

### Adding New Agents

1. Create a new directory under `agents/`
2. Add required files:
   - `AGENTS.md` - Role, workflows, processes
   - `IDENTITY.md` - Name, emoji
   - `SKILL.md` - Capabilities, tool permissions
   - `SOUL.md` - Personality, boundaries
   - `USER.md` - User profile template
3. Update the delegate-agent skill to include the new agent

### Modifying the Orchestrator

Edit `AGENTS.md` to change how the Orchestrator:
- Decides which agent to use
- Coordinates between multiple agents
- Reports results back to you

### Changing Agent Personalities

Edit each agent's `SOUL.md` to adjust their:
- Tone and communication style
- Area of focus
- Special instructions

## Configuration

Edit `openclaw.json` to customize:
- Which AI model to use
- How often agents check in (heartbeat)
- What tools/skills are available
- Session management settings

## Security Notes

- Never commit secrets, API keys, or credentials to version control
- Keep `agents/*/sessions/` out of version control (already in `.gitignore`)
- Review `.gitignore` before committing

## Learning More

- [OpenClaw Documentation](https://github.com/anomalyco/opencode)
- [OpenClaw Skills Guide](https://github.com/anomalyco/opencode/tree/main/docs/skills)
- [Multi-Agent Patterns](https://github.com/anomalyco/opencode/tree/main/docs/agents)

## License

MIT

## Support

If you find these useful, consider [sponsoring](https://github.com/sponsors/cbuntingde) the project.

---

Copyright © 2026 Created by Chris Bunting