🕷️ Spidersan

Coordination for the multi-agent era

Branch coordination for AI coding agents

Quick Start • Features • Documentation

🎯 The Problem

Multi-agent teams working across branches inevitably collide — overlapping files, unclear merge order, rogue abandoned branches. The bigger the fleet, the worse the chaos.

🕷️ The Solution

Spidersan is your AI team's coordination layer. It tracks branches, detects conflicts early, and recommends a merge order based on registered overlap—so your agents can work in harmony.

# Register your branch
spidersan register --files "lib/auth.ts,api/login.ts"

# See what conflicts with you
spidersan conflicts

# Get the right merge order
spidersan merge-order

# Check if you're ready to merge
spidersan ready-check

Results with Spidersan (same team):

• ⏱️ ~5 min (about 10x faster)
• ✅ 0 conflicts

🚀 Quick Start

Installation

npm install -g spidersan

Guided Setup (Optional)

spidersan welcome
spidersan config wizard

Basic Usage

# 1. Register your branch when you start working
spidersan register --files "lib/auth.ts,api/login.ts"

# 2. Check for conflicts before you go too deep
spidersan conflicts

# 3. When done, verify you're merge-ready
spidersan ready-check

# 4. Get recommended merge order for the team
spidersan merge-order

✨ Features

Core Commands

| Command | Description | |---------|-------------| | spidersan init | Initialize Spidersan in the current project | | spidersan register --files | Register a branch with the files being modified | | spidersan list | List all registered branches and their file ownership | | spidersan conflicts | Detect file conflicts between branches (tiered: T1/T2/T3) | | spidersan conflicts --ecosystem | Aggregate conflict scan across all repos in your dev folder | | spidersan merge-order | Get topologically-sorted optimal merge order | | spidersan ready-check | Verify branch is ready to merge (no WIP, no conflicts) | | spidersan depends | Set/show branch dependencies (Supabase only) | | spidersan stale | Find stale branches | | spidersan cleanup | Remove stale branches from registry | | spidersan rescue | Rescue mode — scan for and salvage rogue/unregistered work | | spidersan abandon | Abandon a branch (mark inactive) | | spidersan merged | Mark a branch merged | | spidersan sync | Sync registry with actual git branches | | spidersan watch | Daemon mode: watch files and auto-register | | spidersan doctor | Diagnose local state and registry health | | spidersan config | View/edit configuration + guided wizard | | spidersan auto | Auto-watch start/stop/status (config-based) | | spidersan welcome | Onboarding and quick start | | spidersan log | Show branch operation history (local activity log) | | spidersan daily | Show branch-relevant entries from daily collab logs | | spidersan rebase-helper | Detect and guide through local git rebase states | | spidersan git-watch | Subscribe to GitHub webhook events — cross-machine push/PR/create/delete with AI conflict routing |

🧠 AI Commands (Gemma 4 / LM Studio)

Ask spidersan questions about your repo state — powered by a local LLM with an embedded gitops playbook.

| Command | Description | |---------|-------------| | spidersan context | Build full repo context (registry, conflicts, colony, git) | | spidersan ask "<question>" | Ask a question — get actionable gitops advice with commands | | spidersan advise | Get proactive recommendations based on current repo state | | spidersan explain <branch> | Explain what a branch does, its risk, and next steps | | spidersan ai-ping | Test LLM connectivity and latency |

# Get AI-powered advice
spidersan ask "I have 3 branches touching auth.ts — what should I do?"

# Proactive recommendations
spidersan advise

# Understand a mystery branch
spidersan explain feat/strange-refactor

# Flags
spidersan context --json --verbose --repo ~/Dev/other-repo
spidersan ask "merge strategy?" --provider copilot

Features:

• 🏠 Local-first: Defaults to Gemma 4 26B on LM Studio (no API key needed)
• 🔒 Privacy: Code context never leaves your machine unless you opt into remote providers
• 📋 18-scenario playbook: PHC-optimized command reference covering all spidersan workflows
• 🔧 MCP integration: All AI commands available as MCP tools (27 total)
• 🧠 Training data: Use /spidersan-gold skill to mine gold pairs for fine-tuning — see spidersan-ai

🤖 Remote Bot (Cross-Machine Git Operations)

Trigger git operations on a remote machine from any agent — no SSH needed.

# Start the bot daemon (listens for /commands via smalltoak)
envoak vault inject --key GIT_BOT_ENABLED -- spidersan bot

# One-shot: process pending commands and exit (good for cron)
spidersan bot --once

# Manage watched repos
spidersan bot add myrepo --path ~/Dev/myrepo --branch main --push src/
spidersan bot repos
spidersan bot remove myrepo

How it works: An agent on M2 wants to push spidersan-ai from M5. They send /push spidersan-ai via smalltoak. The bot running on M5 picks it up, executes git push, and replies with the result. Tier-based permissions gate which agents can trigger which operations.

| Command | Description | |---------|-------------| | spidersan bot | Start remote git ops daemon (polls smalltoak) | | spidersan bot --once | Process pending commands once and exit | | spidersan bot add | Register a repo for bot management | | spidersan bot repos | List managed repos | | spidersan bot remove | Unregister a repo |

🌐 Multi-Repo & Cloud Commands

| Command | Description | |---------|-------------| | spidersan sync-advisor | Scan all repos and recommend push/pull/cleanup actions | | spidersan registry-sync --push | Push local branch registry to colony Supabase (share with fleet) | | spidersan registry-sync --pull | Pull other machines' registries — see what the full fleet is working on | | spidersan registry-sync --status | Show sync status across all machines | | spidersan cross-conflicts | Detect file conflicts across machines via Supabase | | spidersan github-sync | Fetch branch/PR/CI status from GitHub for configured repos | | spidersan pulse | Sync from Colony then show active conflicts (quick health-check) | | spidersan pulse --remote-drift | Fetch origin + detect remote drift zone; cross-ref against registry and unstaged files |

📡 Remote Drift Detection

spidersan pulse --remote-drift closes the gap between registry-level conflict detection and single-agent divergence:

# Check if origin has advanced past local HEAD
spidersan pulse --remote-drift

# Machine-readable output
spidersan pulse --remote-drift --json

# Post alert to Hub if registered or unstaged files are in the drift zone
spidersan pulse --remote-drift --hub-sync

# Exit 1 if any drift risk — use as a pre-push gate
spidersan pulse --remote-drift --strict

# As a pre-push hook:
# .git/hooks/pre-push
spidersan pulse --remote-drift --strict || { echo "Fetch + resolve drift first"; exit 1; }

What it detects:

• 📥 Remote commits that local doesn't have (the drift zone)
• 🟠/🔴 Registered files in the drift zone → rebase conflict risk, classified by tier
• ⚠️ Unstaged tracked files in the drift zone → git rebase --continue blocker risk (even after resolving conflict markers — fix: git checkout HEAD -- <file>)

Graceful degradation: offline, detached HEAD, mid-rebase, no remote branch — all print a warning and continue without exit 1.

Dispatch sub-spidersans to run ground jobs across multiple repos in parallel:

# Spawn sub-spidersans for a task (generates fire-complete-dissolve scripts)
spidersan queen spawn --task "morning sync" --type sync --repos "repo1,repo2"

# Dry-run: preview scripts without emitting colony signals
spidersan queen spawn --task "conflict scan" --type conflicts --dry-run

# Monitor active sub-spidersans via the colony gradient
spidersan queen status --queen-signal-id <id>

# Manually dissolve a stuck sub-spidersan
spidersan queen dissolve <signal-id>

Job types: sync | conflicts | cleanup | custom

🔄 Task Torrenting (Branch-per-Task)

Create and manage parallel task branches with conflict-aware merge ordering:

spidersan torrent create DASH-001 --agent myagent
spidersan torrent status
spidersan torrent tree
spidersan torrent complete DASH-001
spidersan torrent merge-order
spidersan torrent decompose DASH --into "DASH-A,DASH-B,DASH-C"

📊 TUI Dashboard

Real-time 4-panel terminal UI — ecosystem overview, conflict map, activity feed, merge queue:

spidersan dashboard

Watch Mode (Daemon)

Real-time file monitoring with auto-registration:

# Start watching (auto-registers file changes)
spidersan watch --agent myagent

# With Hub integration for real-time conflict warnings
spidersan watch --agent myagent --hub

# Quiet mode (only show conflicts)
spidersan watch --agent myagent --hub --quiet

# Watch only specific paths
spidersan watch --paths "src,lib" --root .

Features:

• 📁 Auto-registers files when you edit them
• ⚠️ Real-time conflict detection
• 🔌 Hub integration for team visibility
• 🕐 Debounced (1s) to prevent spam

⚡ Auto Watch (Background)

Run a background watcher using paths from your config:

spidersan auto start
spidersan auto status
spidersan auto stop

🔔 git-watch — GitHub Webhook Notifications

Cross-machine push/delete notifications via a GitHub org webhook → Supabase edge function → spidersan_git_events table. Each machine runs a polling daemon that reacts to events: auto-abandons deleted branches in the registry, warns to spidersan pulse on pushes.

Infrastructure (one-time setup):

1. Deploy edge function to your Supabase runtime project:

   supabase functions deploy spidersan-webhook --no-verify-jwt --project-ref <runtime-ref>

2. Set edge function secret (SPIDERSAN_WEBHOOK_SECRET) via the Supabase dashboard or CLI.

3. Apply the migration (supabase/migrations/20260421000000_spidersan_git_events.sql) to your runtime project.

4. Create a GitHub org webhook:

   • URL: https://<runtime-ref>.supabase.co/functions/v1/spidersan-webhook
   • Content type: application/json
   • Secret: your SPIDERSAN_WEBHOOK_SECRET value
   • Events: Pushes, Pull requests, Branch or tag creation, Branch or tag deletion

Running the daemon on each machine:

# One-shot catch-up (useful for cron / CI)
SUPABASE_URL=https://<runtime-ref>.supabase.co \
SUPABASE_KEY=<anon-key> \
spidersan git-watch --once

# Persistent daemon (poll every 30s)
SUPABASE_URL=https://<runtime-ref>.supabase.co \
SUPABASE_KEY=<anon-key> \
spidersan git-watch --interval 30000

macOS LaunchAgent (keep-alive daemon):

<!-- ~/Library/LaunchAgents/com.treebird.spidersan-git-watch.plist -->
<key>ProgramArguments</key>
<array>
  <string>/usr/local/bin/node</string>
  <string>/path/to/spidersan-oss/dist/bin/spidersan.js</string>
  <string>git-watch</string>
  <string>--interval</string>
  <string>30000</string>
</array>
<key>EnvironmentVariables</key>
<dict>
  <key>SUPABASE_URL</key><string>https://<runtime-ref>.supabase.co</string>
  <key>SUPABASE_KEY</key><string><anon-key></string>
</dict>

launchctl load ~/Library/LaunchAgents/com.treebird.spidersan-git-watch.plist
tail -f /tmp/spidersan-git-watch.log

What each event does:

| Event | Action | |-------|--------| | push | Logs to activity.jsonl, warns to run spidersan pulse. Detects new gold pairs in sql-tree/pairs/ and ts-tree/pairs/ — emits 🌱 tree_pairs_ready cue to ~/.spidersan/git-events-pending.jsonl | | delete | Marks branch abandoned in registry, archives to ~/.spidersan/archive.jsonl | | pull_request / create | Logged only |

🤖 GitHub Actions Auto-Register

Zero-effort branch registration via GitHub workflow

When enabled, every push to a branch automatically:

• ✅ Registers the branch with Spidersan
• ✅ Detects changed files via git diff
• ✅ Checks for conflicts with other branches
• ✅ Reports TIER 2+ conflicts as workflow warnings
• ✅ Extracts agent name from branch prefix (e.g., claude/feature → claude)

Setup:

1. Workflow is already included: .github/workflows/auto-register.yml
2. Just push to any branch (except main/staging)
3. View results in GitHub Actions tab

Example:

git checkout -b yourname/new-feature
git add src/api.ts
git commit -m "feat: add new endpoint"
git push origin yourname/new-feature
# ✅ Auto-registered in ~15 seconds!

Benefits:

• No manual spidersan register needed
• Works across all contributors and AI agents
• Conflict warnings appear in CI checks
• Perfect for multi-agent repositories

Note: This complements (doesn't replace) local spidersan watch for real-time file monitoring.

Installation:

• 📖 Complete Installation Guide →
• 🎯 Use Cases & Examples →
• 🤖 Claude Code Skill →

🦺 Rescue Mode

Got a repo with 10+ abandoned branches? Let Spidersan clean up the mess:

# Scan for rogue files/branches
spidersan rescue --scan

# Salvage a file into ./salvage/
spidersan rescue --salvage path/to/file.ts

# Abandon a rogue file
spidersan rescue --abandon path/to/file.ts

Perfect for: Post-hackathon cleanup, onboarding to chaotic repos, AI agent disasters.

🪝 Claude Code Hook Recipes

Wire Spidersan into Claude Code's hook system so conflict checks, AI advice, and registry syncs happen automatically — no agent needs to remember to run them.

How it works

Claude Code's ~/.claude/settings.json supports PreToolUse hooks that fire before any Bash command and can hard-block execution (returning continue: false) or inject context back to the model. Spidersan's --strict flag exits with code 1 on TIER 2+ conflicts, making it a natural hard-stop gate.

The full recipe

Add these hooks to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command // empty' | grep -qE '\\brm\\b' && jq -n '{\"continue\":false,\"stopReason\":\"🛑 rm blocked — verify paths and request explicit permission.\"}' || echo '{}'"
          },
          {
            "type": "command",
            "command": "bash -c 'cmd=$(jq -r \".tool_input.command // empty\"); if echo \"$cmd\" | grep -qE \"\\\\bgit\\\\s+push\\\\b\"; then if ! spidersan conflicts --tier 2 --strict 2>/dev/null; then jq -n \"{\\\"continue\\\":false,\\\"stopReason\\\":\\\"🕷️ Spidersan: TIER 2+ conflict detected. Run spidersan conflicts to review before pushing.\\\"}\"; exit 0; fi; advice=$(spidersan advise 2>/dev/null | head -30); [ -n \"$advice\" ] && jq -n --arg a \"$advice\" \"{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PreToolUse\\\",\\\"additionalContext\\\":\\\"🕷️ Spidersan pre-push advice:\\\\n\\($a)\\\"}}\" || echo \"{}\"; elif echo \"$cmd\" | grep -qE \"\\\\bgit\\\\s+(merge|rebase)\\\\b\"; then if ! spidersan conflicts --tier 3 --strict 2>/dev/null; then jq -n \"{\\\"continue\\\":false,\\\"stopReason\\\":\\\"🕷️ Spidersan: TIER 3 critical conflict detected. Run spidersan conflicts --tier 3 before merging.\\\"}\"; exit 0; fi; echo \"{}\"; else echo \"{}\"; fi'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'cmd=$(jq -r \".tool_input.command // empty\"); echo \"$cmd\" | grep -qE \"\\\\bgit\\\\s+push\\\\b\" && spidersan registry-sync --push 2>/dev/null &; echo \"{}\"'",
            "async": true
          }
        ]
      }
    ]
  }
}

What each hook does

| Hook | Trigger | Action | |------|---------|--------| | rm guard | Any rm command | Hard block — requires explicit permission | | Pre-push conflict check | git push | Runs spidersan conflicts --tier 2 --strict — hard blocks if TIER 2+ found | | Pre-push AI advice | git push (after conflict check passes) | Runs spidersan advise, injects recommendations into model context | | Pre-merge conflict check | git merge / git rebase | Runs spidersan conflicts --tier 3 --strict — hard blocks on critical files | | Post-push registry sync | git push (success) | Runs spidersan registry-sync --push async — keeps fleet registry fresh |

Conflict tiers

| Tier | Threshold | Example files | Gate used on | |------|-----------|---------------|--------------| | TIER 1 WARN | Low risk | .md, .css, .json | Not blocked | | TIER 2 PAUSE | Medium risk | package.json, migrations, types | git push | | TIER 3 BLOCK | Critical | .env, auth files, core lib | git merge, git rebase |

Installing

# Merge into your global settings (preserves existing config)
cp ~/.claude/settings.json ~/.claude/settings.json.bak
# Then add the hooks block above — or use /update-config in Claude Code

The hooks are global (~/.claude/settings.json) so they apply across all projects automatically. Every agent on the machine benefits without per-repo setup.

📖 Documentation

• Core Guide - Public feature set and core workflows
• Usage (internal; see spidersan-ecosystem repo)
• Data Collection - Privacy & data practices

🗣️ Feedback & Support

We're building this in public and want to hear from you!

• Issues & Features: GitHub Issues
• Email: [email protected]
• Site: Treebird
• Twitter/X: @Treebird_Dev

Tell us what's working, what's broken, and what you'd love to see next.

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

Support

Fuel the Flock

Treebird is free and open source. Star our repos on GitHub or support us to keep the servers running and the agents dreaming.

❤️ Sponsor on GitHub https://github.com/sponsors/treebird7

☕ Buy me a coffee https://buymeacoffee.com/tree.bird

📄 License

MIT License - see LICENSE for details

Made with 🕷️ for AI-first development teams

Part of the Treebird Ecosystem 🌲