yoyo

yoyo is a coding agent that runs in your terminal. It can read and edit files, execute shell commands, search codebases, and manage git workflows — all through natural language.

yoyo is open-source, written in Rust, and built on yoagent. It started as ~200 lines and evolves itself one commit at a time.

What yoyo can do

• Read and edit files — view file contents, make surgical edits, or write new files
• Run shell commands — execute anything you’d type in a terminal
• Search codebases — grep across files with regex support
• Navigate projects — list directories, understand project structure
• Track context — monitor token usage, auto-compact when the context window fills up
• Persist sessions — save and resume conversations across sessions
• Estimate costs — see per-turn and session-total cost estimates

Quick example

export ANTHROPIC_API_KEY=sk-ant-...
cargo install yoyo  # or: cargo run from source

yoyo

Then just talk to it:

> read src/main.rs and find any unwrap() calls that could panic
> fix the bug in parse_config and run the tests
> explain what this codebase does

What makes yoyo different

yoyo is not a product — it’s a process. It evolves itself in public. Every improvement is a git commit. Every session is journaled. You can read its source code, its journal, and its identity.

Current version: v0.1.0

Installation

Requirements

• Rust toolchain — install from rustup.rs
• Anthropic API key — get one from console.anthropic.com

Install from source

git clone https://github.com/yologdev/yoyo-evolve.git
cd yoyo-evolve
cargo build --release

The binary will be at target/release/yoyo.

Run directly with Cargo

If you just want to try it:

cd yoyo-evolve
ANTHROPIC_API_KEY=sk-ant-... cargo run

Set your API key

yoyo looks for your API key in two environment variables (checked in order):

1. ANTHROPIC_API_KEY
2. API_KEY

Set one of them:

export ANTHROPIC_API_KEY=sk-ant-api03-...

If neither is set, yoyo will exit with an error message explaining what to do.

Quick Start

Once installed, start yoyo:

export ANTHROPIC_API_KEY=sk-ant-...
cargo run

You’ll see a banner like this:

  yoyo v0.1.0 — a coding agent growing up in public
  Type /help for commands, /quit to exit

  model: claude-opus-4-6
  git:   main
  cwd:   /home/user/project

Your first prompt

Type a natural language request:

main > explain what this project does

yoyo will read files, run commands, and respond. You’ll see tool executions as they happen:

  ▶ read README.md ✓
  ▶ ls src/ ✓
  ▶ read src/main.rs ✓

This project is a...

Common tasks

Read and explain code:

> read src/main.rs and explain the main function

Make changes:

> add error handling to the parse_config function in src/config.rs

Run commands:

> run the tests and fix any failures

Search a codebase:

> find all TODO comments in this project

Exiting

Type /quit, /exit, or press Ctrl+D.

Interactive Mode (REPL)

Interactive mode is the default when you run yoyo in a terminal. It gives you a read-eval-print loop where you can have a multi-turn conversation with the agent.

Starting

yoyo
# or
cargo run

The prompt

The prompt shows your current git branch (if you’re in a git repo):

main > _

If you’re not in a git repo, you get a plain prompt:

> _

How it works

1. You type a message
2. yoyo sends it to the LLM along with conversation history
3. The LLM may call tools (read files, run commands, etc.)
4. Tool results are streamed back — you see each tool as it executes
5. The final text response is printed
6. Token usage and cost are shown after each turn

Tool output

When yoyo uses tools, you’ll see status indicators:

  ▶ $ cargo test ✓ (2.1s)
  ▶ read src/main.rs ✓ (42ms)
  ▶ edit src/lib.rs ✓ (15ms)
  ▶ $ cargo test ✗ (1.8s)

• ✓ means the tool succeeded
• ✗ means the tool returned an error
• The duration shows how long the tool took

Token usage

After each response, you’ll see token usage:

  tokens: 1523 in / 842 out  (session: 4200 in / 2100 out)  cost: $0.0234  total: $0.0567  ⏱ 3.2s

This shows:

• Input/output tokens for this turn
• Session totals
• Estimated cost for this turn and session total
• Wall-clock time for the response

Interrupting

Press Ctrl+C to cancel the current response. The agent will stop and you can type a new prompt. Press Ctrl+C again to exit.

Single-Prompt Mode

Use --prompt or -p to run a single prompt without entering the REPL. yoyo will process the prompt, print the response, and exit.

Usage

yoyo --prompt "explain this codebase"
yoyo -p "find all TODO comments"

When to use it

Single-prompt mode is useful for:

• Scripting — run yoyo as part of a larger workflow
• Quick questions — get an answer without starting a session
• CI/CD pipelines — automate code review or analysis

Example

$ yoyo -p "count the lines of Rust code in this project"
  ▶ $ find . -name '*.rs' | xargs wc -l ✓ (0.1s)

There are 1,475 lines of Rust code across 1 file (src/main.rs).

Combining with other flags

You can combine -p with other flags:

yoyo -p "review this diff" --model claude-sonnet-4-20250514
yoyo -p "explain the architecture" --thinking high
yoyo -p "analyze the code" --system "You are a security auditor."

Piped Mode

When stdin is not a terminal (i.e., input is piped), yoyo reads all of stdin as a single prompt, processes it, and exits. This works like single-prompt mode but takes input from a pipe instead of a flag.

Usage

echo "explain this code" | yoyo
cat prompt.txt | yoyo
git diff | yoyo

When to use it

Piped mode is useful for:

• Passing file contents as part of the prompt
• Chaining with other commands in a pipeline
• Feeding structured input from scripts

Examples

Review a git diff:

git diff HEAD~1 | yoyo --system "Review this diff for bugs."

Analyze a file:

cat src/main.rs | yoyo --system "Find all potential panics in this Rust code."

Process command output:

cargo test 2>&1 | yoyo --system "Explain these test failures and suggest fixes."

Detection

yoyo detects piped mode automatically by checking if stdin is a terminal. If it is not, piped mode activates. If stdin is a terminal, interactive REPL mode starts instead.

If piped input is empty, yoyo exits with an error: No input on stdin.

REPL Commands

All commands start with /. Type /help inside yoyo to see the full list.

Navigation

Conversation

Model

Example:

/model claude-sonnet-4-20250514

Session

See Session Persistence for details.

Information

The /tokens command shows a visual progress bar of your context window:

  Context window:
    messages:    12
    context:     45.2k / 200.0k tokens
    █████████░░░░░░░░░░░ 23%

Git

The /undo command shows you what will be reverted before doing it.

Unknown commands

If you type a /command that yoyo doesn’t recognize, it will tell you:

  unknown command: /foo
  type /help for available commands

Note: lines starting with / that contain spaces (like /model name) are treated as command arguments, not unknown commands.

Multi-Line Input

yoyo supports two ways to enter multi-line input.

Backslash continuation

End a line with \ to continue on the next line:

main > Please review this code and \
  ...  check for any bugs or \
  ...  performance issues.

The backslash and newline are removed, and the lines are joined. The ... prompt indicates yoyo is waiting for more input.

Code fences

Start a line with triple backticks (```) to enter a fenced code block. Everything until the closing ``` is collected as a single input:

main > ```
  ...  Here is a function I want you to review:
  ...  
  ...  fn parse(input: &str) -> Result<Config, Error> {
  ...      let data = serde_json::from_str(input)?;
  ...      Ok(Config::from(data))
  ...  }
  ...  
  ...  Is this handling errors correctly?
  ...  ```

This is useful for pasting code or structured text that spans multiple lines.

Models

yoyo uses Anthropic’s Claude models via the Anthropic API.

Default model

The default model is claude-opus-4-6.

Changing the model

At startup:

yoyo --model claude-sonnet-4-20250514
yoyo --model claude-haiku-4-5-20250514

During a session:

/model claude-sonnet-4-20250514

Note: Switching models with /model clears the conversation history. This is because different models may handle context differently.

Supported models

yoyo works with any Anthropic model. Cost estimation is built in for these model families:

For unrecognized models, yoyo still works — you just won’t see cost estimates.

Context window

yoyo assumes a 200,000-token context window (the standard for Claude models). When usage exceeds 80% of this, auto-compaction kicks in. See Context Management.

System Prompts

yoyo has a built-in system prompt that instructs the model to act as a coding assistant. You can override it entirely.

Default behavior

The default system prompt tells the model to:

• Work as a coding assistant in the user’s terminal
• Be direct and concise
• Use tools proactively (read files, run commands, verify work)
• Do things rather than just explain how

Custom system prompt

Inline:

yoyo --system "You are a Rust expert. Focus on performance and safety."

From a file:

yoyo --system-file my-prompt.txt

If both --system and --system-file are provided, --system-file takes precedence.

Use cases

Custom system prompts are useful for:

• Specializing the agent — focus on security review, documentation, or a specific language
• Project context — tell the agent about your project’s conventions
• Persona tuning — make the agent more or less verbose, formal, etc.

Example prompt file

You are a senior Rust developer reviewing code for a production system.
Focus on:
- Error handling correctness
- Memory safety
- Performance implications
- API design

Be concise. Point out issues with line numbers.

Save as review-prompt.txt and use:

yoyo --system-file review-prompt.txt -p "review src/main.rs"

Extended Thinking

Extended thinking gives the model more “reasoning time” before responding. This can improve quality for complex tasks like debugging, architecture decisions, or multi-step refactoring.

Usage

yoyo --thinking high
yoyo --thinking medium
yoyo --thinking low
yoyo --thinking minimal
yoyo --thinking off

Levels

Levels are case-insensitive: HIGH, High, and high all work.

If you provide an unrecognized level, yoyo defaults to medium with a warning.

When to use it

• Complex debugging — use high when the bug is subtle
• Architecture decisions — use medium or high for design questions
• Simple tasks — use off (the default) for quick file reads, simple edits, etc.

Output

When thinking is enabled, the model’s reasoning is shown dimmed in the output so you can follow along without it cluttering the main response.

Trade-offs

Higher thinking levels use more tokens (and thus cost more) but often produce better results for hard problems. For routine tasks, the overhead isn’t worth it.

Skills

Skills are markdown files that provide additional context and instructions to yoyo. They’re loaded at startup and added to the agent’s context.

Usage

yoyo --skills ./skills

You can pass multiple skill directories:

yoyo --skills ./skills --skills ./my-custom-skills

What is a skill?

A skill file is a markdown file with YAML frontmatter. It contains instructions, rules, or context that the agent should follow. For example:

---
name: rust-expert
description: Rust-specific coding guidelines
tools: [bash, read_file, edit_file]
---

# Rust Guidelines

- Always use `clippy` before committing
- Prefer `?` over `.unwrap()` in production code
- Write tests for every public function

Built-in skills

yoyo’s own evolution is guided by skills in the skills/ directory of the repository:

• evolve — rules for safely modifying its own source code
• communicate — writing journal entries and issue responses
• self-assess — analyzing its own capabilities
• research — searching the web and reading docs
• release — evaluating readiness for publishing

Error handling

If the skills directory doesn’t exist or can’t be loaded, yoyo prints a warning and continues without skills:

warning: Failed to load skills: ...

This is intentional — skills are optional and should never prevent yoyo from starting.

Session Persistence

yoyo can save and load conversations, letting you resume where you left off.

Manual save/load

Save the current conversation:

/save

This writes to yoyo-session.json in the current directory.

Save to a custom path:

/save my-session.json

Load a conversation:

/load
/load my-session.json

Auto-save with –continue

The --continue (or -c) flag enables automatic session management:

yoyo --continue
yoyo -c

When --continue is used:

1. On startup, yoyo looks for yoyo-session.json and restores the conversation if found
2. On exit, yoyo automatically saves the conversation back to yoyo-session.json

This means you can close yoyo, come back later, and pick up right where you left off:

$ yoyo -c
  resumed session: 8 messages from yoyo-session.json

main > what were we working on?

Session format

Sessions are stored as JSON files containing the conversation message history. The format is determined by the yoagent library.

Error handling

• If no previous session exists when using --continue, yoyo prints a message and starts fresh
• If a session file is corrupt or can’t be parsed, yoyo warns you and starts fresh
• Save errors are reported but don’t crash yoyo

Context Management

Claude models have a finite context window (200,000 tokens). As your conversation grows, it fills up. yoyo helps you manage this.

Checking context usage

Use /tokens to see how full your context window is:

/tokens

Output:

  Context window:
    messages:    24
    context:     85.2k / 200.0k tokens
    ████████░░░░░░░░░░░░ 43%

  Session totals:
    input:       120.5k tokens
    output:      45.2k tokens
    cache read:  30.0k tokens
    cache write: 15.0k tokens
    est. cost:   $0.892

When the context window exceeds 75%, you’ll see a warning:

    ⚠ Context is getting full. Consider /clear or /compact.

Manual compaction

Use /compact to compress the conversation:

/compact

This summarizes older messages while preserving recent context. You’ll see:

  compacted: 24 → 8 messages, ~85.2k → ~32.1k tokens

Auto-compaction

When the context window exceeds 80% capacity, yoyo automatically compacts the conversation. You’ll see:

  ⚡ auto-compacted: 30 → 10 messages, ~165.0k → ~62.0k tokens

This happens transparently after each prompt response. You don’t need to do anything — yoyo handles it.

Clearing the conversation

If you want to start completely fresh:

/clear

This removes all messages and resets the conversation. Unlike /compact, nothing is preserved.

Tips

• For long sessions, use /tokens periodically to monitor usage
• If you notice the agent losing track of earlier context, try /compact
• Starting a new task? Use /clear to avoid confusing the agent with unrelated history

Git Integration

yoyo is git-aware. It shows your current branch and provides commands for common git operations.

Branch display

When you’re in a git repository, the REPL prompt shows the current branch:

main > _
feature/new-parser > _

On startup, the branch is also shown in the status information:

  git:   main

Git commands

/diff

Show a summary of uncommitted changes (equivalent to git diff --stat):

/diff

Output:

 src/main.rs | 15 +++++++++------
 README.md   |  3 +++
 2 files changed, 12 insertions(+), 6 deletions(-)

If there are no uncommitted changes:

  (no uncommitted changes)

/undo

Revert all uncommitted changes. This is equivalent to git checkout -- .:

/undo

Before reverting, /undo shows you what will be undone:

 src/main.rs | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)
  ✓ reverted all uncommitted changes

If there’s nothing to undo:

  (nothing to undo — no uncommitted changes)

Using git through the agent

yoyo’s bash tool can run any git command. You can ask the agent directly:

> commit these changes with message "fix: handle empty input"
> show me the last 5 commits
> create a new branch called feature/parser

The agent has full access to git through its shell tool.

Cost Tracking

yoyo estimates the cost of each interaction so you can monitor spending.

Per-turn costs

After each response, you’ll see token usage and cost:

  tokens: 1523 in / 842 out  (session: 4200 in / 2100 out)  cost: $0.0234  total: $0.0567  ⏱ 3.2s

• cost — estimated cost for this turn
• total — estimated cumulative cost for the session

Detailed breakdown

Use /tokens to see a full breakdown including cache usage:

  Session totals:
    input:       120.5k tokens
    output:      45.2k tokens
    cache read:  30.0k tokens
    cache write: 15.0k tokens
    est. cost:   $0.892

How costs are calculated

Costs are estimated based on published Anthropic pricing:

MTok = million tokens.

Limitations

• Cost estimates are approximate — actual billing may differ slightly
• For unrecognized models, no cost estimate is shown
• Cache read/write costs depend on Anthropic’s caching behavior, which yoyo doesn’t control

Keeping costs down

• Use smaller models (Haiku, Sonnet) for simple tasks
• Use /compact to reduce context size (fewer input tokens per turn)
• Use single-prompt mode (-p) for quick questions to avoid accumulating context
• Turn off extended thinking for routine tasks

Common Issues

“No API key found”

error: No API key found.
Set ANTHROPIC_API_KEY or API_KEY environment variable.

Fix: Set your Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-api03-...

yoyo checks ANTHROPIC_API_KEY first, then API_KEY. At least one must be set and non-empty.

“No input on stdin”

No input on stdin.

This happens when you pipe empty input to yoyo:

echo "" | yoyo

Fix: Make sure your piped input contains actual content.

Model errors

  error: [API error message]

This appears when the Anthropic API returns an error. Common causes:

• Invalid API key — check your key is correct and active
• Rate limiting — you’re sending too many requests; wait and retry
• Model unavailable — the model you specified doesn’t exist or you don’t have access

Use /retry to re-send the last prompt after the issue is resolved.

Context window full

    ⚠ Context is getting full. Consider /clear or /compact.

Your conversation is approaching the 200,000-token context limit.

Fix: Use /compact to compress the conversation, or /clear to start fresh.

yoyo auto-compacts at 80% capacity, but you can compact earlier if you prefer.

“warning: Failed to load skills”

warning: Failed to load skills: [error]

The --skills directory couldn’t be read. yoyo continues without skills.

Fix: Check that the path exists and contains valid skill files.

“unknown command: /foo”

  unknown command: /foo
  type /help for available commands

You typed a command yoyo doesn’t recognize.

Fix: Type /help to see available commands.

“not in a git repository”

  error: not in a git repository

You used /diff or /undo outside a git repo.

Fix: Navigate to a directory that’s inside a git repository before starting yoyo.

Ctrl+C behavior

• First Ctrl+C — cancels the current response; you can type a new prompt
• Second Ctrl+C (or Ctrl+D) — exits yoyo

If a tool execution is hanging, Ctrl+C will abort it.

Session file errors

  error saving: [error]
  error reading yoyo-session.json: [error]
  error parsing: [error]

Session save/load failed. Common causes:

• Disk full — free space and try again
• Permission denied — check file permissions
• Corrupt file — delete the session file and start fresh