How yologdev/yoyo-evolve works
This repository is a Rust-based terminal coding agent with three major concerns layered on top of each other:
1. an interactive agent/runtime for chatting and tool use,
2. a project-aware command and context system,
3. an autonomous evolution pipeline that lets the agent improve itself over time.
Top-level shape
The crate is a single Rust binary, launched from src/main.rs. From there, execution splits into:
• interactive REPL mode,
• single-prompt / piped modes,
• command handling for slash commands,
• session/state management,
• project and git tooling,
• prompt/context assembly,
• setup/onboarding.
The user-facing experience is terminal-first, but the repository also includes supporting automation for GitHub, documentation publishing, and scheduled self-improvement runs.
Core runtime architecture
1) Entry point and configuration
src/main.rs is the application entry point. It wires together:
• CLI parsing from src/cli.rs,
• configuration loading from .yoyo.toml and global config locations,
• model/provider selection,
• permission defaults,
• session startup or resume,
• REPL or one-shot prompt execution.
This layer is the boundary between external inputs and the agent runtime. It determines whether the program runs interactively, processes a single prompt, or reads from stdin.
2) REPL and conversation loop
src/repl.rs owns the interactive terminal loop. It is responsible for:
• reading user input,
• multiline entry and shell-style shortcuts,
• history and bookmarks,
• tab completion,
• streaming assistant output as it arrives,
• dispatching slash commands instead of sending everything to the model.
This is the main human-facing control surface. The REPL is where session state, command dispatch, and the model stream meet.
3) Agent/tool execution boundary
The agent itself is not just a chat loop: it is a tool-using runtime. The README describes support for:
• file reads/writes/edits,
• shell execution,
• search and file listing,
• symbol renaming,
• user clarification,
• parallel tool calls,
• retries with backoff,
• provider switching.
In the repository layout, this behavior is spread across the main binary plus helper modules, but architecturally it forms a distinct tool-execution boundary:
• the model proposes actions,
• the runtime checks permissions,
• tools execute against the local filesystem, shell, and git repo,
• results are streamed back into the conversation.
That boundary is important in diagrams because it separates “LLM reasoning” from “real-world side effects.”
Command subsystem
Slash commands are a major architectural feature and are organized by domain:
• src/commands.rs is the dispatcher and command registry.
• src/help.rs stores command metadata and grouped help text.
• src/commands_git.rs handles git-centric commands such as diff, commit, PR operations, review, and status shortcuts.
• src/commands_project.rs handles project-introspection commands such as health, test, lint, init, index, tree, find, AST search, and docs lookup.
• src/commands_session.rs handles session persistence and context-management commands like save, load, compact, tokens, and cost.
• src/commands_dev.rs, src/commands_file.rs, and src/commands_search.rs support specialized internal command families.
Architecturally, these commands bypass normal agent reasoning when needed. Some are pure local operations, while others invoke the model for synthesis, review, or generated messages. This makes the command layer a control plane on top of the conversational agent.
Prompt and context assembly
4) System prompt construction
src/prompt.rs builds the context the model sees. It gathers several inputs:
• project instructions from YOYO.md, CLAUDE.md, or .yoyo/instructions.md,
• active project memories,
• recently changed files from git-aware context injection,
• system/personality text from repository-managed identity files,
• runtime configuration such as model, provider, thinking level, and permissions.
This module is central to the architecture because it is where the repo turns a raw terminal session into a project-aware agent. The prompt is not static; it is assembled from local repo state and persistent memory.
5) Project identity and memory
There are two related state systems:
• memory.rs manages project memories stored under .yoyo/ style state, including memory.json-like persisted notes.
• the memory/ directory in the repo contains long-lived learning archives and daily synthesized context files:
- learnings.jsonl
- social_learnings.jsonl
- active_learnings.md
- active_social_learnings.md
The architecture here is “append-only archive + synthesized active context.” Raw learnings accumulate over time, while a separate synthesis step compresses them into prompt-friendly markdown that is loaded into future sessions.
Git and project tooling
6) Git integration
src/git.rs provides git-aware operations used by both commands and the prompt system. The git layer is significant because yoyo is designed to work inside a repository and reason about changes, commits, branches, and pull requests.
Git is a first-class data source in the architecture:
• changed files influence context,
• diffs are surfaced to the user,
• commit generation is model-assisted,
• undo/revert flows depend on repository state,
• PR and review workflows integrate with remote hosting.
src/commands_git.rs and src/git.rs together form the “repository operations” boundary between local agent behavior and version control / GitHub workflows.
7) Project inspection and diagnostics
src/commands_project.rs encapsulates auto-detection and execution of project-level tasks:
• health checks,
• tests,
• linting,
• formatting/fixes,
• codebase indexing,
• file tree visualization,
• fuzzy file search,
• AST-based code search,
• documentation lookup.
This subsystem makes the agent project-type-aware. It detects the local stack and chooses appropriate commands rather than assuming a specific language or framework.
The repo itself is Rust, but the project tooling is explicitly polyglot: it mentions Rust, Node, Python, Go, and Make detection.
Session persistence and state management
8) Sessions
src/commands_session.rs manages persistence of the chat history and session state. The README indicates:
• save/load session files,
• resume last session on startup,
• autosave on exit,
• crash recovery,
• compaction when context gets large,
• token and cost reporting.
This is a distinct architectural layer because the agent must preserve continuity across invocations. Session state sits between the REPL and the prompt construction system: the REPL feeds messages into the session model, and the prompt builder turns that history into the next model request.
Formatting and terminal presentation
9) Output rendering
src/format.rs and parts of the REPL handle presentation concerns:
• ANSI formatting,
• markdown rendering,
• syntax highlighting,
• inline diff previews,
• token/cost visualizations,
• readable command output.
This is the boundary between raw agent output/tool results and the terminal UI. It matters in an architecture diagram because the user does not consume the model directly; they consume a rendered, colored, streamed terminal interface.
Setup and onboarding
10) First-run setup
src/setup.rs handles onboarding or initial environment preparation. This is the bootstrap path before the agent can fully operate, likely including config discovery and first-run guidance.
Extensibility layer
The repository exposes three major extension mechanisms:
• MCP servers, configured through command-line flags or .yoyo.toml, using stdio transport,
• OpenAPI tool registration from API specs,
• “skills” loaded from markdown files with YAML frontmatter, found in skills/.
These are important architectural boundaries because they allow the core agent runtime to gain new capabilities without changing the main control loop. Skills are content-driven, while MCP/OpenAPI are external capability integrations.
Autonomous evolution pipeline
A defining feature of this repo is that it is itself the object of automation.
11) Evolution scripts
The scripts/ directory contains the operational pipeline that lets yoyo improve itself:
• evolve.sh and evolve-local.sh orchestrate plan → implement → test → commit loops,
• social.sh handles discussion-based social interactions,
• format_issues.py and format_discussions.py normalize GitHub input,
• daily_diary.sh generates daily narrative summaries,
• build_site.py produces the journey website,
• yoyo_context.sh assembles shared identity/context from repository-managed files.
These scripts are not just utilities; they are the automation backbone for self-maintenance, content synthesis, and external communication.
12) Memory synthesis pipeline
The memory/ folder reflects a two-tier memory architecture:
• raw archives: append-only JSONL logs of learnings,
• synthesized active context: markdown files regenerated from those logs.
The daily synthesis job compresses older content into theme-based summaries and keeps fresh, high-signal content available to the prompt builder. This is a data pipeline from long-term archive to short-term operational memory.
External systems and infrastructure
13) GitHub integration and scheduled automation
The .github/workflows/ directory shows that GitHub Actions is part of the architecture:
• ci.yml for test/verification,
• release.yml for packaging/release,
• pages.yml for documentation/site publishing,
• evolve.yml, social.yml, and synthesize.yml for scheduled autonomous workflows.
The repo also interacts with:
• GitHub Issues as an input queue,
• GitHub Discussions as a social interaction surface,
• GitHub PRs as a change-management workflow,
• GitHub Pages for documentation/website hosting.
So the system is not just a local CLI; it is a long-running agent connected to GitHub as an external coordination plane.
14) Model/provider boundary
The agent supports multiple providers, including Anthropic, OpenAI, Google, Ollama, OpenRouter, xAI, Groq, DeepSeek, Mistral, Cerebras, and custom OpenAI-compatible endpoints.
This means model access is abstracted behind a provider layer. In architecture terms, the conversation loop is provider-agnostic, and model selection is a runtime configuration concern rather than a code-path fork.
Documentation and site generation
The repository includes two documentation surfaces:
• docs/ is an mdBook source tree for the user/developer manual,
• scripts/build_site.py and CI workflows generate the public website under site/.
This separates product documentation from runtime code. The docs explain usage and architecture, while the site acts as a published artifact and project narrative.
Testing and quality gates
The repo is heavily test-driven:
• tests/integration.rs provides subprocess-based integration coverage,
• the README emphasizes a large unit/integration suite,
• mutation testing is supported via cargo-mutants,
• CI workflows enforce correctness before release/evolution commits land.
Architecturally, tests sit between the self-evolving automation and the repository: evolution scripts can propose changes, but passing tests are the gate before commit/push.
High-level data flow
A useful diagram for this repo would show these flows:
1. User input enters the REPL or CLI.
2. CLI/config loading resolves provider, model, permissions, session, and context paths.
3. Prompt assembly pulls in project instructions, memory, git state, and session history.
4. The model generates either direct text or tool calls.
5. Tool execution runs through permission checks and local integrations:
- filesystem,
- shell,
- git,
- search/project inspection,
- external services like GitHub or docs lookup.
6. Results stream back into the conversation and session state.
7. Session state may be saved, compacted, or resumed later.
8. Separate scheduled scripts and GitHub Actions ingest issues/discussions, evolve the code, synthesize memories, and publish docs/site artifacts.
Architectural boundaries to emphasize in a diagram
If you’re drawing this system, the most important boundaries are:
• Terminal UI vs agent runtime: REPL/input rendering is separate from model/tool execution.
• Prompt assembly vs execution: context gathering is distinct from taking actions.
• Local repo vs external services: git/filesystem are local; providers, GitHub, MCP servers, and docs endpoints are external.
• Operational state vs long-term memory: sessions are transient, memory archives are durable, active memory is synthesized.
• Core product vs autonomous maintenance: the binary and its commands are one layer; evolution/social/synthesis scripts and GitHub Actions are another.
Overall, this repository is best understood as a self-hosted, terminal-native coding agent with a strong separation between conversational control, local repository actions, persistent context, and autonomous maintenance workflows.
Main entry points: commands.rs Commands · prompt.rs Prompt · main.rs Main · repl.rs REPL
Components 20
Core runtime
Terminal agent entrypoint, REPL, prompt assembly, output, and setup.
- Main · Launches the agent, loads config, selects mode, and starts a session.
src/main.rs - CLI · Parses flags and startup options that shape runtime behavior.
src/cli.rs - REPL · Runs the terminal conversation loop, input handling, and command dispatch.
src/repl.rs - Format · Formats markdown, diffs, tokens, and assistant output for the terminal.
src/format.rs - Setup · Handles first-run preparation and environment setup.
src/setup.rs - Docs · Stores command metadata and help text for the CLI experience.
src/help.rs
Command plane
Slash-command dispatch and domain-specific local operations.
- Git · Provides repository state, diffs, commits, and branch-aware operations.
src/git.rs - Commands · Routes slash commands to domain-specific handlers.
src/commands.rs - Git commands · Implements commit, diff, review, PR, and status-oriented commands.
src/commands_git.rs - Project commands · Runs health, test, lint, index, tree, search, and docs lookup commands.
src/commands_project.rs - File commands · Handles file-centric command flows and local edits.
src/commands_file.rs - Search commands · Provides search and code-finding command flows.
src/commands_search.rs - Dev commands · Supports development-oriented internal command flows.
src/commands_dev.rs
State and context
Session persistence, prompt context, memory, and identity inputs.
Automation and integrations
Self-evolution scripts, GitHub workflows, skills, docs, and site publishing.
- Skills · Loads capability packs from skill markdown files with frontmatter.
skills - Scripts · Orchestrates evolution, synthesis, social posting, and site generation jobs.
scripts - Workflows · Runs CI, release, pages publishing, and scheduled evolution pipelines.
.github/workflows - Site · Generated public documentation and journey site artifacts.
docs
Connections 24
- Main → CLI: parse · Startup options flow into runtime mode selection.
- Main → REPL: start · Interactive mode enters the terminal loop.
- Main → Setup: bootstrap · First-run setup prepares the environment.
- Main → Sessions: resume · Startup restores prior session state when available.
- REPL → Commands: dispatch · Slash commands bypass normal model chat flow.
- REPL → Prompt: build context · Conversation state is converted into model input.
- REPL → Format: render · Assistant text and tool results are displayed in the terminal.
- Commands → Git commands: route · Git-oriented commands are delegated to their handler.
- Commands → Project commands: route · Project inspection commands are delegated to their handler.
- Commands → Sessions: route · Session management commands operate on persisted state.
- Commands → File commands: route · File-focused commands are handled separately.
- Commands → Search commands: route · Search-focused commands are handled separately.
- Commands → Dev commands: route · Internal development commands are handled separately.
- Git commands → Git: use · Git commands depend on repository state and operations.
- Prompt → Memory: load · Project memory is injected into the request context.
- Prompt → Sessions: load · Recent conversation and compaction state shape the prompt.
- Prompt → Git: inject · Git state and changed files influence the model context.
- Prompt → Skills: include · Loaded skills contribute capability-specific instructions.
- Prompt → Docs: include · Help and command metadata support user-facing guidance.
- Scripts → Memory: synthesize · Automation compresses raw learnings into active context.
- Scripts → Site: build · Documentation and journey artifacts are generated for publication.
- Workflows → Scripts: run · GitHub Actions execute the automation pipeline on schedules and events.
- Workflows → Site: publish · Pages workflow publishes generated documentation artifacts.
- Skills → Commands: extend · Skills broaden the agent's commandable capabilities.