Skip to content

Using Raven

Choose how to talk to Raven, give the session the right working directory, and add other agents or services only when needed. Installed commands below can be prefixed with uv run in a source checkout.

Choose a surface

Goal Entry point Next guide
Terminal session raven tui Command Reference
Browser session raven web Launch WebUI
One task in a checkout raven agent -m "Summarize this project without editing files" Permissions and security
Chat from a messaging platform A configured channel and resident gateway Channels and Messaging
Delegate to a specialist A configured agent in the roster Agent Integrations
Follow up with a specialist Its stateful instance Working with sub-agents
Operate a shared browser Browser tools and the WebUI panel Browser collaboration
Retrieve document passages WebUI Knowledge page and the session's base selection; library/RPC for integrations Knowledge bases
Run and watch a long job Raven-Oncall with a declared campaign Long-running work (Oncall)
Integrate an editor or remote peer ACP or A2A Agent Protocols

raven agent requires a message; it is not an interactive REPL. Use the TUI or WebUI for a session. Start with Quick Start if no model provider is configured.

Work in the right directory

The working directory holds the files the task acts on. Agent home holds identity, memory, skills, and transcripts; it is not an interchangeable name for the project checkout. For a one-shot task:

raven agent --workspace /absolute/path/to/project -m "Read the README and summarize the setup steps"

This executes a model turn and can incur provider charges. For changes, state which files may be edited and how to verify the result. For parallel coding tasks in a Git project, the host's multi-agent-coding skill instructs each coding agent to create a separate worktree and report its path and branch. Check those reports before coordinating concurrent edits. See Working with sub-agents for this workflow and DAG orchestration for manually constructed graphs.

Where Raven keeps state

Raven keeps its runtime state -- configuration, command history, logs -- under one directory: $RAVEN_HOME, or ~/.raven when the variable is unset or blank. The value may be absolute, ~, or start with ~/; a bare ~ and the ~/ prefix both expand to the user's home directory in every front end. ~\ is the Windows spelling of the same prefix: both front ends expand it on Windows, and only the TUI expands it on other platforms. Other leading-tilde forms, such as ~name, are not expanded in the TUI and stay relative values. A relative value stays relative to each process's own working directory, so two front ends can disagree about which directory it names; prefer an absolute value.

Continue a session

Each one-shot CLI invocation starts a fresh session by default. Use one of --continue, --resume <id-or-prefix>, or --session <full-key> when continuity is intentional; these options are mutually exclusive.

raven sessions --help
raven agent --continue -m "Expand the previous summary; do not modify files"

Use the UI's session picker for interactive sessions. A sub-agent instance continues that child's session; it is not the host session id or a DAG node id. See DAG Orchestration.

Set the reasoning effort

The reasoning effort is how much the model thinks before each answer. The words a session may pick are the ones its model declares: minimal, low, medium and high on most models, xhigh or max where the provider publishes them, and whatever narrower ladder an API actually takes (DeepSeek offers low, high and max, folding minimal onto low and medium onto high). The ladder follows the provider that serves the request, not only the model's name: the same model reached through a gateway takes the gateway's words. A model that declares none offers no row at all. Each provider maps the words to its own request (Anthropic's adaptive effort and thinking budgets, the reasoning_effort field of OpenAI-style APIs), and a model with no thinking to move ignores them. Left unset, the provider's own default applies.

Two places set it:

  • For every session: in the WebUI, open Settings, then Parameters on the Chat row, then Reasoning effort; or set agents.defaults.reasoningEffort in ~/.raven/config.json. The first rung, Provider default, clears the key.
  • For one session: the Reasoning effort row of the model picker in the WebUI (open it from the model chip beside the composer), or /effort <word> in the TUI. /effort alone reports the effort in force, and /effort default returns the session to the global setting. Inside a direct chat with a sub-agent instance the command is refused: the pick is the main session's, and an instance has none of its own.

A model's words can also be declared in the provider's model_overlay.reasoningEfforts (Settings, then Advanced on the provider, Add under display names). A non-empty declaration outranks LiteLLM's table for that model, including a route the table marks as not reasoning; leave it blank to fall back to the table.

A pick made for one session outranks the global setting and the session's mode. It is kept on the session's own record, so it survives a gateway restart and comes back when the session is resumed, and it lands on the next turn. A pick the current model does not declare runs at the highest word that model declares below it (max picked on one model, then a switch to a model that stops at high, runs at high); only when the model declares nothing at or below it does the session's mode word or the global setting run instead. The pick stays saved as named for a model that declares it. It moves Raven's own model calls only; sub-agents keep the configured default.

Add capability deliberately

Use a skill for reusable instructions, MCP for external tools, and a plugin for runtime contributions. Use a specialized agent for a separate identity and execution profile; use a DAG or playbook to coordinate dependent work. A2A is for an independently operated peer, not another name for a local plugin.

Skills, Memory and Extensions explains these choices. For scheduled or proactive work, read Proactive Reminders and Follow-ups and keep the appropriate resident host running.

Check results and diagnose problems

Start with raven status and raven doctor. A configured provider, a listed agent, or a successful handshake does not establish that a real task succeeded. Check the final answer, generated files, and relevant tests or task evidence.

For a stalled task, check permission requests, child-agent readiness, provider errors, and the run's progress before retrying. A retry can repeat external side effects. Use raven tracing and raven trajectory --help for diagnostics, and redact private material before sharing it. Trajectory debugging and replay walks through capturing evidence and reproducing harness behavior without repeating recorded external actions.