> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt
> Use this file to discover all available pages before exploring further.

# orcbot push

> Queue tasks for the OrcBot agent with priority levels

## 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

```bash theme={null}
orcbot push "<task description>" [options]
```

## Arguments

<ParamField path="task" type="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.
</ParamField>

## Options

<ParamField path="-p, --priority" type="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
</ParamField>

## 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

```mermaid theme={null}
graph LR
    A[Push Task] --> B[Queue]
    B --> C{Agent Ready?}
    C -->|Yes| D[Execute]
    C -->|No| B
    D --> E{Success?}
    E -->|Yes| F[Complete]
    E -->|No| G{Retries Left?}
    G -->|Yes| B
    G -->|No| H[Failed]
```

## Examples

### Simple Task

```bash theme={null}
orcbot push "Check Bitcoin price and save to journal"
```

Output:

```
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

```bash theme={null}
orcbot push "URGENT: Server is down, check status and alert admin" -p 10
```

Output:

```
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

```bash theme={null}
orcbot push "Research latest AI papers on reasoning and update LEARNING.md" -p 3
```

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

### Multi-Step Orchestration

```bash theme={null}
orcbot push "Find current BTC price, then message Frederick on Telegram with the result" -p 8
```

The agent will:

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

### File Operations

```bash theme={null}
orcbot push "Read ~/reports/monthly.md, summarize it, and send summary to #general on Discord" -p 6
```

### Command Execution

```bash theme={null}
orcbot push "Run npm test in the project directory and report results" -p 7
```

### Integration with External APIs

```bash theme={null}
orcbot push "Fetch weather for London from API and update user profile" -p 5
```

## Advanced Usage

### Verify Task Was Queued

```bash theme={null}
# Push task
orcbot push "Test task" -p 5

# Check queue status
orcbot status
```

Output shows pending tasks:

```
=== OrcBot Status ===
🟢 OrcBot is RUNNING
   PID: 12345

--- Memory & Queue ---
Action Queue: 1 pending
- Test task (priority: 5)
```

### Monitor Task Execution

```bash theme={null}
# Push task
orcbot push "Complex task" -p 8

# Watch logs in real-time
tail -f ~/.orcbot/daemon.log
```

### Queue Multiple Tasks

```bash theme={null}
# 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:**

```json theme={null}
{
  "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:

```bash theme={null}
orcbot push "Research topic X, then create a summary and schedule follow-up research in 1 week" -p 7
```

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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

<Warning>
  **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.
</Warning>

<Note>
  **Priority Range**: Priority values outside 1-10 are clamped. Priority 0 becomes 1, priority 15 becomes 10.
</Note>

<Note>
  **Task Length**: Very long task descriptions (>1000 characters) may be truncated in logs but are fully preserved in execution context.
</Note>

## Troubleshooting

### Task Not Executing

```bash theme={null}
# 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

```bash theme={null}
# 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):

```bash theme={null}
# 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
```

## Related Commands

* [`orcbot run`](/api/cli/run) - Start agent to process tasks
* `orcbot status` - View queue and agent status
* [`orcbot ui`](/api/cli/ui) - Interactive queue management
* [`orcbot gateway`](/api/cli/gateway) - API access for task pushing

## See Also

* [Action Queue Architecture](https://github.com/fredabila/orcbot) - Internal queue implementation
* [Agent Skills Documentation](https://fredabila.github.io/orcbot/docs/) - Available task capabilities
* [Memory System](https://fredabila.github.io/orcbot/docs/) - How tasks interact with memory