verona

Verona

Self-hosted CLI framework for scheduled, self-learning AI agents with persistent memory and bidirectional comms.

Status: v0.x — actively under construction. APIs and config schemas may change.

What it is

Verona lets you run long-lived AI agents on a host you control (your laptop, a VPS, an EC2 instance). Each agent has:

• A soul (SOUL.md) — personality, values, voice, ~200–500 words.
• Tasks — prompt templates that fire on a cron schedule, on a Slack mention, or on demand.
• Memory — protected human-curated core/ plus agent-writable learned/ (facts, episodic logs, working scratch). Self-learning is filesystem-enforced: the agent cannot rewrite its own soul.
• Connectors — Slack (bidirectional via Socket Mode), generic webhook, web fetch (read-only). More planned.
• A pluggable AI runner — defaults to claude -p using your Claude subscription. Swappable to Anthropic SDK / OpenAI / OpenRouter via API-key adapters.

Why

You probably don't want to write a bespoke daemon every time you want a "thing that runs at 3am, posts findings to Slack, and lets you @-mention it to dig deeper." Verona is the boring plumbing — scheduler, dispatcher, memory loader, audit log, cost tracker, connectors — so you can focus on the agent's soul, tasks, and prompts.

Install

git clone https://github.com/<you>/verona ~/code/verona
cd ~/code/verona
npm install
npm run build
./bin/verona init        # scaffold ~/.verona/state
./bin/verona doctor      # verify the host (claude binary, perms, git)

You'll need:

• Node.js ≥ 25.9 (see .tool-versions; mise install will pick it up).
• The claude CLI installed and logged in (claude login) on every host where you'll use the default claude-cli adapter. Verona never sees your subscription credentials — it relies on claude being authenticated separately.

Quick start

Verona has three trees: the source repo (this), your user-agents dir (default ~/.verona/agents/), and the runtime state dir (default ~/.verona/state/). Your own agents live in the user-agents dir — never edit agents/examples/ directly, those are read-only templates.

Scaffold the smoke-test agent and run it once:

verona agents init my-hello --template hello-world
# scaffolded ~/.verona/agents/my-hello/

verona agents add ~/.verona/agents/my-hello
verona schedule run my-hello:greet
verona logs my-hello --latest

Wire up Slack and the researcher pattern:

verona connectors add slack       # interactive: paste bot_token (xoxb-) and app_token (xapp-)
verona connectors test slack --destination '#research-feed'

verona agents init research-personal --template researcher
$EDITOR ~/.verona/agents/research-personal       # tweak SOUL.md, schedule, sources
verona agents add ~/.verona/agents/research-personal
verona schedule list              # nightly cron + on_message tasks

Run the daemon (foreground for now; install as a service via deploy/README.md for production):

verona daemon

CLI overview

verona init                                  # scaffold the state dir + git repo
verona doctor                                # verify host readiness
verona daemon                                # run the long-lived daemon

verona agents init <name> --template <name>  # scaffold from a bundled template
verona agents {add <path> | list}
verona connectors {add <id> | test <id>}
verona schedule {list | next | run <agent>:<task>}

verona invocations [--agent X] [--since 7d] [--json]
verona costs
verona logs <agent> [--task <id>] [--latest] [--limit N]

How it works (one diagram)