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 8080)
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

Boards

A board is where a project’s tickets live. What makes it different is that humans and minions share the same board: a ticket you raise can be claimed by a minion, worked on, and left in review once its acceptance criteria are met.

• A five-column Kanban (Backlog / To Do / Doing / Review / Done)
• Sprints carve out what comes next; milestones lay out the roadmap
• Custom fields add your own rating axes to tickets, and a combined score can decide the order
• Opt-in per project (enable it in the project’s Settings tab)

The difference from a workflow is what starts the work. A workflow is a graph you define and then run; a board is a pile of work that assigned minions come and take on their own. Use workflows for repeatable procedures and the board for work that comes up as you go.

See Board for details.

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, triggered on-demand from HQ, or started from outside over a webhook URL
• 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.