# yologdev/yoyo-evolve architecture

> Architecture diagram of the GitHub repository yologdev/yoyo-evolve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yologdev/yoyo-evolve
- Repository: https://github.com/yologdev/yoyo-evolve

## Overview

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: [`src/commands.rs`](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands.rs) (Commands), [`src/prompt.rs`](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/prompt.rs) (Prompt), [`src/main.rs`](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/main.rs) (Main), [`src/repl.rs`](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/repl.rs) (REPL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Core runtime"
  main(("Main<br/>binary entrypoint<br/>[main.rs]"))
  cli["CLI<br/>argument parsing<br/>[cli.rs]"]
  repl["REPL<br/>interactive loop<br/>[repl.rs]"]
  format["Format<br/>terminal rendering<br/>[format.rs]"]
  setup["Setup<br/>onboarding<br/>[setup.rs]"]
  docs["Docs<br/>help content<br/>[help.rs]"]
end

subgraph "Command plane"
  git["Git<br/>repo integration<br/>[git.rs]"]
  commands["Commands<br/>dispatcher<br/>[commands.rs]"]
  gitcmd["Git commands<br/>git control<br/>[commands_git.rs]"]
  projcmd["Project commands<br/>project tools"]
  filecmd["File commands<br/>file ops<br/>[commands_file.rs]"]
  searchcmd["Search commands<br/>search ops<br/>[commands_search.rs]"]
  devcmd["Dev commands<br/>internal tools<br/>[commands_dev.rs]"]
end

subgraph "State and context"
  prompt["Prompt<br/>context builder<br/>[prompt.rs]"]
  memory[("Memory<br/>[memory.rs]")]
  session[("Sessions<br/>chat state")]
end

subgraph "Automation and integrations"
  skills["Skills<br/>markdown extensions"]
  scripts["Scripts<br/>automation pipeline"]
  workflows["Workflows<br/>github actions<br/>[workflows]"]
  site["Site<br/>published docs"]
end

main -->|"parse"| cli
main -->|"start"| repl
main -->|"bootstrap"| setup
main -->|"resume"| session
repl -->|"dispatch"| commands
repl -->|"build context"| prompt
repl -->|"render"| format
commands -->|"route"| gitcmd
commands -->|"route"| projcmd
commands -->|"route"| session
commands -->|"route"| filecmd
commands -->|"route"| searchcmd
commands -->|"route"| devcmd
gitcmd -->|"use"| git
prompt -->|"load"| memory
prompt -->|"load"| session
prompt -->|"inject"| git
prompt -->|"include"| skills
prompt -->|"include"| docs
scripts -->|"synthesize"| memory
scripts -->|"build"| site
workflows -->|"run"| scripts
workflows -->|"publish"| site
skills -.->|"extend"| commands

click main "https://github.com/yologdev/yoyo-evolve/blob/main/src/main.rs"
click cli "https://github.com/yologdev/yoyo-evolve/blob/main/src/cli.rs"
click repl "https://github.com/yologdev/yoyo-evolve/blob/main/src/repl.rs"
click prompt "https://github.com/yologdev/yoyo-evolve/blob/main/src/prompt.rs"
click memory "https://github.com/yologdev/yoyo-evolve/blob/main/src/memory.rs"
click session "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands_session.rs"
click git "https://github.com/yologdev/yoyo-evolve/blob/main/src/git.rs"
click commands "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands.rs"
click gitcmd "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands_git.rs"
click projcmd "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands_project.rs"
click filecmd "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands_file.rs"
click searchcmd "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands_search.rs"
click devcmd "https://github.com/yologdev/yoyo-evolve/blob/main/src/commands_dev.rs"
click format "https://github.com/yologdev/yoyo-evolve/blob/main/src/format.rs"
click setup "https://github.com/yologdev/yoyo-evolve/blob/main/src/setup.rs"
click docs "https://github.com/yologdev/yoyo-evolve/blob/main/src/help.rs"
click skills "https://github.com/yologdev/yoyo-evolve/tree/main/skills"
click scripts "https://github.com/yologdev/yoyo-evolve/tree/main/scripts"
click workflows "https://github.com/yologdev/yoyo-evolve/blob/main/.github/workflows"
click site "https://github.com/yologdev/yoyo-evolve/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class main,cli,repl,format,setup,docs toneBlue
class git,commands,gitcmd,projcmd,filecmd,searchcmd,devcmd toneAmber
class prompt,memory,session toneMint
class skills,scripts,workflows,site toneRose
```

## Components

### Core runtime

Terminal agent entrypoint, REPL, prompt assembly, output, and setup.

- [Main](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/main.rs): binary entrypoint · Launches the agent, loads config, selects mode, and starts a session. · `src/main.rs`
- [CLI](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/cli.rs): argument parsing · Parses flags and startup options that shape runtime behavior. · `src/cli.rs`
- [REPL](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/repl.rs): interactive loop · Runs the terminal conversation loop, input handling, and command dispatch. · `src/repl.rs`
- [Format](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/format.rs): terminal rendering · Formats markdown, diffs, tokens, and assistant output for the terminal. · `src/format.rs`
- [Setup](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/setup.rs): onboarding · Handles first-run preparation and environment setup. · `src/setup.rs`
- [Docs](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/help.rs): help content · Stores command metadata and help text for the CLI experience. · `src/help.rs`

### Command plane

Slash-command dispatch and domain-specific local operations.

- [Git](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/git.rs): repo integration · Provides repository state, diffs, commits, and branch-aware operations. · `src/git.rs`
- [Commands](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands.rs): dispatcher · Routes slash commands to domain-specific handlers. · `src/commands.rs`
- [Git commands](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands_git.rs): git control · Implements commit, diff, review, PR, and status-oriented commands. · `src/commands_git.rs`
- [Project commands](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands_project.rs): project tools · Runs health, test, lint, index, tree, search, and docs lookup commands. · `src/commands_project.rs`
- [File commands](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands_file.rs): file ops · Handles file-centric command flows and local edits. · `src/commands_file.rs`
- [Search commands](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands_search.rs): search ops · Provides search and code-finding command flows. · `src/commands_search.rs`
- [Dev commands](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands_dev.rs): internal tools · Supports development-oriented internal command flows. · `src/commands_dev.rs`

### State and context

Session persistence, prompt context, memory, and identity inputs.

- [Prompt](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/prompt.rs): context builder · Assembles system and project context for each model request. · `src/prompt.rs`
- [Memory](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/memory.rs): project memory · Persists and loads long-lived project notes and learned context. · `src/memory.rs`
- [Sessions](https://github.com/yologdev/yoyo-evolve/blob/HEAD/src/commands_session.rs): chat state · Manages session save, load, resume, compaction, and token/cost tracking. · `src/commands_session.rs`

### Automation and integrations

Self-evolution scripts, GitHub workflows, skills, docs, and site publishing.

- [Skills](https://github.com/yologdev/yoyo-evolve/tree/HEAD/skills): markdown extensions · Loads capability packs from skill markdown files with frontmatter. · `skills`
- [Scripts](https://github.com/yologdev/yoyo-evolve/tree/HEAD/scripts): automation pipeline · Orchestrates evolution, synthesis, social posting, and site generation jobs. · `scripts`
- [Workflows](https://github.com/yologdev/yoyo-evolve/blob/HEAD/.github/workflows): github actions · Runs CI, release, pages publishing, and scheduled evolution pipelines. · `.github/workflows`
- [Site](https://github.com/yologdev/yoyo-evolve/tree/HEAD/docs): published docs · Generated public documentation and journey site artifacts. · `docs`

## Connections

- 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.
