Raven-1/docs/dev.md
0xKT a27559e331 fix(*): the final audit closes consent, tty truth, and the cache lies
An adversarial last pass over the whole branch found what the review
rounds had not. Consent first: the sh decline arm matched only bare n/N,
so a typed "no" installed LibreOffice through sudo; the arm now takes
the word too, and a tripwire pins the default-yes prompt in both
installers so the review-round decision cannot silently flip back. The
tty gate probed existence where openability is the truth -- the node
exists in CI, cron and docker -t without -i -- so the gate now opens it,
and a consoleless run skips instead of defaulting yes or hanging.
install.ps1 finally carries the everos memory wheel through both of its
paths with sh's own rung discipline, so the Windows summary's memory row
can be green at all. The two cache resolvers follow playwright's real
lookups (XDG_CACHE_HOME, LOCALAPPDATA, chrome-win64 layouts), a
non-object registry degrades instead of raising, and the four mouths
that name a fix now say the same runnable thing on every platform.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-12 00:50:35 +08:00

2.7 KiB

Raven Developer Guide

Build & Run from Source

The project uses Python + uv with hatchling as the build backend.

0. System prerequisites

uv installs everything raven imports. One program it cannot: LibreOffice, which converts a deck (or any Office source document) to PDF. The deck engine renders, measures and previews through that conversion, and the gateway's PDF viewer serves it, so without LibreOffice a deck still builds but nothing that reads the rendered page runs, and several integration tests skip.

apt install libreoffice                          # Debian / Ubuntu
brew install --cask libreoffice                  # macOS
winget install TheDocumentFoundation.LibreOffice # Windows

The browser tool's chromium binary is also not a Python package: a source checkout downloads it with uv sync --all-extras && uv run playwright install chromium (install.sh does this for tool installs).

raven doctor reports it under External tools.

1. Install dependencies

cd /path/to/raven
uv sync

This creates/updates .venv with all core dependencies from uv.lock.

For optional extras:

uv sync --extra channels   # messaging integrations (Telegram, Slack, etc.)
uv sync --extra sandbox    # boxlite sandbox execution
uv sync --extra tools      # web/readability tools
# or all at once:
uv sync --all-extras

2. Install the package in editable mode

uv pip install -e .

This wires up the raven CLI script to your source code so changes take effect immediately.

3. Run the CLI

# via uv run (uses .venv automatically, no activation needed):
uv run raven --help

# or activate the venv first:
source .venv/bin/activate
raven --help

4. First-time setup

uv run raven onboard

Creates ~/.raven/config.json and the workspace directory. Edit the config to add your API key (default provider: OpenRouter — get a key at https://openrouter.ai/keys).

5. Common commands

Command Description
raven tui Start the interactive chat TUI
raven agent -m "Hello" Send a single message and exit
raven gateway Start full server (all channels + heartbeat + cron)
raven status Show config path, workspace, and API key status
raven channels status Show which messaging channels are enabled
raven provider login <name> Authenticate with an OAuth provider (for example openai-codex, minimax-global, or minimax-cn)

6. Run tests

uv run pytest tests/

Requires Python >= 3.12, and LibreOffice for the tests that render a deck (they skip without it). Test configuration is in pyproject.toml (asyncio_mode = "auto").