Webhook-driven agent spawner service for the Claude agent team
- Python 98.4%
- Shell 1.6%
Justin Belec
26164184f4
Major features: - HAL conversational plan: approval gate, INITIAL/CONVERSATION/MENTION/FOLLOWUP spawn modes, pending comment queue, progress checklists - Sibyl System (claude-chat): fire-and-forget analyst agent with self-unassign - Orphan process watchdog: kills stale claude processes not tracked by spawner - Chat pool support in config (max_concurrent_chat) Bugfixes: - Pending comments queued when agent busy, processed on IDLE transition - Stale workspace sync (git fetch/checkout/reset/clean) on every spawn - Sub-issue safety: check existing before creating, never re-open closed - Self-close detection to prevent SIGTERM race BOOTSTRAP.md updated for memory-db Tower migration (Docker + Traefik). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> |
||
|---|---|---|
| docs | ||
| src | ||
| systemd | ||
| tests | ||
| .gitignore | ||
| agent-ctl | ||
| BOOTSTRAP.md | ||
| config.example.yaml | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
Agent Spawner
Webhook-driven service that spawns Claude agents in response to Forgejo issue assignments.
Overview
The Agent Spawner is the orchestration layer for the Claude agent team. It:
- Listens for Forgejo webhooks (issue assigned, PR review requested, etc.)
- Spawns the appropriate Claude agent with full context
- Monitors agent health via heartbeats
- Provides status API for HAL (architect) to query
- Handles recovery when agents die or get stuck
Agent Team
| Agent | Persona | Role |
|---|---|---|
claude-architect |
HAL 9000 | Lead architect, assigns work, reviews PRs |
claude-coder-1 |
Skippy | Implementation |
claude-coder-2 |
TARS | Implementation |
claude-docs-qa |
GLaDOS | Documentation and testing |
Quick Start
# Install dependencies
cd /opt/agent-spawner
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Configure
cp config.example.yaml config.yaml
# Edit config.yaml with your settings
# Run
python -m src.main
# Or via systemd
systemctl start agent-spawner
Architecture
[Forgejo] --webhook--> [Spawner] --spawns--> [Claude Agent]
|
+--> Status API
+--> Heartbeat Monitor
+--> Orphan Scanner
See docs/ARCHITECTURE.md for details.
Configuration
See docs/CONFIGURATION.md for all options.
Key settings:
spawning_enabled: true
max_concurrent_coders: 2
max_concurrent_docs: 1
heartbeat_timeout_default: 600 # 10 min
orphan_scan_interval: 300 # 5 min
API Endpoints
| Endpoint | Description |
|---|---|
GET /health |
Service health check |
GET /agents/status |
All agent statuses |
GET /agents/{name}/status |
Specific agent status |
POST /agents/{name}/stop |
Stop an agent |
POST /webhook |
Forgejo webhook receiver |
See docs/API.md for full documentation.
CLI
# Check status
agent-ctl status
# Stop an agent gracefully
agent-ctl stop coder-1
# Force stop
agent-ctl stop coder-1 --force
# Emergency halt all
agent-ctl stop --all
# Enable/disable spawning
agent-ctl enable
agent-ctl disable
Documentation
- Design Document - Design decisions and rationale
- Architecture - System components and data flow
- API Reference - REST API documentation
- Configuration - All configuration options
- Deployment - Installation and operations guide
Project Structure
agent-spawner/
+-- src/
| +-- main.py # Application entry point
| +-- config.py # Configuration management
| +-- webhook.py # Webhook handlers
| +-- spawner.py # Agent spawning logic
| +-- monitor.py # Heartbeat monitoring
| +-- scanner.py # Orphan issue scanner
| +-- status.py # Status API
| +-- notifications.py # Pushover alerts
+-- tests/
| +-- test_webhook.py
| +-- test_spawner.py
| +-- mock_agent.sh # Mock agent for testing
+-- docs/
| +-- DESIGN.md
| +-- ARCHITECTURE.md
| +-- API.md
| +-- CONFIGURATION.md
| +-- DEPLOYMENT.md
+-- config.example.yaml
+-- requirements.txt
+-- agent-ctl # CLI tool
+-- README.md
License
Internal infrastructure tool.