Swarm Minion

Swarm Minion

A Minion is a containerized AI agent that autonomously works on a single GitHub issue. It clones the repository, reads the issue, implements a solution, creates a PR, and reports results back to the Overlord.

Lifecycle

Container Start
    ↓
Load config from environment
    ↓
Clone repository → Create branch
    ↓
Fetch issue details from GitHub
    ↓
Build system prompt with issue context
    ↓
Run MinionAgent (agentic loop)
    ├── LLM plans approach
    ├── Executes tools (read/write/edit files, run commands)
    ├── May ask clarifying questions (max 3)
    └── Loops until complete or blocked
    ↓
Run tests (if present)
    ↓
Create PR linked to issue
    ↓
PR Review (if enabled)
    ↓
Report completion to Overlord
    ↓
Container exits

Components

Minion
├── MinionConfig      # Environment-based configuration
├── GitHubClient      # Issue fetching and PR creation
├── GitManager        # Clone, branch, commit, push
├── Reporter          # Heartbeat and event reporting to Overlord
├── MinionAgent       # Agentic loop (LLM + tools)
│   ├── LLMClient     # OpenAI-compatible API client
│   ├── ToolExecutor  # Sandboxed tool execution
│   └── PromptBuilder # System prompt construction
└── ReviewWorkflow    # Automated PR review (optional)

MinionAgent

The MinionAgent runs an agentic loop:

1. Send conversation history + tools to LLM
2. LLM responds with text and/or tool calls
3. Execute tool calls (file reads, writes, edits, shell commands)
4. Append results to conversation
5. Repeat until the agent calls task_complete or task_blocked

Available Tools

Tool	Description
read_file	Read file contents from the workspace
write_file	Create or overwrite a file
edit_file	Make targeted edits within a file
list_directory	List directory contents
search_files	Search for patterns in files
glob_files	Find files by glob pattern
run_command	Execute shell commands
task_complete	Signal successful completion
task_blocked	Signal the task is blocked (with optional question)
list_skills	List available skills
use_skill	Execute a learned skill

Agent Results

The agent returns an AgentResult with:

Status	Meaning
COMPLETED	Task finished successfully
BLOCKED	Agent needs human input (may include a question)
TURN_LIMIT	Maximum turns reached
ERROR	Unrecoverable error

Clarifying Questions

When the agent encounters ambiguity, it can call task_blocked with a question:

1. Agent calls task_blocked(question="Which endpoint should I use?")
2. Minion sends QUESTION event to Overlord via Reporter
3. Overlord posts question to Slack
4. Human replies in thread
5. Minion polls for answer (up to 10 minutes)
6. Answer injected into agent conversation
7. Agent resumes work

Limits: 3 questions per run, 10-minute timeout per question. If no answer arrives, the agent continues using its best judgment.

Reporter

The Reporter maintains communication with the Overlord:

Method	Event Type	Description
heartbeat()	HEARTBEAT	Periodic health signal (every 30s)
update_status()	STATUS	Phase updates ("cloning", "working", etc.)
question()	QUESTION	Ask a clarifying question
poll_answer()	-	Poll for answer to a question
completed()	COMPLETED	Success with PR details
error()	ERROR	Failure with error details

PR Creation

After completing work, the Minion:

1. Stages all changes
2. Creates a commit with a descriptive message
3. Pushes the branch to the remote
4. Creates a PR via the GitHub API
5. Links the PR to the original issue
6. Optionally runs automated PR review

Branch Naming

Branches follow the pattern: minion/{minion-id}/{issue-number}

Configuration

All configuration is passed via environment variables (set by the Overlord's DockerManager):

Variable	Default	Description
MINION_ID	-	Unique minion identifier
GITHUB_REPO	-	Repository (owner/name)
GITHUB_ISSUE	-	Issue number
GITHUB_TOKEN	-	GitHub authentication token
OVERLORD_CALLBACK_URL	http://overlord:8080/minion/report	Report endpoint
NEBULUS_BASE_URL	http://localhost:5000/v1	LLM server URL
NEBULUS_MODEL	qwen3-coder-30b	Model to use
NEBULUS_TIMEOUT	600	LLM request timeout
MINION_TIMEOUT	1800	Total minion timeout (30 min)

Container Limits

Resource	Limit
Memory	2 GB
CPU	1 core
Network	nebulus-swarm bridge
Workspace	/workspace

Related Pages

• Nebulus Swarm - System overview
• Swarm Overlord - Control plane
• Model Router - How the model is selected for this minion