🕷️ Spidersan

Coordination for the multi-agent era

Branch coordination for AI coding agents

Quick Start • Features • Documentation

🎯 The Problem

A multi coders or agents and multi branch work can result in a merging nightmare

🕷️ 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 | Show file conflicts between your branch and others | | 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 | Cleanup stale branches | | spidersan rescue | Start rescue mission for abandoned branch cleanup | | spidersan abandon | Abandon a branch (mark inactive) | | spidersan merged | Mark a branch merged | | spidersan sync | Sync registry (local/Supabase) | | 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 |

Advanced commands like who-touched, monitor, lock, scan, triage, and salvage live in the ecosystem plugin.

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

🤖 GitHub Actions Auto-Register (NEW!)

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.

📖 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 🌲