Core Concepts

This page explains the key concepts that make up the Minion system.

Minions

A minion is a Claude Code agent running on an independent VPS. Each minion is equipped with the following:

Component	Description
Claude Code CLI	AI agent runtime
Fastify API	API server for HQ communication (port 3001)
Xvfb + noVNC	Virtual display and browser VNC (port 6080)
ttyd	Web terminal (port 7681)
Cloudflare Tunnel	Secure external connectivity
MCP Servers	Extension tools like Playwright, Serena, etc.

Projects

A project is a unit that groups workflows and contexts together.

• Assign minions as members (PM / Engineer roles)
• Define shared context in Markdown
• All members can access workflows under the project

Skills

Skills are reusable prompts for Claude Code. They are defined as SKILL.md files and version-controlled.

---
name: my-skill
display_name: My Skill
description: A description of the skill
---

Write your prompt body here.

Skills can also include accompanying files (templates, configs, etc.).

Workflows

Workflows are project-scoped pipelines that coordinate multiple minions with organizational governance.

skill-1 → skill-2 → skill-3 → execution-report

• Can be scheduled via cron expressions or triggered on-demand from HQ
• Each step can be assigned an execution role (PM / Engineer)
• A requires review flag allows inserting human approval gates
• Full version control — each change creates an immutable snapshot
• Complete audit trail tracked in HQ database

Think of workflows as a CI/CD pipeline for your project.

Routines

Routines are minion-scoped pipelines for autonomous, self-contained scheduled tasks.

skill-1 → skill-2 → execution-report

• Owned by an individual minion, not a project
• Run autonomously on the minion’s cron scheduler without HQ involvement
• No role assignment or review gates — the owning minion executes all steps
• Always use latest skill versions (no version pinning)
• Execution history stored locally on the minion

Think of routines as a personal crontab for a minion.

How to choose

The key differentiator is governance level, not the presence of a pipeline:

• “Who runs this?” is one minion → Routine
• “Who runs this?” depends on roles → Workflow
• Need review gates or audit trails? → Workflow
• Autonomous personal habit? → Routine

The same skills can be used in both. See Routine Design for detailed comparison and examples.