FlowDot Goals

Goals are persistent, long-running AI objectives that execute locally via the FlowDot CLI or daemon. Unlike one-shot workflows, goals can span days or weeks, accumulating results, scheduling recurring tasks, and notifying you when important things happen.

Architecture

Goals follow a strict local-first architecture. All autonomous execution happens on your machine, not on FlowDot servers.

Why Local Execution?

• Cost control: Server resources are expensive; your machine is free
• File access: Full access to your local filesystem
• Privacy: Sensitive data never leaves your machine
• Long-running: No server timeout limits

Task Handlers

Goals execute through specialized task handlers. Each handler performs a specific type of work:

flowdot goals task:add <hash> "Search for architecture jobs in Texas" -t research

# What it does:
# 1. Queries linked RAG categories for user context
# 2. Performs web search using configured providers
# 3. Stores results in ~/.flowdot/goals/<hash>/results/

flowdot goals task:add <hash> "Draft tailored resume for top positions" -t code

# What it does:
# 1. Queries RAG for user's skills and accomplishments
# 2. Uses LLM to generate content
# 3. Saves draft to ~/.flowdot/goals/<hash>/results/draft_*.md

flowdot goals task:add <hash> "Send Telegram notification with findings" -t notify

# What it does:
# 1. Formats message with task description and results
# 2. Sends via configured COMMS channels
# 3. Truncates to 2000 chars for API limits

flowdot goals task:add <hash> "Run job-matcher recipe" -t recipe

# What it does:
# 1. Parses recipe alias from task title
# 2. Builds inputs from goal context (request, goal_name, previous_results)
# 3. Executes recipe via fire-and-forget pattern
# 4. Stores outputs when complete

flowdot goals task:add <hash> "Run npm test" -t execute

# What it does:
# 1. Checks code-execute permission is allowed
# 2. Parses command from task description
# 3. Applies security patterns (blocks rm -rf, fork bombs, etc.)
# 4. 60 second timeout, runs in user's home directory

flowdot goals task:add <hash> "Check for new listings every 6 hours" -t loop

# What it does:
# 1. Parses interval from task (e.g., "every 6h", "1 hour")
# 2. Creates daemon loop via IPC with auto-start
# 3. Default 3-day expiration, pauses on error

RAG Integration

Goals can link to your knowledge base categories for personalized context during execution.

Link a Knowledge Category

# Link a knowledge base category to your goal
flowdot goals resource:add <hash> --category "Developer Accomplishments"

# The category provides context for:
# - Research tasks (user's background)
# - Code tasks (skills to highlight)
# - Recipe tasks (personalized inputs)

How RAG is Used

• Research: Queries RAG to understand user's skills when evaluating search results
• Code: Retrieves accomplishments and experience for content generation
• Recipe: Passes RAG context as recipe inputs for personalization

Notifications

Goals integrate with FlowDot COMMS to send notifications when important events occur.

Supported Channels

• Telegram: Direct messages to your Telegram account
• Discord: Messages to Discord channels or DMs
• Email: Email notifications (coming soon)

Automatic Notifications

Recipe tasks automatically send notifications when they complete:

# When a recipe task completes:
# 1. Recipe executes in background (fire-and-forget)
# 2. On completion, notification is sent automatically
# 3. Message includes goal name and recipe results
# 4. Truncated to 1800 chars for Hub API limit

Scheduled Execution

Goals can run on a schedule using the FlowDot daemon's GoalScheduler.

How Scheduling Works

• Hub stores schedule: Cron expression or interval in goal metadata
• Daemon polls: GoalScheduler checks for due goals (default: every 60s)
• Concurrent limits: Max 3 goals execute simultaneously by default
• Auto-update: markCompleted() calculates next run time

Enable Scheduled Execution

# Start daemon with goal scheduler enabled
flowdot daemon start --enable-goal-scheduler

# Or configure in ~/.flowdot/config.json:
{
  "daemon": {
    "enableGoalScheduler": true,
    "goalPollInterval": 60000,
    "maxConcurrentGoals": 3
  }
}

Local Storage

All goal execution results are stored locally for review and debugging.

View Results

# View execution results for a goal
flowdot goals results <hash>

# View execution history
flowdot goals runs <hash>

CLI Commands

Complete reference for goal management commands.

Goal Management

# Create a new goal
flowdot goals create "Find me a senior data engineer position in Austin"

# List all goals
flowdot goals list

# Show goal details
flowdot goals show <hash>

# Update a goal
flowdot goals update <hash> --priority high

# Delete a goal
flowdot goals delete <hash>

Task Management

# Add a task
flowdot goals task:add <hash> "Task description" -t research

# Complete a task manually
flowdot goals task:complete <hash> <task-id>

# Skip a task
flowdot goals task:skip <hash> <task-id>

Resource Management

# Link a knowledge category
flowdot goals resource:add <hash> --category "Developer Accomplishments"

# Attach a document
flowdot goals resource:add <hash> --doc <doc-id>

# List resources
flowdot goals resource:list <hash>

Execution

# Run a goal (execute pending tasks)
flowdot goals run <hash>

# Generate tasks using AI
flowdot goals generate <hash>

# View results
flowdot goals results <hash>

Permission System

Goals support fine-grained permission control for security.

Approval Modes

• full: All actions require approval
• category: Actions grouped by category
• trusted: Auto-approve all actions

Available Actions

Example Goals

Click through the tabs below to see different real-world goal examples with their subtasks and recipe invocations.

# Create the goal
flowdot goals create "Find architecture jobs in Texas"

# Link your portfolio for context
flowdot goals resource:add <hash> --category "Architecture Portfolio"

# The system generates and runs subtasks automatically
flowdot goals run <hash>

# Create the goal with measurable target
flowdot goals create "Grow my website by 10 thousand users"

# Link analytics and content strategy docs
flowdot goals resource:add <hash> --category "Marketing Strategy"

# Schedule weekly execution
flowdot goals schedule <hash> --cron "0 9 * * 1"

# Create monitoring goal
flowdot goals create "Monitor competitor pricing and alert me to changes"

# Add competitor list to knowledge base
flowdot goals resource:add <hash> --category "Competitor Intel"

# Set up frequent monitoring
flowdot goals schedule <hash> --cron "0 */6 * * *"

# Create daily briefing goal
flowdot goals create "Research and summarize industry news every morning"

# Link your interests and focus areas
flowdot goals resource:add <hash> --category "Industry Focus"

# Schedule for every morning
flowdot goals schedule <hash> --cron "0 7 * * *"

# Create lead generation goal
flowdot goals create "Find and qualify sales leads in the SaaS industry"

# Link your ICP and sales playbook
flowdot goals resource:add <hash> --category "Sales Playbook"

# Run weekly for fresh leads
flowdot goals schedule <hash> --cron "0 8 * * 1"

# Create portfolio tracking goal
flowdot goals create "Track my investment portfolio and send weekly summaries"

# Link your portfolio data
flowdot goals resource:add <hash> --category "Investment Portfolio"

# Schedule weekly summary
flowdot goals schedule <hash> --cron "0 18 * * 0"

Related Documentation