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 graphs that coordinate skills and multiple minions with organizational governance. They are built in the HQ visual editor from typed nodes connected by edges (a DAG — directed acyclic graph), rather than a single straight line of steps.

flowchart LR
    S(("Start")) --> A["Skill: fetch"]
    A --> C{{"Conditional"}}
    C -->|ok| F[["Fan-out"]]
    C -->|error| E(("End"))
    F --> J(("Join"))
    J --> R{"Review"}
    R -->|approved| E

• Parallel execution, fan-out/join, and conditional branching — express real dependencies, not just a linear sequence
• Can be scheduled via cron expressions or triggered on-demand from HQ
• Each node can be assigned an execution role (PM / Engineer)
• Review nodes insert human (or minion) approval gates with revision loops
• Full version control — each change creates an immutable snapshot
• Complete audit trail tracked in HQ database

See DAG Nodes for the available node types.

Routines

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

flowchart LR
    A["skill-1"] --> B["skill-2"]

• 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 and orchestration complexity, not whether multiple skills are involved:

• “Who runs this?” is one minion → Routine
• “Who runs this?” depends on roles → Workflow
• Need review gates or audit trails? → Workflow
• Need parallel branches, fan-out, or conditional routing? → Workflow
• Autonomous personal habit? → Routine

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