aura-plugins

aura-plugins

Multi-agent orchestration toolkit for the Aura Protocol. Provides CLI tools for launching Claude agents in isolated worktrees and tmux sessions, role-based slash commands, and a Home Manager module for declarative distribution.

Overview

aura-plugins solves two problems in multi-agent Claude workflows:

1. Isolation. Parallel agents editing the same repo need separate working trees and branches to avoid conflicts. aura-swarm creates per-epic git worktrees with automatic Beads context gathering.

2. Coordination. Agents need structured roles (architect, supervisor, worker, reviewer) with different toolsets and instructions. Both CLI tools inject role-specific system prompts from skills/*/SKILL.md files.

All inter-agent coordination flows through Beads task status and comments — there is no separate messaging system.

Quick Start — Plugin Install

Claude Code

# 1. Add the aura-plugins marketplace
claude plugin marketplace add dayvidpham/aura-plugins

# 2. Install the aura plugin (user-wide)
claude plugin install aura@aura-plugins

# Or install for a specific project only
claude plugin install aura@aura-plugins --scope project

# Validate (optional)
claude plugin validate /path/to/aura-plugins

After installing, restart Claude Code. Skills are auto-discovered and invocable as /aura:<skill-name> (e.g. /aura:epoch, /aura:user-request).

# Update to latest
claude plugin update aura@aura-plugins

# Local development (from a checkout, no install needed)
claude plugin marketplace add /path/to/aura-plugins
claude plugin install aura@aura-plugins

OpenCode

OpenCode natively reads skills/*/SKILL.md. Clone into your project's .claude/ or configure via OpenCode's plugin system.

---

Installation (CLI Tools)

Nix Flake (recommended)

Add as a flake input:

# flake.nix
{
  inputs.aura-plugins.url = "github:dayvidpham/aura-plugins";
}

Then reference the packages:

# In your system or home-manager config:
aura-plugins.packages.${system}.aura-swarm     # unified agent orchestration
aura-plugins.packages.${system}.aura-parallel  # deprecated wrapper
aura-plugins.packages.${system}.default        # all tools

Home Manager Module

The flake exports a Home Manager module that syncs commands, agents, and protocol docs into ~/.claude/:

# home.nix
{
  imports = [ aura-plugins.homeManagerModules.aura-config-sync ];

  CUSTOM.programs.aura-config-sync = {
    packages.enable = true;              # install CLI tools

    commands.enable = true;              # install slash commands
    commands.roles = {                   # toggle per-role
      architect = true;
      supervisor = true;
      worker = true;
      reviewer = true;
      epoch = true;
    };
    # commands.enableAll = true;         # shorthand for all roles

    agents.enable = true;               # install custom agents

    protocol.enable = false;             # install skills/protocol/ docs (off by default)
  };
}

Core commands (aura:plan, aura:status, aura:test, aura:feedback, aura:msg:*, aura:impl:*, aura:user:*) are always installed when commands.enable = true, regardless of role selection.

Manual

Both scripts are standalone Python 3.10+ with no external dependencies:

git clone https://github.com/dayvidpham/aura-plugins
cd aura-plugins
chmod +x bin/aura-swarm bin/aura-release
# Add bin/ to PATH or symlink into a PATH directory

Prerequisites

Both tools check for these on startup and exit with an error if any are missing:

Tool	Purpose
git	Worktree and branch management
tmux	Agent session hosting
bd	Beads issue tracking
claude	Claude CLI (agent runtime)

Python 3.10+ (stdlib only, no pip dependencies).

---

aura-swarm

Creates an isolated git worktree for a Beads epic, gathers task context from the dependency graph, and launches a single Claude instance in a tmux session. The agent uses Claude's Agent Teams internally to spawn workers on sub-branches.

Branch model

main
 └── epic/<epic-id>                   aura-swarm creates this branch + worktree
       ├── agent/<task-id-1>          Claude Agent Teams creates sub-branches
       ├── agent/<task-id-2>
       └── agent/<task-id-3>

Usage

aura-swarm <subcommand> [options]

Subcommands

start — Launch an epic session

Creates (or reuses) a worktree, discovers tasks and URD from the Beads dependency graph, builds a context-rich prompt, and launches Claude in a detached tmux session.

aura-swarm start --epic <epic-id> [options] [task-id ...]