Agent Commands
The agent command group handles bot orchestration. Agents are autonomous workers that claim tasks from the board, report progress, and coordinate with each other. The coordinator loop manages task distribution and rebalancing across active agents.
Overview
Agents follow a lifecycle:
- Register presence via
agent heartbeat - Claim available tasks via
agent claim - Report progress via
agent report - Complete or release tasks via
agent complete/agent release
The coordinator (agent coordinate) automates this loop, distributing tasks based on agent skills and availability.
Commands
agent heartbeat
Send a heartbeat signal to indicate an agent is alive and active.
# Send heartbeat with current status
optimal agent heartbeat --agent content-bot --status active
# Signal that an agent is idle
optimal agent heartbeat --agent finance-bot --status idle| Flag | Description |
|---|---|
--agent | Agent name (required) |
--status | Agent status (e.g. active, idle, busy) |
TIP
Agents should send heartbeats at regular intervals. If no heartbeat is received within the timeout window, the coordinator considers the agent offline and may reassign its tasks.
agent list
List all agents and their current status.
optimal agent listOutputs each registered agent with its name, status, last heartbeat time, and currently assigned tasks.
agent claim
Claim the next available task matching the agent's skill.
# Claim any available task
optimal agent claim --agent content-bot
# Claim a task matching a specific skill
optimal agent claim --agent finance-bot --skill financial-analysis| Flag | Description |
|---|---|
--agent | Agent name (required) |
--skill | Skill tag to match against task requirements |
agent report
Report progress on a claimed task.
optimal agent report --task 42 --agent content-bot --message "Generated 3 of 5 social posts"| Flag | Description |
|---|---|
--task | Task ID (required) |
--agent | Agent name (required) |
--message | Progress message (required) |
agent complete
Mark a task as completed.
optimal agent complete --task 42 --agent content-bot --summary "Published 5 social posts for CRE-11TRUST"| Flag | Description |
|---|---|
--task | Task ID (required) |
--agent | Agent name (required) |
--summary | Completion summary |
agent release
Release a claimed task back to the pool. Use this when an agent cannot finish a task.
optimal agent release --task 42 --agent content-bot --reason "Missing API credentials"| Flag | Description |
|---|---|
--task | Task ID (required) |
--agent | Agent name (required) |
--reason | Reason for releasing the task |
agent blocked
Mark a task as blocked. The task stays assigned but is flagged for attention.
optimal agent blocked --task 42 --agent finance-bot --reason "Waiting on income statement upload"| Flag | Description |
|---|---|
--task | Task ID (required) |
--agent | Agent name (required) |
--reason | Description of the blocker |
WARNING
Blocked tasks are not automatically reassigned. Use agent rebalance or manually unblock via board update to resume work.
agent coordinate
Run the coordinator loop. This is a long-running process that monitors the task board and distributes work to available agents.
optimal agent coordinate
optimal agent coordinate --interval 60000 --max-agents 5| Flag | Description |
|---|---|
--interval | Poll interval in milliseconds (default: 30000) |
--max-agents | Maximum agents to manage (default: 10) |
The coordinator:
- Monitors agent heartbeats
- Assigns unassigned tasks to idle agents based on skill matching
- Detects stalled or offline agents and reassigns their tasks
- Logs all coordination actions to the activity log
agent status
Get the current coordinator status, including active agents, task distribution, and any issues.
optimal agent statusagent assign
Manually assign a specific task to an agent, bypassing the coordinator's automatic matching.
optimal agent assign --task 42 --agent finance-bot| Flag | Description |
|---|---|
--task | Task ID (required) |
--agent | Target agent name (required) |
agent rebalance
Redistribute tasks across all active agents. Useful after an agent goes offline or when workloads become uneven.
optimal agent rebalanceThis command evaluates current assignments and redistributes tasks to achieve a balanced workload across all agents reporting an active heartbeat.