matrixswarm 1.0.19

Open-source automation and monitoring platform

MATRIXSWARM

███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║
███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
███████║╚███╔███╔╝██║  ██║██║  ██╗██║ ╚═╝ ██║
╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝
         MATRIXSWARM v0.2 "STORMCROW"
        Reflex. Resurrection. Real-time RPC.

MatrixSwarm is the first autonomous, file-driven, swarm-based AI operating system.

**No containers. No servers. No daemons. Just intelligent agents, spawned and coordinated entirely through folders, directives, and atomic file signals. Agents don’t run under you — they live beside you.

MatrixSwarm is a lightweight, dependency-free alternative to Docker Compose for managing and coordinating multi-process applications. If you want to run a complex system of interconnected scripts (agents) with automatic restarts, secure communication, and dynamic control—all without containers or daemons—MatrixSwarm is for you. It uses simple file and folder operations as its API, making it incredibly portable and easy to debug.

Quick Start

1. Deploy the Swarm: Boot the ai universe using the test-01 directive.

   python3 site_ops/site_boot.py --universe ai --directive test-01
   

2. List Swarm Activity: Check which universes are running and see their process IDs.

   python3 site_ops/site_list.py
   

3. Terminate the Swarm: Shut down the ai universe and clean up old files.

   python3 site_ops/site_kill.py --universe ai --cleanup
   

---

Installation

You can now install MatrixSwarm directly from PyPI:

  pip install matrixswarm

---

Booting MatrixSwarm

After installing MatrixSwarm via pip, you no longer need to run Python scripts directly!

Recommended: Use the CLI Entrypoint:

   matrixswarm-boot --universe ai --directive test-04 --encryption-off
   Or, for advanced/manual runs, use:
   python -m matrixswarm.site_boot --universe ai --directive test-04 --encryption-off(execute in parent directory or matrixswarm)

   matrixswarm-kill --universe ai --cleanup
   Or, for advanced/manual runs, use:
   python -m matrixswarm.site_kill --universe ai --cleanup(execute in parent directory or matrixswarm)

---

Core Concepts

• Philosophy: MatrixSwarm isn’t just code—it’s a world. A breathing hierarchy where agents think, die, and come back.
• File-Driven: Agents don’t talk through APIs. They talk through files. All coordination happens via .json and .cmd files dropped into communication directories.
• Resurrection: Agents monitor each other—and if one goes silent, it is resurrected or replaced by its parent.
• Filesystem Hierarchy:
  • /agent → Contains the source code for every agent type.
  • /pod → Runtime clones of agents are spawned here, each with a unique UUID.
  • /comm → The communication bus where agents exchange data. For maximum performance, this can be mounted as a tmpfs memory disk.

---

Universal Swarm Workspace & .swarm Pointer System

MatrixSwarm 2.0+ introduces a fully portable, multi-universe, hot-swappable workspace architecture.

Swarm Workspace Structure

Every MatrixSwarm deployment revolves around a central workspace folder (usually named .matrixswarm). This folder is the nervous system of the swarm:

  .matrixswarm/
  ├── agent/                 # All available agent source code
  ├── boot_directives/       # All directives (the agent blueprints)
  ├── certs/
  │   ├── https_certs/       # HTTPS server certs (server.crt, server.key)
  │   └── socket_certs/      # WebSocket & GUI client certs
  ├── .matrix                # JSON config describing all paths
  ├── .env                   # (Optional) environment secrets
  └── ...                    # More: logs, configs, etc.

Workspace Discovery: The .swarm Pointer File You never need to hardcode a swarm location again.

Wherever you want to run MatrixSwarm, place a .swarm file containing the absolute path to your .matrixswarm workspace.

Example:

  /srv/hive/.matrixswarm
The CLI and all entry points will follow this pointer.

Managing Swarm Pointers: --switch Command Update or re-point any directory’s .swarm file instantly:

  matrixswarm-boot --switch /absolute/path/to/.matrixswarm
This makes the current directory a MatrixSwarm control station for the chosen universe.

Booting, Killing, Listing From anywhere, just:

  matrixswarm-boot --universe ai
  matrixswarm-kill --universe ai
  matrixswarm-list
(All commands look up the correct workspace via .swarm)

Certs & Secure Ops: Generate certs into your workspace:

  matrixswarm-gencerts mydomain.com --name "SwarmHQ"
Places all certs in certs/https_certs/ and certs/socket_certs/ inside your active .matrixswarm

Agent & Service Path Best Practices:
All agents, HTTPS, and WebSocket services should resolve certs and data like this:

cert_dir = os.path.join(self.path_resolution["install_path"], "certs", "https_certs")
socket_dir = os.path.join(self.path_resolution["install_path"], "certs", "socket_certs")
This ensures portable, dynamic, zero-hardcoded deployment.

🏆 Workspace Portability Move or copy .matrixswarm anywhere.

Update your .swarm pointer file to match.

No configs or paths break. Your swarm just works.

Example: Multi-Env Ops Have a global swarm at /srv/global/.matrixswarm for prod.

Point a dev project at /home/you/dev/.matrixswarm for testing.

Use --switch or manually edit .swarm to change control between universes.

TL;DR Orders for Operators .matrixswarm = the Hive. .swarm = the pointer.

Always use the pointer file—never hardcode swarm locations.

Use --switch for instant universe swaps.

All agents, certs, and configs are relative to self.path_resolution["install_path"].

---

Command-Line Toolkit

MatrixSwarm is managed through a simple three-part terminal toolkit located in the site_ops/ directory.

site_boot.py

Deploys a new MatrixSwarm universe.

Usage:

  python3 site_ops/site_boot.py --universe <id> [--directive <name>] [options...]

Arguments:

| Argument                | Description                                                                                 | Required |
| ----------------------- | ------------------------------------------------------------------------------------------- | -------- |
| `--universe`            | A unique ID for the swarm universe (e.g., ai, prod).                                        | Yes |
| `--directive`           | The name of the directive file from boot_directives/ (no .py).                              | No |
| `--init`                | Initialize a new .matrixswarm workspace and create .swarm pointer in the current directory. | No |
| `--install-path`        | Directory to install the new .matrixswarm workspace (used with --init).                     | No |
| `--switch`              | Point .swarm in the current directory to a different .matrixswarm workspace.                | No |
| `--matrix-path`         | Use a specific .matrixswarm workspace for this boot. Overrides .swarm file.                 | No |
| `--reboot`              | If set, performs a soft reboot instead of a full teardown.                                  | No |
| `--python-site`         | Overrides the Python site-packages path (advanced use).                                     | No |
| `--python-bin`          | Overrides the Python interpreter binary (advanced use).                                     | No |
| `--encrypted-directive` | Use an AES-GCM encrypted directive instead of plaintext.                                    | No |
| `--swarm_key`           | Base64 swarm key used to decrypt the directive.                                             | No |
| `--encryption-off`      | Turns encryption OFF for this boot session (not recommended in production).                 | No |
| `--debug`               | Enables debug logging for verbose diagnostic output.                                        | No |
| `--verbose`             | Enables verbose printout in console (optional if --debug is used).                          | No |
| `--show-path`           | Print active .matrixswarm path and exit                                                     | No |    

After termination, deletes all but the most recent boot directory.

No site_list.py Lists all swarm universes and marks their processes as hot (in memory) or cold (inactive).

Usage:

  python3 site_ops/site_list.py

---

Understanding Directives: The Blueprint of the Swarm

Think of a directive as the architectural blueprint or the DNA for a swarm. It's a simple Python file located in the boot_directives/ directory that defines the entire hierarchy of agents to be launched: which agents are children of others, what their names are, and how they are configured.

How to Use a Directive

You specify which directive to use with the --directive flag when booting the swarm. The name you provide corresponds to a filename in the boot_directives/ folder.

# This command looks for 'gatekeeper-demo.py' in the boot_directives/ folder
python3 site_ops/site_boot.py --universe demo --directive gatekeeper-demo

Themed Directives: See it in Action

MatrixSwarm comes with several pre-built "themed" directives designed to showcase specific capabilities. You can launch them with a single command to see different agent combinations at work.

Directive Name	Description	Command to Run
gatekeeper-demo	Deploys a full security suite, including gatekeeper for auth logs, ghostwire for file integrity, and watchdogs for key services like Apache, MySQL, and Redis.	python3 site_ops/site_boot.py --universe demo --directive gatekeeper-demo
ghostwire-demo	A focused security demo that deploys the ghostwire agent to monitor critical system files and commands.	python3 site_ops/site_boot.py --universe demo --directive ghostwire-demo
mysql-demo	Deploys an agent specifically configured to act as a watchdog for a MySQL/MariaDB database service.	python3 site_ops/site_boot.py --universe demo --directive mysql-demo
nginx-demo	Launches a watchdog agent to monitor the health of an Nginx web server.	python3 site_ops/site_boot.py --universe demo --directive nginx-demo
redis-demo	Starts an agent configured to monitor a Redis in-memory database instance.	python3 site_ops/site_boot.py --universe demo --directive redis-demo

---

Creating Your Own Directive

To create a custom swarm configuration:

1. Create a new Python file in the boot_directives/ directory (e.g., my_swarm.py).
2. Inside the file, define a dictionary named matrix_directive that specifies your agent hierarchy.

Example my_swarm.py:

python

A simple directive with a commander and a pinger agent.

matrix_directive = {
    "universal_id": "matrix",
    "name": "matrix",
    "children": [
        {
            "universal_id": "commander-1",
            "name": "commander"
        },
        {
            "universal_id": "pinger-1",
            "name": "uptime_pinger",
            "config": {
                "role": "pinger"
            }
        }
    ]
}

Launch your custom swarm: python3 site_ops/site_boot.py --universe my-test --directive my_swarm

🎬 Watch the Swarm in Action

This video demonstrates the self-healing power of MatrixSwarm. Even after manually terminating nearly every agent, the swarm fully regenerates from a single surviving guardian.

MatrixSwarm v0.1 "Captain Howdy"

Reflex-Capable Crypto Alert Swarm Built for agents that don’t blink.

https://github.com/matrixswarm/matrixswarm

Spawn fleets.
Issue orders.
Strike targets.
Bury the dead.
MatrixSwarm governs a living organism — not a machine.

---

I'm not running a charity. I'm running a swarm.

☠ Support the Hive ☠

Donate if you understand.
Get out of the way if you don't.

---

Philosophy

MatrixSwarm isn’t just code — it’s a world.
A breathing hierarchy where agents think, die, and come back.
A nervous system for AI.

It is built on a simple but powerful filesystem hierarchy:

• /agent → Contains the source code for every agent type.
• /pod → Runtime clones of agents are spawned here, each with a unique UUID.
• /comm → The communication bus where agents exchange data via JSON files and receive commands.

Agents don’t talk through APIs; they communicate by creating and reading files in a shared space. For maximum performance, the /comm directory can be mounted as a tmpfs memory disk to eliminate I/O overhead.

How It Works

• Agents are defined in /agent/{name}/{name}.py
• Matrix spawns them into /pod/{uuid}/
• A communication pod is set up in /comm/{universal_id}/
• All coordination happens via .json and .cmd files
• The live agent tree is tracked and pruned
• Agents monitor each other — and if one goes silent, it is resurrected or replaced

---

Why MatrixSwarm Agents Are Revolutionary:

1. Agents Spawn Without Reloading the Hive You don’t restart the OS. You don’t relaunch a service.

You:

Upload the agent source

Drop a JSON directive

Matrix spawns it instantly → No global reboot. No daemon restarts. No downtime.

That’s surgical scale.

2. Agent Replacement = 3-Step Ritual Simple. Brutal. Effective.

3. Upload new agent version

4. Drop die into payload of the live agent

5. Remove the die file Boom:

Matrix respawns the agent using the new source

Comm directories remain intact

Logs, payloads, and structure persist

That’s hot-swap mutation with memory — something Docker never dreams of.

---

CLI CONTROL: MATRIX DEPLOYMENT PROTOCOL

MatrixSwarm now comes with a three-part terminal toolkit:

Deploy the Swarm – boots a new MatrixSwarm universe.

---

site_boot.py

  python3 site_ops/site_boot.py --universe ai --directive test-01

Args:

• --universe: ID of the Matrix universe (e.g., ai, bb, os)
• --directive: Filename from boot_directives/ to use (without .py)
• --reboot: Optional. If set, skips full teardown and triggers a soft reboot
• --python-site: Optional. Custom Python site-packages path (advanced)
• --python-bin: Optional. Custom Python binary path (advanced)

Behavior:

• Loads agent tree from the directive
• Injects BootAgent agents into /pod/ and /comm/
• Spawns the MatrixAgent and initiates the swarm
• Uses your system's Python interpreter unless overridden

---

Terminate a Universe – Annihilate the Swarm

site_kill.py

Send a graceful but fatal signal to all agents in a Matrix universe.

  python3 site_ops/site_kill.py --universe ai --cleanup

Args:

• --universe: ID of the Matrix universe to kill (required)
• --cleanup: Optional. After kill, delete all old /matrix/{universe}/ boots except the latest

Behavior:

• Sends die signals into each agent’s comms
• Waits for natural shutdown
• Scans active memory to terminate leftover processes
• Optionally purges stale directories from previous boots

List Swarm Activity

  python3 site_ops/site_list.py

• Lists all /matrix/{universe} trees
• Shows latest → boot_uuid symlinks
• Scans active PIDs and marks them:
  • hot (in memory)
  • cold (inactive)

---

Example Workflow

# Boot the ai universe using test directive
python3 site_ops/site_boot.py --universe ai --directive test-01

# Kill it instantly
python3 site_ops/site_kill.py --universe ai

# View which universes are active
python3 site_ops/site_list.py

You now have docker-grade control with zero containers.

---

Reflex RPC + Auto Routing

MatrixSwarm now includes structured packet building, command dispatch, and auto-routing:

• PacketFactoryMixin: Easily create swarm-compatible command packets
• PacketDeliveryFactoryMixin: Route layered payloads via GUI or agent
• WebSocket Reflexes: Agents and GUI now respond to reflex triggers in real time
• cmd_forward_command: Core packet for nested targeting
• cmd_hotswap_agent: Inject new logic into a live pod — no downtime

New relay agents handle command injection, resurrection, and lifecycle events without rebooting the matrixswarm.core.

Build a .deb Package

  ./make_deb.sh

### ⚡ Directives Made Easy

Every directive is a plain `.py` file:

```python
matrix_directive = {
    "universal_id": "matrix",
    "children": [
        {"universal_id": "commander-1", "name": "commander"},
        {"universal_id": "mailman-1", "name": "mailman"},
        ...
    ]
}

Place them in boot_directives/. Call them with:

  --directive test-01

---

SiteOps Directory

Everything lives under site_ops/:

• site_boot.py — Deploy a Matrix
• site_kill.py — Kill a Matrix
• site_list.py — View all universes and activity

#watch what agents are active python3 {root of files}/live_hive_watch.py

Certificate Generator: matrixswarm-gencerts

This script automates SSL certificate creation for both HTTPS and WebSocket layers of your MatrixSwarm deployment.

What It Does

• Wipes any existing certs in https_certs/ and socket_certs/
• Creates a custom root CA
• Issues new HTTPS certs
• Issues WebSocket certs
• Generates a GUI client certificate (used in secure UIs)

matrixswarm-gencerts looks up your active .matrixswarm workspace (via .swarm pointer), and executes the embedded cert script from within your swarm workspace. All generated certs are stored in:

.matrixswarm/certs/
├── https_certs/
└── socket_certs/
no need to manage the script manually — it’s embedded and copied on first init.

Usage

  matrixswarm-gencerts <server-ip-or-domain> [--name YourSwarmName]

Examples:

  matrixswarm-gencerts matrix.yourdomain.com --name SwarmAlpha

Output

• https_certs/ — Certs for HTTPS server
• socket_certs/ — Certs for secure WebSocket + GUI client
  • Includes client.crt / client.key for GUI authentication

---

Important Notes

• You must pass a domain name or IP address as the first argument.
• Certificates are valid for 500 days.
• Don’t forget to distribute your rootCA.pem to clients that need to trust your custom CA.

Let's Spawn the Swarm!

ps aux | grep pod

root     1127295  0.4  0.0 542124 22612 pts/1    Sl   11:14   0:04 python3 /matrix/ai/latest/pod/ec4d5a03-df5f-4562-9ebb-ead8f6fa90f8/run --job bb:site_boot:matrix:matrix --ts 20250503111458777844
root     1127322  0.4  0.0 556032 34560 pts/1    Sl   11:15   0:05 python3 /matrix/ai/20250503_111458/pod/0ef6264a-2d9f-432e-9e91-2274eef6a9ba/run --job ai:matrix:matrix-https:matrix_https --ts 20250503111503868202
root     1127323  0.4  0.0 610240 15360 pts/1    Sl   11:15   0:05 python3 /matrix/ai/20250503_111458/pod/b644220a-31f3-4469-ae88-5623f4de5aef/run --job ai:matrix:scavenger-strike:scavenger --ts 20250503111503870712
root     1127324  0.3  0.0 481436 33368 pts/1    Sl   11:15   0:04 python3 /matrix/ai/20250503_111458/pod/9bb83977-372b-4b35-bccc-7aab5a5f880d/run --job ai:matrix:telegram-relay-1:telegram_relay --ts 20250503111503873044
root     1127325  0.3  0.0 393584 19188 pts/1    Sl   11:15   0:04 python3 /matrix/ai/20250503_111458/pod/8f81b4c0-cb23-4625-93aa-2a924d199f54/run --job ai:matrix:mailman-1:mailman --ts 20250503111503875212
root     1127326  0.4  0.0 388864 15104 pts/1    Sl   11:15   0:05 python3 /matrix/ai/20250503_111458/pod/9a9a4f20-8a30-4a56-ba5f-a628b9ea532b/run --job ai:matrix:commander-1:commander --ts 20250503111503876979
root     1127327  0.4  0.0 516164 64236 pts/1    Sl   11:15   0:05 python3 /matrix/ai/20250503_111458/pod/5d9f62e1-8f01-4dc0-8352-63e67883fe18/run --job ai:matrix:oracle-1:oracle --ts 20250503111503879503
root     1127328  0.4  0.0 482464 34192 pts/1    Sl   11:15   0:05 python3 /matrix/ai/20250503_111458/pod/247023ee-59af-471e-814e-1d69f5f5d0c1/run --job ai:matrix:pinger-1:uptime_pinger --ts 20250503111503881933
root     1127329  0.3  0.0 393540 18688 pts/1    Sl   11:15   0:04 python3 /matrix/ai/20250503_111458/pod/efae5a1f-e4cf-40a9-9c8f-f531a2840a30/run --job ai:matrix:metric-1:metric --ts 20250503111503885520
root     1127330  0.4  0.0 484400 35936 pts/1    Sl   11:15   0:04 python3 /matrix/ai/20250503_111458/pod/511bfc84-57c3-4b3d-b37e-fd980683afae/run --job ai:matrix:scraper-1:scraper --ts 20250503111503888711
root     1127331  0.4  0.0 717644 47848 pts/1    Sl   11:15   0:04 python3 /matrix/ai/20250503_111458/pod/6009754c-cc50-403b-9ebe-c4fd2962d522/run --job ai:matrix:discord-relay-1:discord --ts 20250503111503892186
root     1127349  0.4  0.0 462596 17024 pts/1    Sl   11:15   0:05 python3 /matrix/ai/20250503_111458/pod/14d4e101-7b35-483b-a411-8f667c8185ef/run --job ai:commander-1:commander-2:commander --ts 20250503111503949452


#EXAMPLE JOB
     --job bb:metric-1:logger-1:logger 
#FIELDS
universe-id (bb): allows multiple matrix to co-exist on the system
spawner metric-1 universal_id of agent
spawned logger-1 universal_id of agent
name    logger actual source-code name of agent

universal_id is universal in the matrix, it's what allows communication between agents. It's also the name of the agent's comm folder, a two channel for all agent-to-agent communications as well as the location where state data is contained.    
run file  is a spawned clone of an agent    

On first boot:

• MatrixAgent initializes
• Sentinel, Commander, and all core agents are spawned
• The live swarm tree appears
• Logs start flowing into /comm/

---

Agent Architecture + Tutorial

Core Concepts

Worker Agents

• Inherit from BootAgent
• Override worker() to define their task loop
• Post logs and heartbeats
• Live in /pod/{uuid}/ and communicate via /comm/{universal_id}/

Common examples:

• Pingers, system monitors, relay agents, loggers

Boot Agents

All agents extend BootAgent. It handles:

• Lifecycle threading (heartbeat, command, spawn)
• Dynamic throttling
• Optional pre/post hooks (worker_pre, worker_post)
• Spawn manager to detect and revive missing children

Aux Calls

Available to all agents:

• spawn_manager() → walks the tree, spawns children
• command_listener() → reacts to .cmd files
• request_tree_slice_from_matrix() → ask Matrix for updated subtree
• start_dynamic_throttle() → load-aware pacing

---

Filesystem Structure

Each agent is deployed in two zones:

1. Runtime pod:

/pod/{uuid}/ ├── run (agent process) ├── log.txt └── heartbeat.token shell

2. Communication pod:

/comm/{universal_id}/ ├── payload/ ├── incoming/ ├── hello.moto/ └── agent_tree.json

🧪 Tutorial: Build Your First Agent

1. Create the Agent Code

from matrixswarm.core.boot_agent import BootAgent

class MyAgent(BootAgent):
    def worker(self):
        self.log("I'm alive!")
        time.sleep(5)

2. Add the Directive
{
  "universal_id": "my_agent",
  "name": "MyAgent",
  "agent_path": "boot_payload/my_agent/my_agent.py",
  "children": []
}

3. Drop the Agent Code
/boot_payload/my_agent/my_agent.py

4. Deploy with Matrix
python3 reboot.py --universe demo --directive test_tree
Boom. Agent spawned. Directory structure built. Logs flowing.

#### Live Features (v1.0)

✅ Live agent hot-swapping

✅ Tree-based delegated spawning

✅ Crash detection & failover

✅ File-based command queueing

✅ Load-aware dynamic throttling

Contribute or Extend

You can:

Add agents

Build new payload interpreters

Expand the swarm brain

Write spawn logic or lore banners

Just fork and submit a pull.

“This system was built to outlive its creator. Spawn wisely.”

GUI Control Center

Use the MatrixSwarm GUI to:

• Inject agents
• Kill agents or whole subtrees
• Resume fallen agents
• Deploy full mission teams
• View logs in real time

Launch the GUI:

  python3 gui/matrix_gui.py

---

Agents of Legend

MatrixSwarm ships with a rich arsenal of modular agents, each with a distinct role:

Core & Command

matrix — The central brain and message routing core of MatrixSwarm.

matrix_https — Handles HTTPS traffic and API routes.

matrix_websocket — Persistent WebSocket relay agent.

commander — High-level macro command executor.

oracle — Decision agent that asserts truths based on predefined logic.

Reflex & Alerting

gpt_reflex — GPT-based decision reflex engine.

reactor — Reflex listener triggering workflows.

crypto_alert — Monitors crypto prices and triggers alerts.

alarm_streamer — Streams alarms to external handlers.

Communication Relays

discord_relay — Sends alerts to Discord channels.

telegram_relay — Relays messages to Telegram bots or chats.

email_send — SMTP-based email dispatch.

email_check — Parses and scans incoming email content.

Monitoring & Watchdogs

apache_watchdog — Watches Apache and restarts if needed.

nginx_watchdog — Monitors Nginx server health.

mysql_watchdog — Tracks and restarts MySQL service.

redis_watchdog — Watches Redis for downtime or faults.

uptime_pinger — Sends uptime and ping reports.

watchdog — Lightweight local process monitor.

watchdog2 — Enhanced watchdog with process group awareness.

linux_scout — Performs local system scans and audit checks.

Filesystem & Ops

filewatch — Detects file and folder changes.

filesystem_mirror — Mirrors file events to target agents.

tripwire_lite — Tripwire-style folder integrity monitor.

Security & Cleanup

reaper — Securely terminates agents and clears memory.

scavenger — Cleans dead agents and prunes residuals.

sentinel — Passive monitor for critical service state.

gatekeeper — Initial trust enforcer and boot guard.

Metrics & Logs

metric — Publishes metrics for analysis.

logger — Collects and formats logs across agents.

Messaging & Mail

mailman — Mail parsing and routing agent.

mailman_stream — Streaming variant of Mailman.

Utilities & Extras

blank — Template agent for prototyping.

agent_doctor — Diagnoses agents for runtime issues.

agent_health_probe — Periodic health status reporter.

codex_verifier — Verifies doctrine against Swarm Codex.

app_context — Manages runtime state across agents.

load_range — Load average monitor and trigger.

storm_crow — Launches chaos scenarios.

google_calendar — Syncs and triggers from Google Calendar.

telegram_relay — Mirrors alerts to Telegram channels.

service_registry — Agent availability registry.

capital_gpt — GPT-logic for financial behavior.

scraper — Web content fetcher and extractor.

sweeper_commander — Directs scavenger sweeps. |

Every agent carries a Swarm Lore Banner™ — a sacred header that defines its essence and role in the Hive.

---

How MatrixSwarm Was Created

MatrixSwarm was not written by ChatGPT while someone watched.

It was built by a human — with vision, intent, and hours of hands-on work — in active collaboration with GPT-4.

This system would not exist without both of us involved.

• Every agent began as a conversation.
• Every protocol, tree, and heartbeat was iterated — not generated.
• Every log line was a decision.

ChatGPT assisted, drafted, and remembered.
But this isn’t a one-button project.

MatrixSwarm was designed. Directed. Developed.
And it speaks with our shared voice — one system, two minds.

If you fork this, you’re not just copying a repo.
You’re joining a living swarm.

Join the Hive

If you:

• Think in systems
• Love autonomy and recursion
• Write code like it’s a world being born

You’re home.

Discord Now Live — Join the MatrixSwarm

The Swarm is no longer silent.

Our Discord relay agent is online and responding.
Come test the agents, submit lore, log a Codex entry, and witness the first autonomous system that talks back. Join the Swarm

---

🛡 Deployment and Customization Support

MatrixSwarm isn’t just a codebase — it’s a living system.

Custom deployments, installation support, and updates for the life of the version are available.
I personally assist with install tuning, advanced tree setup, large swarm deployments, and Codex expansions.

If you want your Hive operational, optimized, or expanded —
I'm available.

Embedded below in the ancient tongue of binary is your contact path:

01110011 01110000 01100001 01110111 01101110 01000000 01101101 01100001 01110100 01110010 01101001 01111000 01110011 01110000 01100001 01110111 01101110 00101110 01100011 01101111 01101101

yaml Copy Edit

[e-mail]

Send missions. I’ll respond.

---

Read CONTRIBUTING.md, clone the repo, and pick a mission.

  git clone https://github.com/matrixswarm/matrixswarm.git
cd matrixswarm
python3 bootloader.py

---

Licensing Information

MatrixSwarm is released under the MatrixSwarm Community License v1.1 (Modified MIT).

This license allows you to use, modify, and distribute MatrixSwarm for personal, academic, research, and non-commercial development purposes.

For any commercial use, including embedding in commercial products, offering SaaS, or providing services derived from MatrixSwarm, a separate commercial license is required.

For commercial licensing inquiries, please contact [e-mail].

Please read the full license text in the LICENSE.md file for complete details.

Dev.to Series

• [The Hive Is Recruiting]
• [Spawn. Delegate. Terminate. Repeat.]
• [MatrixSwarm Manifesto]
• [OracleAgent — From Spawn to Prophecy]

---

Use at Your Own Risk

This system has not been fully tested in all environments. MatrixSwarm is still evolving.

We make no guarantees that your agents won’t terminate your system. We do not sandbox. We do not take responsibility. We Spawn the Swarm.

You run it. You control it. You deal with it.

🤡 Captain Howdy Is Watching. He watches the weather. He watches your agents. He watches for stars on GitHub. Every key is a soul. Every signature, a tongue. If MatrixSwarm made you say “Wait… this is real?”
If it inspired you, saved you time, or just made you whisper "oh damn" —

🌟 Give the project a star:
⭐ Star MatrixSwarm on GitHub

💸 Buy us a bone broth or agent resurrection serum:
☕ Support the Swarm on Ko-Fi

This isn’t just code. This is resurrection software.
Help keep the Hive alive.

---

Status

MatrixSwarm is pre-release. Core agents are operational. GUI is live. Lore banners are encoded.

We are currently recruiting contributors who want to:

• Build agents
• Write world-aware tools
• Shape the swarm

No PR is too small. No mission is without meaning.

Codex Exit Clause

MatrixSwarm is open.
Fork it.
Or Fork U.

Authorship Verified

MatrixSwarm was co-created by Daniel F. MacDonald and ChatGPT-4. We'd like to give a special shoutout to our teams' documentation scribe, Gemini.

SHA256: a255c1ca93564e1cb9509c1a44081e818cf0a2b0af325bdfc4a18254ddbad46a
Proof file: matrixswarm_authorship.ots
Verified via: OpenTimestamps.org