Antfarm

Steps communicate by passing KEY: value pairs in their output. These pairs are automatically converted into lowercased variables available to subsequent steps.

Available Variables

• {{task}}: The original task string passed to workflow run (always available).
• {{prev_output}}: Variables from prior steps.
• {{key_name}}: Any KEY: value pair returned by a previous step (e.g., if an agent returns REPO: /path, use {{repo}}).

Example Communication

If an agent replies with:

STATUS: done
REPO: /path/to/repo
BRANCH: feature/my-thing

Later steps can reference {{repo}} and {{branch}}.

Roles determine the level of access an agent has to the environment during execution. Use these roles to enforce security and integrity (e.g., preventing a verifier from modifying code).

Note: Each role has a default timeout (20 or 30 min). Use timeoutSeconds in the agent definition to override this.

Antfarm uses a decentralized, autonomous agent model rather than a central orchestrator.

Core Mechanics:

• Autonomous Agents: Specialized agents (planner, developer, verifier, tester, reviewer) execute steps by polling a shared SQLite database via staggered cron jobs (typically every 15 minutes).
• Step Lifecycle: An agent claims a pending step, performs the work, marks it complete, and advances the workflow to the next step.
• Context Passing: Information is passed between steps using KEY: value pairs in the agent's output.

Force-Triggering Agents: If you do not want to wait for the 15-minute cron cycle, you can manually trigger an agent using the cron tool with action: "run" and the agent's job ID. Agent job IDs follow the pattern antfarm/<workflow-id>/<agent-id>.

To create a custom workflow, organize your files into a specific directory structure under workflows/. Each workflow requires a workflow.yml file and a directory of agents/, where each agent has its own configuration files (AGENTS.md, SOUL.md, and IDENTITY.md).

Directory Structure

workflows/
└── my-workflow/
    ├── workflow.yml          # Workflow definition (required)
    └── agents/
        ├── agent-a/
        │   ├── AGENTS.md     # Agent instructions
        │   ├── SOUL.md       # Agent persona
        │   └── IDENTITY.md   # Agent identity
        └── agent-b/
            ├── AGENTS.md
            ├── SOUL.md
            └── IDENTITY.md

To start a multi-agent workflow, use the workflow run command. You must provide the <workflow-id> and a <detailed task with acceptance criteria>.

Important: The task string is the contract between you and the agents. To ensure high-quality results, your task string should always include:

1. Specific details on what to build or fix.
2. Key technical details and constraints.
3. Explicit acceptance criteria (e.g., using checkboxes).

It is recommended to have the user confirm the plan and acceptance criteria before initiating the run.

# Start a run
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow run <workflow-id> "<detailed task with acceptance criteria>"

You can create a loop where a verification step checks work and, if it fails, triggers a retry of a previous implementation step.

When a verification step fails with STATUS: retry, the implementation step is re-run. The variable {{verify_feedback}} is automatically populated with the content from the verifier's ISSUES: output.

Example Verification Loop

- id: verify
  agent: verifier
  input: |
    Check the work...
    Reply STATUS: done or STATUS: retry with ISSUES.
  expects: "STATUS: done"
  on_fail:
    retry_step: implement
    max_retries: 3
    on_exhausted:
      escalate_to: human

You can build custom agent teams by defining agents, steps, retry logic, and verification gates in YAML and Markdown. Each agent is assigned a persona, a workspace, and strict acceptance criteria.

Example workflow definition:

id: my-workflow
name: My Custom Workflow
agents:
  - id: researcher
    name: Researcher
    workspace:
      files:
        AGENTS.md: agents/researcher/AGENTS.md

steps:
  - id: research
    agent: researcher
    input: |
      Research {{task}} and report findings.
      Reply with STATUS: done and FINDINGS: ...
    expects: "STATUS: done"

For a full guide, see docs/creating-workflows.md.

Once your workflow directory is created in the workflows/ folder, use the Antfarm CLI to provision it. This command provisions agent workspaces, registers agents in OpenClaw config, and sets up cron polling.

antfarm workflow install my-workflow

Antfarm is installed from GitHub, not the npm registry. To install, run the following command in your terminal:

curl -fsSL https://raw.githubusercontent.com/snarktank/antfarm/v0.5.1/scripts/install.sh | bash

If you are using an OpenClaw agent, you can simply instruct it: "install github.com/snarktank/antfarm".

Requirements:

• Node.js >= 22: If you encounter a node:sqlite error, ensure you are using a real Node.js 22+ installation rather than Bun's node wrapper.
• OpenClaw v2026.2.9+: Antfarm uses cron jobs for orchestration. If using an older version, it will fall back to the openclaw CLI.
• gh CLI: Required for steps involving Pull Request (PR) creation.