Agents

17 specialist agents ship with OpenVesper. Each is a directory of markdown files — no code, no compilation. Install only the ones you need, set one as the default, and switch any time.

Agent workflow

Agents work like any other package manager: browse, install, start, run.

1. Browse

# See all available agents (bundled + your installed)
vesper agent registry

# Search by name, tag, or description
vesper agent search defi

# See details on one agent
vesper agent show bags-hunter

2. Install

Installing an agent copies it from the bundled directory (.agents/) to your user directory (~/.openvesper/agents/). You can then edit the markdown files freely without touching the source.

vesper agent install bags-hunter

# Output:
# ✓ Installed: bags-hunter
#   Path: /home/you/.openvesper/agents/bags-hunter
# Next steps:
#   vesper agent run bags-hunter "test"
#   vesper agent start bags-hunter

3. Start (make it default)

vesper agent start bags-hunter

# Now all queries without -a flag use this agent
vesper -q "What's trending on Bags.fm?"
# → routes to bags-hunter automatically

4. Run (one-off, no default change)

vesper agent run defi-strategist "Best stablecoin yields right now?"

5. List installed

vesper agent list

# Output:
# Installed agents:
#   ● 🎒  bags-hunter     Bags Hunter      ♥
#   ○ 🏦  defi-strategist DeFi Strategist
#
# (● = currently active, ♥ = heartbeat enabled)

6. Stop or uninstall

# Stop using the current default — revert to "auto"
vesper agent stop

# Remove an agent entirely
vesper agent uninstall bags-hunter

Create your own

Scaffold a new agent with all 6 core files pre-filled:

vesper agent create my-trading-coach

This creates ~/.openvesper/agents/my-trading-coach/ with:

SOUL.md — persona template
IDENTITY.md — metadata template
USER.md — user context template
TOOLS.md — tool policy template
HEARTBEAT.md — scheduled checklist (disabled)
MEMORY.md — empty memory store
skills/ — directory for your custom skills

Edit any file, run vesper agent run my-trading-coach "test", iterate. No rebuild needed — markdown files are read fresh on every run.

Browse the catalog

General

🤖 Auto autoDefault agent. Routes to the right tool based on input.

Crypto & DeFi

🎒 Bags Hunter bags-hunterSolana memecoin specialist for Bags.fm — scoring, rug-checking, portfolio review.
🏦 DeFi Strategist defi-strategistMulti-protocol yield, risk decomposition, position monitoring.
🔬 Investment Researcher investment-researcherThesis tracking, market analysis, news impact scoring.
☀️ Solana Dev Coach solana-dev-coachAnchor, SPL, Token-2022, cNFT guidance.

Software development

👨‍💻 Code Reviewer code-reviewerPR reviews, refactor suggestions, style critique.
🛡 Security Reviewer security-reviewerCode audits, secret scanning, dependency review.
🧪 TDD Coach tdd-coachTest-first development guidance, failing-test generation.

Productivity

⚡ Productivity Coach productivity-coachDaily standup, weekly retros, task tracking.
📊 Data Analyst data-analystData exploration, SQL, chart generation.
✍️ Content Writer content-writerBlog drafts, social posts, editorial calendar.
💼 Sales Coach sales-coachPipeline review, cold outreach, follow-up reminders.
⚖️ Legal Assistant legal-assistantContract review, deadline tracking, doc summaries.

Lifestyle

🏛 Stoic Mentor stoic-mentorDaily reflection, perspective on hard situations.
💪 Fitness Trainer fitness-trainerWorkout plans, training adjustments, recovery.
👨‍🍳 Cooking Coach cooking-coachRecipe ideas, meal planning, dietary substitutions.
🗣 Language Tutor language-tutorVocabulary, grammar, conversation practice.
✈️ Travel Planner travel-plannerTrip planning, itineraries, visa lookups.

Scheduling agents (heartbeats)

Every agent ships with a HEARTBEAT.md file. Edit it to set enabled: true and a cron schedule, then the gateway will wake the agent periodically to check on tasks proactively.

See Cron Jobs and Gateway for the proactive loop details.