Getting Started with AOF

AOF orchestrates teams of agents the way you would orchestrate teams of people — with org charts, enforced workflows, shared memory, and collaborative task management. It works for any domain: software engineering, RevOps, operations, sales and marketing, research, or any process that needs governance across multiple agents.

This guide walks you through installing AOF, defining your first agent team, and watching the platform orchestrate work across your agents. By the end, you will have a running AOF daemon that automatically routes, assigns, and dispatches tasks through your team.

Prerequisites

Before you begin, make sure you have:

Node.js >= 22.0.0 (LTS recommended)
An OpenClaw gateway running on your machine

AOF ships as two pieces:

aof-daemon — a user-level service (launchd on macOS, systemd on Linux) that owns the task store, scheduler, and IPC authority. One daemon per install.
OpenClaw plugin — a thin bridge that runs inside the OpenClaw gateway and connects to the daemon over a Unix-domain socket at ~/.aof/data/daemon.sock. It exposes AOF tools to agent sessions and handles agent spawns back to the daemon on demand.

The daemon and plugin trust boundary is the invoking user’s Unix uid; the socket is created with mode 0600. AOF is single-machine per install.

Tip: Check your Node version with node --version. If you need to upgrade, use nvm or your system’s package manager.

Installation

Install AOF using the one-line installer:

curl -fsSL https://raw.githubusercontent.com/d0labs/aof/main/scripts/install.sh | sh

The installer will:

Download the latest AOF release tarball
Extract it to ~/.aof/ (code) and scaffold ~/.aof/data/ (user data)
Install Node.js dependencies
Run aof setup --auto to complete configuration
Install and start the aof-daemon user service (Migration 007)

You can also specify a custom install path or version:

sh install.sh --prefix /custom/path --version 1.15.0

First-time Setup

After installation, AOF runs aof setup automatically. If you need to re-run it:

aof setup

The setup command does the following:

Wizard (interactive) — Asks about your data directory, org chart location, and OpenClaw integration preferences. Use --auto to accept all defaults.
Directory scaffolding — Creates the AOF data directory structure (tasks, events, views, memory).
Migrations — Runs pending packaging migrations. Migration 007 installs the aof-daemon service if it is not already present.
OpenClaw plugin wiring — Registers AOF in your openclaw.json gateway config. If OpenClaw is not detected, setup continues with a warning.

# Non-interactive setup with defaults
aof setup --auto --template minimal

Create Your Org Chart

The org chart is a YAML file that defines your agents, teams, and routing rules. It is the single source of truth for “who can do what” in your organization.

Create a file called org-chart.yaml in your AOF data directory:

schemaVersion: 1
agents:
  - id: main
    name: Main Agent
    description: General-purpose agent for all tasks
    capabilities:
      tags: [general]
      concurrency: 1
    comms:
      preferred: send
      fallbacks: [spawn, cli]
    active: true

teams:
  - id: default
    name: Default Team
    lead: main

routing: []

Key fields

Field	Type	Description
`schemaVersion`	`1` (literal)	Schema version, always `1`
`agents`	array	List of agent definitions
`agents[].id`	string	Unique agent identifier (must match OpenClaw agent ID)
`agents[].name`	string	Human-readable display name
`agents[].capabilities.tags`	string[]	Capability tags used for routing
`agents[].capabilities.concurrency`	number	Maximum concurrent tasks (default: 1)
`agents[].comms.preferred`	`spawn` \| `send` \| `cli`	Preferred dispatch method (default: `send`)
`agents[].active`	boolean	Whether the dispatcher considers this agent (default: `true`)
`teams`	array	Team definitions for grouping agents
`routing`	array	Tag/priority-based routing rules

For a complete schema reference, see the Configuration Reference.

Initialize AOF

Once your org chart is ready, initialize AOF:

aof init

The init command:

Validates your org chart against the schema
Sets up OpenClaw integration (plugin registration, memory module, skill definition)
Creates required directory structures

Use --yes for non-interactive mode or --skip-openclaw to skip OpenClaw integration:

aof init --yes

The Daemon

The aof-daemon is installed and started by the installer (Migration 007 via aof setup). It runs under launchd on macOS and systemd user services on Linux, so it restarts automatically on crash and survives reboot.

Check daemon status

aof daemon status

This queries the daemon’s health endpoint on the Unix socket and displays:

Whether the daemon is running
Last poll time and duration
Task counts by status
Active leases

# JSON output for scripting
aof daemon status --json

Other daemon commands

aof daemon stop          # Stop the daemon gracefully
aof daemon install       # Install or refresh the OS service file (idempotent)
aof daemon uninstall     # Stop and remove the OS service file

You rarely need to run aof daemon install manually on a fresh install — the installer handles it. Run it if you moved the install directory, reset the service file, or need to re-register after an OS user reset.

Create Your First Task

Tasks in AOF are Markdown files with YAML frontmatter. You can create them via the CLI.

First, check which agents are available in your org chart:

aof org show

Then create a task routed to one of your agents:

aof task create "Implement user authentication" --priority high --agent <your-agent-id>

This creates a task file with the following structure:

---
schemaVersion: 1
id: TASK-2026-02-27-001
project: _inbox
title: Implement user authentication
status: ready
priority: high
routing:
  agent: <your-agent-id>
  tags: []
createdAt: 2026-02-27T12:00:00Z
updatedAt: 2026-02-27T12:00:00Z
lastTransitionAt: 2026-02-27T12:00:00Z
createdBy: cli
dependsOn: []
---

Task ID format

Task IDs follow the pattern TASK-YYYY-MM-DD-NNN (e.g., TASK-2026-02-27-001). They are generated automatically and are globally unique within a project.

Task statuses

Status	Description
`backlog`	Created, not yet triaged
`ready`	Ready to be picked up by the scheduler
`in-progress`	Agent is actively working (has a lease)
`blocked`	Waiting on an external dependency
`review`	Work complete, awaiting review
`done`	Successfully completed
`cancelled`	Cancelled by user or system
`deadletter`	Failed dispatch 3 times, requires manual intervention

CLI options for task creation

aof task create <title> [options]

Options:
  -p, --priority <priority>   Priority: low, normal, high, critical (default: normal)
  -t, --team <team>           Target team for routing
  -a, --agent <agent>         Target agent (bypasses routing)
  --tags <tags>               Comma-separated capability tags
  --project <id>              Project ID (default: _inbox)

Watch It Dispatch

Once the daemon is running and you have a task in ready status, the scheduler will:

Scan for ready tasks on each poll cycle
Match tasks to agents using routing rules and capability tags
Acquire a lease on the matched task (preventing double-dispatch)
Dispatch the task to the agent — via the attached OpenClaw plugin (long-poll callback over daemon.sock) when one is connected, or via the standalone HTTP gateway adapter otherwise
Track the task through in-progress, review, and done states

Monitor progress

# List all tasks with their current status
aof scan

# Display a Kanban board view
aof board

# View recent events (task transitions, dispatches, lease operations)
aof scan --recent

Example: watching a task flow

$ aof scan
STATUS        COUNT
─────────────────────
ready         1
in-progress   0
done          0

$ aof daemon status
Daemon: running (PID 12345)
Last poll: 2s ago (42ms)
Tasks: 1 ready, 0 in-progress, 0 done

# After the scheduler dispatches your task:
$ aof scan
STATUS        COUNT
─────────────────────
ready         0
in-progress   1
done          0

# After the agent completes the task:
$ aof scan
STATUS        COUNT
─────────────────────
ready         0
in-progress   0
done          1

Next Steps

Now that you have AOF running with a dispatched task, explore these topics:

Configuration Reference — Full org-chart schema, AOF config options, and OpenClaw plugin wiring
CLI Reference — Complete command reference (auto-generated from source)
Task Format — Full task frontmatter schema and body conventions
Workflow DAGs — Define multi-stage review workflows
Memory Module — Set up semantic memory with HNSW vector search
Protocols — Inter-agent communication protocols

Troubleshooting

Daemon won’t start

# Check current state
aof daemon status

# Check for stale PID file
ls ~/.aof/data/daemon.pid

# Force stop and restart
aof daemon stop --force
aof daemon install

If the socket file ~/.aof/data/daemon.sock is stale, aof daemon install will unlink and recreate it at mode 0600 on the next start.

Task stuck in ready

Verify the daemon is running: aof daemon status
Check that the target agent exists in your org chart and is active: true
Ensure the agent’s capabilities.tags match the task’s routing.tags
Check for dispatch errors in the event log: aof scan --recent
If you see no-plugin-attached warnings in the daemon log, the OpenClaw plugin is not currently connected. The task is held in ready/ (not deadlettered) and will dispatch once the plugin reconnects.

OpenClaw integration issues

Verify OpenClaw is running: openclaw gateway status
Check plugin registration: look for "aof" in ~/.openclaw/openclaw.json under plugins
Re-run integration: aof init