swarmpy

A single-file Python/uv port of SwarmForge.

The goal is intentionally boring:

• one file: swarm.py
• one global command: swarmpy
• no shell helper scripts
• no Terminal.app / osascript
• one tmux session per workflow
• one tmux window per agent role
• git worktrees when configured
• multiple workflows per project
• simple config-driven agent launch

Requirements

• uv
• tmux
• git
• optional agent CLIs depending on config: claude, codex, opencode, pi

Install global CLI

Install the global swarmpy command once:

uv run --script swarm.py install

This creates a symlink:

~/.local/bin/swarmpy -> /path/to/swarm.py

Make sure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Then use:

swarmpy --help

Without installing, you can still run:

uv run --script swarm.py [COMMAND]

Install agent skill

This repository includes a root SKILL.md for the open agent skills ecosystem. The npx skills CLI discovers root-level SKILL.md files and installs them into agent-specific skill directories such as .claude/skills/<skill>/SKILL.md, .agents/skills/<skill>/SKILL.md, or .pi/skills/<skill>/SKILL.md depending on the selected agent.

Install it so coding agents understand SwarmPy's workflow layout, worktrees, logs, agent context, and coordination commands instead of relying on --help alone:

npx skills add https://github.com/msadig/swarmpy -g -y

Install for a specific agent, for example Claude Code or Pi:

npx skills add https://github.com/msadig/swarmpy -g -a claude-code -y
npx skills add https://github.com/msadig/swarmpy -g -a pi -y

For a project-local install, omit -g:

npx skills add https://github.com/msadig/swarmpy -y

Manual Claude Code install shape:

~/.claude/skills/swarmpy-workflows/SKILL.md

After publishing/refreshing the repo, it can be discovered from https://skills.sh/.

Workflows

A project can have many workflows. Each workflow has its own config, role prompts, settings, tmux session, tmux windows, worktrees, logs, and agent context.

Tmux grouping is workflow-first:

swarmpy-myproject-development    # tmux session
  architect                      # tmux window
  coder                          # tmux window
  reviewer                       # tmux window
  logger                         # tmux window

swarmpy-goldinvest-seo           # tmux session
  collector                      # tmux window
  analyst                        # tmux window
  writer                         # tmux window
  reviewer                       # tmux window
  logger                         # tmux window

Default workflow layout:

swarmforge/
  swarmforge.conf
  settings.env
  constitution.prompt
  architect.prompt
  coder.prompt
  reviewer.prompt

Named workflow layout:

swarmforge/
  workflows/
    development/
      swarmforge.conf
      settings.env
      constitution.prompt
      architect.prompt
      coder.prompt
      reviewer.prompt
    content/
      swarmforge.conf
      settings.env
      constitution.prompt
      researcher.prompt
      writer.prompt
      reviewer.prompt

Create two workflows in the same project:

swarmpy init /path/to/project -w development
swarmpy init /path/to/project -w content

List workflows:

swarmpy workflows -p /path/to/project
swarmpy workflows -p /path/to/project --json

--json emits { "project": "...", "workflows": [{ "name", "path", "config_file" }, ...] } and exits 0 even when the list is empty.

Launch one workflow:

swarmpy launch /path/to/project -w development

Launch another workflow independently:

swarmpy launch /path/to/project -w content

Workflow-specific runtime state:

.swarmforge/<workflow>/
.worktrees/<workflow>/
logs/<workflow>/agent_messages.log
agent_context/<workflow>/

Workflow-specific settings live in:

swarmforge/workflows/<workflow>/settings.env

That file is sourced before each agent starts, so you can put environment variables there, for example:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GITHUB_LABEL=bug
REPORT_OUTPUT_DIR=agent_context/content/reports

Config

Each workflow has a swarmforge.conf:

window architect claude master
window coder codex coder
window reviewer codex reviewer
window logger none none

Format:

window <role> <agent> <worktree>

Agents:

• claude
• codex
• opencode
• pi
• none

Worktree behavior:

• master uses the main working directory
• none uses the main working directory and creates no worktree
• any other value creates .worktrees/<workflow>/<name> on branch swarmpy-<project>-<workflow>-<name>

You can also launch the whole workflow from one shared worktree:

swarmpy launch /path/to/project -w development --worktree nightly

That creates/uses:

.worktrees/development/nightly

and runs every non-none role there, regardless of the per-role worktree names in swarmforge.conf.

CLI

Show top-level help:

swarmpy --help

Show help for a command:

swarmpy help notify
swarmpy cleanup --help

Commands:

install    install the global `swarmpy` command
init       create workflow config and role prompt scaffolding
launch     start the configured workflow
workflows  list workflows configured in a project
sessions   list configured sessions and running status
notify     send a message to a role, index, or tmux target
log        append a message to logs/<workflow>/agent_messages.log
logs       show or follow logs/<workflow>/agent_messages.log
attach     attach to a workflow session and select a role window
cleanup    kill workflow tmux sessions

Create workflow scaffolding:

swarmpy init /path/to/project -w development

This creates:

swarmforge/workflows/development/swarmforge.conf
swarmforge/workflows/development/settings.env
swarmforge/workflows/development/constitution.prompt
swarmforge/workflows/development/architect.prompt
swarmforge/workflows/development/coder.prompt
swarmforge/workflows/development/reviewer.prompt

Launch:

swarmpy launch /path/to/project -w development

Launch from one shared workflow worktree:

swarmpy launch /path/to/project -w development --worktree nightly

List sessions:

swarmpy sessions -p /path/to/project -w development
swarmpy sessions -p /path/to/project -w development --json

--json emits { "project", "workflow", "sessions": [{ "index", "role", "session", "window", "target", "display", "agent", "running" }, ...] }. If sessions.tsv is missing, JSON is printed to stdout with an error field and the process exits 1.

Attach to a role:

swarmpy attach coder -p /path/to/project -w development

Notify an agent:

swarmpy notify coder "Please implement the next slice." -p /path/to/project -w development

Append to workflow log:

swarmpy log reviewer "Review started." -p /path/to/project -w development

Show recent workflow logs:

swarmpy logs -p /path/to/project -w development

Follow workflow message logs:

swarmpy logs -f -p /path/to/project -w development

Show raw tmux output for one agent/window:

swarmpy logs --pane coder -p /path/to/project -w development

Follow raw tmux output for one agent/window:

swarmpy logs --pane coder -f -p /path/to/project -w development

Follow raw tmux output for every agent/window in the workflow:

swarmpy logs --all-panes -f -p /path/to/project -w development

Show the log file path:

swarmpy logs --path -p /path/to/project -w development

Cleanup all sessions for a workflow:

swarmpy cleanup -p /path/to/project -w development

Cleanup explicit sessions:

swarmpy cleanup swarmpy-myproject-development

Tests

Run the regression suite:

python3 test.py

The tests cover CLI help, workflow scaffolding, global swarmpy installation, and a logger-only tmux workflow with notify/log/cleanup.