beaver-gateway/README.md

beaver-gateway

A gateway for personal agents built on the Claude Agent SDK: conversations with a lifecycle, windows to talk through, jobs, memory hooks, and a policy boundary - without an opinion about what the agent is for. A setup is one config.py (or a package next to it) that assembles a Gateway; this repo holds the primitives, beaver-agent is a full setup built on them.

What it gives a setup

• agents/ - what an agent is: a Claude agent with a prompt per conversation kind, skill sets per kind, gateway tools, a PreToolUse policy; a Raycast agent for cheap fast answers.
• backends/ - how a turn runs: the Claude Agent SDK subprocess with a session pool, transcripts and session stores; the Raycast wire.
• conversations/ - the model of a conversation: kinds (master, branch, deep, job, fork), rows and windows, the inject queue with priorities, seeds, turns, questions, closing through a distiller, master rotation, the envelope, the in-process gateway tools.
• jobs/ - cron, webhook and event jobs on pgqueuer, deferred injects, the subscription budget.
• frontends/ - the windows: Telegram (master = General, topic = branch), markdown files in a vault, /api + the admin SPA, an Anthropic-compatible /anthropic/v1/messages, MCP re-exposure at /mcp/<name>.
• mcp/ - MCP servers a setup declares (stdio, http, python tools), aggregated in-process and handed to agents by name.
• vault/ - watching a directory of notes for the envelope.
• security/ - bearer tokens, the audit log, credential redaction.
• events/ - the in-process bus every frontend taps, and the stream event protocol backends emit.
• storage/ - SQLModel tables and the Postgres session store.

config.py defines Gateway and loads a setup; app.py builds the runtime from it; cli.py is the entrypoint. Every string the gateway puts in front of a model or a user has an English default and is overridable (ConversationTexts, TelegramTexts).

Run

uv sync                       # python
cd ui && bun install && cd .. # admin + panel SPA, built into ui/build
cp examples/config.py /config/config.py
DATABASE_URL=postgresql+psycopg://... CONFIG_PATH=/config/config.py uv run beaver-gateway

examples/config.py is the smallest setup that starts. The setup's own secrets come from .env (load_dotenv runs before the config is executed).

Develop

make check   # ruff format --check, ruff check, ty, pytest
make fix

No comments in code: modules carry a one-line docstring saying what they are for, public configuration fields carry a one-line docstring saying what they mean; everything else is the code.