aura-plugins

aura-plugins now carries the operational pieces that still belong outside the Go Pasture repo:

• bin/aura-swarm: worktree and tmux orchestration — deprecated; do not use it for orchestration or handoff (see AGENTS.md).
• nix/hm-module.nix: Home Manager sync for aura-swarm and Pasture-generated skills/agents.
• skills/protocol/: protocol reference documentation retained for humans and agents.
• .claude-plugin/marketplace.json: marketplace registry entries for external plugins.

Pasture is the source of truth for protocol implementation, generated skills, and generated agents. This repo no longer ships the retired Python protocol engine, Aura plugin package, daemon, message CLI, release CLI, or Python tests.

Install

Nix Package

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

Use the package directly:

aura-plugins.packages.${system}.aura-swarm

The default package is a symlink join containing aura-swarm. The tool itself is deprecated (see aura-swarm); the package remains for the Home Manager module's packages.enable.

Home Manager

The module installs aura-swarm and projects Pasture's generated harness trees into the managed home with pure Nix file ownership. The schema is a closed three-by-three matrix: three harnesses (claude-code, opencode, codex) each with a skills, agents, and hooks cell. Every cell is sourced from that harness's own generated tree in the pinned Pasture flake input — Aura never recreates protocol content, never substitutes one harness's files for another, never runs Pasture's installer or a native plugin manager, and never writes Pasture's installation inventory or any harness's private trust state.

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

  CUSTOM.programs.aura-config-sync = {
    enable = true;
    packages.enable = true;

    # Harnesses are opt-in. Within an enabled harness, skills and agents are on
    # by default and hooks are off by default.
    harnesses."claude-code" = {
      enable = true;               # ~/.claude/skills/…, ~/.claude/agents/…
      hooks.enable = true;         # ~/.claude/hooks/… (payload files only)
    };

    harnesses.opencode.enable = true;
      # ~/.config/opencode/skills/<name>/SKILL.md
      # ~/.config/opencode/agent/<role>.md
      # hooks (opt-in): ~/.config/opencode/plugins/pasture-hooks.ts

    harnesses.codex = {
      enable = true;               # ~/.agents/skills/…, ~/.codex/agents/…
      agents.enable = true;
      skills.target = "some/other/skills";  # per-cell destination override
    };

    protocol.enable = false;       # optional local protocol docs sync
  };
}

Destinations are configurable. Each harness has a targetRoot (defaults: .claude, .config/opencode, and the home directory itself for Codex, whose native layout spans ~/.agents and ~/.codex), and each cell may set its own target, which wins over the harness-derived destination. Destinations may be home-relative or absolute; an absolute path is accepted only when it resolves beneath home.homeDirectory. Paths outside the managed home, .. traversal, colliding destinations, and parent/child ownership overlap are all rejected during evaluation, before any file is realized.

Hook cells project hook payload files only. The module never installs a Git hook, never touches core.hooksPath, and never edits a harness's private trust or enablement state; switching a projected hook payload on remains a deliberate action in the harness's own configuration:

• Claude Code — the projected ~/.claude/hooks/hooks.json is the payload's own manifest, not a file Claude Code reads. To enable it, merge that file's hooks object into the hooks key of your ~/.claude/settings.json (this module does not manage that file) and replace each ${CLAUDE_PLUGIN_ROOT} placeholder with ~/.claude, so the commands read e.g. bash ~/.claude/hooks/scripts/git-discipline.sh and cat ~/.claude/hooks/bd-prime.md.
• OpenCode — plugins are discovered directly from ~/.config/opencode/plugins/, so the projected pasture-hooks.ts is loaded without any configuration edit; no OpenCode config file is written by Aura or by Pasture.
• Codex — the projected ~/.codex/hooks.json and ~/.codex/hooks/events/*.sh are public configuration only. Installing them does not claim execution: review and approve the hooks through Codex's native hooks interface. Neither Aura nor Pasture reads or modifies private trust state. This cell is also layout-locked — its public configuration invokes each script as sh .codex/hooks/events/<Event>.sh, so a target/targetRoot that would move it is rejected rather than installed inert.

Host-load proof is deferred. The flake check proves byte identity, file modes, destinations, cell isolation, and that no harness receives another harness's schema — it does not prove that a live Claude Code, OpenCode, or Codex process loads each projected cell. That per-cell native host-load evidence is still outstanding and tracked in #8; treat the hooks cells in particular as unverified in-host until it lands.

Claude Code has two possible controllers. This module writes payload files into ~/.claude, while pasture install claude-code … drives Claude Code's native plugin manager for the same cells. Choose one per cell: Home Manager rewrites its projected paths on every activation, and Pasture treats declaratively owned destinations as externally controlled — it will not adopt or remove them.

The previous flat options (commands.*, agents.*, opencode.*, codex.*) were removed rather than aliased. Defining any of them fails evaluation with the exact replacement path, for example CUSTOM.programs.aura-config-sync.harnesses."claude-code".skills.enable.

These destinations follow the official Codex skill documentation and custom-agent documentation. The plugin documentation describes plugins as packages containing skills and/or an MCP server, so custom-agent TOMLs remain this module's separate Home Manager projection. The former .codex/skills path is superseded; this module installs no duplicate skill tree.

This Home Manager projection and the imperative pasture install workflow are two independent installation paths: the home-manager installation exists for those who are using NixOS and want declarative opt-in. the imperative pasture install work exists for those who are not doing so, or want something more flexible with less overhead. Home Manager activation regenerates the managed files, so imperative edits made directly to those projected paths do not persist across the next activation.

For local Pasture development, override the generated source:

CUSTOM.programs.aura-config-sync.pasture.source = ../pasture;

Manual (deprecated script)

aura-swarm is a Python 3.10+ script with only standard-library runtime dependencies. It requires the deprecated scripts/aura_protocol/session_registry.py on PYTHONPATH. Retained for reference only:

PYTHONPATH=scripts bin/aura-swarm --help

When running outside the Nix wrapper, set AURA_PACKAGE_SKILLS_DIR to a Pasture skills/ directory if the target project does not provide local role skills:

AURA_PACKAGE_SKILLS_DIR=/path/to/pasture/skills PYTHONPATH=scripts bin/aura-swarm start --swarm-mode intree --role supervisor --prompt "..."

aura-swarm (deprecated)

Deprecated. bin/aura-swarm and its session state in scripts/aura_protocol/session_registry.py are retained for reference only; do not use them for orchestration or handoff. The Home Manager module still installs the aura-swarm package when packages.enable is set, and the commands below still build and run, but new work should use the supported tooling instead.

aura-swarm supports two launch modes:

• Worktree mode creates or reuses an isolated git worktree for a Beads epic and launches Claude in tmux.
• Intree mode launches one or more Claude sessions in the current checkout without creating worktrees.

Examples:

aura-swarm start --epic aura-example --model sonnet
aura-swarm start --swarm-mode intree --role supervisor -n 1 --prompt "Coordinate this implementation"
aura-swarm status
aura-swarm attach aura-example
aura-swarm stop aura-example
aura-swarm cleanup --done

Prerequisites:

Tool	Purpose
git	Worktree and branch management
tmux	Agent session hosting
bd	Beads issue tracking
claude	Agent runtime

Marketplace

This repo remains a marketplace registry, but it no longer contains a self-installable aura plugin. Use the pasture marketplace entry for the generated protocol skills and agents.

Development

Useful checks before landing changes:

nix flake check --no-build
nix build .#aura-swarm --no-link
nix run .#aura-swarm -- --help

The Python package metadata exists only to package aura-swarm and the retained session registry helper. There are no third-party Python dependencies.