Self-Evolving Agent

An OpenCode MCP plugin that gives the AI the capability to autonomously complete an ultimate goal through a structured pipeline with ROI-based termination.

Inspired by OpenMontage's instruction-driven pipeline approach and built with OhMyOpenAgent-level production quality.

How It Works

User: "Here's my ultimate goal"
         │
         ▼
  ┌─ CLARIFY ──┐  ← AI asks clarifying questions, presents landscape analysis
  │             │
  └────▶────────┘
         │  (user approves)
         ▼
  ┌─ PLANNING ─┐  ← AI decomposes into milestones with binary success criteria
  │             │
  └────▶────────┘
         │  (user confirms)
         ▼
  ┌─ EXECUTING ┐  ← AI iterates: pick milestone → execute → self-review → assess
  │  (loop)    │
  └────▶────────┘
         │  (ROI < 10%)
         ▼
  ┌─ TERMINATED┐  ← Report generated, goal archived

The AI has full architectural authority during execution — it can replace, delete, or add any component, constrained only by consistency with the ultimate goal.

The pipeline automatically stops when continued optimization would cost more than 10% in resources for less than 10% in improvement.

Installation

Via npm (recommended)

# Install globally
npm install -g self-evolving-agent

# Install the OpenCode skill
npm run setup-skills --prefix $(npm root -g)/self-evolving-agent

Manual install

git clone <repo>
cd self-evolving-agent
npm install
npm run build
npm run setup-skills

Register in OpenCode config

Add to your opencode.jsonc (user-level at ~/.config/opencode/opencode.jsonc):

{
  "mcp": {
    "self-evolving-agent": {
      "type": "local",
      "command": ["npx", "self-evolving-agent"],
      "enabled": true
    }
  }
}

If installed globally:

{
  "mcp": {
    "self-evolving-agent": {
      "type": "local",
      "command": ["self-evolving-agent"],
      "enabled": true
    }
  }
}

Configure (optional)

Create self-evolving-agent.jsonc in your project root to override defaults:

{
  // ROI threshold: stop when improvement ratio drops below this
  "roi_threshold": {
    "min_roi_ratio": 0.10,
    "min_performance_delta": 0.5,
    "max_stagnant_iterations": 5
  },
  "state_dir": ".omo/ulw-loop",
  "verbose": false
}

Use it

Restart OpenCode, then say:

"Here's my ultimate goal: build an automated deployment system for our microservices. I want you to take full ownership and autonomously plan, implement, iterate until it's truly production-ready, stopping only when further effort gives diminishing returns."

The @self-evolving-agent skill will activate, walking through the 4-phase pipeline.

Configuration

Create self-evolving-agent.jsonc in your project root to override defaults:

{
  // ROI threshold: stop when improvement ratio drops below this
  "roi_threshold": {
    "min_roi_ratio": 0.10,          // 10% minimum ROI
    "min_performance_delta": 0.5,   // Minimum meaningful improvement
    "max_stagnant_iterations": 5    // Force stop after 5 stagnant cycles
  },
  // State persistence directory
  "state_dir": ".omo/ulw-loop",
  // Verbose logging
  "verbose": false
}

MCP Tools

| Tool | Description | |------|-------------| | init_goal | Initialize a new ultimate goal session | | transition | Transition between pipeline phases | | add_milestone | Add a milestone to track sub-goals | | update_milestone | Update milestone status | | update_performance | Record performance score for ROI calculation | | log_decision | Record an immutable decision (append-only journal) | | list_decisions | Query decisions with category/impact filters | | list_goals | List all active goal sessions | | get_status | Get current goal state and metrics | | assess_roi | Evaluate ROI — determines if execution should continue | | generate_report | Generate completion report (Markdown) | | doctor | Run health diagnostics |

Architecture

self-evolving-agent/
├── src/
│   ├── index.ts             MCP Server entry (11 tools)
│   ├── types.ts             Branded types + domain model
│   ├── config.ts            Zod schemas for configuration
│   ├── config-loader.ts     JSONC config file loader
│   ├── schemas.ts           Zod schemas for all persisted data
│   ├── state-machine.ts     Phase state machine (atomic writes)
│   ├── roi-engine.ts        ROI calculation engine
│   ├── journal.ts           Immutable decision journal (atomic)
│   ├── report.ts            Markdown report generator
│   ├── doctor.ts            Health diagnostics
│   └── errors.ts            Typed error classes
├── .opencode/skills/self-evolving-agent/
│   ├── SKILL.md             Main behavioral protocol
│   └── references/          Phase-specific protocol files
├── .github/workflows/ci.yml
├── package.json
└── tsconfig.json

Pipeline Phases

CLARIFY

AI presents a broad-but-shallow analysis of the goal, asks 2-5 clarifying questions, and waits for user approval before proceeding.

PLANNING

Goal is decomposed into 3-7 milestones with binary success criteria. Each milestone logs rationale via the decision journal.

EXECUTING

The AI autonomously picks pending milestones, implements, self-reviews, and logs decisions. After each iteration, ROI is assessed. Full architectural authority applies — any component can be replaced, added, or removed.

TERMINATED

The pipeline terminates when:

• ROI drops below threshold (default: 10%) — spending 100% resources yields <10% improvement
• Performance stagnates for 5+ iterations
• All milestones are complete

License

MIT — see LICENSE