sven

# Agent Sven

**A keyboard-driven AI agent for the terminal and desktop.** Built in Rust, sven
works as an interactive TUI, a Slint desktop GUI (`sven-ui`), a headless CI
runner, a networked node that teams up with other sven instances, and a
proactive personal automation platform — two binaries, one agent.

[![CI](https://github.com/swedishembedded/sven/actions/workflows/ci.yml/badge.svg)](https://github.com/swedishembedded/sven/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-informational)](CHANGELOG.md)

![sven TUI showing a live chat session with streamed markdown response and vim-style navigation](docs/sven-landing.png)

Give sven a task in plain English. It reads your code, runs commands, writes
files, searches the web, and delegates subtasks to peer agents — all
autonomously, all in your terminal. Beyond interactive sessions, sven runs 24/7
as a proactive agent: checking email and calendar, sending briefings via
Telegram, making voice calls, and running scheduled workflows.

## Key Features

- **Interactive TUI** — Full-screen Ratatui interface with scrollable markdown chat, vim-style navigation, and live-streamed responses. Swap to an embedded Neovim buffer with `--nvim`.
- **Desktop GUI** — `sven-ui` is a native Slint window with the full agent and tool suite, no terminal required.
- **Headless / CI** — Reads from stdin or a markdown workflow file, writes clean text to stdout. Pipeable: chain sven instances to build multi-agent pipelines.
- **Markdown workflow files** — `##`-headed steps, YAML frontmatter, per-step directives, and variable templating make `.md` files first-class agent programs (unique to sven).
- **Agent networking** — Multiple sven nodes discover each other via mDNS (or a relay), and the LLM gains `list_peers` and `delegate_task` tools to route work across machines.
- **GDB hardware debugging** — First AI agent with native GDB integration: connects to a target, loads firmware, sets breakpoints, and inspects registers, all autonomously.
- **Proactive automation** — Scheduler, email (IMAP/Gmail), calendar (CalDAV/Google), voice (TTS/STT/calls), semantic memory, and 6 messaging channels run 24/7 as a node.
- **Skills system** — Markdown instruction files the agent loads on demand for coding standards, project conventions, or multi-step procedures.
- **32 model providers** — OpenAI, Anthropic, Gemini, Ollama, and 28 more — no external gateway, pure Rust.
- **MCP — server and client** — Expose sven's tools to Cursor, Claude Desktop, and other MCP hosts; or connect sven to external MCP servers (including OAuth-protected ones) and use their tools directly inside any session.
- **ACP** — Drive sven from Zed, VS Code, or JetBrains via the Agent Client Protocol; no daemon, no IDE key, sven manages its own model.
- **Large-content analysis** — RLM context tools (`context_open`, `context_query`, `context_reduce`) memory-map files and codebases far larger than any context window and analyse them via parallel sub-agent chunking.
- **Knowledge base** — `.sven/knowledge/*.md` documents encode project facts; sven auto-detects drift when source files change after a document's `updated:` date and warns at session start.
- **Terminal-native, zero runtime deps** — Structured text in, structured text out. No Node.js, no Python, no screenshots, no pixel-clicking.

## Quick Start

**Prerequisites:** Rust toolchain, API key for at least one supported provider (e.g. `OPENROUTER_API_KEY` for zero-config start with `openrouter/auto`).

```sh
# Build and run
make release && ./target/release/sven

# Pipe a one-shot task
echo "Summarise the project" | sven

# Run a multi-step workflow file
sven --file plan.md
```

See [Installation](docs/01-installation.md) and [Quick Start](docs/02-quickstart.md) for full setup details.

Install shell completions:

```sh
sven completions bash >> ~/.bashrc      # also: zsh, fish, powershell
```

## Agent modes

| Mode | Behaviour |
|------|-----------|
| `research` | Read-only tools. Good for exploration and analysis. |
| `plan` | No file writes. Produces structured plans without side effects. |
| `agent` | Full read/write access. Default for interactive use. |

Set with `--mode` or cycle live in the TUI with `F4`.

## Conversation history

```sh
sven chats                  # list saved conversations (ID, date, turns, title)
sven --resume               # pick a conversation to resume with fzf
sven --resume <ID>          # resume a specific conversation directly
```

## GDB-native hardware debugging

Sven is the **first AI agent with native GDB integration** for autonomous
embedded hardware debugging. Give it a plain-English task and it will start a
GDB server, connect to the target, load your firmware, set breakpoints, inspect
registers and variables, and report its findings — all without leaving your
terminal.

![sven GDB session showing autonomous breakpoint inspection on an embedded target](docs/sven-gdb-1.png)

| Tool | What it does |
|------|-------------|
| `gdb_start_server` | Start JLinkGDBServer / OpenOCD / pyocd (auto-discovers config from project files) |
| `gdb_connect` | Connect `gdb-multiarch --interpreter=mi3` and optionally load an ELF |
| `gdb_command` | Run any GDB/MI command and return structured output |
| `gdb_interrupt` | Send Ctrl+C to a running target |
| `gdb_wait_stopped` | Poll until the target halts (after a step, breakpoint, or interrupt) |
| `gdb_status` | Query the current run state and any pending stop events |
| `gdb_stop` | Kill the debug session and free the probe |

See [Example 11](docs/06-examples.md#example-11--embedded-gdb-debugging-session) and the [GDB section of the User Guide](docs/03-user-guide.md#gdb-debugging-tools).

## Agent-to-agent task routing

Multiple sven nodes find each other on a local network via mDNS — or across
networks via a relay — and each node automatically gains two tools the LLM can
use during any session:

| Tool | What it does |
|------|-------------|
| `list_peers` | List connected peer agents with their name, description, and capabilities |
| `delegate_task` | Send a task to a named peer; the remote agent runs it through its own model+tool loop and returns the full result |

**Declarative agent teams** are defined in `.sven/teams/*.yaml`. Manage them with:

```sh
sven team start --file .sven/teams/myteam.yaml   # spawn all team members
sven team status myteam                           # show live task board
sven peer chat backend-agent                      # interactive session with any peer
```

See [docs/08-node.md](docs/08-node.md) for setup, relay configuration, and security.

## Proactive agent capabilities

When running as a node (`sven node start`), sven gains a full automation stack:

| Integration | What it does | Docs |
|-------------|--------------|------|
| **Messaging** (Telegram, Discord, WhatsApp, Signal, Matrix, IRC) | Reach your agent or let it reach you via any channel | [docs/12-channels.md](docs/12-channels.md) |
| **Scheduler** (cron, intervals, one-shot) | Run prompts on a schedule; the agent can also schedule jobs at runtime | [docs/13-scheduler.md](docs/13-scheduler.md) |
| **Email** (IMAP/SMTP, Gmail API) | List, read, send, reply to, and search email | [docs/14-email.md](docs/14-email.md) |
| **Calendar** (CalDAV, Google Calendar) | Query schedule, create and update events | [docs/15-calendar.md](docs/15-calendar.md) |
| **Voice** (ElevenLabs TTS, Whisper STT, Twilio calls) | Synthesize speech, transcribe audio, make outbound phone calls | [docs/16-voice.md](docs/16-voice.md) |
| **Semantic memory** (SQLite + FTS5 + embeddings) | Remember anything; recall with natural-language queries | [docs/17-memory.md](docs/17-memory.md) |
| **Webhooks** | Trigger the agent from any external system via a generic HTTP hook | [docs/18-webhooks.md](docs/18-webhooks.md) |

See [docs/19-use-cases.md](docs/19-use-cases.md

[truncated…]