If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/muesli/beehive shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 17 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live muesli/beehive repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/muesli/beehive.

What it runs against: a local clone of muesli/beehive — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in muesli/beehive | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1198 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of muesli/beehive. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/muesli/beehive.git
#   cd beehive
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of muesli/beehive and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "muesli/beehive(\\.git)?\\b" \\
  && ok "origin remote is muesli/beehive" \\
  || miss "origin remote is not muesli/beehive (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "beehive.go" \\
  && ok "beehive.go" \\
  || miss "missing critical file: beehive.go"
test -f "app/app.go" \\
  && ok "app/app.go" \\
  || miss "missing critical file: app/app.go"
test -f "api/api.go" \\
  && ok "api/api.go" \\
  || miss "missing critical file: api/api.go"
test -f "bees/actions.go" \\
  && ok "bees/actions.go" \\
  || miss "missing critical file: bees/actions.go"
test -f "api/context/context.go" \\
  && ok "api/context/context.go" \\
  || miss "missing critical file: api/context/context.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1198 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1168d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/muesli/beehive"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Beehive is a Go-based event/agent automation system that connects modular integrations (called 'Hives') to create triggered workflows. It lets users wire together external services like Twitter, IRC, Slack, Twilio, and Jenkins, listening for events and executing automated actions in response—essentially a self-hosted IFTTT-like engine with a REST API and web UI. Monolithic single-binary architecture: app/app.go bootstraps the system, api/ exposes REST endpoints for bees/chains/actions, bees/ contains 40+ integration drivers (each a subdirectory), and admin/ holds systemd service definitions. Configuration is file-based; chains and actions are defined declaratively and exposed via REST API at http://localhost:8181.

Home automation enthusiasts, DevOps engineers, and power users who want to build custom event-driven workflows without cloud vendor lock-in. Contributors are typically Go developers comfortable with plugin architectures who want to add new service integrations (Hives).

Actively maintained but niche: the project has Go 1.13+ requirement, CI/CD via GitHub Actions (.github/workflows/go.yml), Docker support, and official releases on multiple platforms (Linux x86_64/armv6, macOS, Windows). Last evidenced by maintained .goreleaser.yml and active Dockerfile, suggesting production readiness for self-hosted automation, though smaller community than mainstream competitors.

Heavy dependency on external service libraries (40+ integrations like anaconda for Twitter, discordgo, go-jira) creates maintenance burden and potential breaking API changes from upstream. Single-maintainer risk (muesli) is typical for hobby projects. The codebase is 650KB of Go, suggesting moderate complexity; asset bundling via bindata_stub.go indicates build-time requirements that can fail silently if assets are missing.

Project maintains active CI via GitHub Actions (.github/workflows/go.yml), releases via GoReleaser, and Docker builds. No specific breaking changes or major refactors evident from file list, suggesting focus on stability and incremental Hive additions rather than core engine changes.

git clone --recursive https://github.com/muesli/beehive.git
cd beehive
make
./beehive --help

The --recursive flag is critical to fetch submodules. Run make to compile; binaries will be in the current directory. Assets (images, JS, CSS in assets/) must be present for the web UI to work.

Daily commands:

make
./beehive

By default listens on http://localhost:8181. Systemd unit available at admin/beehive.service for production deployment. Configuration read from ~/.beehive/ or custom path via CLI flags.

• beehive.go — Main entry point and application bootstrap—all contributors must understand the app initialization flow.
• app/app.go — Core application orchestration logic that manages the event/agent lifecycle and hive interactions.
• api/api.go — REST API server setup and routing—entry point for all external API requests.
• bees/actions.go — Defines the base interface and utilities for bee actions—critical for understanding how agents execute tasks.
• api/context/context.go — Request context handling for the API layer—essential for understanding how requests flow through middleware.
• Makefile — Build and release configuration—necessary for contributors to understand the build process and bee plugin structure.

• App (Core Orchestrator) (Go, EventBus) — Manages hive lifecycle, event bus, chain state, and graceful shutdown
  • Failure mode: Crash → all hives stop listening, chains halt; recovery requires restart
• Hives (External Integrations) (Go, service-specific SDKs/APIs) — Connect to external services (Twitter, Slack, IRC, etc.); emit events and execute actions
  • Failure mode: Hive crash → that integration stops; other hives unaffected; chains depending on it block
• Event Bus (Go channels, EventBus library) — In-memory event routing between hives and chains; applies filters and triggers actions
  • Failure mode: Loss of in-flight events if not persisted; no event replay on restart
• REST API (HTTP, Go net/http) — CRUD operations for chains, queries for hive/action status, dashboard backend
  • Failure mode: API down → cannot modify chains, but running chains continue; restart recovers
• Chain (Automation Workflow) (Go, EventBus) — Listens for matched events, evaluates filters, executes ordered actions
  • Failure mode: Action failure → chain halts; other chains unaffected; logged for debugging

• External Event (e.g., Twitter) → Hive — Service emits event (tweet, mention, etc.) to its registered hive
• Hive → Event Bus — Hive publishes event struct with type and payload to in-memory event bus
• Event Bus → Chain — Event bus matches event against all registered chain triggers; dispatches to matching chains
• Chain → Action —

Add a new Bee (Hive Module)

1. Create a new directory under bees/ named after your bee (e.g., bees/mycustomebee/) (bees/mycustomebee/)
2. Implement the bee struct and event/action methods, following the pattern in bees/actions.go and bees/alertoverbee/alertoverbee.go (bees/mycustomebee/mycustomebee.go)
3. Create a factory struct and Register method in a separate file to handle bee instantiation (bees/mycustomebee/mycustomebeesfactory.go)
4. Add a README.md documenting configuration and capabilities (bees/mycustomebee/README.md)
5. Update the Makefile to include your bee in the build targets (add to plugin compilation rules) (Makefile)

Add a new API Resource Endpoint

1. Create a new resource directory under api/resources/myresource/ (api/resources/myresource/)
2. Implement the main resource handler with a struct and Register function, following the pattern in api/resources/bees/bees.go (api/resources/myresource/myresource.go)
3. Implement GET, POST, PUT, DELETE methods in separate files (e.g., myresource_get.go, myresource_post.go) (api/resources/myresource/myresource_get.go)
4. Register your resource in api/api.go by calling your resource's Register function in the API initialization (api/api.go)

Add a new automated chain/workflow

1. Use the Chains API POST endpoint (api/resources/chains/chains_post.go) to create a new chain definition (api/resources/chains/chains_post.go)
2. Define the trigger (event from a bee) and the actions to execute in the chain configuration (api/resources/chains/chains.go)
3. The app automatically registers and manages chain lifecycle through the app's event bus and bee coordination (app/app.go)

• Go — Fast compilation, concurrent event processing via goroutines, simple binary distribution for diverse hive modules
• Modular plugin architecture (hives in bees/) — Allows independent development and deployment of integrations without rebuilding core; extensible without monolithic coupling
• Event-driven (EventBus) — Decouples hives from chains and actions; enables reactive automation triggered by external events
• REST API — Standard interface for creating/managing chains, querying hive status, and integrating with external dashboards

• Plugin-based hives over built-in integrations

  • Why: Reduces core binary size and allows selective deployment of only-needed hives
  • Consequence: Added build complexity and plugin versioning challenges; must maintain plugin compatibility with core API

• Event-driven architecture over polling

  • Why: Lower latency, responsive automation, efficient resource usage
  • Consequence: Harder to debug event flow; requires careful handling of event ordering and lost event scenarios

• Synchronous REST API for chain CRUD

  • Why: Simple, familiar interface for web dashboards and user tools
  • Consequence: No built-in webhooks or async notifications; clients must poll for chain execution results

• User authentication/authorization—designed for trusted admin environments, not multi-tenant SaaS
• Distributed/clustered deployment—single-node application without cross-instance event replication
• Persistent event logging—events are ephemeral unless explicitly stored by bee handlers
• Real-time UI synchronization—REST API only; dashboard must poll for updates

Assets (images, JS, CSS in assets/) must be present at build time or embedded via bindata; missing assets silently break the web UI. The --recursive clone flag is mandatory—missing submodules cause build failures. Beehive writes config to ~/.beehive/ by default; ensure the user has write permissions. Some Hives require external service credentials (API keys, OAuth tokens) that must be configured post-startup via the REST API.

• Event-driven architecture — Beehive's core design principle: Hives emit events, chains listen and filter them, then trigger actions; understanding this pub-sub model is essential to extending the system
• Plugin/module pattern — Each Hive is a self-contained plugin with a standardized interface; understanding how Beehive loads and manages plugins is critical for adding new integrations
• RESTful API design — Beehive uses go-restful to expose resources (bees, chains, actions); contributors must understand REST conventions to add or modify API endpoints correctly
• Service integration patterns — Each Hive adapts an external service (Twitter, IRC, Discord) to Beehive's event/action model; learning how twitterbee wraps the Twitter API helps implement new Hives
• Go embedding and asset bundling — Beehive uses bindata to embed web UI assets (images, CSS, JS) into the binary; understanding this build step is essential to modify the frontend without breaking the build
• systemd service management — Beehive is typically deployed as a systemd service (admin/beehive.service); understanding unit files is essential for production deployments on Linux
• Filter chains and conditional logic — Chains in Beehive allow filtering events (e.g., only act if a stock price drops below X); this composable filtering model is the key to flexible automation

• n8n/n8n — Web-based workflow automation platform with a node-based UI; similar event-driven architecture but cloud-first vs Beehive's self-hosted model
• serverless/serverless — Serverless framework for event-triggered functions; similar automation concept but cloud-centric and function-oriented vs Beehive's service-integration model
• muesli/duit — GUI toolkit by the same author (muesli); potentially relevant for future UI modernization or alternative interfaces to Beehive
• go-task/task — Go-based task runner with event/dependency chains; shares automation philosophy but lacks Beehive's external service integrations

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Go unit tests for API resource handlers (api/resources/*/)

The api/resources/ directory contains multiple handler files (actions_get.go, bees_post.go, chains_delete.go, etc.) but there are no corresponding *_test.go files visible in the structure. These HTTP handlers need unit test coverage to ensure request validation, response marshaling, and error handling work correctly. This is critical for an API-driven system like Beehive.

• [ ] Create api/resources/actions/actions_test.go with tests for POST/GET handlers
• [ ] Create api/resources/bees/bees_test.go covering POST/PUT/DELETE/GET operations
• [ ] Create api/resources/chains/chains_test.go for chain CRUD operations
• [ ] Create api/resources/hives/hives_test.go for hive retrieval
• [ ] Create api/resources/logs/logs_test.go for log filtering and pagination
• [ ] Update .github/workflows/go.yml to include -race flag and code coverage reporting

Add GitHub Actions workflow for building multi-arch Docker images

The repo has a Dockerfile and .goreleaser.yml for releases, but the .github/workflows/go.yml likely only runs tests. Modern Go projects should automatically build and push multi-architecture Docker images (linux/amd64, linux/arm64, linux/arm/v7) to support deployment on Raspberry Pi and ARM servers. This is especially valuable for a self-hosted automation system.

• [ ] Create .github/workflows/docker.yml with docker/setup-buildx-action
• [ ] Configure build matrix for linux/amd64, linux/arm64, linux/arm/v7 architectures
• [ ] Add Docker image tagging logic (latest, version tags on releases)
• [ ] Integrate with .goreleaser.yml or trigger on git tags
• [ ] Document Docker image usage in README.md with arm/arm64 examples

Create integration tests for core bee modules (hive connectivity)

The dependencies show many bee integrations (Discord, GitHub, JIRA, IRC, Email, etc.) but there's no visible integration test suite. Adding tests that verify bee initialization, event triggering, and chain execution would catch breaking changes early. Focus on core bees that many workflows depend on.

• [ ] Create bees/*/bee_test.go files for critical bees (croncron, execbee, emailbee, githubee)
• [ ] Add test fixtures in bees/*/testdata/ for mock event payloads
• [ ] Implement mock versions of external services (fake SMTP, fake GitHub API responses)
• [ ] Create app/app_test.go to test bee registration and chain execution flow
• [ ] Document how to run integration tests in CONTRIBUTING.md (which appears missing)

• Add integration tests for api/resources/chains/chains_post.go and chains_delete.go; the repo currently lacks test coverage for chain creation/deletion, which is a critical workflow feature.
• Document the Hive plugin interface: create a guide in the wiki or README explaining how to write a new Bee by reverse-engineering bees/twitterbee/ and bees/discordbee/, since no plugin template exists.
• Add unit tests for api/resources/bees/bees_post.go to validate Hive instantiation with malformed configs; error handling isn't tested and could mask bugs.

• High · Outdated and Potentially Vulnerable Dependencies — go.mod dependency file. Multiple dependencies are pinned to very old versions (2016-2019 era) with known vulnerabilities. Notable examples: go-jira v1.13.0 (2019), bwmarrin/discordgo v0.23.1 (outdated), go-telegram-bot-api (pinned to 1.0.1-0.2), and cloudflare-go v0.10.6. These old versions likely have unpatched security vulnerabilities. Fix: Update all dependencies to their latest stable versions. Run 'go get -u ./...' and 'go mod tidy'. Regularly scan for vulnerabilities using 'go list -json -m all | nancy sleuth' or similar tools. Consider using Dependabot for automated updates.
• High · Incompatible/Fork Dependencies Without Maintenance — go.mod dependency file. Several dependencies are marked as '+incompatible' (emicklei/go-restful, go-mail/mail) or are unmaintained forks (MariaTerzieva/gotumblr, Profpatsch/GoOse), indicating they may not receive security updates and could have unresolved vulnerabilities. Fix: Replace '+incompatible' dependencies with maintained versions. Migrate to actively maintained forks or alternative libraries. Audit and test each migration carefully.
• High · Hardcoded Configuration Defaults in Docker — Dockerfile, line with ENV CANONICAL_URL=http://localhost:8181. The Dockerfile contains a hardcoded CANONICAL_URL default of 'http://localhost:8181' using plain HTTP, not HTTPS. When deployed to production, this may result in insecure communication if not properly overridden. Fix: Remove hardcoded localhost defaults from production Dockerfile. Use HTTPS by default (https://localhost:8181). Force users to explicitly set CANONICAL_URL in production. Add validation to reject non-HTTPS URLs in production mode.
• High · Exposed API Port Without Authentication Enforcement — Dockerfile ENTRYPOINT and EXPOSE directive. Port 8181 is exposed for the admin interface without visible authentication mechanisms in the Docker configuration. The ENTRYPOINT launches beehive with -bind 0.0.0.0:8181, making it accessible to all network interfaces. Fix: Implement mandatory authentication (OAuth2, JWT, or HTTP Basic Auth). Use network policies or firewall rules to restrict admin interface access. Consider binding to localhost by default and requiring explicit configuration for external access. Add TLS/HTTPS requirement.
• Medium · Missing Security Headers Configuration — api/api.go and api/resources directories. No visible configuration for security headers (HSTS, X-Frame-Options, CSP, X-Content-Type-Options) in the REST API setup. The api/api.go file likely serves without these protections. Fix: Add middleware to inject security headers: X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection: 1; mode=block, Content-Security-Policy appropriate for your use case, and HSTS headers for HTTPS.
• Medium · Configuration File Stored in World-Accessible Volume — Dockerfile VOLUME /conf and admin/beehive.service.conf. The beehive.conf configuration file is stored in a Docker volume (/conf) that may contain sensitive credentials (API keys, passwords, tokens) for integrated services (Twitter, Slack, Discord, etc.). No encryption or access controls are visible. Fix: Encrypt the configuration file at rest. Use environment variables or secret management systems (HashiCorp Vault, Docker Secrets, Kubernetes Secrets) for sensitive credentials. Implement file-level permissions (chmod 600) for config files. Document secure credential handling.
• Medium · Third-Party Integration Keys Without Rotation Policy — assets/bees/ and multiple integration modules. The system integrates with numerous external services (27+ 'bees' for Twitter, Slack, GitHub, etc.) requiring API keys and tokens. No visible key rotation, revocation, or expiration mechanism is documented. Fix: Implement key rotation policies for all external service credentials. Add audit logging for credential usage. Use short-lived tokens where possible. Provide secure credential update mechanisms. Document credential lifecycle management.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.