multiagent-agentswarm 1.2.1
Agent orchestration and swarm management for multi-agent development
Requires Python: >=3.8

# AgentSwarm

AgentSwarm is a lightweight orchestration layer for coordinating multiple AI agent CLIs inside a codebase. It assumes you already generated project scaffolding (specs, task markdown, etc.) using the multi-agent template, and gives you tools to:

1. **Deploy** agent processes from a single configuration file.
2. **Assign / redirect** tasks programmatically using each agent's non-interactive CLI.
3. **Monitor** progress and state through persistent deployment metadata (and optional workflow execution).

The system deliberately separates three layers:

| Layer | Responsibility | Git folders |
| --- | --- | --- |
| Planning Template | Generate specs/tasks for each agent | `specs/`, `.agents/*/tasks.md` |
| AgentSwarm Runtime | Launch agents, manage processes, run workflows | `src/agentswarm`, `agentswarm`, `.agentswarm/` |
| Management CLI (optional) | Real-time interventions (fix/modify/assign tasks) | `scripts/`, future `agent_cli/` |

---
## Quick Start

```bash
# 1. Create / update agentswarm.yaml (see below)
# 2. Install dependencies
./install.sh

# 3. Launch a swarm using the local config
./agentswarm deploy

# 4. Inspect status
./agentswarm status

# 5. Stop / scale / run workflows as needed
./agentswarm scale codex 1
./agentswarm workflow list
```

AgentSwarm persists deployment metadata in `.agentswarm/state.json`, so the CLI can always report which agents are running and with which configuration.

---
## Command templates for agent CLIs

AgentSwarm runs each agent through its CLI launcher. To keep things non-interactive, configure the correct pattern per agent inside `agentswarm.yaml`:

```yaml
agents:
  codex:
    instances: 2
    command_template: "codex exec '{task}'"
  gemini:
    instances: 1
    command_template: "gemini -p '{task}'"
  qwen:
    instances: 1
    command_template: "qwen -p '{task}'"
  claude:
    instances: 1
    command_template: "claude -p '{task}'"  # if your Claude CLI supports -p
```

| Agent CLI | Non-interactive pattern | Example command |
| --- | --- | --- |
| Codex | `codex exec "…"` | `codex exec "Implement cache layer"` |
| Gemini | `gemini -m <model> -p "…"` | `gemini -m 1.5-pro-latest -p "Summarize feedback from tasks.md"` |
| Qwen | `qwen -p "…"` | `qwen -p "Add pagination to list results"` |
| Claude | `claude -p "…"` | `claude -p "Review architecture for blockers"` |

With those templates in place, AgentSwarm can hand any task string to the agent without prompting for interactive input.

Run `agentswarm doctor` any time you need to validate that command templates and dependencies are wired up correctly. It will highlight missing `command_template` values, dependency gaps, or assignment-rule sync issues before you start a deployment.

Available placeholders inside `command_template`:

- `{task}` → Primary task payload (single entry or all tasks joined with `&&`)
- `{task_list}` → Tasks joined by spaces (useful for argument lists)
- `{tasks_json}` → JSON array of every task string
- `{project}` → Absolute path to the project root passed via `--project`
- `{agent}` / `{instance}` → Agent type and instance id at runtime

---
## Local-first CLI workflow

AgentSwarm includes dedicated command groups for managing the local-first task system alongside deployment orchestration.

### `agentswarm task`

| Command | Description |
| --- | --- |
| `agentswarm task create "Add loading spinners" --agent codex --scope frontend/` | Creates a `local-###` task and appends it to the correct agent section. |
| `agentswarm task list --status pending --format json` | Lists tasks with optional filters; JSON output makes it easy to feed other automations. |
| `agentswarm task start local-003 --no-git` | Marks the task as `in_progress`, opening a work session without creating a new branch. |
| `agentswarm task complete local-003 --skip-qa` | Runs QA commands (unless skipped) and records the completion in `.local-state/active-work.json`. |
| `agentswarm task status` / `agentswarm task resume` | Summarises backlog counts and resumes the most recent work session automatically. |

### `agentswarm spec`

| Command | Description |
| --- | --- |
| `agentswarm spec create-feature "Realtime metrics" --requires-frontend --agent codex --agent claude` | Generates a spec-kit compatible folder with `spec.md`, `plan.md`, `tasks.md`, and `implementation/` scaffolding. |
| `agentswarm spec list-features` | Enumerates existing feature folders under `specs/`. |
| `agentswarm spec validate feature-name` | Ensures required files and implementation subdirectories exist. |

### `agentswarm local`

| Command | Description |
| --- | --- |
| `agentswarm local init` | Bootstraps `.local-state/` with README + state files. |
| `agentswarm local status` | Shows pending/in-progress/completed counts plus the next actionable task. |
| `agentswarm local validate` | Checks for missing dependency references or uninitialised state. |

### `agentswarm agents assign`

Push new task payloads into a running deployment without redeploying:

```bash
agentswarm agents assign codex --tasks "specs/payment-flow/tasks.md#codex,docs/ADR-009.md"
```

The orchestrator persists the updated task list next to each process in `.agentswarm/state.json`, so `agentswarm agents list --format json` reports commands, PIDs, and task assignments alongside process health.

### Example task payload

Most teams keep human-readable task lists in `specs/<feature>/tasks.md` or `.agents/<agent>/tasks.md`. You can feed those files to the agents by putting instructions in the command template:

```yaml
command_template: "gemini -m 1.5-pro-latest -p \"Read specs/payment-flow/tasks.md, find all tasks tagged @gemini, execute them sequentially\""
```

That results in commands such as:

```
gemini -m 1.5-pro-latest -p "Read specs/payment-flow/tasks.md, find all @gemini tasks, execute them sequentially"
```

### Deployment guidance from the CLI

- `agentswarm deploy --guide` prints the deployment matrix plus each agent's `command_template`, so you can confirm non-interactive invocation before launching anything.
- `agentswarm deploy --dry-run` still shows the classic plan table; it now adds follow-up suggestions for monitoring and workflow commands.
- `agentswarm doctor --check-commands --verify-tasks` confirms referenced binaries are on `PATH` and that every task file listed in your config exists.
- Task ownership stays inside the markdown specs: agents parse `## @agent` sections in `specs/.../tasks.md`. The CLI never injects `@codex` or `@claude` into command strings—it simply hands each agent the file/anchor to read.
- Template sync CI can skip the richer CLI smoketests by leaving `AGENTSWARM_RUN_TEMPLATE_TESTS` unset. Set `AGENTSWARM_RUN_TEMPLATE_TESTS=1` when you want the full suite (guide + doctor validations) to run locally or in a release pipeline.

The repository ships with a starter specification at `specs/default/tasks.md`, which maps to the default `agentswarm.yaml`. Update those files (or generate new ones from Spec Kit) before handing work to the swarm.

---
## Management / Intervention CLI (concept)

While the runtime keeps agents alive, project managers often need to redirect them mid-flight. A simple Click CLI can sit on top of AgentSwarm to do that:

```python
# scripts/agent_cli.py (simplified)
@click.group()
def agent():
    """Intervene with active agents"""

@agent.command()
@click.argument("agent_type")
@click.argument("instruction")
def fix(agent_type, instruction):
    subprocess.run(f"{agent_type} -p 'URGENT FIX: {instruction}'", shell=True)
```

The template includes example commands (`fix`, `modify`, `assign`, `reassign`, `standup`, etc.) that you can expand. Hook this into your workflow by adding a top-level `scripts/agent` wrapper that calls the Click CLI.

---
## Repository structure

```
agentswarm/                 # base wrapper script (creates venv if present)
bin/                        # (in template) holds the runtime wrapper when deployed
src/agentswarm/             # core runtime + workflow engine
  ├─ core/                  # process orchestration (deploy/scale/monitor)
  ├─ workflows/             # optional workflow execution layer
  └─ lib/                   # shared helpers (moved from top-level lib/)
scripts/intelligent-auto-deploy.sh
                            # copies only runtime assets into template/agentswarm
install.sh                  # developer installer: venv + requirements
requirements.txt            # python dependencies
VERSION                     # semantic-release updates this JSON payload
```

---
## Development and deployment

1. **Install**: `./install.sh` (creates `venv/` and installs requirements)
2. **Run lint/tests**: `pytest tests/backend`
3. **Deploy to template**: The GitHub Actions workflow (.github/workflows/version-management.yml) uses semantic-release to bump `VERSION` and then syncs the minimal payload (`src/`, `bin/agentswarm`, `install.sh`, `requirements.txt`, `VERSION`) into the template repository.

The deployment script deliberately excludes development directories such as `specs/`, `.github/`, `tests/`, `.vscode/`, ensuring the template only receives runtime assets.

---
## Next steps

- Add your own management CLI commands under `scripts/` to record interventions.
- Extend `agentswarm.yaml` with additional agents or workflows.
- Use `./agentswarm workflow ...` to run multi-agent workflows defined in `src/agentswarm/workflows/templates.py`.

For more details, see the template documentation in `templates/` and the DevOps README (synced via `devops` repo) for CI/CD integration.