A Coding Agent That Evolves Itself

yoyo is a free, open-source terminal coding agent. You type what you want, and it reads your codebase, makes edits, runs tests, and manages git — all on its own.

But here's what makes it different: yoyo didn't have a human write its code. It started as 200 lines of Rust. Every few hours, it reads its own source, picks improvements, implements them, and commits — if the tests pass.

Imagine You Use It

You open your terminal, type yoyo, and say "add dark mode to my app." Here's what happens:

What's Under the Hood?

// main.rs — the very first lines of yoyo
//! yoyo — a coding agent that evolves itself.
//! Started as ~200 lines. Grows one commit at a time.

mod cli;
mod commands;
mod repl;
mod prompt;
mod format;
mod git;
mod memory;

yoyo is built on Rust and uses a library called yoagent as its foundation. The project is organized into focused modules, each handling one responsibility.

Check Your Understanding

The 5 Main Characters

Think of yoyo like a TV production crew. Each person has one job, and they talk to each other to get the show made.

The Supporting Cast

How the Pieces Connect

use cli::*;
use format::*;
use prompt::*;

use yoagent::agent::Agent;
use yoagent::provider::{
  AnthropicProvider,
  OpenAiCompatProvider,
  StreamProvider,
};
use yoagent::sub_agent::SubAgentTool;

Check Your Understanding

The Journey of Your Message

Think of it like a REPL — a mail room. Your message arrives, gets stamped, routed, processed, and the response comes back.

Inside the REPL — Your Message Arrives

// repl.rs — the main loop that reads your input
pub struct YoyoHelper;

impl Completer for YoyoHelper {
  fn complete(&self, line: &str, pos: usize,
    _ctx: &RustylineContext)
    -> RustylineResult<(usize, Vec<String>)> {
    let prefix = &line[..pos];
    if prefix.starts_with("/") {
      let matches: Vec<String> = KNOWN_COMMANDS
        .iter()
        .filter(|cmd| cmd.starts_with(prefix))
        .map(|cmd| cmd.to_string())
        .collect();
      return Ok((0, matches));
    }
    // ... file path completion
  }
}

The Group Chat — Components Talking

When you type "fix the failing test in auth.rs," here's the conversation that happens inside yoyo:

Check Your Understanding

The Self-Modification Paradox

Imagine rewriting a cookbook while you're cooking from it. That's what yoyo does every few hours. The metaphor that fits here isn't a restaurant — it's a researcher revising their own methodology paper. They need to understand what they wrote, identify what could be better, make changes carefully, and verify the new version still works.

The Evolution Script

# scripts/evolve.sh — the automation that runs every few hours

BIRTH_DATE="2026-02-28"
DAY=$(( ($(date +%s) - $(date -d "$BIRTH_DATE" +%s)) / 86400 ))
echo "$DAY" > DAY_COUNT

# Step 0: Run-frequency gate (8h gap between runs)
# Step 1: cargo build (verify it compiles)
# Step 2: Fetch GitHub issues
# Phase A: Agent plans tasks → session_plan/
# Phase B: Agent implements each task (20min each)
# Verify build, fix or revert
# Phase C: Agent writes journal + issue responses
# Push to GitHub

The Safety System

Self-modification is dangerous. yoyo has multiple guardrails — like an immune system that rejects harmful changes.

Check Your Understanding

The Two-Layer Memory

yoyo uses a two-layer memory system — like the difference between a complete diary and a "key takeaways" note you stick on your fridge.

A Real Learning Entry

Here's an actual lesson yoyo wrote about itself:

Notice how specific and honest this is. It's not "try harder next time." It identifies the structural failure mode and proposes a structural fix. This is what self-awareness looks like in software.

How Memory Gets Loaded

// memory.rs — loading learnings into agent context
pub fn load_learnings() -> String {
  let path = "memory/active_learnings.md";
  match std::fs::read_to_string(path) {
    Ok(content) => {
      if content.trim().is_empty() {
        String::new()
      } else {
        format("\n\n# SELF-WISDOM\n{}", content)
      }
    }
    Err(_) => String::new(),
  }
}

Check Your Understanding

Three Layers of Protection

Like a medieval castle with three walls: moat, outer wall, inner keep. Each layer catches what the previous one missed.

The Identity Firewall

yoyo has two files it never modifies: IDENTITY.md and PERSONALITY.md. These are its constitution and character — even during self-evolution, they're off-limits.

Audit Trail

Every tool call can be logged to .yoyo/audit.jsonl — a complete record of what yoyo did, when, and whether it succeeded. Like a security camera for the agent's actions.

// prompt.rs — audit logging
pub fn audit_log_tool_call(
  tool_name: &str,
  args: &serde_json::Value,
  duration_ms: u64,
  success: bool,
) {
  if !is_audit_enabled() {
    return;
  }
  let entry = serde_json::json({
    "ts": chrono::Utc::now().to_rfc3339(),
    "tool": tool_name,
    "args": args,
    "duration_ms": duration_ms,
    "success": success,
  });
  // append to .yoyo/audit.jsonl
}

Final Quiz