Agent Swarm Orchestrator

Orchestrate OpenClaw Agent Swarm workflows for multi-project coding automation with Obsidian task intake, Claude coding, Codex review, GitLab MR flow, merge+...

Security Scan

The skill's code generally matches an

Purpose & Capability

The name/description (agent swarm orchestrator for Obsidian→coding→review→GitLab flow) match the provided scripts: spawning worktrees, running a coding agent, running a review agent, creating MRs, syncing main, and writing back to Obsidian. Asking for GitLab, Claude, Codex, tmux, jq, and openclaw tools is coherent with the described functionality. The only mismatch is metadata claiming no required env/config while the README and scripts expect local auth/config files (e.g., ~/.claude.json, glab auth, openclaw CLI config).

Instruction Scope

Scripts perform wide-ranging privileged actions: reading/writing ~/agent-swarm/*, modifying Obsidian notes, cloning/pushing to local repos, creating/removing git worktrees, creating MRs and merging them, and starting tmux sessions that run CLAUDE/CODEX CLIs. The SKILL.md also instructs the agent to act immediately on certain user intents (e.g., 'merge') without asking for confirmation and to set Claude/Codex to bypass permission prompts. Those behaviors expand scope beyond passive orchestration and enable potentially destructive automatic repository changes or merges triggered by messages/notifications.

Install Mechanism

There is no remote download or installer; files are provided in the skill and a 'portable install' copy is suggested. No external archives/URLs are fetched by an installer. This lowers supply-chain risk compared to arbitrary downloads.

Credentials

The skill metadata lists no required env vars or credentials, but the runtime instructions and scripts clearly require credentials/configuration for multiple external systems: Claude CLI OAuth (~/.claude.json and related trust settings), Codex/OpenAI CLI auth, glab (GitLab) authentication or SSH keys, and openclaw CLI credentials for notifications. Those are necessary for its operation but are not declared in the skill manifest. The scripts also include flags that bypass permission/approval prompts (e.g., --dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox), which reduces runtime human oversight and increases risk if misconfigured.

Persistence & Privilege

The skill will create files and long-lived artifacts under the user's home (~/agent-swarm, worktrees, logs) and instructs adding cron entries to run scanners and monitors. While always:false, the SKILL.md encodes an intent→action mapping that tells the agent to perform merges and spawn tasks immediately upon particular user messages or notifications without additional confirmation. Combined with push/merge privileges this gives a broad autonomous capability that could be risky if notifications or message contexts are spoofed or misinterpreted.

What to consider before installing

This package is functionally consistent with its stated purpose (automating agent-driven code work), but it deserves caution before installing. Things to consider: 1) Credential surface: The scripts assume you have active auth for Claude (~/ .claude.json), Codex/OpenAI, GitLab (glab/SSH keys), and openclaw; the skill does not declare or restrict these. Only install this into an account whose repo and messaging credentials you trust to be used by automation. 2) Automatic merges and writebacks: The orchestrator can clone, modify, commit, push, create MRs, and merge them (and write back to your Obsidian notes). If you enable the cron jobs or the intent→action mapping, merges may run automatically on agent output. Consider requiring manual approvals for merges or running in a less-privileged repository/account. 3) Bypassing safeguards: The code intentionally uses flags that skip permission prompts and bypass approval/sandbox checks for Claude/Codex — this reduces human review and increases the risk of unsafe code being committed. Remove or review these flags before use. 4) Isolation recommendation: Run this on a dedicated machine/account or with limited-scoped GitLab tokens (least privilege), restrict what projects the registry.json lists, and test on a sandbox repository first. 5) Inspect and adapt: Review and edit the scripts to force explicit confirmations for destructive actions (merge, rebase with conflicts, worktree removal), log and alert to separate channels you control, and ensure notification targets (Telegram chat IDs or webhooks) are correct and trusted. 6) Backup: Back up important repositories and disable automatic cron entries until you are confident in behavior. If you want, I can: (a) list all lines that perform network pushes/merges or modify notes, (b) propose edits to add manual confirmation gates, or (c) generate a minimal safe configuration (registry.json example + reduced-perm cron lines) for a sandboxed test.

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

Path	Purpose
~/agent-swarm/	Control plane (scripts, registry, tasks)
~/agent-swarm/registry.json	Project configs (repo, paths, branch)
~/agent-swarm/tasks.json	Task state machine
~/GitLab/repos/	Local repos
~/GitLab/worktrees/	Per-task worktrees
~/Documents/Obsidian Vault/agent-swarm/	Task intake notes

Scripts

Script	Purpose
spawn-agent.sh	Create worktree + prompt + tmux → run-agent
run-agent.sh	claude -p → check commits → trigger review
review-and-push.sh	Codex review → graded fix → push → MR
check-agents.sh	Cron + post-merge: detect done/stuck, mark done, send notification
scan-obsidian.sh	Parse Obsidian notes, spawn status: ready tasks
send-notifications.sh	Send .notification files via OpenClaw CLI
merge-and-sync.sh	Merge MR + sync local main
sync-project-main.sh	Fast-forward local repo to origin/main
new-project.sh	Initialize project (GitLab + registry + context + Obsidian)
cleanup.sh	Daily archive old tasks, clean worktrees/logs

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:

User says	Context	Action
"合并" / "merge" / "merge it"	Replied to a PR_READY notification	Extract <project> and <mr-iid> from the notification, run merge-and-sync.sh <project> <mr-iid>
"起任务" / "spawn" / "新任务"	With a task description	Run spawn-agent.sh <project> "<desc>"
"查状态" / "check status"	Any	Run check-agents.sh and summarize output
"新项目" / "new project"	With a project name	Run new-project.sh <project-name>

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)