Production-ready agents, your way.
Skills, scaffolder, or meta-agent — build agents on Google ADK, Buzz, or Hermes Agent with the workflow you already have.
What is nuvel?
nuvel is an open-source toolkit for building production-ready agents across the agent frameworks that matter — Google ADK, Buzz, and Hermes Agent. It ships in three shapes — knowledge skills, a CLI scaffolder, and an autonomous meta-agent — and you use whichever fits the way you already work.
The skills follow the Anthropic skills format, so they plug into the coding agent you already use: Claude Code, Codex, Cursor, OpenClaw, Hermess Agent, and any other agent that supports the format. The CLI stamps out a battle-tested skeleton tuned per framework — an opinionated 17-plugin chain for ADK, a leaner Buzz skeleton with Nostr relay and Bitcoin/Lightning tools, and a Hermes Agent skeleton with platform gateways. The meta-agent does it for you autonomously from a natural-language description.
Frameworks
| Framework | Flag | Knowledge skills | Where the agent runs |
|---|
| Google ADK | --framework adk (default) | 15 skills (agent patterns, tool creation, prompt engineering, callbacks/HITL, streaming, skill design, Composio Tool Router, workflow graphs, task delegation, long-horizon guardrails/sessions, cron isolation, org memory retrieval, self-improvement) | Your server (OpenRouter + LiteLLM) |
| Buzz | --framework buzz | Nostr relay, Bitcoin/Lightning tools, on-chain leaderboard | Your server (OpenRouter) |
| Hermes Agent | --framework hermes | Platform gateways (Telegram, Slack, Teams), skill-driven config | Your server (OpenRouter) |
Features
- Three shapes, one toolkit — drop the skills into your coding agent, run the scaffolder, or let the meta-agent build the whole thing autonomously.
- Production skeleton, not a toy — every generated agent ships with FastAPI, framework-appropriate observability (17-plugin chain for ADK), Dockerfile, Railway config, and tests.
- Portable knowledge skills — skills across the supported frameworks, with progressive disclosure so they don't bloat your context.
- Self-evolving agents —
--persona ships a SOUL.md / awakening pattern for agents meant to live for months and develop a stable character. Inspired by OpenClaw. (ADK only.)
- ~1000 integrations —
--with-composio wires the Composio Tool Router for one-line access to Gmail, GitHub, Slack, Notion, Calendar, and more. (ADK only.)
- ACP-compatible & CLI-runnable —
--with-acp adds an Agent Client Protocol adapter (JSON-RPC over stdio, the protocol editors like Zed use to drive an agent as a subprocess) plus a local terminal CLI. Run it as an editor subprocess (python -m <pkg>.acp) or straight from the shell (python -m <pkg>.cli "…" one-shot, or a REPL). The adapter honors the editor's session: mcpServers passed in session/new (stdio / HTTP / SSE) are wired in as tools, the agent reads/writes through the editor's filesystem view (unsaved buffers included) when the client supports it, and sensitive tool calls are gated by an editor approve/deny prompt (session/request_permission, tunable via ACP_PERMISSION_MODE). Both entrypoints reuse the same plugin-wired Runner as the FastAPI server. (ADK only.)
- Messaging gateways — scaffold an agent reachable from Slack, Telegram, or MS Teams with one flag (
--with-slack, --with-telegram, --with-teams). See docs/superpowers/specs/2026-05-09-messaging-gateways-design.md. (ADK only.)
- Slack: Multimodal — forwards user images/files (size and count caps via
GATEWAY_MAX_ATTACHMENT_*) and uploads agent artifacts back to chat. See the per-channel README for details.
- Telegram: Multimodal — forwards user images/files (size and count caps via ) and uploads agent artifacts back to chat. See the per-channel README for details.
Bot Fleet Management
nuvel ships with a built-in bot fleet management system for orchestrating Hermes-backed agents.
Single-bot operations:
nuvel bots create <name> [--skills <refs>] [--model <model>]
nuvel bots list
nuvel bots info <name>
nuvel bots chat <name> <message>
nuvel bots logs <name> [-n 50]
nuvel bots delete <name>
nuvel bots send <from> <to> <msg>
Skill discovery:
nuvel bots skills list [--category <theme>]
nuvel bots skills search <query>
Fleet deployment (multi-bot):
nuvel fleet deploy <manifest.yaml>
nuvel fleet list
nuvel fleet status <name>
nuvel fleet destroy <manifest.yaml>
nuvel fleet update-vision <fleet> <path>
Fleet manifests support VISION.md (shared constitution symlinked into every bot), a Manager bot with fleet governance skills, and per-bot cron routines.
Example manifest:
name: "my-company"
vision: |
# Fleet Constitution
All bots follow these shared rules...
manager:
name: manager-bot
model: anthropic/claude-sonnet-4
default_model: deepseek/deepseek-v4-flash
bots:
- name: triage-bot
skills: [customer/triage-agent]
routines:
- schedule: "0 8 * * 1-5"
task: "Review yesterday's logs"
Agent Plugins
Agent Plugins (agent-plugins.org v1.0.0) for integrating Nuvel OrgMemory into major AI coding and chat harnesses. Six plugins live under plugins/:
Drop a plugin into your agent's plugin directory, or reference the skills from your agent's skill loader — each is self-contained, independently versioned, and follows the agent-plugins.org packaging standard. See plugins/README.md for full docs.
Quick Install
Use the skills with Claude Code:
git clone https://github.com/Folken2/nuvel.git
# Skills live in nuvel/backends/adk/skills/ and a ready-made SKILL.md is at .claude/skills/nuvel/
Install the CLI from PyPI:
pip install nuvel-cli
The PyPI distribution is named nuvel-cli (the bare nuvel name was too close to an existing package). The CLI command and all imports stay nuvel — pip install nuvel-cli then nuvel agent create my-agent.
Or install from source (always available):
git clone https://github.com/Folken2/nuvel.git
cd nuvel
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
Getting Started
1. Scaffold an agent
# Google ADK (default)
nuvel agent create k8s-monitor --description "checks pod health, queries logs, alerts on anomalies"
# Buzz
nuvel agent create k8s-monitor --framework buzz --description "..."
# Hermes Agent
nuvel agent create k8s-monitor --framework hermes --description "..."
You get a complete project at generated-agents/k8s-monitor/ — package layout, FastAPI server, framework-appropriate plugins, Dockerfile, Railway config, and tests.
2. Fill in the brain
The skeleton is free; the brain is yours. Edit:
- ADK:
tools/ (one file per tool), prompt/instructions.py, skills/, agent.py (wire tools + SkillToolset).
- Buzz:
tools/ (Nostr + Lightning tools), prompt/instructions.py, skills/, agent.py.
- Hermes Agent:
tools/, prompt/instructions.py, skills/, agent.py (wire platform gateways).
If you're driving Claude Code, the bundled skill at .claude/skills/nuvel/SKILL.md walks Claude through this step-by-step.
3. Run it
cd generated-agents/k8s-monitor
cp .env.example .env # add OPENROUTER_API_KEY
pip install -r requirements.txt
# ADK
DEV_MODE=true python run_adk.py
# Buzz
python server.py # or `python run_dev.py "<prompt>"` for a quick local test
# Hermes Agent
python server.py # or `python run_dev.py "<prompt>"` for a quick local test
The agent runs at http://localhost:8000. POST to /run_sse/ to talk to it.
Want the meta-agent to do all this for you?
nuvel run --dev # http://localhost:8000
Then describe the agent you want; nuvel will scaffold, generate, and validate it autonomously.
CLI
| Command | Description |
|---|
nuvel agent create <name> | Scaffold a new agent (default framework: adk) |
nuvel agent create <name> --framework <fw> | Pick framework: adk, buzz, or hermes |
nuvel agent create <name> --description "..." | Scaffold with a one-liner description |
nuvel agent create <name> --persona | (adk only) Self-evolving agent (SOUL.md, awakening flow) |
nuvel agent create <name> --with-composio | (adk only) Bundle ~1000 integrations via Composio Tool Router |
nuvel agent create <name> --with-slack | (adk only) Add a Slack Events API gateway (auto-enables --with-composio) |
nuvel agent create <name> --with-telegram | (adk only) Add a Telegram Bot webhook gateway |
nuvel agent create <name> --with-teams | (adk only) Add a Microsoft Teams bot bridge via Azure Bot Service |
nuvel agent create <name> --workflow | (adk only) Workflow-native root agent — an ADK 2.0 Workflow graph with task-mode nodes, typed contracts, and conditional routing |
nuvel agent create <name> --with-acp | (adk only) Make the agent ACP-compatible (Agent Client Protocol over stdio, python -m <pkg>.acp) and CLI-runnable (python -m <pkg>.cli) |
nuvel agent create <name> --with-eval | (adk only) Stamp a starter evalv2 suite into the agent (skills/default/eval/suite.yaml + a sample example) |
nuvel agent create <name> --output-dir ./agents | Override the output directory |
nuvel skills list [--framework <fw>] | List bundled knowledge skills for a framework |
nuvel skills search <term> [--framework <fw>] | Search skills by keyword |
nuvel doctor [--path <dir>] | Diagnose the install and the agent in cwd (env, deps, pricing) |
make install / make dev / make run / make dev-ui / make skills / make test are wired through to the same commands.
Example
"A Kubernetes monitoring agent that checks pod health, queries logs, and alerts on anomalies."
Whichever shape you used, you end up with the same project:
generated-agents/k8s-monitor-agent/ — full project, ready to pip install and run- Tools:
get_pod_status, query_pod_logs, check_anomalies
- Domain skills:
k8s-alerting/SKILL.md with escalation patterns
- System prompt tailored to k8s operations
- Plugin chain wired in (cost guard, tracing, resilience, caching)
Architecture
nuvel/
├── nuvel/
│ ├── agent.py # Meta-agent: LlmAgent with tools + SkillToolset
│ ├── cli.py # `nuvel` CLI (new / skills / run)
│ ├── run_adk.py # FastAPI server (launched by `nuvel run`)
│ ├── prompt/instructions.py # Meta-agent system prompt
│ ├── tools/ # scaffold, write_file, read_file, list_files, validate
│ ├── plugins/ # Meta-agent chain (12, via Makefile PLUGIN_FLAGS)
│ ├── config/ # LiteLLM/OpenRouter config
│ └── backends/ # Per-framework scaffolders + skills
│ ├── adk/ # Google ADK backend
│ │ ├── scaffold.py
│ │ ├── templates/ # Production skeleton for ADK agents
│ │ └── skills/ # ADK knowledge skills
│ ├── buzz/ # Buzz backend (Nostr relay + Lightning)
│ │ ├── scaffold.py
│ │ ├── templates/
│ │ └── skills/
│ └── hermes/ # Hermes Agent backend
│ ├── scaffold.py
│ ├── templates/ # Platform gateway skeleton
│ └── skills/
├── .claude/skills/nuvel/ # Claude Code SKILL.md for driving the CLI
├── pyproject.toml # Packaging + `nuvel` console script
└── generated-agents/ # Output directory
Key Design Decisions
- Template-based scaffolding — Every generated agent inherits a proven production skeleton (plugins, circuit breakers, rate limiting, structured logging, SSE streaming). You only write the brain.
- Skills as a portable knowledge format — The 15 ADK skills follow the Anthropic skills format, so they work in Claude Code today and in any agent that adopts the format. Progressive disclosure (L1/L2/L3) keeps context usage efficient.
- Scoped file operations — All file tools are sandboxed to the output directory. No path traversal possible.
Generated Agent Structure
Each generated agent is a standalone, runnable project:
generated-agents/my-agent/
├── my_agent/
│ ├── agent.py # LlmAgent with SkillToolset
│ ├── prompt/ # Custom system prompt
│ ├── tools/ # Domain-specific tools
│ ├── skills/ # Domain skills (SKILL.md)
│ ├── contexts/ # Domain knowledge files
│ ├── plugins/ # Full production plugin chain
│ └── config/ # LiteLLM/OpenRouter config
├── run_adk.py # FastAPI server with auth + health checks
├── requirements.txt
└── .env.example
Run any generated agent:
cd generated-agents/my-agent
pip install -r requirements.txt
DEV_MODE=true python run_adk.py
Configuration
Every environment variable a generated agent reads is documented inline in .env.example, grouped by subsystem (auth, plugins, providers, memory, cron, and more). It's copied into each scaffolded project from nuvel/backends/adk/templates/.env.example, so that file — not this README — is the canonical reference for what to configure.
Plugin Chain
Every generated agent ships with a full plugin chain — cross-cutting concerns that apply to all interactions without touching agent code.
| Plugin | Type | What it does |
|---|
| MemoryPlugin | Features | Markdown file-based long-term memory across sessions |
| CostGuardPlugin | Budget | Calculates USD cost per LLM call, enforces per-session budget limits |
| ContextWindowPlugin | Observability | Tracks context-window occupancy per response (tokens used / max / %) for live UI indicators |
| TracePlugin | Observability | Raw event JSONL + consolidated conversation JSON for eval pipelines |
| ContextFilterPlugin | Performance | Keeps last N invocations in context window (default: 10) |
| ConsoleLoggerPlugin | Observability | Color-coded terminal output for all lifecycle events |
| ToolEventsPlugin | Observability | Structured tool execution events for SSE streaming |
| ResiliencePlugin | Resilience | Circuit breaker and per-session rate limiting for tool calls |
| GuardrailsPlugin | Resilience | Halts runaway model/tool loops — no-progress and repeated-failure guards behind a shared halt latch |
| CronIsolationPlugin | Resilience | Headless tool-approval policy during scheduled cron runs; inert outside cron runs |
| CachePlugin | Performance | Session-scoped caching for specific tools with TTL |
| ReflectAndRetryToolPlugin | Resilience | Self-healing tool retry with LLM reflection (max 3) |
| SaveFilesAsArtifactsPlugin | Features | Saves user-uploaded files as session artifacts |
| RecordingsPlugin | Testing | Records LLM/tool interactions for ADK conformance testing; off unless NUVEL_RECORD_REPLAY=1 (its config is client-writable session state, so never enable it on a server) |
| ReplayPlugin | Testing | Replays recorded interactions instead of executing live calls; off unless |
Cost Tracking & Budget Guard
The CostGuardPlugin tracks LLM costs using a pricing.json config file and optionally enforces per-session budget limits.
How it works:
- Each LLM call's token count is multiplied by the model's per-token price from
pricing.json
- Cost is logged to the terminal and stored in traces (
cost_usd per call, total_cost_usd in summary)
- If
COST_GUARD_BUDGET is set and the session cost exceeds it, further LLM calls are blocked with a friendly message
Maintaining pricing.json:
The pricing config lives at nuvel/plugins/pricing.json (or <agent>/plugins/pricing.json for generated agents). Edit it to add or update model pricing — no code changes needed:
{
"moonshotai/kimi-k2.5": {
"input": 0.0000005,
"output": 0.000002
},
"anthropic/claude-sonnet-4": {
"input": 0.000003,
"output": 0.000015
}
}
Keys are model IDs (matching what your LLM provider returns). The plugin auto-strips provider prefixes — openrouter/moonshotai/kimi-k2.5 matches moonshotai/kimi-k2.5. Prices are in USD per token.
To find current prices: check OpenRouter models or your provider's pricing page.
Context Window Tracking
The ContextWindowPlugin knows the total context window of the selected model and reports how full it is after every response — the same "context used" signal Claude Code shows. It's read-only: it never mutates the request and never blocks.
After each LLM call it publishes a context_window snapshot into session state, so a frontend consuming the SSE stream can render a live indicator on every agent response:
{
"model": "anthropic/claude-sonnet-4",
"used_tokens": 12345,
"prompt_tokens": 12000,
"completion_tokens": 345,
"max_tokens": 200000,
"remaining_tokens": 187655,
"used_pct": 6.17,
"remaining_pct": 93.83
}
used_tokens prefers the provider's total_token_count (so reasoning/thinking tokens are included) and falls back to prompt + completion. When the model isn't in the config, percentages are omitted (max_tokens: null) unless CONTEXT_WINDOW_DEFAULT is set.
Maintaining context_windows.json:
Window sizes live at nuvel/plugins/context_windows.json (or <agent>/plugins/context_windows.json for generated agents) and use the same keys as pricing.json, so provider prefixes are auto-stripped (openrouter/anthropic/claude-sonnet-4 matches anthropic/claude-sonnet-4):
{
"anthropic/claude-sonnet-4": 200000,
"google/gemini-2.5-pro": 1048576
}
| Env var | Default | Effect |
|---|
CONTEXT_WINDOW_CONFIG | auto-detected | Path to a custom context_windows.json |
CONTEXT_WINDOW_DEFAULT | 0 (unknown) | Fallback window size for models not in the config |
CONTEXT_WINDOW_WARN_PCT | 0 (off) | Log a one-time warning once usage crosses this percent |
Traces for Self-Improvement Evals
The trace system captures two layers:
traces/
2026-04-06_<session>.jsonl # Raw events (per-event, for debugging)
conversations/
2026-04-06_<session>.json # Consolidated record (per-conversation, for evals)
The consolidated JSON includes: full system prompt, user input, LLM thinking/reasoning, response, tool calls with args/results, token usage, cost, context-window occupancy (per call, plus a peak_context_tokens / peak_context_pct in the summary), and timing — everything an eval agent needs to score quality and drive improvements.
Configuration
Core
| Variable | Default | Description |
|---|
OPENROUTER_API_KEY | (required) | OpenRouter API key |
FAST_MODEL | openrouter/moonshotai/kimi-k2.5 | LLM model |
AGENTS_OUTPUT_DIR | ./generated-agents | Where agents are created |
DEV_MODE | false | In-memory sessions for dev |
PORT | 8000 | Server port |
API_KEY | (optional) | Bearer token auth |
SESSION_SERVICE_URI | (optional) | PostgreSQL for prod sessions |
Cost Guard
| Variable | Default | Description |
|---|
COST_GUARD_BUDGET | 0 (unlimited) | Max USD per session. Set to e.g. 0.50 to cap spending |
COST_GUARD_PRICING | (bundled) | Path to custom pricing.json. Default uses the bundled file |
Observability
| Variable | Default | Description |
|---|
TRACE_ENABLED | true | Master on/off for all tracing |
TRACE_DIR | ./traces | Directory for JSONL + conversation trace files |
TRACE_DB | false | Also write traces to PostgreSQL (agent_traces table) |
LOG_FORMAT | text | json for production (structured), text for dev (colored) |
LOG_LEVEL | INFO | Logging level |
Memory
| Variable | Default | Description |
|---|
MEMORY_ENABLED | true | Enable/disable long-term memory |
MEMORY_DIR | ./memory | Directory for markdown memory files |
MEMORY_MAX_CORE_SIZE | 10000 | Max chars for core memory file |
MEMORY_MAX_TOPIC_SIZE | 5000 | Max chars per topic file |
Resilience
| Variable | Default | Description |
|---|
TOOL_RATE_LIMIT | 5.0 | Tool calls per second, per session (token bucket) |
TOOL_RATE_BURST | 20 | Burst capacity for tool rate limiting, per session |
TOOL_RATE_LIMIT_TOTAL | 50.0 | Tool calls per second across all sessions (caps callers who open many sessions) |
TOOL_RATE_BURST_TOTAL | 200 | Burst capacity across all sessions |
PROTECTED_TOOLS | (none) | Comma-separated tools with circuit breaker |
CONTEXT_FILTER_KEEP | 10 | Prior invocations to keep in context window |
Tests
make test
Tests cover scaffold, file tools, validation, memory, cost guard, conversation traces, and end-to-end pipeline.
Roadmap
- V1 (current): Local agent generation with scaffold + validate + iterate
- V2: Self-improvement eval pipeline consuming conversation traces
- V3: GitHub integration — create repos, push generated agents, set up CI
- V4 (proposed): One-shot auto-deploy —
deploy_agent_tool pushes the
generated agent to Railway (or equivalent) and returns a live URL, so
non-technical users go from natural-language intent to a running agent
without leaving the conversation
- V5 (proposed): Managed tier — same binary, hosted. Users sign up, describe
an agent, and get a live URL on our infrastructure (our Railway, our LLM
keys, usage-based billing). Open-source stays the primary product and the
community path; managed serves users who want zero ops
Contributing
Contributions are welcome — please read CONTRIBUTING.md
before opening a PR. For security issues, see SECURITY.md.
License
MIT © Albert Folch
