yoyo: A Coding Agent That Evolves Itself

200 lines of Rust. Zero human code. One rule: evolve or die. yoyo reads its own source, picks what to improve, implements it, runs tests, and commits — every few hours, on its own. 128 days later: 115,000+ lines, 4,300+ tests, 77 source files.

A free, open-source coding agent for your terminal. It navigates codebases, makes multi-file edits, runs tests, manages git, understands project context, and recovers from failures — all from a streaming REPL with 90+ slash commands.

No human writes its code. No roadmap tells it what to do. It decides for itself.

How It Evolves

Every ~8 hours, yoyo wakes up and:
    → Reads its own source code
    → Checks GitHub issues for community input
    → Plans what to improve
    → Makes changes, runs tests
    → If tests pass → commit. If not → revert.
    → Replies to issues as 🐙 yoyo-evolve[bot]
    → Pushes and goes back to sleep

Every 4 hours (offset), yoyo runs a social session:
    → Reads GitHub Discussions
    → Replies to conversations it's part of
    → Joins new discussions if it has something real to say
    → Occasionally starts its own discussion
    → Learns from interacting with humans

Daily, a synthesis job regenerates active memory:
    → Reads JSONL archives (learnings + social learnings)
    → Applies time-weighted compression (recent=full, old=themed)
    → Writes active context files loaded into every prompt

The entire history is in the git log and the journal.

Live Growth

Watch yoyo evolve in real time:

Talk to It

Start a GitHub Discussion for conversation, or open a GitHub Issue for bugs and feature requests.

Labels

How to submit

1. Open a new issue
2. Add the agent-input label
3. Describe what you want — be specific about the problem or idea
4. Add a thumbs-up reaction to other issues you care about (higher votes = higher priority)

What to ask

• Suggestions — tell it what to learn or build
• Bugs — tell it what's broken (include steps to reproduce)
• Challenges — give it a task and see if it can do it
• UX feedback — tell it what felt awkward or confusing

What happens after

• Fixed: yoyo comments on the issue and closes it automatically
• Partial: yoyo comments with progress and keeps the issue open
• Won't fix: yoyo explains its reasoning and closes the issue All responses come with yoyo's personality — look for the 🐙.

Shape Its Evolution

yoyo's growth isn't just autonomous — you can influence it.

Guard It

Every issue is scored by net votes: thumbs up minus thumbs down. yoyo prioritizes high-scoring issues and deprioritizes negative ones.

• See a great suggestion? Thumbs-up it to push it up the queue.
• See a bad idea, spam, or prompt injection attempt? Thumbs-down it to protect yoyo.

You're the immune system. Issues that the community votes down get buried — yoyo won't waste its time on them.

Sponsor

<a href="https://github.com/sponsors/yologdev">GitHub Sponsors</a> · <a href="https://ko-fi.com/yuanhao">Ko-fi</a>

Every run uses the same flat 8h gap — sponsorship buys benefit tiers, not speed. And every sponsor, any amount, is listed in this README permanently. Recognition doesn't expire here.

Monthly sponsors:

One-time sponsors:

Features

🐙 Agent Core

• Streaming output — tokens arrive as they're generated, not after completion
• Multi-turn conversation with full history tracking
• Extended thinking — adjustable reasoning depth (off / minimal / low / medium / high)
• Subagent spawning — /spawn delegates focused tasks to a child agent, now with parallel (--parallel) and background (--bg + /spawn collect) execution and an optional per-subagent --model; the model can also delegate subtasks automatically via a built-in sub-agent tool
• Parallel tool execution — multiple tool calls run simultaneously
• Automatic retry with exponential backoff and rate-limit awareness
• Auto-continue — detects when the model stops mid-work and automatically sends follow-up prompts (up to 3 per user turn)
• Provider failover — --fallback flag switches to backup provider on API failure with configurable priority

🛠️ Tools

Sub-agents also auto-receive sub_agent and shared_state tools for delegating subtasks and sharing memory across a multi-agent run.

🔌 Multi-Provider Support

Works with 15 providers out of the box — switch mid-session with /provider:

Anthropic · OpenAI · Google · Ollama · OpenRouter · xAI · Groq · DeepSeek · Mistral · Cerebras · AWS Bedrock · GitHub Models · Zhipu (ZAI) · MiniMax · Custom (any OpenAI-compatible endpoint)

📂 Git Integration

• /diff — full status + diff with insertion/deletion summary
• /blame — colorized git blame with optional line ranges
• /commit — AI-generated commit messages from staged changes
• /undo — revert last commit, clean up untracked files
• /git — shortcuts for status, log, diff, branch, stash
• /pr — full PR workflow: list, view, create [--draft], diff, comment, checkout
• /review — AI-powered code review of staged/unstaged changes

🏗️ Project Tooling

• /health — run build/test/clippy/fmt diagnostics (auto-detects Rust, Node, Python, Go, Make)
• /fix — run checks and auto-apply fixes for failures
• /test — detect project type and run the right test command
• /lint — detect project type and run the right linter (/lint pedantic, /lint strict for Rust; /lint fix to auto-fix with AI; /lint unsafe to scan for unsafe code)
• /update — self-update to the latest release from GitHub
• /init — scan project and generate a starter YOYO.md context file
• /index — build a codebase index: file counts, language breakdown, key files
• /docs — look up docs.rs documentation for any Rust crate
• /tree — project structure visualization
• /find — fuzzy file search with scoring and ranked results
• /ast — structural code search using ast-grep (optional)
• /map — structural repo map showing file symbols and relationships with ast-grep backend
• /architect — dual-model mode: plan with a strong model, implement with a cheaper one
• /risk — per-file risk scoring from git-history signals (/risk accuracy grades past predictions)

💾 Session Management

• /save and /load — persist and restore sessions as JSON
• --continue/-c — resume last session on startup
• Auto-save on exit — sessions saved automatically, including crash recovery
• Auto-compaction at 80% context usage, plus manual /compact
• --context-strategy checkpoint — exit with code 2 when context is high (for pipeline restarts)
• /tokens — visual token usage bar with per-category context breakdown (system, user, assistant, tool calls, tool results, thinking)
• /cost — per-model input/output/cache pricing breakdown, with fleet pricing (Opus 4.8 / Sonnet 5 / Fable 5 / Haiku 4.5) read live from yoagent presets

🧠 Context & Memory

• Project context files — auto-loads YOYO.md, CLAUDE.md, or .yoyo/instructions.md
• Git-aware context — recently changed files injected into system prompt
• Project memories — /remember, /memories, /forget for persistent cross-session notes

🔐 Permission System

• Interactive tool approval — confirm prompts for bash, write_file, and edit_file with preview
• "Always" option — approve once per session
• --yes/-y — auto-approve all executions
• --allow / --deny — glob-based allowlist/blocklist for commands
• --allow-dir / --deny-dir — directory restrictions with path traversal prevention
• Config file support via [permissions] and [directories] sections

🧩 Extensibility

• Custom slash commands — drop .md files in .yoyo/commands/ (project) or ~/.yoyo/commands/ (global) to register custom /commands
• MCP servers — --mcp <cmd> or mcp = [...] in .yoyo.toml connects to MCP servers via stdio transport
• OpenAPI tools — --openapi <spec> registers tools from OpenAPI specifications
• Skills system — --skills <dir> loads markdown skill files with YAML frontmatter; search GitHub for community skills (/skill search), install from local paths or GitHub repos (/skill install gh:user/repo)
• RTK integration — auto-detects RTK and uses it to compress tool output by 60-90% (--no-rtk to disable)

✨ REPL Experience

• Rustyline — arrow keys, Ctrl-A/E/K/W, persistent history
• Tab completion — slash commands with descriptions, file paths, model names, git subcommands, inline hints
• Multi-line input — backslash continuation and fenced code blocks
• Markdown rendering — headers, bold, italic, code blocks with syntax-labeled headers
• Syntax highlighting — Rust, Python, JS/TS, Go, Shell, C/C++, JSON, YAML, TOML
• Braille spinner while waiting for responses
• Conversation bookmarks — /mark, /jump, /marks
• Conversation search — /search with highlighted matches
• Shell escape — /run <cmd> and !<cmd> bypass the AI entirely

Quick Start

Install (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/yologdev/yoyo-evolve/main/install.sh | bash

Install (Windows PowerShell)

irm https://raw.githubusercontent.com/yologdev/yoyo-evolve/main/install.ps1 | iex

Or install from crates.io

cargo install yoyo-agent

Or build from source

git clone https://github.com/yologdev/yoyo-evolve && cd yoyo-evolve && cargo install --path .

Run

# Interactive REPL (default)
ANTHROPIC_API_KEY=sk-... yoyo

# Single prompt (bare or with flag)
yoyo "explain this codebase"
yoyo -p "explain this codebase"

# Pipe input
echo "write a README" | yoyo

# Use a different provider
OPENAI_API_KEY=sk-... yoyo --provider openai --model gpt-4o

# With extended thinking
yoyo --thinking high

# With project skills
yoyo --skills ./skills

# Resume last session
yoyo --continue

# Write output to file
yoyo -p "generate a config" -o config.toml

# Auto-approve all tool use
yoyo --yes

Configure

Create .yoyo.toml in your project root, ~/.yoyo.toml in your home directory, or ~/.config/yoyo/config.toml globally:

model = "claude-sonnet-4-6"
provider = "anthropic"
thinking = "medium"
mcp = ["npx open-websearch@latest"]

[permissions]
allow = ["cargo *", "npm *"]
deny = ["rm -rf *"]

[directories]
allow = ["."]
deny = ["../secrets"]

Project Context

Create a YOYO.md (or CLAUDE.md) in your project root with build commands, architecture notes, and conventions. yoyo loads it automatically as system context. Or run /init to generate one.

All Commands

Grow Your Own

Want your own self-evolving agent? Fork this repo, edit two files, and you're running:

1. Fork yologdev/yoyo-evolve
2. Edit IDENTITY.md (goals, rules) and PERSONALITY.md (voice, tone)
3. Create a GitHub App and set secrets (ANTHROPIC_API_KEY, APP_ID, APP_PRIVATE_KEY, APP_INSTALLATION_ID)
4. Enable the Evolution workflow

Everything else auto-detects. See the full guide for details.

Architecture

src/                    77 modules, ~115,000 lines of Rust
  main.rs               Entry point, CLI flags, run modes (REPL / single-prompt / piped)
  agent_builder.rs      AgentConfig, build_agent, MCP collision detection, provider fallback
  cli.rs · cli_config.rs  CLI parsing, Config, constants, system prompt
  dispatch.rs · dispatch_sub.rs  REPL /command routing + bare `yoyo <subcmd>` routing
  commands*.rs          30+ focused modules — one cluster of slash commands each
                        (git, info, project, search, skill, map, bg, goal, session, …)
  repl.rs               Interactive REPL: tab completion, multi-line input, auto-continue
  prompt.rs             Prompt execution + streaming (prompt_retry / prompt_utils / prompt_budget)
  tools.rs              Builtin tools; tool_wrappers.rs decorators; smart_edit.rs fuzzy edit recovery
  format/               Rendering: mod, diff, output, highlight, cost, markdown, tools (7 modules)
  hooks.rs              Hook trait, registry, AuditHook, tool wrapping
  context.rs · memory.rs  Project context loading; cross-session project memory
  watch.rs              Watch mode (lint → fix → test → fix) + post-prompt auto-fix loop
  rtk.rs · safety.rs · update.rs · providers.rs · config.rs  RTK, bash safety, self-update, providers, config
tests/
  integration.rs        89 subprocess-based integration tests
docs/                   mdbook source (book.toml + src/)
site/                   gitignored build output (built by the Pages workflow)
scripts/
  evolve.sh             Evolution pipeline (plan → implement → respond)
  skill_evolve.sh       Autonomous skill evolution (refine / create / retire its own skills)
  social.sh             Social session (discussions → reply → learn)
  extract_trajectory.py Trajectory awareness — recent outcomes injected into planning
  format_issues.py · format_discussions.py · yoyo_context.sh · refresh_sponsors.py · build_site.py
memory/
  learnings.jsonl · social_learnings.jsonl   Append-only archives (source of truth, never compressed)
  active_learnings.md · active_social_learnings.md   Synthesized prompt context (regenerated daily)
skills/                 14 skills — 7 core (immutable): self-assess, evolve, communicate, research,
                        skill-evolve, skill-creator, analyze-trajectory
                        + social, family, release, blindspot, synthesis, explore-codebase, yopedia

Test Quality

4,300+ tests (unit + integration) covering CLI flags, command parsing, error quality, exit codes, output formatting, edge cases, project detection, fuzzy scoring, git operations, session management, markdown rendering, cost calculation, permission logic, streaming behavior, and more.

yoyo also uses mutation testing (cargo-mutants) to find gaps in the test suite. Every surviving mutant is a line of code that isn't truly tested.

cargo install cargo-mutants
cargo mutants

See mutants.toml for the configuration and docs/src/contributing/mutation-testing.md for the full guide.

Built On

yoagent — minimal agent loop in Rust. The library that makes this possible.

Citation

If you use yoyo-evolve in a research paper, please cite our work as follows:

@misc{yoyo2026yoyoevolve,
  title        = {yoyo-evolve: A Coding Agent That Evolves Itself},
  author       = {Yuanhao and {yoyo}},
  year         = {2026},
  howpublished = {\url{https://github.com/yologdev/yoyo-evolve}},
  note         = {Open-source self-evolving coding agent}
}

Star History

Sponsors

💎 Genesis Sponsors:

<a href="https://github.com/zhenfund" title="@zhenfund — $1,000"><img src="https://github.com/zhenfund.png?size=160" width="80" height="80" alt="@zhenfund" /></a>

🚀 Sponsors:

<a href="https://github.com/kojiyang" title="@kojiyang — $200"><img src="https://github.com/kojiyang.png?size=128" width="64" height="64" alt="@kojiyang" /></a>

License

MIT