## Summary raven agents new scaffolds a complete, working agent on the installed raven: eleven fire-tested template files land in the raven home's agents/ tree (discovered with zero registration), a four-segment health card examines the result (atomic write, doctor, a real ACP handshake smoke, next steps), and --engine-wheel grows the same scaffold into the wheel-shaped harness the shipped engines use. The developer guide ships with it, in-repo and editor-checkable. Key decisions: - **Templates are real code, fire-tested before templating.** The eleven files under raven/templates/agents_scaffold/ pass ruff and py_compile like any source, ride the wheel, and their content was proven live before landing: discovery, handshake, and plugin tool/hook injection all green on a hand-assembled probe in a disposable home. A dedicated spike also proved the placement is invisible to the import-linter contracts and needs exactly one coverage-gate exclusion line. - **Home-first landing, registration as an explicit act.** The default target is the raven home's agents/ tree, discovery's first root: a scaffolded folder is on the roster without any registration. --register mirrors the generated install.py through the same pinned write door; --here lands in the checkout for in-repo agent work. - **The scaffold examines its own work.** Doctor re-validates the manifest, re-parses the plugin manifest, compiles every generated file, and really scans discovery; smoke spawns the launcher for one initialize frame. Three smoke outcomes are told apart: GREEN, the launcher's loud no-key refusal (fail-closed design, passed through verbatim), and FAILED with the scene preserved. Display names are fenced so no input can corrupt the generated manifest. - **Schemas derive from the models.** scripts/export_agent_schemas.py renders schemas/subagent.schema.json (a discriminated union on kind) and schemas/raven-plugin.schema.json from the pydantic models; a contract family holds the on-disk files byte-equal to a fresh render and validates every real manifest on the tree against them. Editors get instant validation with two settings lines, documented in the guide. - **The lexicon follows the terminology ruling.** agents/BUILDING.md is the from-zero developer guide (gold standard: a developer who never read the source reaches a green handshake in ten minutes); CONTEXT.md renames the category entry to Discovered agent -- agent the thing, harness the mechanism, subagent the protocol seat -- with product absorbed into Avoid; the charter gains the scaffold entry and the engine-ownership line. - **--engine-wheel lands both shapes.** User mode drops the engine project in the working directory (pip install -e territory); --here lands it on the plugins-dist shelf. The launcher adopts the official ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine is missing; the doctor reports that row as disabled by design with the install cure printed. No plugins/ directory ships beside an engine-shaped agent, matching the shipped engines. - **A pre-push adversarial review hardened the whole surface.** Two hostile lenses (filesystem edges of a command that writes into real raven homes; template quality as the file set every future agent copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could pin an enabled row that cannot start, the name fence ignored the discovered tree, one installed engine wheel rode the host's and every sibling's turns through a fixed tool name, and crash residue was discovered as a hidden live agent. All fourteen close in a dedicated hardening commit, each with a regression test built from the review's own reproduction. - **Near-zero kernel touch, and the two touches are the review's.** Nothing under raven/contracts/ or the agent loop changed. The branch carries exactly two narrow runtime fixes exposed by the review: discovery now skips dot-directories (crash residue is never an agent), and the config schema gains an engine round-trip field (declared as a field-level neutral seam; merge and readiness semantics untouched). ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - Every commit landed through a full-suite rehearsal on a clean bench before touching the branch; tails over the original base's 19953 passed / 137 skipped: 19980 (templates + command), 19993 (doctor + smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout, every step a pure addition, +65 tests net. The branch diff is fingerprint-stable across the rebase (git patch-id --stable verified pairwise across two clean rebases); the branch closes at 20094 passed / 137 skipped / exit 0 on the current main base, +80 tests net over whatever base it sits on -- re-measured in full after every rebase. - A real-machine pass on the live raven home closed the loop end to end: one command scaffolds into ~/.raven/agents, the four-segment card runs all green, and a genuine LLM turn has the agent's own model call its own scaffolded hello tool through the permission gate and relay the exact output; the probe was then removed without touching the roster. - Gold tests spawn for real: scaffold into an isolated home, assert the four doctor lines, readiness ready, and a live ACP initialize handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal passthrough and an engine twin pins disabled-as-designed. - Schema contract: mutation audits both directions (tampered model and tampered file each turn the family red); all six subagent manifests and all eight raven-plugin.toml files on the tree validate. - make lint-python, uv run lint-imports (9 contracts kept, 0 broken), make check-large-files, make check-source-language: green at every step; wheel build carries all seventeen template files and none of schemas/. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes New command surface only: no existing agent, roster row, or runtime path changes behavior. The generated .env stays untracked and the wheel builder still refuses secrets. The one gate change is a coverage-gate exclusion declaring templates non-production. Rollback: revert the squash commit; scaffolded agents already created keep working, since they run on the installed raven like any discovered folder. ## Related Issues N/A
Raven
Raven is The Self-Improving Agent Harness, built on EverOS, with opt-in Deep Research for multi-source investigation.
Raven helps agents improve across runs by continuously refining the systems around them: tools, skills, memory, code execution, policies, and working environment. EverOS provides durable user memory, agent memory, and world knowledge across sessions, so successful workflows can evolve into reusable Agent Templates and digital workers.
Update: Raven added Deep Research. Enable it with raven deep-research enable
to give the agent access to MiroThinker-backed, multi-source research when a
task needs deeper investigation.
Raven is pre-alpha. Interfaces and configuration may change quickly.
Benchmarks
| Benchmark | Raven Result | Comparison |
|---|---|---|
| Efficiency | 56.7% at 27B; 58.1% at 397B |
Hermes 46.8% / 47.9%; +9.9pp at 27B |
| Self-evolution | Ranked #1 on EvoAgentBench |
+6.2pp over the next result across four methods |
| Proactivity | 0.60 F1 on ProAgentBench |
2.4x Hermes/OpenClaw at 0.253 |
Results describe the published test configurations; model, task set, and evaluation protocol all affect outcomes.
https://github.com/user-attachments/assets/3c541dae-5852-447f-8ea6-c9877612ad57
Quick Start
Install
Linux, macOS, or WSL2:
curl -fsSL https://raven.evermind.ai/install.sh | bash
Native Windows PowerShell:
irm https://raven.evermind.ai/install.ps1 | iex
Windows PowerShell 5.1 may reject the redirect. Use the direct installer URL instead:
irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex
The agent products ship with raven itself: a wheel carries the agents/
product tree and copies it out to your raven home on first use, and a source
checkout reads the tree in place. Setup asks about each product and registers
the ones you take up, on the model it is tuned for or on this raven's LLM.
See agents/README.md.
Onboard and run
raven
That is the whole first run: with nothing configured yet, raven walks you through setup and then opens the TUI in the same session. To reconfigure later, run raven onboard explicitly.
The bilingual onboarding wizard configures seven areas without requiring manual edits to ~/.raven/config.json:
- LLM provider and model
- Sandbox or execution location
- Chat channels
- EverOS long-term memory
- Web access (pick a search vendor and a page reader, give each its key)
- Sub-agents shipped in this checkout
- Cold-start import from other AI tools
Step 5 also mirrors every web vendor key into ~/.raven/env (owner-only) and offers to add one
guarded source line to your shell rc, so new shells and the cli / acp sub-agents --
whose environment is captured from a login shell -- inherit them.
Provider setup includes an in-step connectivity check. Optional steps can be skipped and configured later. If setup is incomplete, run:
raven doctor
Upgrade
raven upgrade --check
raven upgrade
Upgrades preserve configuration, sessions, and memory. Raven does not update automatically.
Deep Research
Deep Research gives Raven a dedicated path for open-ended questions that require broad web search, source reading, analysis, and multi-source cross-checking. It uses MiroThinker and returns a self-contained answer with inline citations and references.
Configure it during onboarding or later:
raven deep-research enable
raven deep-research get
Once configured, Raven can invoke deep_research when a task needs more than a quick lookup. Before a paid, minute-scale run, interactive surfaces ask whether to use Deep Research or regular search for that query.
Delivery adapts to where Raven is running:
- CLI and TUI: progress streams inline while Raven searches, reads pages, and runs analysis. The completed report is shown directly without being rewritten by the main model.
- Gateway channels: the run continues in the background and the completed report is delivered back to the originating conversation.
- Local archive: every completed result is saved under
<workspace>/deep_research/for later use.
Use regular search for a single fact or URL. Use Deep Research for comparisons, landscape reviews, technical investigations, and questions where source agreement matters.
Tracing
Tracing makes Raven's reasoning path inspectable without sending trace data to a hosted service. Open the local dashboard with:
raven tracing
Each session.turn becomes a trace tree containing the work that happened beneath it:
- LLM calls, models, token usage, cost, latency, and errors
- Tool inputs and outputs
- Subagent runs and parent-child relationships
- Skill reads and injections
- Memory recall, storage, extraction, and consolidation
- Large prompts and results stored as out-of-line artifacts
Tracing is enabled by default and is designed to never interrupt Raven's control flow. Spans are stored locally at ~/.raven/traces/logs/audit-spans.log; set RAVEN_TRACING_DIR to move the state directory or RAVEN_TRACING=0 to disable recording.
The schema follows a small, versioned semantic contract. See the Tracing Standard API for span names, attributes, artifact behavior, and extension rules.
Core Systems
| System | What it adds |
|---|---|
| EverOS memory | Durable user memory, agent memory, and world knowledge across sessions |
| Context Engine | Explicit token budgets and a unified assembly pipeline that preserves the most useful context |
| Proactivity | Sentinel observations, scheduled work, nudge policy, and deferred decisions |
| SkillForge | Built-in, workspace, EverOS, and mirrored skills with retrieval, feedback, and evolution |
| Evolver | Reproducible evaluation loops for improving agents and reusable procedures |
| Agent Templates | Shareable starting points for specialized digital workers built on the same harness |
Providers and Gateways
Raven supports API-key, OAuth, local, and OpenAI-compatible providers. The onboarding catalog includes OpenRouter, OpenAI, Anthropic, Gemini, MiniMax, DeepSeek, Z.ai, DashScope, Moonshot, VolcEngine, SiliconFlow, Groq, AiHubMix, Azure OpenAI, GitHub Copilot OAuth, OpenAI Codex OAuth, Ollama, and hosted vLLM.
Twelve gateway adapters connect Raven to Telegram, Slack, Discord, WhatsApp, Matrix, Feishu, WeCom, Mochat, QQ, DingTalk, Email, and WeChat.
raven channels list
raven channels enable <adapter>
raven gateway
Command Reference
| Command | Purpose |
|---|---|
raven or raven tui |
Launch the terminal UI |
raven agent -m "..." |
Run a one-shot task |
raven onboard |
Configure providers, sandboxing, channels, memory, web tool keys, sub-agents, and import |
raven status |
Show configuration and runtime status |
raven doctor |
Diagnose provider and environment problems |
raven tracing |
Open the local trace dashboard |
raven tracing compact |
Fold duplicate trace artifacts to reclaim disk space |
raven sessions list |
Browse, resume, fork, export, or delete sessions |
raven skill list |
Inspect the local SkillForge catalog |
raven sentinel status |
Inspect proactive memory and scheduled nudges |
raven cron list |
Inspect scheduled jobs |
raven gateway |
Run messaging gateways |
raven gateway reload / status / stop |
Drive a running gateway through its control plane (rebuild from config without a restart, inspect the generation, stop gracefully) |
raven upgrade |
Upgrade a managed installation |
Run raven --help or raven <command> --help for the complete CLI surface.
Documentation
- Documentation index
- Developer workflow
- Tracing Standard API
- Sandbox usage
- Memory plugin architecture
- Self-evolution loop mapping
- Proactivity implementation
Repo layout
The top-level packages under raven/, in one line each. This list is the
canonical set of commit scopes (see AGENTS.md); a change living wholly in a
top-level tree outside raven/ uses that tree as its scope instead (agents,
evolver, ui, ...). Layer seats (which package may
import which) are recorded under Layer Seats in CONTEXT.md, routed from
CONTEXT-MAP.md; this section only says what each package does.
| Package | What it is |
|---|---|
acp |
ACP server side: raven as an agent another host can talk to |
acp_client |
ACP client side: raven driving a third-party local agent as a sub-agent backend |
agent |
The agent loop, its tools, and sub-agent orchestration |
auth |
Authentication and authorization primitives |
browser |
Browser automation and its outbound-address policy |
channels |
Per-service channel adapters (telegram, discord, feishu, ...) and the channel contract |
cli |
The raven command-line surface |
config |
Config schema, loader, migrations, and update helpers |
contracts |
The papers: declared shapes, two promise tiers, no machinery |
context_engine |
Context assembly for a turn |
core |
Assembly root: the *_stack builders and the admission door |
eval_engine |
Evaluation harness |
gateway |
Daemon plumbing: channel manager, outlet, live probe, run lock |
i18n |
User-facing text in the user's language |
importer |
External data import |
knowledge |
Knowledge base service |
market |
Plugin market: catalog, trust, install, ledger |
mcp |
MCP client machinery |
memory_engine |
Long-term memory engine |
home |
Where raven keeps everything: the one address resolver |
observability |
What a raven span means: the attribute vocabulary and the usage it reports |
ops |
Machine registry and on-call operations |
permissions |
The gate at the tool dispatch door: which calls run, ask, or are refused |
playbook |
Playbook runtime |
plugins |
Plugin discovery, manifests, registry, and bundled plugins |
proactive_engine |
Cron, heartbeat, sentinel: turns raven starts itself |
providers |
LLM provider pool and resolution |
routing |
Model routing |
rpc |
The RPC surface (TUI and tools talk here) |
sandbox |
Execution sandboxing |
security |
Outbound address policy and prompt-injection fences |
session |
Session export and titles |
skill_hub |
Skill hub: client, install engine, policy and install audit |
spine |
The kernel: submit, lanes, cancel, emit, delivery |
templates |
Packaged data assets (no Python) |
token_wise |
Token efficiency: cache optimizer, usage tracker |
tracing |
Span capture: context, the instrument decorator, the store |
trajectory |
Turn trajectory store and verdicts |
updates |
The install's own lifecycle: release lookup, upgrade plan and handoff, update nudge |
utils |
Shared helpers, including the atomic write primitive |
Architecture
CLI / TUI / Messaging Gateways
|
v
RPC / Spine
|
v
Agent Loop
+-------+-------+
| | |
Providers Tools Subagents
| | |
+--- Context Engine ---+
|
+-------+--------+
| |
EverOS Memory SkillForge
| |
+--- Proactivity + Evolver
The Python runtime and React/Ink TUI communicate only through the typed RPC contract. The Spine carries runtime events, while the Agent Loop coordinates providers, tools, context, memory, skills, subagents, and proactive work.
Key directories:
raven/
├── spine/ # Per-turn backbone: submit -> lanes -> emit
├── contracts/ # Papers: the interfaces every shelf implements
├── core/ # Assembly root: build_runtime and the *_stack builders
├── agent/ # Agent loop, tools, hooks, subagents, context builder
├── channels/ # Telegram, Discord, Slack, Matrix, WhatsApp, WeCom, ...
├── gateway/ # Daemon plumbing: channel manager, outlet, generations, lock
├── rpc/ # Python side of the native TUI protocol
├── providers/ # LLM provider adapters
├── context_engine/ # Context assembly and Curator path
├── proactive_engine/ # Sentinel, scheduler, nudges, feedback
├── memory_engine/ # EverOS memory, local skills, SkillForge
├── playbook/ # Stored orchestrations: library, match funnel, executor
├── token_wise/ # Usage tracking and cache placement
├── tracing/ # Span capture (the dashboard lives in cli/tracing_viewer/)
├── observability/ # The span vocabulary a standalone kernel may not hold
├── home.py # RAVEN_HOME and the config path, resolved once
├── sandbox/ # Isolated command execution
├── security/ # Trust boundaries and network checks
├── cli/ # `raven` command line entry point
└── config/ # Config schema and update helpers
ui-tui/ # React/Ink native terminal UI
bridge/ # WhatsApp TypeScript bridge
benchmarks/ # Benchmark adapters, including AppWorld evolver wiring
evolver/ # Benchmark-driven harness self-evolution: a tool over the library, not in the wheel
agents/ # Product definitions served over ACP: launcher + rendered config + product plugins
plugins-dist/ # Standalone plugin distributions (everos-memory, ppt-engine) on the raven.plugins entry-point group
schemas/ # Editor-facing JSON Schemas exported from the pydantic models (scripts/export_agent_schemas.py)
EverMind Ecosystem
Raven is part of the EverMind open-source ecosystem. Explore EverOS, EverAlgo, HyperMem, EvoAgentBench, EverMemBench, and EverMe.
Contributing
Issues and pull requests are welcome. Start with the developer workflow, follow AGENTS.md for repository rules, and use GitHub Discussions for design conversations.