This guide walks you through your first conversation with Ryvos. You should have already installed Ryvos and run ryvos init.

Your First Command

The simplest way to use Ryvos is the run command:

ryvos run "hello, what can you do?"

Here is what happens under the hood:

1. Ryvos loads your config from ~/.ryvos/config.toml
2. Builds the context stack (identity, narrative, focus layers)
3. Sends your prompt to the configured LLM provider
4. Streams the response back to your terminal in real time

You will see streaming output like this:

▶ ryvos run "hello, what can you do?"
[session: a1b2c3d4]

I'm Ryvos, your AI agent runtime. Here's what I can do:

• Execute shell commands and scripts
• Read, write, and edit files
• Search codebases with grep and glob
• Manage Git repositories
• Run HTTP requests and web searches
• Query databases (SQLite)
• Automate browser interactions
• Manage memory across conversations
• Schedule recurring tasks via cron
• Communicate across Telegram, Discord, Slack, and WhatsApp

What would you like to work on?

Five Ways to Interact

Ryvos offers multiple interaction modes for different workflows:

REPL

The interactive Read-Eval-Print Loop is the default mode when you run ryvos with no arguments:

ryvos

╭──────────────────────────────╮
│  ryvos v0.6.5                │
│  Model: claude-sonnet-4-20250514   │
│  Session: new                │
╰──────────────────────────────╯

You > List all Rust files in this directory

Type your messages interactively. The session persists until you type exit or press Ctrl+C.

Single Run

Execute a single prompt and exit:

ryvos run "refactor the error handling in src/main.rs to use thiserror"

Useful for scripting and CI/CD pipelines. Combine with --json for machine-readable output.

TUI

A full terminal UI with panels for chat, tool output, and status:

ryvos tui

The TUI provides:

• Split-pane chat and tool output view
• Real-time streaming display
• Keyboard navigation (arrows, Enter, Ctrl+C)
• Adaptive banner with session info

Daemon

Always-on mode with all channels active:

ryvos daemon --gateway

This starts:

• All configured channel adapters (Telegram, Discord, etc.)
• Web UI at http://localhost:18789
• Viking memory server at http://localhost:1933 (if enabled)
• Heartbeat monitoring
• Cron scheduled tasks

Gateway

HTTP/WebSocket API server for programmatic access:

ryvos serve

Exposes the REST and WebSocket API at http://localhost:18789 without starting channel adapters.

A Real Example: Code Review

Let Ryvos review a file in your project:

cd ~/my-project
ryvos run "review src/lib.rs for potential bugs and suggest improvements"

Ryvos will:

1. Read the file using the read tool
2. Analyze the code for issues (error handling, edge cases, performance)
3. Search related files with grep if it needs context
4. Report findings with specific line references and suggested fixes

▶ Analyzing src/lib.rs...
  [tool: read] Reading src/lib.rs (247 lines)
  [tool: grep] Searching for unwrap() calls...

Found 3 issues:

1. Line 42: `unwrap()` on network response — will panic on timeout
   Fix: Use `map_err()` or `?` operator with custom error type

2. Line 89: SQL query built with string concatenation
   Fix: Use parameterized queries to prevent injection

3. Line 156: Mutex lock held across async `.await`
   Fix: Scope the lock guard before the await point

Working with Tools

Ryvos has 86+ built-in tools. You do not need to invoke them directly — the agent decides which tools to use based on your request. But understanding the categories helps you craft better prompts:

Resume a Session

Every run gets a session ID. You can resume a previous session:

# List recent sessions
ryvos run --list-sessions
 
# Resume a specific session
ryvos run --resume a1b2c3d4 "continue where we left off"

Session history is stored in SQLite with WAL mode for crash safety. Your conversation context, tool calls, and results are all preserved.

Workspace Files

Ryvos reads special files from your workspace directory to customize behavior:

Create any of these in your project root or ~/.ryvos/ to customize the agent.

:::tip Start with SOUL.md to give your agent a personality. Run ryvos soul for an interactive interview that generates this file for you. :::

What Happens Behind the Scenes

When you send a message, Ryvos executes a ReAct loop:

User prompt
    ↓
┌─────────────────────────────┐
│  1. Load context (3 layers) │
│  2. Estimate token budget   │
│  3. Send to LLM             │
│  4. Parse response           │
│  5. Execute tool calls       │
│  6. Append results           │
│  7. Check guardian limits    │
│  8. Loop or return answer    │
└─────────────────────────────┘
    ↓
Final response

The loop continues for up to 25 turns (configurable) or 600 seconds, whichever comes first. If the context grows too large, Ryvos automatically compacts it by summarizing older messages.

Next Steps

• Configuration Reference — Customize every aspect of Ryvos
• LLM Providers — Configure your preferred AI model
• CLI Reference — All commands and flags
• Built-in Tools — Explore all 86+ tools
• Memory System — Understand how Ryvos remembers