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/mojombo/god 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.

GO — Healthy across all four use cases

• 22+ active contributors
• Distributed ownership (top contributor 42% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{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 mojombo/god repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mojombo/god.

What it runs against: a local clone of mojombo/god — 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 mojombo/god | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 802 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mojombo/god. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mojombo/god.git
#   cd god
#
# 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 mojombo/god and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "lib/god.rb" \\
  && ok "lib/god.rb" \\
  || miss "missing critical file: lib/god.rb"
test -f "lib/god/watch.rb" \\
  && ok "lib/god/watch.rb" \\
  || miss "missing critical file: lib/god/watch.rb"
test -f "lib/god/process.rb" \\
  && ok "lib/god/process.rb" \\
  || miss "missing critical file: lib/god/process.rb"
test -f "lib/god/condition.rb" \\
  && ok "lib/god/condition.rb" \\
  || miss "missing critical file: lib/god/condition.rb"
test -f "lib/god/driver.rb" \\
  && ok "lib/god/driver.rb" \\
  || miss "missing critical file: lib/god/driver.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 802 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~772d)"
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/mojombo/god"
  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).

God is a Ruby-based process monitoring and management framework that keeps server processes running with configurable health checks and automatic restart logic. It uses a DSL-based configuration (.god files) to define conditions (CPU/memory usage, process exits, HTTP health checks) and actions (restart, notify), with native C extensions (kqueue on BSD/macOS, netlink on Linux) for efficient event-driven monitoring instead of polling. Monolithic gem structure: lib/god.rb is the entry point, lib/god/conditions/ holds pluggable health check classes (cpu_usage.rb, http_response_code.rb, process_exits.rb), lib/god/behaviors/ wraps recovery actions (clean_pid_file.rb, notify_when_flapping.rb), ext/god/ contains native C handlers (kqueue_handler.c, netlink_handler.c for efficient event loops), and examples/.god are runnable DSL configs demonstrating typical use cases.

DevOps engineers and Ruby on Rails developers who need to keep production services alive without shell scripts or heavyweight tools like Supervisor/Monit. Users write declarative Ruby configs in examples/*.god to monitor app servers, background workers, and system daemons.

God reached production maturity around 2012–2013 but shows signs of age: the repo has minimal recent commits (no .travis.yml updates for modern Ruby), no visible test directory in the file list, and documentation lives in asciidoc format rather than markdown. It remains functional for legacy Rails deployments but is not actively developed—considered stable but not recommended for new projects.

Single-author gem (Tom Preston-Werner archived after career shift), C extensions for kqueue/netlink require compilation and OS-specific maintenance, and no visible automated test suite increases regression risk on new Ruby versions. Last active period appears to be ~2012; integration with modern process managers (systemd, Docker) is absent.

No active development visible—this is a legacy-maintenance repository. The .travis.yml exists but shows no recent CI activity, and the file structure suggests the project is frozen around Ruby 1.9 era (lib/god/compat19.rb hints at that transition period). No open PRs or milestones are evident from the file manifest.

Clone and build: git clone https://github.com/mojombo/god.git && cd god && bundle install && rake build. The Gemfile and god.gemspec define dependencies; bin/god is the executable entry point. Run god -h to verify installation, then execute a sample config with god -c examples/single.god.

Daily commands: Run the daemon directly: god -c config/god.god to monitor processes defined in a *.god DSL file. Or use init scripts at init/god or init/lsb_compliant_god for systemd/upstart integration. Development: bundle exec god -c examples/single.god to test a sample config.

• lib/god.rb — Primary entry point and module definition that initializes all core components and DSL environment.
• lib/god/watch.rb — Core abstraction for monitored process watches; every process monitoring rule ultimately extends or uses this class.
• lib/god/process.rb — Process state machine that defines the lifecycle and transitions for monitored processes.
• lib/god/condition.rb — Base class for all monitoring conditions; understanding this is essential for extending God with custom monitoring logic.
• lib/god/driver.rb — Main event loop and scheduling engine that orchestrates condition checking and actions across all watched processes.
• lib/god/contact.rb — Base class for notification contacts; required for understanding how alerts propagate to external systems.
• bin/god — CLI entry point and command dispatcher that loads configuration and starts the monitoring framework.

• Watch — Wraps a monitored process

Add a new monitoring condition

1. Create new condition class in lib/god/conditions/ that extends Condition or Metric (lib/god/condition.rb)
2. Implement the test method to return true/false based on process state (lib/god/conditions/cpu_usage.rb)
3. Add configurable attributes via the Configurable mixin (lib/god/configurable.rb)
4. Reference your condition in a watch DSL block using 'notify_when' or 'restart_when' helper methods (lib/god/watch.rb)

Add a new notification contact

1. Create new contact class in lib/god/contacts/ extending Contact (lib/god/contact.rb)
2. Implement the notify method to send alerts to external system (lib/god/contacts/slack.rb)
3. Add configurable attributes (API keys, URLs, usernames) via Configurable (lib/god/configurable.rb)
4. Register contact in watch configuration using contact helper DSL (lib/god/watch.rb)

Add a new behavior for process cleanup

1. Create new behavior class in lib/god/behaviors/ extending Behavior (lib/god/behavior.rb)
2. Implement init method to execute on process startup or shutdown (lib/god/behaviors/clean_pid_file.rb)
3. Add the behavior to a watch using the 'behavior' DSL keyword (lib/god/watch.rb)

Add custom process monitoring logic

1. Define a new Watch block in your config file or examples/ (examples/single.god)
2. Configure process lifecycle (start/stop/restart commands) (lib/god/process.rb)
3. Add conditions (process_running, cpu_usage, memory_usage, http_response_code) (lib/god/conditions/process_running.rb)
4. Specify contacts for notifications and optional behaviors for cleanup (lib/god/contact.rb)

• Ruby — Enables rapid configuration and extension via DSL; low barrier to entry for DevOps workflows and custom monitoring logic
• Process polling + event handlers (kqueue/netlink) — Hybrid approach allows cross-platform support (macOS kqueue, Linux netlink) while defaulting to portable polling
• State machine (process lifecycle) — Cleanly models process states (up, restart, start, stop, exit) and prevents invalid transitions during restarts
• Multiple notification backends (email, Slack, Jabber, etc.) — Decouples alerting from core monitoring; teams can choose their preferred notification channel

• Polling-based condition checking vs. pure event-driven model

  • Why: Polling is simpler, more reliable, and works cross-platform; event handlers are optional optimizations
  • Consequence: Higher CPU/memory overhead on large process counts, but more predictable and debuggable behavior

• DSL configuration in Ruby files vs. YAML/JSON

  • Why: Ruby DSL allows dynamic logic, conditionals, and custom helpers; YAML would require more complex schema
  • Consequence: Requires Ruby knowledge to write configs; potential security risks if configs are untrusted (mitigated by local-only usage)

• Single-threaded event loop with blocking condition checks

  • Why: Simplifies state management and prevents race conditions; avoids complexity of thread synchronization
  • Consequence: Slow conditions can block other watch evaluations; mitigation is timeout-based skip logic

• In-process storage (registry, timeline) vs. external database

  • Why: Faster startup, zero external dependencies, simpler operational model
  • Consequence: Monitoring state is lost on restart; no cross-node coordination for multi-machine deployments

• Does not provide distributed process monitoring or multi-machine coordination
• Does not persist monitoring history or metrics beyond current runtime (not a time-series database)
• Does not handle process authentication or privilege escalation beyond basic sudo support
• Does not provide real-time dashboard or web UI (config-file based only)
• Does not support Windows (Unix/Linux/macOS only, per file structure and ext/ native code)

Ruby 1.9+ compatibility code (lib/god/compat19.rb) hints that upgrades to modern Ruby may require testing; C extensions must be compiled per-platform (rake compile needed post-gem-install); PID file cleanup (lib/god/behaviors/clean_pid_file.rb) is a separate behavior and not automatic—must be explicitly included in god configs or stale PIDs will prevent restarts; no env var configuration visible, configs are pure Ruby files, so secrets management is your responsibility; the daemon runs as single process and may be a bottleneck monitoring many services.

• kqueue and netlink event loops — God avoids polling process state by using OS-native event APIs (kqueue on BSD/macOS in ext/god/kqueue_handler.c, netlink on Linux); understanding these is key to why God is efficient vs. naive monitoring
• Process flapping detection — lib/god/conditions/flapping.rb and lib/god/behaviors/notify_when_flapping.rb prevent restart loops when a process fails rapidly; core pattern for stable monitoring
• Pluggable architecture via Ruby subclassing — God::Condition and God::Behavior are abstract base classes allowing users to add custom monitors/actions without forking; understanding the pattern in lib/god/condition.rb and lib/god/behavior.rb is essential to extending God
• DSL (Domain-Specific Language) via Ruby metaprogramming — God configs are pure Ruby (examples/*.god) using method_missing and block_eval patterns; users write declarative syntax ('God.watch do') that calls Ruby methods—core UX paradigm
• Condition chaining and complex logic — lib/god/conditions/complex.rb allows AND/OR logic across multiple conditions; understanding composition is needed to avoid false restarts
• PID-based process lifecycle management — God monitors processes by PID, requiring explicit cleanup (lib/god/behaviors/clean_pid_file.rb); understanding Unix process state and PID file conventions is prerequisite knowledge
• Daemon processes and signal handling — God itself runs as a daemon; the init scripts (init/god, init/lsb_compliant_god) and CLI startup logic assume POSIX signal handling for graceful shutdown

• topfunky/monit — Similar process monitoring and restart capability; Monit is compiled C with config DSL, competing tool in same space
• skarnet/s6 — Modern lightweight process supervision suite; preferred for containerized deployments where God lacks native Docker integration
• evanphx/foreman — Ruby-based process manager for development; simpler than God but less suited for production process health monitoring
• socketry/async — Modern Ruby async I/O framework; God's kqueue/netlink logic could be ported to async-based event loop for Ruby 2.7+ compatibility
• rails/rails — God's primary historical use case; Rails developers used God to keep Unicorn/Puma processes alive in production pre-systemd

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 comprehensive test suite for lib/god/conditions/ directory

The conditions directory contains 13 different condition implementations (process_running, memory_usage, cpu_usage, http_response_code, file_mtime, etc.) but there's no visible test directory in the file structure. These conditions are core to God's monitoring capabilities and lack of tests makes it risky for contributors to modify or extend them. A new contributor could add unit tests for each condition class to improve reliability and serve as documentation.

• [ ] Create test/god/conditions/ directory structure
• [ ] Add test_process_running.rb with tests for process detection edge cases
• [ ] Add test_memory_usage.rb and test_cpu_usage.rb with mock system calls
• [ ] Add test_http_response_code.rb with HTTP stub/mock responses
• [ ] Add test_file_mtime.rb and test_file_touched.rb with temporary file fixtures
• [ ] Ensure tests integrate with existing test framework (likely minitest or rspec)

Add test suite for lib/god/contacts/ directory notification plugins

The contacts directory has 10 different notification integrations (email, slack, hipchat, jabber, airbrake, sensu, etc.) that handle critical alert delivery. These are external-facing features that could silently fail without tests. A contributor should add unit tests with mocked API calls to ensure notifications don't break during refactoring and to document expected behavior for each contact type.

• [ ] Create test/god/contacts/ directory
• [ ] Add test_email.rb with SMTP stub testing
• [ ] Add test_slack.rb and test_hipchat.rb with HTTP webhook mocking
• [ ] Add test_webhook.rb with generic HTTP POST verification
• [ ] Add test_sensu.rb and test_statsd.rb with network socket mocking
• [ ] Document required credentials/environment variables in test setup

Add GitHub Actions CI workflow for Ruby versions and platform matrix

The repo has .travis.yml indicating Travis CI history, but modern GitHub-hosted repos should use GitHub Actions. God supports multiple Ruby versions and has native extensions (ext/god/ with C code for kqueue and netlink). A new contributor could add a comprehensive GitHub Actions workflow that tests across Ruby 2.7+, tests on Linux and macOS, and validates that native extensions compile correctly.

• [ ] Create .github/workflows/ci.yml workflow file
• [ ] Configure matrix for Ruby versions: 2.7, 3.0, 3.1, 3.2, 3.3
• [ ] Add separate jobs for Linux (ubuntu-latest) and macOS (macos-latest) to test kqueue vs netlink handlers
• [ ] Include steps to compile native extensions in ext/god/ directory
• [ ] Add gem dependency caching to speed up workflow runs
• [ ] Include linting step (rubocop) if not already configured

• Add comprehensive RSpec test suite for lib/god/conditions/ (currently no visible test/ directory)—start with cpu_usage.rb, memory_usage.rb, and http_response_code.rb, which have no documented test coverage.
• Modernize documentation: convert doc/god.asciidoc and doc/intro.asciidoc to Markdown in doc/ and add a 'Getting Started' section with a 5-minute tutorial using examples/single.god as the base.
• Add a systemd integration condition class (lib/god/conditions/systemd_status.rb) to detect systemd-managed service failures, filling the gap between God's native process monitoring and modern init systems.

• High · Potential Command Injection in Process Execution — lib/god/system/process.rb, lib/god/driver.rb, lib/god/cli/run.rb. The codebase is a process monitor that executes system commands and monitors processes. Without seeing the actual implementation in lib/god/system/process.rb and lib/god/driver.rb, there is significant risk of command injection if user input (from config files or CLI) is not properly sanitized before being passed to system calls or exec operations. Fix: 1) Always use parameterized execution (e.g., system([cmd, arg1, arg2])) instead of string interpolation for shell commands. 2) Validate and sanitize all process names, commands, and arguments. 3) Use allowlists for permitted commands and process names. 4) Avoid using shell=true when spawning processes.
• High · Unsafe Network Communication in Monitoring Plugins — lib/god/contacts/webhook.rb, lib/god/contacts/hipchat.rb, lib/god/contacts/campfire.rb, lib/god/contacts/slack.rb, lib/god/contacts/twitter.rb, lib/god/contacts/airbrake.rb, lib/god/contacts/sensu.rb. Multiple contact plugins (webhook.rb, hipchat.rb, campfire.rb, slack.rb, twitter.rb, airbrake.rb, sensu.rb) make HTTP requests and communicate with external services. These may transmit sensitive data or credentials over unencrypted channels, or use insecure SSL/TLS configurations. Fix: 1) Enforce HTTPS/TLS for all external communications. 2) Implement certificate pinning for critical integrations. 3) Validate SSL certificates properly. 4) Never transmit API keys or credentials in plain text. 5) Use environment variables or secure vaults for credentials, not hardcoded values.
• High · Potential Privilege Escalation Risk — init/god, init/lsb_compliant_god, lib/god/driver.rb. God is a privileged process monitor that likely runs as root or with elevated privileges to monitor and restart system processes. The codebase includes shell scripts (init/god, init/lsb_compliant_god) that may not properly validate inputs before executing commands with elevated privileges. Fix: 1) Minimize privileges to only what is necessary. 2) Validate all input to privileged operations. 3) Use drop-privilege mechanisms after initialization. 4) Audit shell scripts for injection vulnerabilities. 5) Implement proper access controls and logging for privileged operations.
• Medium · Hardcoded Credentials Risk in Configuration Examples — examples/gravatar.god, examples/events.god, examples/single.god. Example configuration files (examples/gravatar.god, examples/events.god, examples/single.god) may contain hardcoded credentials, API keys, or sensitive configuration that users might copy directly into production configurations. Fix: 1) Remove all sensitive data from example files. 2) Use placeholder comments (e.g., # API_KEY_HERE) instead of real credentials. 3) Document how to properly load credentials from environment variables or secure vaults. 4) Add warnings in documentation about not hardcoding secrets.
• Medium · Unsafe File Operations and Path Traversal — lib/god/behaviors/clean_pid_file.rb, lib/god/behaviors/clean_unix_socket.rb, lib/god/conditions/file_mtime.rb, lib/god/conditions/file_touched.rb. The codebase handles file operations (clean_pid_file.rb, clean_unix_socket.rb, file_mtime.rb, file_touched.rb) without visible path validation. This could allow path traversal attacks if file paths are user-controlled or derived from untrusted input. Fix: 1) Validate and sanitize all file paths. 2) Use allowlists for permitted directories and files. 3) Implement strict path canonicalization. 4) Avoid following symlinks without explicit validation. 5) Use Pathname.expand_path and verify the result is within expected directory.
• Medium · Missing Input Validation in HTTP Monitoring — lib/god/conditions/http_response_code.rb. The http_response_code condition monitors HTTP responses but may not properly validate hostnames, URLs, or SSL configurations, potentially enabling SSRF attacks or allowing connections to internal/restricted networks. Fix: 1

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.