Creating Agents

New agents are created through the CLI wizard, non-interactive flags, or the JSON-RPC bridge API. Each method uses the same scaffolding engine under the hood.

CLI Wizard

reeve agents add

The interactive wizard walks you through:

1. Name — Agent identifier (e.g., marketing-manager)
2. Role — Select from coordinator, manager, worker, research, assistant
3. Workspace — Directory for the agent's context files
4. Team — Optional team grouping
5. Channel bindings — Which messaging platforms to connect
6. Auth — API keys or shared auth

What gets created

When you create an agent, the scaffolding engine:

1. Creates the workspace directory
2. Writes role-appropriate template files:
   • AGENTS.md — Agent instructions (role-specific)
   • SOUL.md — Personality and communication style
   • HEARTBEAT.md — Periodic check instructions (managers/research only)
   • TOOLS.md — Available tool documentation
   • IDENTITY.md — Name, emoji, theme
3. Creates a memory/ directory for persistent memory
4. Adds the agent entry to reeve.json with role defaults
5. Applies model, heartbeat, and subagent config from role defaults

Non-interactive mode

For scripting and automation:

reeve agents add \
  --name ad-optimizer \
  --role worker \
  --workspace ~/reeve-workspaces/ad-optimizer \
  --team marketing

Role-Based Templates

Each role has tailored workspace files:

Manager templates

# AGENTS.md (manager role)
## Three-Tier Architecture
- Manager: Strategic planning, delegation, oversight
- Pipeline Manager: Complex multi-file orchestration
- Workers: Focused task execution

## Management Framework
- Spawn pipeline-manager for complex work
- Dispatch workers for focused tasks
- Monitor sub-agent health and progress

Worker templates

# AGENTS.md (worker role)
## Scope
- Execute assigned tasks within your workspace
- Report completion to spawning agent
- No management framework (lean and focused)

Research templates

# AGENTS.md (research role)
## Research Tools
- web_search, web_fetch, browser for deep research
- Knowledge base for document ingestion
- Memory search for accumulated knowledge

Template variables are substituted at scaffold time: {{agentId}}, {{agentName}}, {{role}}, {{description}}, {{workspace}}, {{team}}, {{date}}.

Idempotent Scaffolding

The scaffolding engine is idempotent — it won't overwrite existing files. This means:

• Running reeve agents add for an existing agent updates config but doesn't clobber workspace files
• You can safely re-scaffold after editing your AGENTS.md
• The wx file flag ensures no accidental overwrites

From the Frontend

The Cockpit's Agent Management UI (/cockpit/settings/agents) provides a visual interface:

1. Click "New Agent"
2. Fill in name, role, workspace path
3. Configure model and heartbeat overrides
4. Click Create

This calls agents.create via the JSON-RPC bridge (see API Reference).