Skip to main content

Overview

The orcbot push command adds a task to the OrcBot action queue. Tasks are executed by the agent in priority order, with support for retry logic, TTL (time-to-live), and task chaining.

Usage

Arguments

string
required
Task description or instruction for the agent. This is the main work item that will be executed. Can be a simple command or complex multi-step instruction.

Options

number
default:"5"
Task priority from 1-10. Higher numbers execute first. Default is 5 (medium priority).
  • 10: Critical/urgent tasks
  • 7-9: High priority
  • 4-6: Normal priority (default: 5)
  • 1-3: Low priority/background tasks

Behavior

Queue Processing

  1. Task added to ActionQueue with specified priority
  2. Agent processes queue in priority order (highest first)
  3. Task metadata logged to ~/.orcbot/actions.json
  4. Execution tracked with timestamps and status
  5. Retry logic applied if task fails

Priority Ordering

Tasks are executed in this order:
  1. Highest priority value first (10 before 5)
  2. Within same priority: FIFO (first added, first executed)
  3. Failed tasks retry based on TTL and retry count

Task Lifecycle

Examples

Simple Task

Output:

High Priority Task

Output:

Background Research Task

This task will execute after higher priority tasks, suitable for background work.

Multi-Step Orchestration

The agent will:
  1. Search for Bitcoin price
  2. Extract the current value
  3. Send message to Frederick via Telegram

File Operations

Command Execution

Integration with External APIs

Advanced Usage

Verify Task Was Queued

Output shows pending tasks:

Monitor Task Execution

Queue Multiple Tasks

Task Queue Architecture

Storage

File: ~/.orcbot/actions.json Format:

Retry Logic

  • Default retries: 3
  • TTL: 1 hour (3600000ms)
  • Backoff: Exponential (1s, 2s, 4s, …)
  • Failed tasks: Removed after max retries or TTL expiry

Task Chaining

Tasks can create follow-up tasks:
The agent may:
  1. Execute initial research
  2. Create summary task
  3. Schedule future task using schedule_task skill

Integration with Agent Skills

Tasks can invoke any available skill:

Web & Browser Skills

File & System Skills

Communication Skills

Memory & Learning Skills

Programmatic Access

For advanced use cases, push tasks via the Gateway API:

Limitations

Agent Must Be Running: Tasks are only executed when the agent is running (orcbot run or orcbot run --daemon). Pushing tasks while agent is stopped queues them for execution when agent starts.
Priority Range: Priority values outside 1-10 are clamped. Priority 0 becomes 1, priority 15 becomes 10.
Task Length: Very long task descriptions (>1000 characters) may be truncated in logs but are fully preserved in execution context.

Troubleshooting

Task Not Executing

Task Failed

Clear Queue

To manually clear the queue (use with caution):
  • orcbot run - Start agent to process tasks
  • orcbot status - View queue and agent status
  • orcbot ui - Interactive queue management
  • orcbot gateway - API access for task pushing

See Also