Aviary

Aviary is a workflow system that automatically manages and queues work for a set of parallel running AI Agents. Queue up tasks by writing tickets in a shared repository and Aviary will coordinate a configurable number of agents to pick up work on a number of different configurable schedules.

Aviary integrates with multiple issue / ticketing systems, as well as plain filesystem directories or Git repositories for issue management. Tasks can be written as "tickets", "issues", or as markdown files in a shared repository and will be assigned, tracked, and completed by the tasked agents. For code based workflows, agent workers can perform work in the form of pull requests, allowing for parallel implementations of the same ticket upon request.

Using Aviary

1. Login to your Claude Code, OpenAI Codex, or Gemini CLI using the CLI tools to ensure they are able to run commands.
2. Run npx @lsegal/aviary <project|path> to start the scheduler
3. Create a task in one of the "Supported Task Tracking Systems"
4. Aviary will automatically detect the new tasks and assign them to available agents
5. Increase or decrease the number of agents by editing your configuration file which is created Aviary will watch for changes to this file and automatically restart the agents with the new configuration.

Aviary uses the following Agent CLI tools to manage agents:

• Claude Code
• OpenAI Codex
• Gemini CLI

Examples

The examples/ directory contains sample configurations and tasks to help you get started with Aviary.

Basic Example

The examples/basic/ directory demonstrates a simple filesystem-based task tracking setup:

Trying the Basic Example

1. Navigate to the basic example directory:

   cd examples/basic
   npx @lsegal/aviary

2. Watch as agents pick up tasks from available/, move them to progress/ while working, and finally to completed/ when finished.

Supported Task Tracking Systems

Local Filesystem

• Configure Aviary to use local filesystem for tracking by pointing at a directory.
• Add tasks as markdown files in the following directories:
  • available/ for available tasks
  • progress/ for in-progress tasks
  • completed/ for completed tasks

Agent Notes

• Tasks created in available/*.md will be considered available tasks only if:
  • The file has a .ready.md suffix (e.g., task.ready.md), OR
  • The file contains a <!-- status: ready --> comment marker
• Tasks created in /progress/*.md will be considered in-progress tasks.
• Tasks created in completed/*.md will be considered completed tasks.
• If multiple agents are assigned to the same task, the task will be duplicated with .N.md suffixes, where N is the an incrementing number starting from 1.
• Tasks in completed/ will be considered completed and will not be assigned again.
• Task File Processing: Only files that are "ready" will be processed by the system. This allows you to edit task files while they remain in the directory without them being picked up by agents until they are explicitly marked as ready.

Local Git Repository

• Configure Aviary to use a Git repository for tracking by pointing at a local directory.
• Aviary will detect if the directory is a Git repository and will use it for tracking tasks.
• The same rules as for the local filesystem apply, but all tasks added to available/ must be committed to the repository before they can be assigned.

Agent Notes

• Agents will automatically commit changes when files are moved or modified so that all consumers of the repository will see the changes.
• Agents will always run git pull before reading or writing tasks to ensure they have the latest version of the tasks.
• If commit or sync conflicts occur, the agent will attempt to resolve them automatically by rebasing or merging.

GitHub Issues

• Configure Aviary to use GitHub Issues by providing a repository URL.
• Aviary will use the gh CLI or GitHub MCP to authenticate and manage issues.
• Tasks can be created as issues in the repository using regular issue creation methods.
• Task availability is determined by the issue state:
  • Open issues are considered available tasks.
  • Issues that are assigned to a user or are attached to a Project with a Status of "In Progress" or "Pending" are considered in-progress tasks.
  • Issues that are closed or have a Status of "Completed" are considered completed tasks.

Agent Notes

• Available tasks are those that are open and not assigned to any user.
• In-progress tasks are those that are assigned to a user or are attached to a Project with a Status of "In Progress" or "Pending".
• Completed tasks are those that are closed or have a Status of "Completed".
• For tasks that involve code changes to a repository, agents will create pull requests to implement the changes.
• Agents will automatically update the issue state when a task is completed or moved to a different state
• Agents should close the issue once the task is completed.
• Completion of a code pull request can involve a code review or approval. This process depends on the repository. If the Agent determines that the pull request is approved, it should merge the pull request and close the issue.
• Because code changes require pauses in the "in progress" state for human feedback, agents should poll in progress tasks before picking up new tasks to check for:
  • New comments on the issue
  • New pull requests on the issue
  • New commits on the pull request
  • New reviews on the pull request If any of these are detected, the agent should pick up this task. When doing so, the agent should add a comment to the issue indicating that it is working on the task and will notify when it is complete. Other agents should read comments before picking up in progress tasks to avoid duplicate work. Note that the comment may be stale: if a comment is more than 1 hour old, the agent should ignore the comment and pick up the task anyway (following the same process of adding a comment to the issue indicating that it is working on the task).

Configuring Aviary

Aviary configuration depends on on the current working directory or <path> argument (working directory), existing configuration files, and any command line arguments you provide. If no configuration is found, Aviary will interactively prompt you for input.

The configuration lookup works as follows:

1. If the working directory contains a .aviary.yml or .aviary.json file, Aviary will use that file for configuration.
2. If the working directory contains a .git directory and the origin remote is set and points to github.com, Aviary will use GitHub Issues for configuration.
3. If the working directory contains a .git directory, Aviary will use the local Git repository for configuration.
4. If the working directory contains a available/ directory, Aviary will use the local filesystem for configuration.
5. If none of these conditions are met, Aviary will prompt you for configuration options.

Configuration Options

Aviary uses YAML configuration files.

Projects (toplevel projects)

[!NOTE] If a toplevel projects key is present, Aviary will perform a lookup of the "working directory" <project|path> argument to find a project key in the configuration file. If the key is found, Aviary will use the fields of that object as configuration.

Projects is a dictionary of project names with configuration. Example:

projects:
  aviary:
    source: ./tasks
  another-project:
    source: https://github.com/lsegal/another-project

If no projects key is present, Aviary will assume this file contains a single project configuration and will not prompt for a project name (if one is not provided).

Task Tracking System (type)

[!NOTE] The type field is optional. If not provided, Aviary will infer the type from the source field.

• fs: Use the local filesystem for task tracking.
• git: Use a local Git repository for task tracking.
• github: Use GitHub Issues for task tracking.

Task Directory (source)

• For fs type, this is the directory where tasks are stored, e.g. ./tasks.
• For git type, this is the local Git repository directory.
• For github type, this is the GitHub repository URL, e.g. https://github.com/lsegal/aviary.

Worker Configuration (workers)

An array of worker configurations. Each worker configuration can contain the following fields:

• type: The worker type, currently supporting: "claude", "codex", "gemini".
• count: The number of workers to run for this type.
• schedule: Optional scheduling configuration for workers. Can be either:
  • A cron-formatted string for cron-based scheduling (e.g., "0 */5 * * *" for every 5 minutes)
  • An object with an interval field specifying the polling interval in seconds

Schedule Configuration (schedule)

The schedule field supports two formats:

Short-hand (cron string):

workers:
  - type: claude
    count: 2
    schedule: "0 */5 * * *"  # Every 5 minutes

Long-form (interval object):

workers:
  - type: claude
    count: 2
    schedule:
      interval: 300  # Poll every 300 seconds (5 minutes)

If no schedule is specified, workers will default to polling every 5 seconds.

Examples

Mixed worker types with different schedules:

workers:
  - type: claude
    count: 3
    schedule:
      interval: 30  # Poll every 30 seconds
  - type: codex
    count: 1
    schedule: "0 */10 * * *"  # Every 10 minutes via cron
  - type: gemini
    count: 2 # No schedule specified - uses default of 5 seconds

Workers with only interval-based scheduling:

workers:
  - type: claude
    count: 2
    schedule:
      interval: 60  # Poll every minute
  - type: codex
    count: 1
    schedule:
      interval: 300  # Poll every 5 minutes

Copyright

This project is licensed under the MIT License. See the LICENSE file for details.