nuvel

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/:

Plugin	Harness	MCP Support	Skills
codex-plugin	OpenAI Codex CLI	✅ streamable-http	setup, agent, review
claude-code-plugin	Anthropic Claude Code CLI	✅ stdio	setup, agent, review
chatgpt-plugin	OpenAI ChatGPT (web/app)	❌	setup, workflows
claude-plugin	Anthropic Claude (web/app)	❌	setup, workflows
grokbot-plugin	xAI GrokBot (web/app/API)	❌	setup, workflows
cursor-plugin	Cursor IDE	✅ stdio	setup, agent, review

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:

1. Each LLM call's token count is multiplied by the model's per-token price from pricing.json
2. Cost is logged to the terminal and stored in traces (cost_usd per call, total_cost_usd in summary)
3. 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