Creating Goals

Goals can be created three ways: the CLI wizard (for humans), the agent tool (for agents), or the Cockpit dashboard (for the web UI).

CLI Wizard

The reeve goal create command launches an interactive wizard:

reeve goal create

The wizard prompts for:

Title — What the goal is about
Description — Full context and success criteria
Agent — Which agent owns this goal
Phases — Add one or more phases (name, type, description)
Budget — Optional token/dollar caps and approval gates
Deadline — Optional target completion date

Non-interactive mode

Pass all fields as flags for scripting:

reeve goal create \
  --title "Launch email campaign" \
  --agent marketing-agent \
  --phase "Research audience:once" \
  --phase "Write sequences:once" \
  --phase "Monitor performance:loop" \
  --budget-cost 50 \
  --approval-gate 25

Agent Tool

Agents create goals using the goals tool with action: "create":

goals({
  action: "create",
  goal: {
    title: "Optimize ad spend for Q1",
    description: "Reduce CPA by 20% while maintaining volume. Current CPA: $12.50.",
    agentId: "ad-optimizer",
    phases: [
      {
        name: "Audit current campaigns",
        description: "Pull performance data, identify waste",
        type: "once"
      },
      {
        name: "Implement optimizations",
        description: "Pause underperformers, reallocate budget, test new creatives",
        type: "once"
      },
      {
        name: "Monitor & iterate",
        description: "Check metrics every 30 minutes, adjust bids and budgets",
        type: "loop"
      }
    ],
    budget: {
      maxCost: 100,        // $100 total token spend
      maxTokens: 5000000,  // 5M tokens
      approvalGate: 50     // Pause at $50 and ask human
    },
    deadline: "2026-03-31T00:00:00Z",
    reportInterval: "2h"   // Report progress every 2 hours
  }
})

Required fields

Field	Type	Description
`title`	string	Goal title (required)
`agentId`	string	Owning agent ID
`phases`	array	At least one phase with `name` and `type`

Optional fields

Field	Type	Description
`description`	string	Full context and success criteria
`budget`	object	`maxTokens`, `maxCost`, `maxSessions`, `approvalGate`
`deadline`	string	ISO 8601 date
`reportInterval`	string	How often to auto-report (e.g., "2h", "30m")
`reportChannel`	string	Channel for auto-reports
`state`	object	Initial state (arbitrary JSON)
`metrics`	array	Initial metrics to track

Goal Object

When created, a goal gets this structure:

{
  "id": "g_abc123",
  "agentId": "marketing-agent",
  "createdBy": "user",
  "title": "Launch email campaign",
  "description": "...",
  "status": "active",
  "phases": [
    {
      "id": "p_1",
      "name": "Research audience",
      "type": "once",
      "status": "running"
    },
    {
      "id": "p_2",
      "name": "Write sequences",
      "type": "once",
      "status": "pending"
    },
    {
      "id": "p_3",
      "name": "Monitor performance",
      "type": "loop",
      "status": "pending"
    }
  ],
  "currentPhase": 0,
  "budget": {
    "maxCost": 50,
    "usedCost": 0,
    "approvalGate": 25
  },
  "state": {},
  "metrics": [],
  "createdAt": "2026-02-27T12:00:00Z",
  "startedAt": "2026-02-27T12:00:00Z"
}

The first phase is automatically set to "running" status. Subsequent phases stay "pending" until the current phase completes.

Cockpit Dashboard

The Goals Dashboard at /cockpit/goals provides a visual interface:

Click "New Goal" to open the creation form
Fill in title, description, agent, and phases
Set budget and deadline
Click Create

The dashboard shows all goals with real-time status, phase progress bars, budget usage, and activity logs.

When a goal is created, the gateway automatically sets up cron jobs for any loop phases and registers webhook endpoints for any event-driven phases.

What Happens After Creation

The goal is stored in SQLite (~/.reeve/goals/goals.db)
The first phase is marked as running
If the goal has loop phases, cron jobs are scheduled via goals/scheduler.js
The goal appears in the agent's context during heartbeats via goals/heartbeat-hook.js
The agent sees its active goals and current phase, guiding its next actions

See Phases for how phase advancement works.

Creating Goals

On this page