autobeat

name	autobeat
description	Use when delegating work to background agents, creating workflows, choosing between autobeat primitives (tasks, pipelines, loops, orchestrations, schedules), monitoring progress, or troubleshooting failures.
user-invocable	false
allowed-tools	Read, Grep, Glob

Autobeat Agent Orchestration

Autobeat lets you delegate work to background AI agent instances, build task pipelines, create iterative loops, schedule recurring work, and run autonomous orchestrations. Two runtimes supported: Claude, Codex.

Iron Law

USE THE SIMPLEST PRIMITIVE THAT FITS

Single task beats pipeline. Pipeline beats loop. Loop beats orchestrator. Each level adds overhead and complexity — only escalate when the simpler primitive genuinely cannot express your intent. If you catch yourself building a pipeline with one step, use a task. If you're manually wiring 5 sequential tasks with dependsOn, use a pipeline.

When This Skill Activates

• Delegating work to background agents
• Choosing between tasks, pipelines, loops, schedules, or orchestrations
• Building multi-step workflows or dependency graphs
• Setting up iterative improvement (retry/optimize loops)
• Monitoring task progress or troubleshooting failures
• Scheduling recurring work

Capability Hierarchy

Use this decision tree to pick the right primitive:

Is it a single, self-contained piece of work?
  YES → DelegateTask (single task)

Is it a fixed sequence of steps?
  YES → How many steps?
    2-20 → CreatePipeline
    >20  → Break into multiple pipelines or use orchestrator

Does it need iterative improvement?
  YES → Is the exit condition objective (shell exit code / script score)?
    YES → CreateLoop with evalMode: shell
    NO  → CreateLoop with evalMode: agent
           Which eval sub-strategy?
             Need findings-only feedback, always run to maxIterations? → evalType: feedforward (default)
             Need AI judge to decide continue/stop?                   → evalType: judge
             Need deterministic structured pass/fail (Claude only)?    → evalType: schema

Is the goal open-ended and complex?
  YES → CreateOrchestrator (autonomous planning + delegation)

Should it run on a schedule?
  YES → Wrap any of the above: ScheduleTask, SchedulePipeline, ScheduleLoop

Primitive Comparison

Primitive	Use When	Complexity	Autonomy
Task	Single work item	Lowest	None
Pipeline	Fixed sequence (2-20 steps)	Low	None
Loop	Iterative improvement	Medium	Exit condition only
Orchestrator	Open-ended goals	Highest	Full (plans + delegates)
Schedule	Any of the above, recurring/deferred	+1 layer	Timer-driven

Quick Reference

MCP Tools

Tool	Purpose
DelegateTask	Run a single task in a background agent
TaskStatus	Check task status (omit taskId for all)
TaskLogs	Read stdout/stderr from a task
CancelTask	Cancel a running task
RetryTask	Re-run a failed/completed task
ResumeTask	Resume from checkpoint with context
CreatePipeline	Sequential task chain (2-20 steps)
CreateLoop	Iterative retry/optimize loop
LoopStatus	Check loop progress and history
ListLoops	List loops with status filter
CancelLoop	Cancel an active loop
PauseLoop	Pause a loop mid-iteration
ResumeLoop	Resume a paused loop
ScheduleTask	Schedule a task (cron or one-time)
SchedulePipeline	Schedule a recurring or one-time pipeline
ScheduleLoop	Schedule a recurring loop
ListSchedules	List schedules with status filter
ScheduleStatus	Get schedule details + history
PauseSchedule	Pause a schedule
ResumeSchedule	Resume a paused schedule
CancelSchedule	Cancel a schedule
CreateOrchestrator	Autonomous goal execution
OrchestratorStatus	Check orchestration progress
ListOrchestrators	List orchestrations
CancelOrchestrator	Cancel an orchestration
ListAgents	List available agents with auth status
ConfigureAgent	Check auth, store/reset API keys
InitCustomOrchestrator	Scaffold custom orchestrator (state file, exit script, snippets)
PipelineStatus	Check pipeline entity status
ListPipelines	List pipelines with status filter
CancelPipeline	Cancel a pipeline and optionally its tasks

CLI Commands

Command	Purpose
beat run "<prompt>"	Delegate a task
beat status [task-id]	Check task status
beat logs <task-id>	Read task output
beat cancel <task-id>	Cancel a task
beat resume <task-id>	Resume from checkpoint
beat pipeline "<step1>" --delay 5m "<step2>"	Create pipeline
beat loop "<prompt>" --until "<cmd>"	Retry loop
beat loop "<prompt>" --eval "<cmd>" --maximize	Optimize loop
beat loop "<prompt>" --eval-mode agent --strategy retry	Agent eval loop
beat schedule create "<prompt>" --cron "0 9 * * *"	Cron schedule
beat orchestrate "<goal>"	Start orchestration
beat orchestrate status <id>	Check orchestration
beat orchestrate init "<goal>"	Scaffold custom orchestrator
beat dashboard / beat dash	Terminal dashboard TUI
beat list / beat ls	List tasks
beat agents check	Check agent auth status
beat agents config set/show/reset	Agent config management
beat config show/set/reset/path	Config management

Composition Patterns

Pipeline-in-Loop: Repeat a multi-step pipeline until quality passes.

CreateLoop { pipelineSteps: ["lint", "test", "build"], strategy: "retry", exitCondition: "npm test" }

Loop-in-Schedule: Run an optimization loop daily.

ScheduleLoop { strategy: "optimize", cronExpression: "0 2 * * *", ... }

Task Dependencies (manual DAG): Fan-out, then fan-in.

A = DelegateTask("generate data")
B = DelegateTask("process subset 1", dependsOn: [A])
C = DelegateTask("process subset 2", dependsOn: [A])
D = DelegateTask("merge results", dependsOn: [B, C], continueFrom: B)

System Prompts

Inject custom instructions into any agent. Identical mechanics across all tools that accept systemPrompt.

Agent	Mechanism	Behavior
Claude	--append-system-prompt	Appends to Claude's built-in system prompt
Codex	-c developer_instructions	Sets developer instructions config

Supported on: DelegateTask, CreatePipeline (pipeline + per-step), CreateLoop, ScheduleTask, SchedulePipeline (pipeline + per-step), ScheduleLoop, CreateOrchestrator.

Caveat: CreateOrchestrator systemPrompt replaces auto-generated role instructions entirely (not appends). This prevents conflicting ROLE sections. Use InitCustomOrchestrator for custom orchestrators with full prompt control.

Model Selection

Override the default model per task, per pipeline step, or per loop iteration.

Resolution order: per-task model > agent-config default (ConfigureAgent) > agent's built-in default.

Pipelines support per-step overrides: set model at pipeline level for the default, override on individual steps[] as needed.

Model names are opaque to autobeat — validation is the agent CLI's responsibility.

Translation Proxy & Ollama Runtime

Configure via ConfigureAgent (set action):

• proxy: "openai": Routes Anthropic API calls through a local proxy that translates to OpenAI-compatible format. Requires baseUrl and apiKey. Works with all agents.
• runtime: "ollama": Wraps agent spawns with ollama launch. Supported agents: claude, codex.

Mutually exclusive — runtime takes precedence if both are set. Clear with empty string: proxy: "" or runtime: "".

Anti-Patterns

Mistake	Why It's Wrong	Fix
Pipeline with 1 step	Unnecessary overhead	Use DelegateTask
Manual dependsOn chain for sequential tasks	Error-prone wiring	Use CreatePipeline
Loop without exit condition (shell mode)	Runs forever	Set exitCondition, or use evalMode: agent with an evalType
Orchestrator for simple sequences	Overkill	Use Pipeline or Loop
Polling TaskStatus in a tight loop	Wastes resources	Check periodically (30s+)
Ignoring workingDirectory	Tasks run in wrong directory	Always set workingDirectory
Unlimited maxIterations with no failures cap	Risk of infinite loop	Set maxIterations or maxConsecutiveFailures
Using CreateOrchestrator for custom eval	Auto-generated prompts don't support custom eval logic	Use InitCustomOrchestrator + CreateLoop

Extended References

Load these for deep dives on specific capabilities:

• orchestration.md — Choosing primitives, composition patterns, orchestrator guardrails. Load when planning complex workflows.
• loops.md — Retry/optimize strategies, agent eval mode, git integration, recipes. Load when creating loops.
• dependencies.md — DAGs, pipelines, context passing, failure cascade. Load when wiring task dependencies.
• monitoring.md — Status checking, recovery, troubleshooting. Load when monitoring or debugging.
• capability-matrix.md — Complete parameter tables for all MCP tools and CLI commands. Load for exact parameter names and defaults.