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
orcbot push "<task description>" [options]
Arguments
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
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
orcbot push "Check Bitcoin price and save to journal"
Pushing task: "Check Bitcoin price and save to journal" with priority 5
Manual task pushed via CLI: Check Bitcoin price and save to journal
High Priority Task
orcbot push "URGENT: Server is down, check status and alert admin" -p 10
Pushing task: "URGENT: Server is down, check status and alert admin" with priority 10
Manual task pushed via CLI: URGENT: Server is down, check status and alert admin
Background Research Task
orcbot push "Research latest AI papers on reasoning and update LEARNING.md" -p 3
Multi-Step Orchestration
orcbot push "Find current BTC price, then message Frederick on Telegram with the result" -p 8
- Search for Bitcoin price
- Extract the current value
- Send message to Frederick via Telegram
File Operations
orcbot push "Read ~/reports/monthly.md, summarize it, and send summary to #general on Discord" -p 6
Command Execution
orcbot push "Run npm test in the project directory and report results" -p 7
Integration with External APIs
orcbot push "Fetch weather for London from API and update user profile" -p 5
Advanced Usage
Verify Task Was Queued
# Push task
orcbot push "Test task" -p 5
# Check queue status
orcbot status
=== OrcBot Status ===
🟢 OrcBot is RUNNING
PID: 12345
--- Memory & Queue ---
Action Queue: 1 pending
- Test task (priority: 5)
Monitor Task Execution
# Push task
orcbot push "Complex task" -p 8
# Watch logs in real-time
tail -f ~/.orcbot/daemon.log
Queue Multiple Tasks
# Queue several tasks with different priorities
orcbot push "Background: Update learning notes" -p 2
orcbot push "Normal: Check email" -p 5
orcbot push "Urgent: System health check" -p 9
# Agent will process in order: 9, 5, 2
Task Queue Architecture
Storage
File: ~/.orcbot/actions.json
Format:
{
"actions": [
{
"id": "act_1709548815123_abc123",
"task": "Check Bitcoin price and save to journal",
"priority": 5,
"status": "pending",
"createdAt": "2026-03-04T10:30:15.123Z",
"source": "cli",
"metadata": {
"retries": 0,
"maxRetries": 3,
"ttl": 3600000
}
}
]
}
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:
orcbot push "Research topic X, then create a summary and schedule follow-up research in 1 week" -p 7
- Execute initial research
- Create summary task
- Schedule future task using
schedule_task skill
Integration with Agent Skills
Tasks can invoke any available skill:
Web & Browser Skills
orcbot push "Navigate to example.com and extract article text" -p 6
orcbot push "Search for 'TypeScript best practices' and summarize results" -p 5
File & System Skills
orcbot push "Read /var/log/app.log and check for errors" -p 8
orcbot push "Run 'df -h' and report disk usage if over 80%" -p 9
Communication Skills
orcbot push "Send daily standup reminder to team on Discord" -p 7
orcbot push "Check for new emails and summarize urgent ones" -p 8
Memory & Learning Skills
orcbot push "Research WebAssembly 2025 trends and update LEARNING.md" -p 4
orcbot push "Recall conversations about project X from last week" -p 6
Programmatic Access
For advanced use cases, push tasks via the Gateway API:
curl -X POST http://localhost:3100/api/tasks \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-key" \
-d '{
"task": "Automated task from API",
"priority": 8
}'
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
# Check if agent is running
orcbot status
# View queue
orcbot status
# Look for: "Action Queue: X pending"
# Check logs
tail -f ~/.orcbot/daemon.log | grep "action:"
Task Failed
# View actions.json for error details
cat ~/.orcbot/actions.json | jq '.actions[] | select(.status=="failed")'
# Check retry count
cat ~/.orcbot/actions.json | jq '.actions[] | .metadata.retries'
Clear Queue
To manually clear the queue (use with caution):
# Stop agent first
orcbot stop
# Edit actions.json to remove pending tasks
vim ~/.orcbot/actions.json
# Or reset entirely
orcbot reset --memory
# Restart agent
orcbot run --daemon
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
