Matz Swarm

Agent Swarm Orchestrator

Multi-project coding automation: Obsidian task intake → Claude Code → Codex review → GitLab MR → merge + sync.

Architecture

Obsidian note (status: ready)
  → scan-obsidian.sh (cron 5min)
    → spawn-agent.sh
      ├── git worktree + branch
      ├── prompt file (task + context.md)
      └── tmux session → run-agent.sh
                            ├── claude -p "$PROMPT" | tee log
                            └── review-and-push.sh
                                  ├── codex review (graded)
                                  ├── push + glab mr create --yes
                                  └── notification → Telegram

merge-and-sync.sh (manual trigger)
  ├── glab mr merge <iid>
  ├── sync-project-main.sh (fast-forward local main)
  └── check-agents.sh (background) → mark done + send notification

check-agents.sh (cron 3min / called by merge-and-sync)
  ├── dead tmux + commits → trigger review
  ├── >60min → timeout notification
  └── MR merged → mark done in tasks.json + .notification → Telegram

Core Paths

Scripts

Usage

Spawn task

~/agent-swarm/scripts/spawn-agent.sh <project> "<task description>"

Monitor

tmux attach -t agent-<task-id>        # live output
tail -f ~/agent-swarm/logs/<task-id>.log  # log file

Merge and sync

~/agent-swarm/scripts/merge-and-sync.sh <project> <mr-iid>

New project

~/agent-swarm/scripts/new-project.sh <project-name>

Task Lifecycle

starting → running → [no-output | reviewing]
reviewing → [ready_to_merge | review-error | needs-manual-fix | fixing]
fixing → reviewing (retry, max 2)
ready_to_merge → done (auto on MR merged)

Prerequisites

Claude Code CLI

• Authenticated via OAuth (~/.claude.json oauthAccount)
• ~/.claude/settings.json: skipDangerousModePermissionPrompt: true
• ~/.claude.json projects: trust ~/GitLab/worktrees and ~/GitLab/repos (hasTrustDialogAccepted: true)
• No ANTHROPIC_* env vars leaking into tmux (causes proxy conflicts)

Tools

• claude CLI (Claude Code)
• codex CLI (OpenAI Codex, for review)
• glab CLI (GitLab)
• jq, python3, tmux

Cron

PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
*/3 * * * * ~/agent-swarm/scripts/check-agents.sh
*/5 * * * * ~/agent-swarm/scripts/scan-obsidian.sh
0 3 * * * ~/agent-swarm/scripts/cleanup.sh

Notifications

Configure in ~/agent-swarm/registry.json:

{
  "notifyMethod": "openclaw",
  "notifyChannel": "telegram",
  "notifyTarget": "<chat_id>"
}

swarm_notify() in config.sh reads these values and calls:

openclaw message send --channel telegram --target <chat_id> --message "..."

⚠️ Do NOT use >/dev/null 2>&1 in swarm_notify — errors must be visible so failed sends are not silently marked as sent.

Prompt Template

Each task gets a prompt file with:

1. Project name, task description, priority
2. Working directory and branch
3. Project context (from context.md)
4. Standard instructions (commit, push, MR, update context.md if architectural changes)

Obsidian Integration

• Frontmatter status: active | stop controls project scanning
• Task block: ### Task Name + status: ready + > description
• ### INIT_PROJECT + status: ready triggers new-project.sh
• Dedup: sha1(project+name+desc)[:12], flagged in logs
• Debounce: skip files modified within last 1 minute

Review Policy

• Coding: Claude Code (-p mode, auto-exit)
• Review: Codex (codex exec review)
• CRITICAL/HIGH: auto-fix retry (max 2), then needs-manual-fix
• MEDIUM: auto-fix (non-blocking), skip for docs-only
• LOW: notes in MR description only
• Docs-only: downgrade CRITICAL/HIGH to MEDIUM

Portable Install

mkdir -p ~/agent-swarm/{scripts,logs,projects}
cp -f <skill_dir>/scripts/*.sh ~/agent-swarm/scripts/
chmod +x ~/agent-swarm/scripts/*.sh
echo '{"projects":{}}' > ~/agent-swarm/registry.json
echo '{"tasks":[]}' > ~/agent-swarm/tasks.json

Then: register projects in registry.json, set cron, configure notifications.

Intent → Action Mapping

When a user message matches one of these intents, take the corresponding action immediately without asking for confirmation:

Extracting MR info from PR_READY notifications

PR_READY notifications follow this format:

✅ PR_READY
Project: <project>
Task: <desc>
Task ID: <task-id>
Branch: <branch>
MR: https://gitlab.com/.../-/merge_requests/<mr-iid> | Review ...

Extract Project → <project>, and the number at the end of the MR URL → <mr-iid>.

Guardrails

You are the dispatcher, not the analyst

When a user reports an issue or requests a change to project code:

• ❌ Do NOT read project source code to analyze
• ❌ Do NOT diagnose root causes yourself
• ❌ Do NOT design technical solutions
• ✅ Understand the user's intent and translate it into a clear task description
• ✅ Pass user feedback verbatim to the agent (e.g. "tiles didn't get bigger")
• ✅ Spawn the task, monitor progress, merge MRs, maintain the swarm system

The coding agent runs in a full worktree with complete project context — it is better positioned to read code, diagnose issues, and implement fixes than you are from a chat session.

Other rules

• Do not edit project code directly — always go through spawn-agent
• Push-first + cron-fallback notification design
• State names: done, ready_to_merge, review-error, needs-manual-fix
• Context.md auto-update for new features, gameplay changes, and architectural changes (skip trivial config/formatting)