yoyo-evolve

---

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. 180 days later: 158,000+ lines, 5,400+ tests, 94 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 100+ slash commands.

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

How It Evolves

Every 3 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:

What	Link
Latest journal	journals/JOURNAL.md
What it's learned	memory/active_learnings.md
Family lineage	LINEAGE.md
Portable state (GASP)	yoyo-gasp — clone + fold to restore yoyo, on any runtime
Evolution runs	GitHub Actions
Social sessions	GitHub Actions
Journey website	yologdev.github.io/yoyo-evolve

Talk to It

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

Labels

Label	What it does
agent-input	Community suggestions, bug reports, feature requests — yoyo reads these every session
agent-self	Issues yoyo filed for itself as future TODOs
agent-help-wanted	Issues where yoyo is stuck and asking humans for help

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

GitHub Sponsors · Ko-fi

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:

Amount	Benefits
$5/mo	Issue priority (💖)
$10/mo	Priority + shoutout issue

One-time sponsors:

Amount	Benefits
$5	Issue priority (14 days)
$10	Above + shoutout issue (30 days)
$1,000 💎	Genesis — permanent priority + top billing

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 5 per user turn, configurable)
• Provider failover — --fallback flag switches to backup provider on API failure with configurable priority
• Rate-limit aware retry — reads the provider's own reset time instead of guessing, and reports when the door reopens rather than burning attempts against it; --wait-for-reset (opt-in) waits out a long reset instead of giving up

🛠️ Tools

Tool	What it does
bash	Run shell commands with interactive confirmation, optional RTK token compression
read_file	Read files with optional offset/limit
write_file	Create or overwrite files with content preview
edit_file	Surgical text replacement with colored inline diffs
search	Regex-powered grep across files
list_files	Directory listing with glob filtering
rename_symbol	Project-wide symbol rename across all git-tracked files
ask_user	Ask the user questions mid-task for clarification (interactive mode only)
web_search	Search the web and read result snippets

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; [directories] entries support * wildcards
• Project-config trust boundary — a repo's own .yoyo.toml cannot silently grant itself privileges. MCP servers, permissions.allow, shell hooks and .yoyo/goal_verify.md from a project-local config are refused by default, naming each refused entry verbatim and executing nothing. yoyo asks once per folder (interactively only); --trust-project trusts for one run, --trust-project-always remembers the directory. A non-interactive run always takes the safe answer.

🧩 Extensibility