{"id":46681956,"url":"https://github.com/swedishembedded/sven","last_synced_at":"2026-03-15T19:41:56.623Z","repository":{"id":340670127,"uuid":"1154877341","full_name":"swedishembedded/sven","owner":"swedishembedded","description":"Agent Sven: The Native Peer-to-Peer AI Agent","archived":false,"fork":false,"pushed_at":"2026-03-09T00:58:18.000Z","size":3588,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-09T03:22:07.403Z","etag":null,"topics":["ai-agent","coding","linux","p2p","runtime","terminal-based"],"latest_commit_sha":null,"homepage":"https://agentsven.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swedishembedded.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T21:53:34.000Z","updated_at":"2026-03-09T00:58:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"47505627-969c-4725-ad38-a9a2aed13905","html_url":"https://github.com/swedishembedded/sven","commit_stats":null,"previous_names":["swedishembedded/sven"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/swedishembedded/sven","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swedishembedded%2Fsven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swedishembedded%2Fsven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swedishembedded%2Fsven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swedishembedded%2Fsven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swedishembedded","download_url":"https://codeload.github.com/swedishembedded/sven/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swedishembedded%2Fsven/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30386961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","coding","linux","p2p","runtime","terminal-based"],"created_at":"2026-03-09T00:13:16.024Z","updated_at":"2026-03-11T16:00:56.352Z","avatar_url":"https://github.com/swedishembedded.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Sven\n\nA keyboard-driven AI coding agent for the terminal. Built in Rust, sven works\nas an interactive TUI, a headless CI runner, and a networked node that teams\nup with other sven instances — all from the same binary.\n\n![sven start](docs/sven-landing.png)\n\n---\n\n## What sven does\n\nGive sven a task in plain English. It reads your code, runs commands, writes\nfiles, searches the web, debugs hardware, and delegates subtasks to peer agents\n— all autonomously, all in your terminal.\n\n### Interactive TUI\n\nA full-screen Ratatui interface with a scrollable markdown chat log, vim-style\nnavigation, and live-streamed responses. Swap between a plain ratatui view and\nan embedded Neovim buffer with `--nvim`.\n\n### Headless / CI\n\nReads instructions from stdin or a markdown file, writes clean text to stdout,\nand exits with a meaningful code. Designed to compose with other tools via\npipes.  With a positional prompt and piped stdin (e.g. `cmd | sven \"fix these errors\"`),\nstdin is appended to the prompt with a blank line as one user message.  Workflow\nparsing (multi-step `##` sections) applies only when using `-f`/`--file`.\n\n```sh\n# Pipe a task\necho \"Summarise the project\" | sven\n\n# Multi-step workflow file (only -f uses ## steps)\nsven --file plan.md\n\n# Chain agents: plan → implement\nsven --file plan.md | sven --mode agent \"Implement the plan above.\"\n```\n\n### Node (agent + P2P + HTTP)\n\n```sh\nsven node start\n```\n\nRuns the full agent plus a P2P networking stack and an HTTPS/WebSocket\nendpoint. The node IS the agent — not a proxy. Multiple nodes discover each\nother automatically on a local network (or via a relay across the internet) and\ncan delegate work to each other.\n\n```sh\n# Send a task to a running node from the command line\nexport SVEN_NODE_TOKEN=\u003ctoken from first startup\u003e\nsven node exec \"delegate the database migration to backend-agent and the UI changes to frontend-agent\"\n```\n\n---\n\n## GDB-native hardware debugging\n\nSven is the **first AI agent with native GDB integration** for autonomous\nembedded hardware debugging. Give it a plain-English task and it will start a\nGDB server, connect to the target, load your firmware, set breakpoints, inspect\nregisters and variables, and report its findings — all without leaving your\nterminal.\n\n```\nYou: Use gdb tools to connect to the target, reset it, and set a breakpoint on\n     nrf uart tx function. Then inspect the parameters that are passed to it the\n     first time and show me what they are. Use zephyr.elf as the executable.\n```\n\nThe agent then autonomously calls the GDB tools in sequence:\n\n```\ngdb_start_server → gdb_connect → gdb_command (×N) → gdb_stop\n```\n\n![sven GDB session start](docs/sven-gdb-1.png)\n\n![sven GDB session result](docs/sven-gdb-2.png)\n\n![sven GDB session in Neovim](docs/sven-gdb-nvim.png)\n\n| Tool | What it does |\n|------|-------------|\n| `gdb_start_server` | Start JLinkGDBServer / OpenOCD / pyocd (auto-discovers config from project files) |\n| `gdb_connect` | Connect `gdb-multiarch --interpreter=mi3` and optionally load an ELF |\n| `gdb_command` | Run any GDB/MI command and return structured output |\n| `gdb_interrupt` | Send Ctrl+C to a running target |\n| `gdb_wait_stopped` | Poll until the target halts (after a step, breakpoint, or interrupt) |\n| `gdb_status` | Query the current run state and any pending stop events |\n| `gdb_stop` | Kill the debug session and free the probe |\n\nSee [Example 11](docs/06-examples.md#example-11--embedded-gdb-debugging-session)\nand the [User Guide GDB section](docs/03-user-guide.md#gdb-debugging-tools).\n\n---\n\n## Agent-to-agent task routing\n\nMultiple sven nodes find each other on a local network via mDNS — or across\nnetworks via a relay — and each node automatically gains two tools the LLM can\nuse during any session:\n\n| Tool | What it does |\n|------|-------------|\n| `list_peers` | List connected peer agents with their name, description, and capabilities |\n| `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 |\n\n```\nYou are the orchestrator for a small team. Use list_peers to find who is\nonline, then:\n1. Delegate the database migration to the backend-agent.\n2. Delegate the UI changes to the frontend-agent.\n3. Summarise what each agent did.\n```\n\nsven handles the rest — calling `list_peers`, picking the right peers, calling\n`delegate_task` for each, and assembling the results.\n\nSee [docs/08-node.md](docs/08-node.md) for setup, security, and configuration.\n\n---\n\n## Features\n\n### Workflow files — unique to sven\n\nsven treats markdown files as first-class workflow definitions:\n\n```markdown\n# Security Audit\n\nSystematic security review of the codebase.\n\n## Understand the codebase\n\u003c!-- sven: timeout=60 --\u003e\nRead the project structure and summarise the architecture.\n\n## Identify risks\n{{context}}\nLook for OWASP Top-10 issues and insecure defaults.\n\n## Write report\nProduce a structured security report with severity ratings.\n```\n\n```sh\nsven --file audit.md --var context=\"Focus on authentication.\"\n```\n\n| Feature | sven | Codex | Claude Code | OpenClaw |\n|---------|------|-------|-------------|----------|\n| Markdown workflow files (`##` steps) | ✓ native | — | — | — |\n| YAML frontmatter (mode, timeouts, vars) | ✓ | — | — | — |\n| Per-step options (`\u003c!-- sven: ... --\u003e`) | ✓ | — | — | — |\n| Variable templating (`{{key}}`) | ✓ | — | — | — |\n| Pipeable conversation output | ✓ full conv. | last msg only | last msg only | — |\n| `sven validate --file` dry-run | ✓ | — | — | — |\n| Per-step artifacts directory | ✓ | — | — | — |\n| `conversation` / `json` / `compact` / `jsonl` output | ✓ | `json` only | `stream-json` | `json` |\n| Auto-detect CI environment | ✓ GHA/GL/CircleCI/Travis/Jenkins/Azure/Bitbucket | — | — | — |\n| Git context injection (branch/commit/dirty) | ✓ | ✓ | partial | — |\n| Auto-load `AGENTS.md` / `.sven/context.md` / `CLAUDE.md` | ✓ all three | ✓ `AGENTS.md` | ✓ `CLAUDE.md` | ✓ `AGENTS.md` |\n| **Native GDB hardware debugging** | ✓ first-class | — | — | — |\n| **Agent-to-agent P2P task routing** | ✓ built-in | — | — | — |\n| **Skills system** | ✓ built-in | — | — | — |\n| Zero runtime dependencies | ✓ native Rust | ✓ native Rust | Node.js | Node.js |\n| TUI + headless + node in one binary | ✓ | separate | separate | separate |\n\n### Tool suite\n\nThe agent has a rich built-in toolset:\n\n| Category | Tools |\n|----------|-------|\n| **Files** | `read_file`, `write_file`, `edit_file`, `delete_file`, `list_dir` |\n| **Search** | `find_file`, `grep`, `search_codebase` |\n| **Shell** | `run_terminal_command`, `shell` |\n| **Web** | `web_fetch`, `web_search` |\n| **Images** | `read_image` |\n| **Sub-agents** | `task` — spawn a focused sub-agent for a self-contained subtask |\n| **GDB / hardware** | `gdb_start_server`, `gdb_connect`, `gdb_command`, `gdb_interrupt`, `gdb_wait_stopped`, `gdb_status`, `gdb_stop` |\n| **Agent networking** | `list_peers`, `delegate_task` *(node mode only)* |\n| **Session** | `switch_mode`, `todo`, `update_memory`, `ask_question`†, `read_lints`, `load_skill` |\n\n†`ask_question` is only available in interactive TUI sessions.\n\nEach tool call goes through an approval policy — auto-approved, denied, or\npresented for confirmation based on glob patterns you configure.\n\n### Skills system\n\nSkills are markdown instruction files that the agent loads on demand to gain\nspecialized expertise for a task. Skills can encode coding standards, project\nconventions, domain knowledge, or multi-step procedures. Load a skill with\n`load_skill` or configure auto-loading in `.cursor/skills/`.\n\n### Project awareness\n\nWhen a session starts, sven automatically:\n\n1. Walks up the directory tree to find the `.git` root.\n2. Injects the absolute project path so tools use it for all file operations.\n3. Collects live git metadata (branch, commit, remote, dirty status).\n4. Reads `.sven/context.md`, `AGENTS.md`, or `CLAUDE.md` and injects the\n   contents as project-level instructions.\n\n### Persistent memory\n\n`update_memory` writes durable facts to a memory file that is injected at the\nstart of every session. The agent can learn and remember things about your\nproject across conversations.\n\n### Pipeable conversations\n\nsven headless output is valid sven conversation markdown — it can be piped\ndirectly into another sven instance:\n\n```sh\n# Chain agents: plan → implement\nsven --file plan.md | sven --mode agent \"Implement the plan above.\"\n\n# Save the full trace for fine-tuning (includes system prompts, OpenAI format)\nsven --file workflow.md --output-jsonl trace.jsonl\n```\n\n---\n\n## Model Providers\n\nSven supports **32 model providers** natively in Rust — no external gateway\nrequired.\n\n| Category | Providers |\n|----------|-----------|\n| Major cloud | OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, Cohere |\n| Gateways | OpenRouter, LiteLLM, Portkey, Vercel AI, Cloudflare |\n| Fast inference | Groq, Cerebras |\n| Open models | Together AI, Fireworks, DeepInfra, Nebius, SambaNova, Hugging Face, NVIDIA NIM |\n| Specialized | Mistral, xAI (Grok), Perplexity |\n| Regional | DeepSeek, Moonshot, Qwen/DashScope, GLM, MiniMax, Baidu Qianfan |\n| Local / OSS | Ollama, vLLM, LM Studio |\n\n```sh\nsven list-providers --verbose\nsven -M anthropic/claude-opus-4-6 \"Refactor this code\"\nsven -M groq/llama-3.3-70b-versatile \"Explain the algorithm\"\nsven -M ollama/llama3.2 \"Quick local question\"\n```\n\nSee [docs/providers.md](docs/providers.md) for configuration details.\n\n---\n\n## Documentation\n\n| Section | Topic |\n|---------|-------|\n| [Introduction](docs/00-introduction.md) | What sven is and how it works |\n| [Installation](docs/01-installation.md) | Getting sven onto your machine |\n| [Quick Start](docs/02-quickstart.md) | Your first session in five minutes |\n| [User Guide](docs/03-user-guide.md) | TUI navigation, modes, tools, conversations |\n| [CI and Pipelines](docs/04-ci-pipeline.md) | Headless mode, scripts, and CI integration |\n| [Configuration](docs/05-configuration.md) | All config options explained |\n| [Examples](docs/06-examples.md) | Real-world use cases |\n| [Troubleshooting](docs/07-troubleshooting.md) | Common issues and fixes |\n| [Node / P2P](docs/08-node.md) | Remote access, device pairing, agent networking |\n| [IDE integration (ACP)](docs/03-user-guide.md#ide-integration-via-acp) | Zed, JetBrains, VS Code via Agent Client Protocol |\n\nBuild the full user guide locally:\n\n```sh\nmake docs        # → target/docs/sven-user-guide.md\nmake docs-pdf    # → target/docs/sven-user-guide.pdf (requires pandoc)\n```\n\n---\n\n## Agent modes\n\n| Mode | Behaviour |\n|------|-----------|\n| `research` | Read-only tools. Good for exploration and analysis. |\n| `plan` | No file writes. Produces structured plans without side effects. |\n| `agent` | Full read/write access. Default for interactive use. |\n\nSet with `--mode` or cycle live in the TUI with `F4`.\n\n---\n\n## CI / pipeline mode\n\nWhen stdin is not a TTY, or when `--headless` is passed, sven enters headless\nmode.  **Workflow structure (H1, `##` steps) applies only when you use\n`-f`/`--file`**; piped stdin is never parsed as a workflow (it is one plain-text\nmessage or conversation/JSONL).  When using a workflow file:\n\n- The first `#` H1 heading is the conversation title.\n- Text between H1 and the first `##` is appended to the system prompt.\n- Each `##` H2 heading is a step sent to the model.\n- `\u003c!-- sven: mode=X model=Y timeout=Z --\u003e` directives set per-step options.\n\n```sh\nsven --file plan.md                              # run a workflow\nsven --file audit.md --output-format json        # structured JSON output\nsven --file plan.md --output-last-message out.txt\nsven --file workflow.md --output-jsonl trace.jsonl  # full trace for fine-tuning\nsven --file review.md --var branch=main --var pr=42\nsven validate --file plan.md                     # dry-run: parse only\n```\n\n**Exit codes:** `0` success · `1` agent error · `2` validation error · `124` timeout · `130` interrupt\n\n---\n\n## Node — remote access and agent networking\n\n```sh\n# Start the node (generates TLS cert and bearer token on first run)\nsven node start [--config .node.yaml]\n\n# Send a task to the running node from another terminal\nexport SVEN_NODE_TOKEN=\u003ctoken\u003e\nsven node exec \"What files are in the current directory?\"\n\n# Or run the interactive TUI connected to the node (list_peers, delegate_task)\nexport SVEN_NODE_URL=wss://127.0.0.1:18790/ws\nsven\n\n# Pair a mobile/native operator device\nsven node authorize \"sven://12D3KooW...\"\n\n# Rotate the bearer token\nsven node regenerate-token\n\n# List authorized operator devices (NOT agent peers — see below)\nsven node list-operators\n```\n\nSecurity defaults — all on, none optional:\n\n| What | Default |\n|------|---------|\n| HTTP TLS | On — ECDSA P-256, 90-day auto-generated cert |\n| TLS version | TLS 1.3 only |\n| P2P encryption | Noise protocol (Ed25519), always on |\n| P2P authorisation | Deny-all — every operator device must be explicitly paired |\n| HTTP binding | `127.0.0.1` — loopback only |\n| Bearer token storage | SHA-256 hash only — plaintext never written to disk |\n\n---\n\n## IDE integration — ACP\n\nSven implements the [Agent Client Protocol (ACP)](https://agentclientprotocol.org),\nletting ACP-aware editors drive it directly as an AI coding agent over stdio.\nNo daemon, no relay, no IDE API key required — sven manages its own model.\n\n```sh\n# Zed: add to ~/.config/zed/settings.json\n{\n  \"agent_servers\": {\n    \"sven\": { \"type\": \"custom\", \"command\": \"sven\", \"args\": [\"acp\", \"serve\"] }\n  }\n}\n```\n\nThe same `sven acp serve` command works for VS Code (ACP extension) and JetBrains\n(AI Assistant plugin). To attach an IDE to a running `sven node` instead of\nspawning a local agent:\n\n```sh\nsven acp serve --node-url wss://localhost:8443 --token \"$SVEN_NODE_TOKEN\"\n```\n\nSee the [IDE integration guide](docs/03-user-guide.md#ide-integration-via-acp)\nand the [ACP technical reference](docs/technical/acp.md) for full details.\n\n---\n\n## Building\n\n```sh\nmake build      # debug build\nmake release    # optimised release build\nmake deb        # Debian package\n```\n\nRequires a recent stable Rust toolchain. No other system dependencies.\n\n---\n\n## Configuration\n\nsven merges YAML config files from lowest to highest priority:\n\n1. `/etc/sven/config.yaml`\n2. `~/.config/sven/config.yaml`\n3. `.sven/config.yaml`\n4. `sven.yaml`\n5. `--config \u003cpath\u003e`\n\nRun `sven show-config` to see the full resolved config. Key sections:\n\n- `model` — provider, model name, API key env var, base URL override, token limits.\n- `agent` — default mode, max autonomous rounds, compaction threshold, system prompt override.\n- `tools` — timeout, Docker sandbox, auto-approve and deny glob patterns.\n- `tui` — theme, markdown wrap width, ASCII-border fallback.\n\n---\n\n## Workspace layout\n\n```\nsven/\n├── src/                    # binary entry-point and CLI\n└── crates/\n    ├── sven-config/        # config schema and loader\n    ├── sven-model/         # ModelProvider trait + 32 drivers\n    ├── sven-core/          # agent loop, session, context compaction\n    ├── sven-tools/         # full tool suite + approval policy\n    ├── sven-input/         # markdown step parser and message queue\n    ├── sven-ci/            # headless runner and output formatting\n    ├── sven-tui/           # Ratatui TUI: layout, widgets, key bindings\n    ├── sven-p2p/           # libp2p node: Noise, mDNS, relay, task routing\n    ├── sven-node/          # node: HTTP/WS node + P2P + Slack + agent wiring\n    ├── sven-runtime/       # shared runtime utilities\n    └── sven-bootstrap/     # first-run setup helpers\n```\n\n---\n\n## Testing\n\n```sh\nmake test       # unit and integration tests (cargo test)\nmake bats       # end-to-end tests (requires bats-core)\nmake check      # clippy lints\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswedishembedded%2Fsven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswedishembedded%2Fsven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswedishembedded%2Fsven/lists"}