djbelieny/nova

An AI team that asks before it acts — 24 specialist agents, task decomposition, and human approval before anything ships, spends, or sends. Self-hosted, multi-channel (Telegram/WhatsApp/Slack), MIT...

1 stars · 0 forks · TypeScript Topics: automation, telegram-bot, self-hosted, multi-agent, ai-agents, bun, claude

README

Nova A self-hosted AI team that runs your operation — and asks before it acts. Nova is a self-hosted, open-source AI platform: a team of 24 specialist agents plus an automation layer that reacts to events and runs the repeatable work in the background. You reach it from Telegram, Slack, Discord, or a terminal — or a webhook, a metric, or a connector event fires it — and it runs on your own model subscriptions and your own machine, with human approval where it matters.

Website  ·  Documentation  ·  Quick start  ·  MIT license

message ──▶ channel ──▶ relay ──▶ orchestrator ──▶ planner or (Telegram/ │ classify │ decompose into event Slack/ │ (heuristic → │ subtasks with (webhook, Discord/ │ pattern cache → │ dependencies) metric, terminal) │ LLM) │ connector) ▼ ▼ agent-router ◀── 24 specialist agents │ prepare ──▶ approve ──▶ execute (safe) (your gate) (ships/spends/sends)

What it is

Multi-agent, not a chatbot. 24 specialist agents (marketing, ops, data, legal, and more — each just a markdown file). A message is classified cheaply, then answered directly, routed to one specialist, or decomposed into a dependency-ordered plan run across several. An optional distributed executive board (7 reasoning personas) can deliberate on strategic questions. Event-driven, not just a chat bot. A message is one trigger; a webhook, a metric crossing a threshold, a connector event, or a semantic match is another. Any of them can run an agent or a playbook (a reusable SOP), and durable processes carry multi-day work across waits and restarts. Nova runs the operation in the background, not only when you ask. Two-phase execution + governance. For interactive requests the safe half — research, drafts, generation — runs freely; then an inline Approve / Revise / Cancel gate; only after you approve does the consequential half — publish, send, spend — run. Autonomous paths (schedules, automations) are pre-authorized and governed by spending caps, role-based permissions, and content policies that can hard-block. Agents also earn autonomy over time (a per-category ladder). Your models, your machine. It drives the official vendor CLIs (Claude Code, Gemini, Codex) as subprocesses, so it runs on subscriptions you already pay for instead of metered API tokens — and it also supports any OpenAI-compatible API (OpenRouter, DeepSeek, xAI, local Ollama/vLLM). It does not reuse or extract tokens. Storage is local split SQLite; embeddings run locally (all-MiniLM-L6-v2, 384-dim). Your keys, your data. MIT licensed.

What it does Core orchestration

24 specialist agents + task decomposition with dependency resolution and parallel execution Two-phase approval gate + an earned-autonomy ladder (ask → notify → auto-within-caps) Persistent memory (facts, goals, tasks) with local semantic recall Knowledge base (RAG) — feed it PDFs, docs, and URLs; retrieved across agents with citations, on personal / team / per-agent scopes Multi-channel: Telegram (primary), Slack, Discord, terminal (nova chat / nova connect); WhatsApp per-user Workboards — boards of typed cards with stages you define: create one with nova workboard create or ask a specialist agent to put a set of results on a board ("put these leads on a board"); agents fill and move cards, you drag them across stages in the dashboard, and a stage can optionally queue a playbook or agent task when a card enters it, behind the same approval gate

Business automation

Playbooks — reusable, versioned, parameterized SOPs Automations — an event (webhook, metric, connector, or semantic match) runs an agent or playbook, with dedupe, rate limits, retries, and a dead-letter queue Durable processes — multi-day flows that wait for a timer or event and resume, surviving restarts Document extraction — schema → strict, type-checked JSON from PDFs/DOCX Connectors — two-way Stripe, Shopify, Zendesk, HubSpot (read + write) Connected data — query HTTP JSON/CSV, read-only SQLite, or a connector read action ROI reporting — tasks automated, hours saved, and value vs. cost

Governance & hardening

Compliance policies — spend caps, approval routing, and PII/content checks that can hard-block (prevent execution even after approval) Role-based permissions (capabilities) and out-of-office delegation Exactly-once idempotency, advisory locks (no double-fire), and AES-256-GCM encrypted secrets

Foundations

13 MCP servers (Notion, Google Workspace, Playwright, Cloudflare, ClickUp, GoHighLevel, Firecrawl, Tavily, Exa, and more) — called via mcp2cli, where agents discover tools on demand instead of loading every schema into context 45 skills (image/doc generation, research writing, and more) invoked by agents as needed Scheduler + proactive services (morning briefings, smart check-ins) Voice — inbound and outbound calls via Twilio; voice messages transcribed with Groq or local Whisper A unified nova CLI and a web dashboard

How it works Every incoming message is classified through three tiers, cheapest first:

Heuristic — short, simple messages skip straight to the model (no classifier LLM call). Pattern cache — a request that matches a plan that worked before reuses it, skipping classification. LLM classification — only genuinely new, complex asks pay for a cheap classify call (simple / routed / complex).

Complex requests are decomposed into subtasks with dependencies; independent branches run in parallel, each on a specialist agent with its own tools and MCP access. Consequential actions run in the execute phase, which waits for your approval (or runs under an earned autonomy grant with a spending cap). Prepared artifacts — copy, images, files — flow from prepare into execute. Honest about the boundaries Nova connects to real accounts and can spend real money, so it's worth being precise about what protects you:

The approval gate is the default safety boundary — not a sandbox. Sandboxed execution is opt-in and off by default: agent tools run unsandboxed on your host. A hardened Docker sandbox exists (NOVA_SANDBOX_BACKEND=docker) but is not the default, and if Docker isn't installed it falls back to unsandboxed with a warning. Run it as a dedicated user / on a VPS, and turn on the Docker sandbox if that matters to you. "Asks before it acts" is about interactive requests. Things you set up in advance to run on their own — scheduled tasks, automations, and durable-process steps — are pre-authorized when you create them and run without a fresh prompt each time (that's the point of automating). The controls on those autonomous paths are the earned-autonomy ladder with spending caps and the hard-block compliance policies (which stop execution even there). It's young and solo-built. ~390 unit tests across the suite, but no end-to-end tests of the full automation chain yet, and it's a broad surface for one maintainer. The connector set is a starter four. Read the code before you trust it with the keys.

On top of the approval gate, four controls are on by default: least-privilege agent env (NOVA_AGENT_ENV_STRICT), an egress leak firewall that redacts/blocks secrets leaving the system (NOVA_LEAK_FIREWALL), an untrusted-input firewall that neutralizes tool/web/email content before it reaches an agent prompt (NOVA_UNTRUSTED_FIREWALL), and a dashboard that binds loopback-only unless DASHBOARD_PASS is set. Run nova doctor --security to grade your deployment. Quick start Prerequisites

Bun (curl -fsSL https://bun.sh/install | bash) The Claude Code CLI installed and authenticated (or another supported provider) A Telegram account and a bot token from @BotFather

Option A: One-line install (recommended) curl -fsSL https://mynova.space/install | bash That clones Nova to ~/nova, installs anything missing (Bun, the Claude Code CLI), and launches a guided setup wizard (nova init) that connects Telegram and an AI provider — no file editing, and it can auto-detect your Telegram user ID. The wizard is resumable.

Prefer to clone yourself? git clone https://github.com/djbelieny/nova.git && cd nova && bash bootstrap.sh does the same. Just checking prerequisites? bash bootstrap.sh --check reports what's installed and changes nothing.

Option B: Manual setup git clone https://github.com/djbelieny/nova.git cd nova bun run setup # install deps, create .env

edit .env with your tokens/keys

capabilities

governance

Documentation

mynova.space/docs — every feature, command, and configuration option SETUP.md — guided setup walkthrough docs/ARCHITECTURE.md — deep technical reference CLAUDE.md — architecture & conventions SECURITY.md — reporting vulnerabilities · CONTRIBUTING.md — how to contribute

License MIT — take it, customize it, make it yours. Built with open source Nova stands on a lot of other people's work. Each project below is used under its own license (full license texts ship in node_modules); thank you to their maintainers. Runtime & AI

Bun — the runtime · TypeScript sqlite-vec — vector search inside SQLite Transformers.js — local embeddings, running the all-MiniLM-L6-v2 model Model Context Protocol SDK — MCP mcp2cli — the MCP-to-CLI bridge Nova drives so agents call MCP tools from the shell instead of loading every schema into context RTK — Rust Token Killer (Apache-2.0) — installed by bootstrap.sh and on by default; compresses the output of common dev commands (git, build, test, grep…) by 60–90% before it re-enters an agent's context. Nova routes its own shell through it and it's safe by design (unknown commands pass through unchanged). Disable with NOVA_RTK=off.

Channels & UI

grammY (Telegram) · Bolt (Slack) · discord.js (Discord) · Ink + React (terminal & dashboard)

Documents & media

pdf-parse · mammoth · docx · PptxGenJS · sharp · Playwright

Other

groq-sdk (transcription) · Resend (email) · dotenv

Nova runs on the official vendor CLIs — Claude Code, the Gemini CLI, and Codex — driven as subprocesses under your own subscriptions. Those are proprietary tools, not bundled with Nova. And it grew out of Goda's minimal Claude Code Telegram Relay pattern — the original "run Claude Code as an always-on Telegram bot" idea — since almost entirely rewritten into the platform you see here.

Built by Jake Belieny

source