Discord Animus Agent - Complete GitHub to Discord Integration

A production-ready Flask webhook processor that receives GitHub organization events, validates HMAC signatures, processes them through Letta AI agents, and delivers intelligent Discord notifications.

📢 Repository Status: This repository is now public and open for contributions!

🎯 Project Status: COMPLETE ✅

Full GitHub → Letta → Discord integration is operational and production-ready!

✅ Complete System Features

🔐 HMAC-SHA256 Signature Verification - Secure webhook authentication
📡 GitHub Event Processing - Issues, PRs, pushes, releases, comments, and more
🤖 Letta AI Integration - Sends events to Mouse agent for intelligent processing
💬 Discord Messaging - Self-contained Discord tool with zero dependencies
⏱️ Event Buffering - 2-second delays prevent overwhelming AI agents
📊 Health Monitoring - Health check and statistics endpoints
🔄 Auto-Recovery - Cron-based auto-restart system
📝 Structured Logging - JSON-formatted logs with full context
🧪 Comprehensive Testing - Real GitHub event testing completed
🚀 Production Management - Complete deployment and management scripts
📚 Full Documentation - Comprehensive guides and API references

🏗️ Complete Architecture

GitHub Events → Webhook Processor → Letta Agent (Mouse) → Discord Channel
     ↓              ↓                    ↓              ↓
  HMAC Verify   Event Buffer        AI Processing   Self-Contained
  Event Parse   2s Delay           Agent Targeting   HTTP Client

🚀 Quick Start

1. Clone and Setup

git clone https://github.com/AnimusUNO/animus-discord.git
cd animus-discord
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# .\venv\Scripts\Activate.ps1  # Windows
pip install -r requirements.txt

2. Configure Environment

# Copy example configuration
cp config.env.example .env

# Edit .env file with your settings
# WEBHOOK_SECRET=your_github_webhook_secret
# LETTA_API_KEY=your_letta_api_key
# DISCORD_BOT_TOKEN=your_discord_bot_token
# DISCORD_CHANNEL_ID=your_discord_channel_id

3. Start Webhook Processor

# Production mode (recommended)
./manage-webhook.sh start

# Development mode
python webhook_processor.py

4. Verify Installation

# Check health
curl http://localhost:5000/health

# Check statistics
curl http://localhost:5000/stats

# View logs
./manage-webhook.sh logs

API Endpoints

POST /webhook

Main webhook endpoint for receiving GitHub events.

Headers Required:

X-Hub-Signature-256: HMAC-SHA256 signature
X-GitHub-Event: Event type (issues, push, pull_request, etc.)
X-GitHub-Delivery: Unique delivery ID
Content-Type: application/json

Response:

{
  "status": "processed",
  "event_id": "delivery-id",
  "processed_at": "2025-10-09T20:44:05Z",
  "event_count": 1
}

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "uptime_seconds": 3600,
  "events_processed": 42,
  "timestamp": "2025-10-09T20:44:05Z"
}

GET /stats

Statistics endpoint.

Response:

{
  "uptime_seconds": 3600,
  "events_processed": 42,
  "start_time": "2025-10-09T19:44:05Z",
  "webhook_secret_configured": true,
  "debug_mode": false
}

Supported Event Types

Issues: opened, closed, assigned, labeled, etc.
Pull Requests: opened, closed, merged, reviewed, etc.
Push: code commits, branch updates, tags
Release: published, unpublished
Repository: created, deleted, archived, renamed
Team: member added/removed, permissions changed
Organization: member added/removed, billing changes
Workflow Runs: CI/CD pipeline events
Deployments: deployment status updates
Security Events: vulnerability alerts, dependency updates

Event Processing

Normalized Event Structure

All events are normalized into a consistent structure:

{
  "event_type": "issues",
  "delivery_id": "unique-delivery-id",
  "timestamp": "2025-10-09T20:44:05Z",
  "action": "opened",
  "repository": {
    "id": 111222333,
    "name": "repo-name",
    "full_name": "org/repo-name",
    "url": "https://github.com/org/repo-name",
    "private": false,
    "default_branch": "main"
  },
  "sender": {
    "id": 987654321,
    "login": "username",
    "name": "User Name",
    "email": "user@example.com",
    "avatar_url": "https://avatars.githubusercontent.com/u/987654321"
  },
  "organization": {
    "id": 444555666,
    "login": "org-name",
    "name": "Organization Name",
    "url": "https://github.com/org-name"
  },
  "issue": {
    "issue_id": 123456789,
    "number": 42,
    "title": "Issue Title",
    "body": "Issue description",
    "state": "open",
    "labels": ["bug", "priority-high"],
    "assignees": ["username"],
    "url": "https://github.com/org/repo/issues/42"
  }
}

Event Filtering

Events are filtered based on configurable rules:

Parse Errors: Automatically skipped
Test Repositories: Skipped (repositories with "test" in name)
Custom Rules: Extensible filtering system

Security

HMAC Signature Verification

All webhook requests are verified using HMAC-SHA256 signatures:

def verify_signature(payload_body: bytes, signature_header: str) -> bool:
    sha_name, signature = signature_header.split('=')
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Environment Variables

WEBHOOK_SECRET: GitHub webhook secret (required)
FLASK_SECRET_KEY: Flask secret key (required)
PORT: Server port (default: 5000)
DEBUG: Debug mode (default: False)
LOG_LEVEL: Logging level (default: INFO)

Testing

Unit Tests

# Run all tests
python -m pytest test_webhook_processor.py -v

# Run specific test categories
python -m pytest test_webhook_processor.py::TestWebhookProcessor -v
python -m pytest test_webhook_processor.py::TestWebhookEndpoints -v
python -m pytest test_webhook_processor.py::TestEventParsing -v

Integration Tests

# Test with running server
python start_webhook.py &
python test_webhook_cli.py --test-endpoint

Manual Testing

Start webhook processor:
```
python start_webhook.py
```

Update GitHub webhook URL:

gh api --method PATCH /orgs/AnimusUNO/hooks/574364342 \
  -f config='{"url":"http://localhost:5000/webhook","content_type":"json","secret":"animus_webhook_secret_2024"}'

Trigger test events:
- Make commits to AnimusUNO/animus-discord
- Create issues in the repository
- Create pull requests

Monitor logs:

# Check webhook processor logs
# Verify events are received and processed

📁 Complete Project Structure

animus-discord/
├── webhook_processor.py      # Main Flask application with Letta integration
├── letta_integration.py       # Letta AI client integration
├── letta_discord_tool.py      # Self-contained Discord tool
├── manage-webhook.sh          # Production webhook management script
├── manage-cron.sh             # Cron job management for auto-recovery
├── launch-webhook.sh          # Webhook startup script
├── requirements.txt           # Python dependencies
├── requirements-dev.txt       # Development dependencies
├── config.env.example         # Environment configuration template
├── docs/                      # Complete documentation
│   ├── discord-bot-setup.md   # Discord bot configuration guide
│   ├── discord-tool.md        # Discord tool documentation
│   ├── letta-api-reference.md # Letta API reference
│   ├── letta_tool_compatibility_notes.md
│   ├── production-deployment.md # Production deployment guide
│   └── project-plan.md        # Original project plan
├── scripts/                   # Setup utilities
│   ├── setup-webhook.sh       # GitHub webhook setup
│   └── setup-webhook.ps1      # Windows version
├── test_webhook_processor.py  # Unit tests
├── test_webhook_cli.py        # CLI testing tool
├── LAUNCH_SCRIPTS.md          # Management script documentation
├── LICENSE                    # AGPLv3 license for code
├── LICENSE-CC-BY-SA          # CC-BY-SA license for documentation
└── CONTRIBUTING.md            # Contribution guidelines

🔧 Complete Configuration

Environment Variables

Variable	Required	Description
`WEBHOOK_SECRET`	✅	GitHub webhook secret for HMAC verification
`LETTA_API_KEY`	✅	Letta API key for agent communication
`DISCORD_BOT_TOKEN`	✅	Discord bot token for messaging
`DISCORD_CHANNEL_ID`	✅	Discord channel ID for notifications
`FLASK_SECRET_KEY`	✅	Flask secret key for sessions
`PORT`	❌	Server port (default: 5000)
`DEBUG`	❌	Debug mode (default: False)
`LOG_LEVEL`	❌	Logging level (default: INFO)

GitHub Webhook Setup

Create Organization Webhook:

./scripts/setup-webhook.sh AnimusUNO https://your-domain.com/webhook your_secret

Configure Events: Select all events (["*"]) for comprehensive monitoring
Verify Setup:
```
gh api /orgs/AnimusUNO/hooks
```

🤖 Complete Letta Integration

Agent Configuration

The system sends GitHub events to the Mouse agent (agent-c2fef691-44d3-4e86-9dbb-a6a681355a8b) which:

Processes events using AI reasoning
Formats messages for Discord
Sends notifications via self-contained Discord tool
Handles rate limiting with 2-second buffering

Discord Tool

The letta_discord_tool.py provides a self-contained Discord messaging function:

✅ Zero external dependencies - Uses only Python built-ins
✅ Letta-compatible - Proper JSON schema and function signature
✅ Agent-specific - Targets Animus agent explicitly
✅ Production-ready - Comprehensive error handling

🛠️ Complete Management Commands

Webhook Management

# Start webhook
./manage-webhook.sh start

# Stop webhook
./manage-webhook.sh stop

# Restart webhook
./manage-webhook.sh restart

# Check status
./manage-webhook.sh status

# View logs
./manage-webhook.sh logs

# Health check
./manage-webhook.sh health

# Statistics
./manage-webhook.sh stats

Auto-Recovery Setup

# Install cron job for auto-restart
./manage-cron.sh install

# Check cron status
./manage-cron.sh status

# Remove cron job
./manage-cron.sh remove

🧪 Complete Testing

Manual Testing

# Create test issue
gh issue create --title "Test Issue" --body "Testing webhook integration"

# Add comment
gh issue comment 1 --body "Test comment"

# Close issue
gh issue close 1

Health Verification

# Check webhook health
curl http://localhost:5000/health

# Check statistics
curl http://localhost:5000/stats

# Monitor logs
./manage-webhook.sh logs

🚀 Complete Production Deployment

Server Setup

# Clone repository
git clone https://github.com/AnimusUNO/animus-discord.git
cd animus-discord

# Setup virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure environment
cp config.env.example .env
# Edit .env with production values

# Start webhook
./manage-webhook.sh start

# Setup auto-recovery
./manage-cron.sh install

GitHub Webhook Configuration

# Update webhook URL
gh api --method PATCH /orgs/AnimusUNO/hooks/574364342 \
  --field config[url]="https://your-domain.com/webhook" \
  --field config[secret]="your-production-secret"

Current Production Status

Webhook ID: 574364342
Organization: AnimusUNO
Events: All events (["*"])
Status: ✅ Active and processing events
Agent: Mouse (Mini model 4.1)
Buffer: 2-second delays active

Monitoring

Health Checks

Endpoint: GET /health
Response: JSON with status, uptime, event count
Use Case: Load balancer health checks

Statistics

Endpoint: GET /stats
Response: Detailed statistics
Use Case: Monitoring dashboards

Logs

Format: Structured JSON logs
Levels: DEBUG, INFO, WARNING, ERROR
Context: Event details, processing results

📚 Complete Documentation

Discord Bot Setup - Complete Discord bot configuration guide
Discord Tool - Self-contained Discord tool documentation
Letta API Reference - Letta integration API reference
Letta Tool Compatibility - Letta integration requirements
Production Deployment - Complete production deployment guide
Management Scripts - Management script documentation
Project Plan - Original project planning document

🎯 Project Completion Summary

This project successfully delivers a complete end-to-end GitHub to Discord integration:

✅ Phase 1: GitHub Webhook Processor - Complete
✅ Phase 2: Letta AI Integration - Complete
✅ Phase 3: Discord Messaging Tool - Complete
✅ Production Management: Auto-recovery and monitoring - Complete
✅ Documentation: Comprehensive guides and references - Complete

Future Enhancement Opportunities

While the core project is complete, potential enhancements could include:

Enhanced Event Filtering - Advanced filtering rules
Multiple Agent Support - Support for multiple Letta agents
Metrics Integration - Prometheus/StatsD integration
Alerting System - Error notification system
Web Dashboard - Real-time monitoring interface

Troubleshooting

Common Issues

Signature Verification Failed:
- Check WEBHOOK_SECRET matches GitHub webhook secret
- Verify webhook URL is correct
Events Not Processing:
- Check webhook is active in GitHub
- Verify webhook URL is accessible
- Check logs for errors
High Memory Usage:
- Check for memory leaks in event processing
- Monitor event queue size

Debug Mode

Enable debug mode for detailed logging:

export DEBUG="True"
python start_webhook.py

🤝 Contributing

We welcome contributions to the Discord Animus Agent! Since this repository is now public, we encourage community participation.

📖 For detailed contribution guidelines, see CONTRIBUTING.md

Quick Start

Fork the repository on GitHub
Clone your fork and set up the development environment
Create a feature branch and make your changes
Run tests and ensure everything passes
Create a Pull Request with a clear description

Areas for Contribution

While the core project is complete, contributions are welcome for:

Enhanced Features: Advanced filtering, multiple agent support
Testing: Additional test coverage and edge cases
Documentation: Improvements and additional examples
Performance: Optimization and monitoring enhancements
Security: Enhanced security features and audits
Bug Fixes: Issue resolution and improvements

License

This project uses dual licensing:

Source Code: Licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details
Documentation & Media: Licensed under Creative Commons Attribution-ShareAlike 4.0 International - see the LICENSE-CC-BY-SA file for details

What this means:

Code: AGPLv3 ensures that any modifications or network services using this code must also be open source
Documentation: CC-BY-SA allows sharing and adaptation of documentation with proper attribution

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
docs		docs
scripts		scripts
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LAUNCH_SCRIPTS.md		LAUNCH_SCRIPTS.md
LICENSE		LICENSE
LICENSE-CC-BY-SA		LICENSE-CC-BY-SA
README.md		README.md
config.env.example		config.env.example
launch-webhook.sh		launch-webhook.sh
letta_discord_tool.py		letta_discord_tool.py
letta_integration.py		letta_integration.py
manage-cron.sh		manage-cron.sh
manage-webhook.sh		manage-webhook.sh
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
test_webhook_cli.py		test_webhook_cli.py
test_webhook_processor.py		test_webhook_processor.py
webhook_processor.py		webhook_processor.py

License

Licenses found

AnimusUNO/animus-discord

Folders and files

Latest commit

History

Repository files navigation

Discord Animus Agent - Complete GitHub to Discord Integration

🎯 Project Status: COMPLETE ✅

✅ Complete System Features

🏗️ Complete Architecture

🚀 Quick Start

1. Clone and Setup

2. Configure Environment

3. Start Webhook Processor

4. Verify Installation

API Endpoints

POST /webhook

GET /health

GET /stats

Supported Event Types

Event Processing

Normalized Event Structure

Event Filtering

Security

HMAC Signature Verification

Environment Variables

Testing

Unit Tests

Integration Tests

Manual Testing

📁 Complete Project Structure

🔧 Complete Configuration

Environment Variables

GitHub Webhook Setup

🤖 Complete Letta Integration

Agent Configuration

Discord Tool

🛠️ Complete Management Commands

Webhook Management

Auto-Recovery Setup

🧪 Complete Testing

Manual Testing

Health Verification

🚀 Complete Production Deployment

Server Setup

GitHub Webhook Configuration

Current Production Status

Monitoring

Health Checks

Statistics

Logs

📚 Complete Documentation

🎯 Project Completion Summary

Future Enhancement Opportunities

Troubleshooting

Common Issues

Debug Mode

🤝 Contributing

Quick Start

Areas for Contribution

License

What this means:

About

Resources

License

Licenses found

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages