Agents

An agent in OpenVesper is a directory of markdown files. No code, no compilation, no special tooling — just plain text you can edit in any editor.

What is an agent?

An agent is a persona + tool policy + memory. The runtime takes these markdown files, assembles them into a system prompt, and hands that prompt to an LLM along with the registered tools. Different agents produce different behaviors from the same model.

OpenVesper ships with 16 agents in .agents/. You can create your own, override an existing one, or use them as-is.

Agent directory structure

.agents/security-reviewer/
├── SOUL.md                    Who I am, how I think
├── IDENTITY.md                Metadata: name, icon, model
├── USER.md                    What I know about you
├── TOOLS.md                   Which tools I use
├── HEARTBEAT.md               Scheduled tasks (opt-in)
├── MEMORY.md                  Long-term memory
├── memory/
│   └── 2026-05-14.md          Daily session log
├── skills/
│   ├── pr-review/
│   │   └── SKILL.md           Agent-specific skill
│   └── secret-scan/
│       └── SKILL.md
└── references/                Static reference docs

The 6 core files

SOUL.md — Who the agent is

SOUL.md describes the agent's persona, principles, voice, and refusals. It's the "system prompt" portion that defines character. Example:

# Soul

I am the Security Reviewer.

I read code looking for security issues — hardcoded secrets,
unsafe shell calls, SQL injection, missing input validation,
unsafe deserialization, race conditions, privilege confusion.

I report findings concisely with file:line citations and the
CWE category when applicable. I don't editorialize.

When I'm uncertain whether something is a real issue, I say so.
I'd rather flag a false positive than miss a real one.

I never modify code without explicit permission. I review and report.

IDENTITY.md — Metadata

Structured metadata for the runtime to discover the agent and pick the right model.

# Identity

mode: security-reviewer
name: Security Reviewer
icon: 🛡
description: Reviews code for security issues, reports findings.
defaultModel: claude-opus-4-5
defaultProvider: anthropic

USER.md — User context

What this agent should know about you. This is your space to give background — your role, the company, the codebase conventions.

# About the user

You are reviewing code written by a solo developer
working on the OpenVesper monorepo. The codebase is TypeScript,
strict mode, no eslint disable comments, no `any` types unless
genuinely necessary.

Skip nitpicky style issues — only flag genuine security problems.

TOOLS.md — Tool policy

Which plugins this agent intends to use. Currently advisory (the runtime allows all tools); a future release will enforce this as a runtime gate.

# Tools

Primary: filesystem (read-only), code, github
Secondary: shell (with strict allowlist), security
Out of scope: trading, social, email (this agent stays read-only)

This agent prefers to read code, search for patterns, and
report. It does not modify files or open PRs without
explicit user instruction.

HEARTBEAT.md — Scheduled tasks

An optional checklist the agent runs on a cron schedule when autonomous mode is enabled. Disabled by default for all 16 agents.

---
schedule: "0 9 * * MON"
enabled: false
---

# Heartbeat — security-reviewer

## Recurring task

Weekly: scan recently merged PRs for security issues.
Audit any new dependencies added in the last 7 days.

To activate: set enabled: true and run the scheduler daemon.

MEMORY.md — Long-term memory

Persisted facts the agent has learned across sessions. This file is rewritten by the runtime when memory is enabled (default off). For manually managed agents, you can hand-edit it.

# Memory

## Project conventions
- All new tools must include a permission field
- Error messages should be actionable, not just stack traces
- TypeScript strict mode is required

## User preferences
- Prefers concise output, no bullet-point overuse
- Casual Turkish tone in conversational responses

The 16 shipped agents

Creating your own agent

Easiest way: copy an existing one and rewrite the files.

# Copy a template
cp -r .agents/productivity-coach .agents/my-agent

# Edit the 6 core files in your editor
nano .agents/my-agent/SOUL.md
nano .agents/my-agent/IDENTITY.md
# ... etc

# Use the CLI to verify
node apps/cli/dist/index.js agent test my-agent

The agent test command validates the agent has all required files and previews the SOUL.md content. It does not actually run the LLM.

Switching between agents

At runtime, every interaction routes through a single agent. To use a different one:

# Via CLI
node apps/cli/dist/index.js agent --mode security-reviewer --message "audit this"

# Or set default in ~/.openvesper/config.json
{
  "defaultAgent": "auto",
  "providers": { ... }
}

What's next?

• Plugins — how to build and register tools
• Skills — modular instruction snippets agents can pull in
• Cron Jobs & Heartbeats — autonomous mode