Introduction

ShrimpHub spawns LLM-powered subprocess agents to build, refactor, and maintain software projects — autonomously, in parallel, against a SQLite task queue.

What it is

ShrimpHub is an agent orchestration server that turns natural-language project descriptions into running DAGs of agents. Each agent runs as a subprocess, executing a constrained tool loop (max 200 calls). Tasks declare dependencies; the planner generates parallel-friendly graphs that converge at integration points.

Who it's for

• Solo developers shipping side projects on nights and weekends
• Game studios using Godot/Python pipelines who want continuous polish during off-hours
• Engineering teams automating refactor and migration work across many repos

What it isn't

• A SaaS product. The whole controller runs on your laptop, against your provider keys, your filesystem.
• A hands-free product. You're the operator — the dashboard exists so you can intervene when an agent goes sideways.
• An IDE. ShrimpHub manages the work; your editor still owns the code.

Architecture

The controller is split across API route modules, orchestration modules, task mutation guards, maintenance helpers, and closure subsystems. State lives in SQLite. Agents run as subprocesses.

Modules

                   ┌────────────────────────────┐
                   │   swarm/api.py             │  Flask app bootstrap
                   │   route registration       │
                   └──────────────┬─────────────┘
                                  │
            ┌─────────────────┼────────────────┐
            ▼                 ▼                ▼
   ┌────────────┐    ┌──────────────┐    ┌────────────────┐
   │  swarm/    │    │  swarm/      │    │  swarm/        │
   │orchestrator│    │ agent_       │    │ validation.py  │
   │   .py      │    │ lifecycle.py │    │                │
   └─────┬──────┘    └──────┬───────┘    └────────────────┘
         │                 │
         │ spawns          │ tracks
         ▼                 ▼
   ┌────────────────────────────────┐
   │  data/agent_<id>.py            │  subprocess wrappers
   │  → swarm/agent_runtime.py     │  LLM tool loop (max 200)
   └────────────────────────────────┘

   State: data/swarm.db (SQLite WAL) + history JSONL + verification records

API route modules

HTTP routes are no longer concentrated in one file. Projects, tasks, agents, config, chat, wizard, dependency integrity, history, webhooks, metrics, and plans each have dedicated swarm/api_*.py modules registered by the Flask app.

Agent lifecycle

1. orchestrator.fill_slots() picks the next ready task from SQLite (respecting deps, locks, paused projects)
2. generate_task_script() builds a thin Python wrapper with embedded config + prompts
3. The wrapper launches as a subprocess and imports swarm.agent_runtime
4. rt.main() runs the tool loop: call LLM → parse [TOOL_CALL] → execute → repeat, capped at 200 loops
5. On completion, orchestrator captures git diff --stat and runs post-task validation in a daemon thread
6. Failed validation auto-spawns a priority-100 bug task; exhausted retries spawn a recovery agent

State ownership

Configuration

All controller settings live in config.json at the project root. The file is gitignored. Most settings can be updated live from the dashboard without restarting the server.

Schema

Accepted values

Meta-agent config

meta_mode_enabled is the master switch. Individual meta-agents keep their own enabled flag and cadence. The Gardener defaults to a 6-hour interval; the Scheduler defaults to 15 minutes; the Cartographer defaults to 2 hours; the Meta Auditor defaults to weekly.

{
  "meta_mode_enabled": true,
  "gardener_enabled": true,
  "gardener_schedule_hours": 6,
  "gardener_max_tasks_per_run": 10,
  "gardener_skip_projects": ["archive-prototype"],
  "librarian_enabled": false,
  "librarian_trigger_interval": 50,
  "librarian_max_prompt_tasks": 3,
  "cartographer_enabled": false,
  "cartographer_interval_hours": 2,
  "meta_auditor_enabled": false,
  "meta_auditor_interval_days": 7,
  "meta_auditor_max_tasks": 20,
  "scheduler_enabled": false,
  "scheduler_interval_minutes": 15
}

Escalation policy

escalation_policy controls what happens when a task exhausts its attempts. Each task type can set max_attempts and on_exhaust. Common exhaustion actions are research for implementation tasks and cancel for QA or planning tasks.

{
  "escalation_policy": {
    "bug":     { "max_attempts": 3, "on_exhaust": "research", "research_max_attempts": 2 },
    "feature": { "max_attempts": 3, "on_exhaust": "research", "research_max_attempts": 2 },
    "qa":      { "max_attempts": 2, "on_exhaust": "cancel" }
  }
}

Live updates

Most settings can be changed without a restart by POSTing to the API. /api/managed-projects accepts managed_projects and paused_projects; fields you omit are left unchanged.

curl -X POST http://localhost:5001/api/managed-projects \
  -H "Content-Type: application/json" \
  -d '{"managed_projects": ["my-game", "todo-app", "new-project"]}'

Environment variables

API keys go in .env, never in config.json:

ANTHROPIC_API_KEY=sk-ant-...
MINIMAX_API_KEY=mx-...
OPENROUTER_API_KEY=or-...
KIMI_API_KEY=k2-...

Godot bootstrap and recovery

The controller normally installs Godot bootstrap files automatically during project creation and imported-project repair. Use this page as a recovery checklist only when validation, QA, or replanning is failing because those files drifted or were removed.

Bootstrap files

project.godot checklist

[autoload]
StateServer="res://autoload/state_server.gd"

[editor_plugins]
enabled=PackedStringArray("res://addons/gut/plugin.cfg")

[application]
run/main_scene="res://scenes/main.tscn"

Validation command

The controller runs project validation automatically after tasks. For manual checks, use the configured Godot binary or set GODOT_PATH/godot_path.

godot --headless --path /path/to/game --script res://check_scripts.gd --quit

Manual recovery

Only run these steps if the automatic bootstrap did not run, or a project has lost required files. Template files live in templates/godot/ in the controller repo. GUT is installed from the controller's local cache or the pinned upstream source.

cp -f shrimphub/templates/godot/check_scripts.gd /path/to/game/
mkdir -p /path/to/game/autoload
cp -f shrimphub/templates/godot/autoload/state_server.gd /path/to/game/autoload/
cp -rf shrimphub/templates/godot/test /path/to/game/
python - <<'PY'
from pathlib import Path
from swarm.godot_bootstrap import install_gut_into_project
install_gut_into_project(Path("/path/to/game"))
PY

Controller config

The project directory must be at <workspace>/<project-name> and contain project.godot.

{
  "workspace": "/path/to/projects/parent",
  "managed_projects": ["my-godot-game"],
  "godot_path": "/path/to/godot"
}

Windows notes

• Use python -m venv .venv and activate with .venv\Scripts\Activate.ps1.
• Put Godot on PATH or set GODOT_PATH/godot_path.
• Headless validation and harness paths are portable; macOS screenshot fallbacks are not.

Tasks & types

Every unit of work is a task. Tasks have a type, a priority, a set of dependencies, and a description. The scheduler picks the next ready task using the configured strategy.

At the role level, task types collapse into four groups: implementation agents do the work, QA agents validate it, research agents diagnose without owning implementation, and planning agents create task graphs for others to execute.

Built-in types

Task format

{
  "id":           "feature-9a3f1b",
  "project":      "my-game",
  "type":         "feature",
  "description":  "Add player inventory UI with drag-drop slots",
  "priority":     80,
  "status":       "pending",
  "dependencies": ["feature-base"],
  "max_attempts": 3
}

Batch creation

The batch endpoint generates IDs upfront so you can wire a full DAG in one request. Use integer indices in depends_on to reference siblings in the same batch.

curl -X POST http://localhost:5001/api/tasks/batch \
  -H "Content-Type: application/json" -d '{
    "project": "my-app",
    "tasks": [
      {"type": "bug",     "description": "Fix login crash"},
      {"type": "bug",     "description": "Fix session expiry"},
      {"type": "feature", "description": "Add OAuth", "depends_on": [0, 1]}
    ]
  }'

Delegation

Broad implementation tasks can delegate in two ways. delegate_helper is read-only, transient analysis that reports back to the parent. delegate_task_batch creates durable child tasks in the DAG with declared write scopes, parent metadata, retries, recovery, and normal operator visibility.

Child batches must declare file or module ownership. Parallel children are valid only when write scopes are disjoint; overlapping work must be explicitly sequenced or kept inside the parent task.

Custom task types

The built-in list is no longer the whole story. Agent profile plugins can register new task types with a role family, prompt file, permission profile, tool allowlist or blocklist, and context providers. See Plugins.

Scenario QA

scenario_qa writes a focused JSON scenario and runs it deterministically against a live Godot game. It is best for concrete player flows such as booting to the main menu, starting gameplay, or reaching a scoring state.

Scenario format

{
  "goal": "Boot to the main menu and start gameplay",
  "seed": 42,
  "steps": [
    { "op": "capture", "name": "01_boot", "vision": "Is a main menu visible? Answer yes or no.", "timeout_seconds": 15 },
    { "op": "assert_invariant", "name": "nonblank_screen", "timeout_seconds": 5 },
    { "op": "press_button", "id": "StartButton", "timeout_seconds": 10 },
    { "op": "wait", "seconds": 2 },
    { "op": "assert_state", "path": "game_state.scene", "ne": null, "timeout_seconds": 5 }
  ]
}

Supported operations

Assertions

assert_state supports these comparators: eq, ne, gt, lt, gte, lte, and contains. Built-in invariants are nonblank_screen, stateserver_ok, and no_crash.

Agent tools

The scenario_qa agent gets two scenario-specific tools:

• write_scenario(path, scenario) writes JSON under test/scenarios/.
• run_scenario(scenario_path, project_path, out_dir) executes the scenario and returns pass/fail details plus trace paths.

If the scenario fails, the executor files a bug task automatically. scenario_qa does not loop retrying the same scenario.

Maturity gate

Scenario QA should only run once the project has GAME_DESIGN.md, at least one real .tscn scene, and autoload/state_server.gd registered. Earlier than that, it should complete with a note rather than producing noisy bug tasks.

Self-healing chains

When agents fail, ShrimpHub recovers automatically. Retries, continuation tasks, validation bug insertion, recovery branches, and integrity repairs cooperate to keep dependency chains alive.

Automatic retry

Failed tasks reset to pending with the failure reason prepended to the prompt on the next attempt. The default is 3 attempts. After the final failure, a recovery task is created — its description includes the full failure history of all prior attempts.

Continuation reparenting

When an agent hits the 200-loop ceiling, it spawns a continuation task. The orchestrator detects the spawn and reparents all downstream dependents to the continuation. The user sees one logical task; under the hood it's a chain.

Validation bug insertion

After a successful run, project validation can still fail. The controller creates a high-priority bug task and places it into the dependency chain, so downstream tasks wait on the validation fix instead of trusting the original completed task.

Self-healing dependencies

A task's dependency is considered "met" if it is completed or no longer exists in the database. This is intentional: if a dep gets pruned as failed, dependents unblock automatically. Chains never stall on missing deps.

Integrity repairs

The dependency integrity API classifies live issues separately from archival-only graph hygiene. Repairs are deterministic endpoints for stale heads, stale planner snapshots, recursive recovery chains, and orphaned agents.

Dependency graphs

Tasks form a directed acyclic graph (DAG). The planner generates parallel-friendly graphs that fan out from shared foundations and converge at integration tasks.

Cycle detection

Cycles are rejected at task-creation time. Posting a task whose dependencies form a cycle returns 400 with a path showing the offending loop.

Parallel execution levels

The DAG is partitioned into levels — tasks with no remaining unmet deps form level 0; tasks whose deps are all in level 0 form level 1; and so on. The scheduler can spawn an arbitrary number of level-N tasks concurrently, bounded only by max_active_agents.

Visualization

The dashboard renders a live SVG of the dependency graph using Graphviz DOT, served from GET /api/dependencies/dot. Nodes are colored by status; edges show direction; failed nodes are circled in magenta.

Graph tools

The API also exposes ready tasks, execution order, dependency integrity, bulk graph edits, subgraphs, critical path data, task lookup, and task-history views. The dashboard's dependency panel uses these routes for operator repair and graph inspection.

Integrity model

Controller integrity checks protect live task graph continuity: valid project heads, dependency blockers, recovery branches, planner snapshots, and agent ownership.

Signals

API and repairs

Read integrity with GET /api/dependencies/integrity. Repair through deterministic endpoints: POST /api/projects/<project>/reconcile-head, POST /api/plans/<project>/cleanup, POST /api/projects/<project>/cleanup-recovery, and POST /api/agents/reconcile.

Mutation boundaries

New mutation paths should route through canonical modules: swarm/integrity.py for predicates, swarm/task_mutations.py for safe dependency rewrites and resets, swarm/maintenance/project_heads.py for project heads, swarm/maintenance/plans.py for planner snapshots, swarm/maintenance/agents.py for runtime drift, and swarm/maintenance/recovery.py for recovery branches.

LLM providers

ShrimpHub ships with four built-in providers and supports any custom OpenAI-compatible or Anthropic-compatible endpoint. The recommended happy path is MiniMax M2.7 for worker agents, especially when you are offloading work from Claude or Codex into a longer-running task queue.

Built-in providers

Overriding a model

{
  "llm_provider": "openrouter",
  "llm_providers": {
    "openrouter": { "model": "google/gemini-2.0-flash-exp" }
  }
}

Registering a custom provider

POST to /api/provider with the connection details. format is one of anthropic, anthropic_native, or openai.

{
  "provider":    "my-local",
  "base_url":    "http://localhost:11434/v1",
  "api_key_env": "OLLAMA_KEY",
  "format":      "openai",
  "model":       "llama3.2",
  "max_tokens":  4096
}

You can also persist the same provider in config.json:

{
  "llm_provider": "my-local",
  "llm_providers": {
    "my-local": {
      "base_url": "http://localhost:11434/v1",
      "api_key_env": "OLLAMA_KEY",
      "format": "openai",
      "model": "llama3.2",
      "max_tokens": 4096
    }
  }
}

REST API

The controller exposes a Flask HTTP API on localhost:5001. All endpoints return JSON. Manager-equivalent actions are available — the dashboard chat uses these same routes.

Common request bodies

# Create one task
curl -X POST http://localhost:5001/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"project":"my-game","type":"feature","description":"Add pause menu","priority":50}'

# Create a dependency-aware batch
curl -X POST http://localhost:5001/api/tasks/batch \
  -H "Content-Type: application/json" \
  -d '{"project":"my-game","tasks":[{"type":"feature","description":"Build HUD"},{"type":"qa","description":"Verify HUD flow","depends_on":[0]}]}'

# Fill available agent slots
curl -X POST http://localhost:5001/api/spawn-batch

# Enable auto mode
curl -X POST http://localhost:5001/api/auto-mode \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

# Switch provider
curl -X POST http://localhost:5001/api/provider \
  -H "Content-Type: application/json" \
  -d '{"provider":"claude"}'

# Append a dependency edge: task waits on dependency
curl -X POST http://localhost:5001/api/tasks/feature-hud/dependencies \
  -H "Content-Type: application/json" \
  -d '{"dependency":"feature-foundation"}'

# Set a closure spec, then verify it
curl -X POST http://localhost:5001/api/projects/my-game/closure/spec \
  -H "Content-Type: application/json" \
  -d '{"closure_spec":{"profile":"godot","mode":"stabilize","critical_flows":[{"id":"main-flow","description":"Boot to main menu and start gameplay."}]}}'
curl -X POST http://localhost:5001/api/projects/my-game/closure/verify

Projects

Tasks

Agents

Control and configuration

Meta mode

Gardener

Meta Auditor

Other meta-agent route pattern

The broader meta-agent suite follows the same route pattern by namespace: /api/librarian/status, /run, /config; /api/cartographer/status, /run, /config; and /api/scheduler/status, /run, /config. Archaeologist follows the same project-focused investigation model.

Chat, wizard, and plans

Closure and integrity

Command line

The current controller is operated primarily through the dashboard and REST API. Local command-line use is centered on starting the server and running validation/test utilities.

Commands

shrimphub start                         # start installed launcher
python swarm_runner.py api              # start from source checkout
python -m pytest                      # run controller tests
python validate_godot.py /path/to/game  # run Godot validation helper
curl http://localhost:5001/api/ping     # check local server health

API scripting

For automation, call the REST API directly. For example, POST /api/tasks/batch seeds a DAG, POST /api/spawn-batch fills available slots, and POST /api/auto-mode toggles continuous operation.

Notes

• config.json controls workspace, providers, concurrency, auth, and project lists.
• The installer creates a small shrimphub launcher for start, update, and config. Deeper automation should call the REST API directly.
• Remote repo provisioning is optional and disabled by default in the example config.

MCP integration

Agents can call any MCP (Model Context Protocol) server you configure. Use this to give agents domain-specific tools — game engines, design tools, internal APIs.

Configure servers

{
  "mcp_servers": {
    "godot": {
      "command": "godot-mcp",
      "args":    ["--stdio"],
      "env":     { "GODOT_PROJECT_PATH": "/path/to/project" }
    }
  }
}

MCP clients are initialized inside the agent process with the project path as their working directory. If a server fails to start, agents will see MCP tool errors in their logs; the controller does not silently replace that server with a fallback.

Agent-facing tools

Each registered server exposes two tools to agents:

• mcp_list_tools(server) — discover available tools
• mcp_call_tool(server, tool_name, args) — invoke a tool

Agent profile plugins

Plugins let you add new task types, or override existing task behavior, without editing the controller core. A plugin is declared as YAML under plugins/ and loaded when the server starts.

What plugins can do

• Register a new task type such as lore_pass or accessibility_audit
• Override the prompt used for a task type
• Assign one of the four role families: implementation, QA, research, or planning
• Enforce a permission profile at tool-dispatch time, not just in prompt text
• Allow or block specific tools with an explicit allowlist or blocklist
• Inject runtime context from project files, shell commands, or HTTP GET calls

Create a plugin

1. Create a *.yaml file in plugins/ at the swarm root.
2. Optionally create a separate prompt YAML file with system and user keys.
3. Restart the server. Plugins are loaded once at startup.
4. Create a task with the new type through the dashboard, API, or agent tools.

plugin_id: "lore_pass"
task_type: "lore_pass"
display_name: "Lore Consistency Pass"
role: "implementation"
permission_profile: "read_write"
prompt_file: "plugins/lore_pass_prompt.yaml"

tools_blocked:
  - "run_command"
  - "web_search"
  - "create_task"

context_providers:
  - type: "file"
    path: "GAME_DESIGN.md"
    max_chars: 12000
  - type: "command"
    command: "find . -name '*.md' -not -path './.git/*' | head -30"
    timeout_seconds: 5
    max_chars: 1000

YAML fields

Role families

Permission profiles

Permission profiles are enforced by the tool dispatcher. A plugin prompt cannot talk its way around a blocked tool.

Permission order is: profile blocks, then tools_blocked, then tools_allowed. The blocklist always wins.

Tool names for allow/block lists

tools_allowed and tools_blocked take exact dispatcher tool names as strings. They do not take tool categories, glob patterns, or function signatures.

tools_allowed:
  - "read_file"
  - "list_files"
  - "search_code"
  - "write_file"

tools_blocked:
  - "run_command"
  - "git_push"
  - "web_search"

Allowlisting a task-specific tool does not make it globally available. For example, harness_step is still only registered for harness QA task types, and write_scenario is still only registered for scenario_qa.

Common plugin policies:

• Read-only investigation: allow file inspection, search, scratchpad, task context, and optionally write_file for a report path if the role needs one.
• Text-only implementation: allow file inspection and mutation, then block run_command, web_search, create_task, and git_push if you want human review before pushing.
• QA-style task: prefer permission_profile: "qa_write", then allow the specific QA tools the task needs.

Context providers

Context providers run before the agent starts and append labelled context to the task description. Output is truncated by max_chars.

Prompt files

A plugin prompt file must be YAML with system and user keys. It uses Jinja-style variables with << variable >> syntax.

system: |
  You are a lore consistency editor for the game << project >>.
  Review narrative text against GAME_DESIGN.md. Fix inconsistencies in place.
  Commit and push when done.

user: |
  << description >>

Common variables include project, description, project_path, project_path_arg, godot_bin, godot_command, godot_status, and prompt_intent_variant.

Constraints

• Plugins are loaded at startup only. Restart the server to pick up new or changed plugin files.
• Only *.yaml plugin files are loaded.
• Duplicate task_type declarations are ignored after the first plugin, with a warning.
• Command and HTTP provider timeouts are capped at 30 seconds.
• Plugins can override built-in task types, but new task types are safer for most use cases.

Troubleshooting

• If a plugin does not load, check startup logs for [Plugins] lines and validate the YAML.
• If a context provider does not run, check agent logs for provider entries and confirm paths are relative to the project root.
• If a blocked tool is still available, restart the server and check for authority-denial messages in the agent log.
• If a prompt fails to render, confirm the prompt path is relative to the swarm root and uses << var >>, not double-curly syntax.

Meta-agents

Meta-agents are scheduled agents that operate across the entire swarm rather than on one project. They form the observability and self-improvement layer above the standard task pool: read broadly, create tasks narrowly, and avoid direct project-code edits.

Suite

Operating rules

• Meta-agents read all active projects and swarm history.
• They create normal project tasks for execution rather than directly editing project code.
• Each meta-agent has its own prompt at prompts/<agent_name>.yaml and task type matching its name.
• Reports are written under data/, usually as <AGENT_NAME>_REPORT.md.
• meta_mode_enabled acts as the master switch for the layer.

Gardener

The Gardener surveys all active projects, identifies failure patterns that appear across multiple codebases, creates targeted fix tasks, and maintains the shared swarm knowledge base.

• Reads recent failures, active agent state, and data/swarm_knowledge.jsonl
• Writes data/swarm_knowledge.jsonl, data/SWARM_KNOWLEDGE.md, and data/GARDENER_REPORT.md
• Uses confidence labels: confirmed, suspected, and disputed
• Dashboard controls: enabled toggle, status line, Run Now, and knowledge viewer

Librarian

The Librarian closes the feedback loop between real agent failures and the prompt files that drive future agents. It groups recurring failures by task type, identifies likely prompt instruction gaps, and creates bounded prompt-edit tasks on swarm-controller.

• Reads data/task-history.jsonl, data/agent-history.jsonl, prompts/*.yaml, and shared knowledge
• Writes data/LIBRARIAN_REPORT.md
• Creates at most librarian_max_prompt_tasks prompt refactor tasks per run

Cartographer

The Cartographer turns task counts and health scores into a readable project map: what each project is doing, where it is stuck, how long it has been in that state, and whether known Gardener patterns apply.

• Writes data/PROJECT_MAP.md and data/SWARM_SUMMARY.json
• Feeds the dashboard and gives other meta-agents shared narrative context

Meta Auditor

The Meta Auditor is distinct from the per-project audit task type. It looks across projects for systemic template drift, missing required files, autoload collisions, and dependency hygiene issues, then creates coordinated fix tasks instead of N unrelated repairs.

• Writes data/AUDIT_REPORT.md
• Creates at most meta_auditor_max_tasks coordinated fix tasks
• Focuses on repeated structural issues, especially shared Godot templates and project setup

Scheduler

The Scheduler observes queue composition, active agents, quota pressure, health scores, time of day, and project priority, then adjusts future scheduling decisions. It does not kill running agents.

• Can adjust max_active_agents when enabled
• Can pause or unpause projects when scheduler_allow_pause is true
• Writes data/SCHEDULER_LOG.md as its decision log

Archaeologist

The Archaeologist is the recovery investigator for projects that have gone silent, emptied their queue after failures, or fallen into long recovery chains. It is read-only on project code and produces an ARCHAEOLOGY_REPORT.md plus a recovery task DAG.

API endpoints

See REST API for current endpoint tables. The active pattern is /status, /run, and /config under each meta-agent API namespace.

Dashboard

The dashboard at http://localhost:5001 is your primary control surface. Auto-refreshes every 5 seconds; SSE streams agent output live.

Surfaces

• Sidebar — managed projects with active task counts
• Provider bar — switch LLM provider and model; shows API-key status
• Quota meter — live API usage with reset countdown
• Active agents grid — one card per running agent; click to open the log panel with live SSE, loop count, and context compaction meter
• Pending tasks — DAG-ordered queue
• Project cards — health bar, recent commits, closure status, Repair, Restart, Replan, and closure actions
• Dependency integrity panel — live and archival findings with deterministic repair buttons
• Meta-agents panel — master meta-mode, Gardener knowledge, Meta Auditor status, and controls for the broader suite
• Spawn bar — bottom-center; max agents, spawn N, run all, auto mode, kill all, QA cycle cap
• Unified chat — natural-language control with API actions, project creation, and debugging flows
• History — archived agent runs, failed task history, requeue actions, and pruning

Entry-points

Security & auth

ShrimpHub is designed to run under your control. Authentication is opt-in. Exposing the server to a network without auth is a footgun.

Enable authentication

Set login_required: true in config.json. Default credentials are admin / admin — change them before exposing the server.

{
  "login_required": true,
  "login_username": "admin"
}

Setting a strong password

python - <<'PY'
from swarm.login import hash_password_for_storage
pw, salt = hash_password_for_storage(input("Password: "))
print(f'"login_password_hash": "{pw}",')
print(f'"login_salt": "{salt}"')
PY

Add the printed values to config.json with login_required and login_username:

{
  "login_required": true,
  "login_username": "admin",
  "login_password_hash": "<printed hash>",
  "login_salt": "<printed salt>"
}

Closure mode

Closure mode moves the controller beyond expansion. Each project can carry a machine-readable finish contract, durable verification runs, regression tracking, and repair-first scheduling when health drops.

State model

Modules

Closure logic lives under swarm/closure/: specs, verification runs, regressions, verification execution, status derivation, repair planning, proposals, escalation, documents, and project seeds. Project-scoped API routes live in swarm/api_projects.py.

Repair-first behavior

Failed verification becomes structured regressions and repair tasks. Red or stalled projects can freeze feature expansion while the controller spends its repair budget on restoring boot, tests, smoke checks, and required critical flows.

Recovery & repair

When automatic self-healing isn't enough, operator-facing repair tools let you intervene surgically without editing the database by hand.

Reset a single task

Resets a failed task to pending with attempts=0. Optionally include a recovery note — it gets prepended to the prompt on the next attempt, telling the agent what went wrong and what to try differently.

Project repair

Surgical fix for a broken project — resets failed/orphaned tasks, resurrects missing dep tasks from task-history.jsonl, and recomputes the project head. Safe to run repeatedly.

Integrity repair

Use the integrity panel for stale heads, stale plans, recursive recovery chains, continuity gaps, and agent/runtime drift. These repairs map to dedicated endpoints and are intended to be deterministic and idempotent.

Closure repair

Closure repair converts failed verification into structured follow-up tasks tied to regressions. This is the preferred path when a project boots incorrectly, fails smoke checks, or repeats the same failure fingerprint.

Project restart

Nuclear reset — every task in the project goes back to pending with attempts=0. Use only when repair can't resolve the breakage.

Re-queue from history

If a task was pruned (deleted from the live queue but archived in task-history.jsonl), the dashboard's ↺ Re-queue button on a history card resurrects it with attempts reset.