Overview
Theorcbot 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
- Task added to ActionQueue with specified priority
- Agent processes queue in priority order (highest first)
- Task metadata logged to
~/.orcbot/actions.json - Execution tracked with timestamps and status
- Retry logic applied if task fails
Priority Ordering
Tasks are executed in this order:- Highest priority value first (10 before 5)
- Within same priority: FIFO (first added, first executed)
- Failed tasks retry based on TTL and retry count
Task Lifecycle
Examples
Simple Task
High Priority Task
Background Research Task
Multi-Step Orchestration
- Search for Bitcoin price
- Extract the current value
- Send message to Frederick via Telegram
File Operations
Command Execution
Integration with External APIs
Advanced Usage
Verify Task Was Queued
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:- Execute initial research
- Create summary task
- Schedule future task using
schedule_taskskill
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
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):Related Commands
orcbot run- Start agent to process tasksorcbot status- View queue and agent statusorcbot ui- Interactive queue managementorcbot gateway- API access for task pushing
See Also
- Action Queue Architecture - Internal queue implementation
- Agent Skills Documentation - Available task capabilities
- Memory System - How tasks interact with memory