Velor

Velor is a Rust agent supervisor and orchestration layer for Codex, Claude Code and Oh My Pi. It wraps them in a template-driven execution loop with crash recovery, a streaming terminal UI, a cron scheduler, an encrypted secrets vault, and a Telegram control plane that lets me start, steer, and review agent runs from my phone.

I used it as my primary agent supervisor for about seven months. It is now published as experimental, source-available software.

Why I built it

Claude Code and Codex are powerful, but running them autonomously — across multiple repos, on a schedule, overnight, or triggered from my phone — required glue that did not exist. The vendors ship interactive CLIs; what I wanted was a supervisor.

The core abstraction is deliberately small: a prompt template (MiniJinja, defined in TOML) plus a completion token. Velor renders the template, spawns the agent binary, streams its output, and loops until the agent emits the token. When a run fails, Velor retries with exponential backoff and preserves the conversation, so the agent resumes with context instead of starting cold.

Everything else in the project exists to make that loop survivable in daily use:

• Crash recovery — retries preserve conversation history; permanent errors (bad config, auth) stop the loop, transient ones (rate limits, provider outages) are waited out
• Project rules — .agents/rules/*.mdc files injected into prompts by glob, so agents pick up the same conventions my editors enforce
• Automations — cron-scheduled recurring runs with catch-up for missed schedules and SQLite-backed history
• A secrets vault — XChaCha20-Poly1305 encryption with OS keyring integration, because agent configs accumulate credentials fast

The TUI

Running vel with no subcommand opens a streaming terminal interface, and that surface is where Velor is most mature. A live transcript shows thinking, text, tool activity, and syntax-highlighted file diffs as the agent works. Because an autonomous run can go sideways, the TUI is built for intervention: i interrupts and redirects the agent mid-run, f queues a follow-up, and the transcript can be scrolled and copied out for post-mortems.

Building a UI that stays responsive while a subprocess streams megabytes of output taught me a lot about bounded buffers, entry coalescing, and rendering budgets — the transcript enforces limits on entries, bytes, and lines so a runaway run cannot exhaust memory.

The Telegram control plane

vel serve turns Velor into a personal agent service. A long-polling Telegram bot receives text or photos, dispatches the matching runner profile, and streams progress back by editing a single message. Prefix routing picks the model — opus: or codex: in front of a message selects a different runner from a configurable table. Replying to a run message continues that same agent session, context intact.

In practice this was the feature that changed how I worked: an agent could be grinding through a refactor while I was away from my desk, and I could check in, steer, or collect the result from my phone.

What seven months of dogfooding taught me

Velor developed Velor. Most of the interesting code exists because a real run hit a real failure mode: providers that exit successfully with empty output under throttling (and the runaway loop that caused before a guard existed), deadlocks in mid-run steering, Ctrl+C handling across process groups, and Telegram message limits during verbose streaming.

The supervision path is where the hard-won lessons live — error classification (retry versus abort), backoff that plateaus instead of giving up on time-based rate limits, and cancellation that actually reaches the process group.

Where it stands

I have since replaced Velor with herdr and Oh My Pi — together they cover the parts of Velor I relied on day to day, and Oh My Pi gives me a maintained UI with upstream improvements for free.

Velor itself remains experimental and is not under active feature development. It is published as a working record — a real, self-hosted agent supervisor and orchestration layer that carried production-personal workloads every day for seven months.

License

Velor is source-available under the PolyForm Noncommercial License 1.0.0: personal, educational, and research use is permitted; commercial use requires a separate commercial license. Machine-learning training and text-and-data-mining rights are reserved to the maximum extent permitted by applicable law.