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/hashicorp/serf 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 the board

• Last commit 3w ago
• 37+ active contributors
• Distributed ownership (top contributor 21% of recent commits)
• MPL-2.0 licensed
• CI configured
• Tests present

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

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.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 "cmd/serf/main.go" \\
  && ok "cmd/serf/main.go" \\
  || miss "missing critical file: cmd/serf/main.go"
test -f "cmd/serf/command/agent/agent.go" \\
  && ok "cmd/serf/command/agent/agent.go" \\
  || miss "missing critical file: cmd/serf/command/agent/agent.go"
test -f "cmd/serf/command/agent/ipc.go" \\
  && ok "cmd/serf/command/agent/ipc.go" \\
  || miss "missing critical file: cmd/serf/command/agent/ipc.go"
test -f "client/rpc_client.go" \\
  && ok "client/rpc_client.go" \\
  || miss "missing critical file: client/rpc_client.go"
test -f "cmd/serf/command/agent/config.go" \\
  && ok "cmd/serf/command/agent/config.go" \\
  || miss "missing critical file: cmd/serf/command/agent/config.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 53 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~23d)"
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/hashicorp/serf"
  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).

Serf is a decentralized service discovery and orchestration tool that uses a gossip protocol (via hashicorp/memberlist) to detect node failures, propagate events, and coordinate cluster membership without a master node. It runs lightweight agents on each node that communicate efficiently via UDP/TCP gossip to manage service discovery, configuration changes, and cluster orchestration at scale. Single-binary CLI tool with modular architecture: cmd/serf/command/ contains CLI command implementations (agent, event, force_leave, info) each with their own tests; cmd/serf/command/agent/ contains the core agent logic (agent.go, config.go, ipc.go for RPC communication); client/ provides an RPC client library for external callers; serf/ package (inferred) contains core gossip/membership logic. Configuration flows through HCL parsing into agent lifecycle management.

Infrastructure engineers and DevOps teams managing distributed systems who need lightweight, masterless cluster coordination (e.g., auto-scaling web servers, organizing memcached clusters, triggering deploys via events, updating DNS as nodes join/leave).

Production-ready but in maintenance mode. The codebase is well-structured with comprehensive tests (cmd/serf/command/*_test.go files present), CI/CD via GitHub Actions (.github/workflows/check.yml), and clear documentation (docs/index.html.markdown). However, the website was sunset in October 2024, and this is a mature HashiCorp project that is no longer actively developed—expect stability but limited feature additions.

Low risk for operations teams already using it; moderate risk for new adopters due to maintenance-mode status. Dependencies are well-maintained HashiCorp libraries (memberlist, mdns, go-metrics) and stable Go packages. No evidence of security vulnerabilities in the dependency chain visible. The main risk is that new features or major refactors are unlikely; issues may take longer to resolve.

Limited active development. The repo is in maintenance mode post-website-shutdown. GitHub workflows run checks on PRs. Focus is likely on security patches and critical bug fixes rather than feature work. No specific active milestones visible in provided data.

git clone https://github.com/hashicorp/serf.git
cd serf
go build -o serf ./cmd/serf
./serf agent -node=test-node -bind=127.0.0.1:5000 -rpc-addr=127.0.0.1:7373

Daily commands: Development: go build ./cmd/serf or use GNUmakefile. Run agent: ./serf agent -config-dir=/etc/serf -node=nodename. Join cluster: serf join <other-node-address>. Commands via RPC: serf event myevent or serf info query via client/rpc_client.go.

• cmd/serf/main.go — Entry point for the serf CLI tool; all contributors must understand how commands are dispatched and initialized.
• cmd/serf/command/agent/agent.go — Core agent implementation containing the main gossip loop, event handling, and RPC server; the backbone of Serf's orchestration.
• cmd/serf/command/agent/ipc.go — Inter-process communication server that exposes agent functionality via RPC; critical for external integrations.
• client/rpc_client.go — RPC client library that external tools and scripts use to communicate with a running Serf agent.
• cmd/serf/command/agent/config.go — Configuration parsing and validation; every deployment path depends on correct config handling.
• cmd/serf/command/agent/event_handler.go — Event routing and handler orchestration; core abstraction for reacting to cluster membership and user events.

Add a New CLI Subcommand

1. Create a new command file (e.g., cmd/serf/command/mycommand.go) implementing the Command interface with a Run() and Help() method. (cmd/serf/command/mycommand.go)
2. Register the command in the command factory in cmd/serf/commands.go by adding an entry to the commands map. (cmd/serf/commands.go)
3. Use the RPC client from client/rpc_client.go to communicate with the running agent if your command needs to query or control it. (client/rpc_client.go)
4. Write unit tests in cmd/serf/command/mycommand_test.go covering argument parsing and RPC calls. (cmd/serf/command/mycommand_test.go)

Add a New RPC Endpoint to the Agent

1. Define the RPC method and arguments in the agent's RPC handler (expand cmd/serf/command/agent/agent.go with a new receiver method like RpcMyEndpoint(args, reply)). (cmd/serf/command/agent/agent.go)
2. Add the corresponding client call in client/rpc_client.go to marshal arguments and invoke the RPC method. (client/rpc_client.go)
3. Update cmd/serf/command/agent/ipc.go to register the new RPC method on the IPC server. (cmd/serf/command/agent/ipc.go)
4. Test with integration tests in cmd/serf/command/agent/agent_test.go to verify end-to-end RPC communication. (cmd/serf/command/agent/agent_test.go)

Add Event Handler Execution (Script/Webhook)

1. Extend the event handler lookup logic in cmd/serf/command/agent/event_handler.go to recognize your handler type and invoke it. (cmd/serf/command/agent/event_handler.go)
2. Parse your handler configuration in cmd/serf/command/agent/config.go under the event handlers section. (cmd/serf/command/agent/config.go)
3. Write handler execution logic that integrates with the agent's main loop in cmd/serf/command/agent/agent.go (where events are dispatched). (cmd/serf/command/agent/agent.go)
4. Test handler invocation with mock handlers defined in cmd/serf/command/agent/event_handler_mock.go. (cmd/serf/command/agent/event_handler_test.go)

Add Agent Configuration Option

1. Add a new field to the agent config struct in cmd/serf/command/agent/config.go and parse it from the JSON/HCL config file. (cmd/serf/command/agent/config.go)
2. Use the new config value in cmd/serf/command/agent/agent.go during agent initialization or in the main event loop. (cmd/serf/command/agent/agent.go)
3. Add command-line flags in cmd/serf/command/agent/command.go if the option should be settable via CLI. (cmd/serf/command/agent/command.go)
4. Write config parsing tests in cmd/serf/command/agent/config_test.go to verify the option is correctly read and applied. (cmd/serf/command/agent/config_test.go)

• Memberlist (gossip protocol) — Decentralized, fault-tolerant cluster membership using efficient gossip; no single point of failure unlike centralized registration.
• Go net/rpc for IPC — Lightweight in-process RPC for CLI-to-agent communication; avoids heavyweight frameworks for local communication.
• mDNS (mdns library) — Enables zero-configuration discovery in local networks without external infrastructure (DNS, Consul).
• Coordinate system (Vivaldi) — Lightweight network latency estimation without dedicated measurement; enables proximity-aware operations.
• Event handlers as external executables — Language-agnostic extensibility; scripts can be written in any language (bash, Python, etc.).

• Decentralized gossip over centralized coordination

  • Why: Fault tolerance and partition tolerance without a SPOF; eventual consistency is acceptable for cluster state.
  • Consequence: Higher latency for state propagation (~seconds), not suited for real-time coordination; requires monitoring for split-brain scenarios.

• External event handlers (scripts) over built-in plugins

  • Why: Simplicity and language-agnostic extensibility; no need to recompile Serf.
  • Consequence: Higher overhead per event (process spawn); potential security risk if

Agent requires -bind (gossip address) and -rpc-addr (IPC socket) to be explicitly set; defaults may not work as expected. Event handlers are spawned as subprocesses (see event_handler.go); ensure handler scripts are executable and can access environment variables. Log levels (cmd/serf/command/agent/log_levels.go) are case-sensitive. mDNS (mdns.go) requires network permissions; may fail silently in containerized environments. IPC uses Unix sockets or TCP; ensure RPC address is not publicly exposed.

• Gossip Protocol — Serf's entire architecture is built on gossip-based propagation; understanding epidemic algorithms is essential to debug cluster convergence, message loss, and eventual consistency behavior.
• Failure Detection (SWIM Algorithm) — Serf detects node failures via the SWIM (Scalable Weakly-consistent Infection-style Process Group Membership) algorithm implemented in memberlist; this determines how quickly the cluster reacts to node deaths.
• IPC (Inter-Process Communication) — The agent communicates with CLI commands and external services via RPC over Unix sockets or TCP (ipc.go, rpc_client.go); understanding the protocol is critical for building integrations.
• Event System (Lamport Clocks / Causal Ordering) — Serf's event propagation maintains causal ordering via sequence numbers; events are guaranteed to reach all nodes eventually but ordering depends on Lamport logical clocks.
• MessagePack Serialization — Serf uses hashicorp/go-msgpack for compact binary RPC serialization; understanding the format helps debug protocol compatibility and payload sizes.
• Quorum / Consensus-Free Coordination — Unlike Raft-based systems, Serf is masterless and does not require quorum; instead it uses eventual consistency and gossip for convergence, trading strong consistency for availability.
• Log Streaming / Event Handlers — Serf spawns external event handler scripts (event_handler.go) and streams logs via log_writer.go; this subprocess lifecycle and streaming model is how operators integrate Serf into their infrastructure.

• hashicorp/consul — Successor project with service mesh; uses Serf's memberlist library internally and includes service discovery with more features (health checks, ACLs).
• hashicorp/memberlist — Core dependency: implements the gossip protocol that Serf wraps; understanding this is essential for tuning cluster behavior.
• hashicorp/mdns — Companion library for mDNS-based service discovery; used by Serf for local network discovery.
• hashicorp/go-metrics — Metrics collection library used by Serf; understanding this helps with monitoring and debugging agent performance.
• distribution/distribution — Alternative decentralized orchestration approach using different patterns; useful for understanding trade-offs vs. gossip-based systems.

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 coverage for IPC event/log/query streaming layers

The repo has multiple streaming IPC implementations (ipc_event_stream.go, ipc_log_stream.go, ipc_query_response_stream.go) with corresponding test files, but these are critical paths for agent-client communication. Given the complexity of streaming state management and error handling, these deserve expanded test coverage for edge cases like connection drops, buffer overflows, and concurrent access patterns. This directly impacts reliability of the serf agent's RPC streaming capabilities.

• [ ] Review cmd/serf/command/agent/ipc_event_stream_test.go and identify missing test scenarios (e.g., rapid subscribe/unsubscribe, stream cancellation, backpressure handling)
• [ ] Review cmd/serf/command/agent/ipc_log_stream_test.go for similar gaps and add integration tests with actual log rotation
• [ ] Review cmd/serf/command/agent/ipc_query_response_stream_test.go to test concurrent query responses and partial failure scenarios
• [ ] Add benchmarks to measure streaming performance under load

Add integration tests for agent configuration and flag parsing edge cases

The cmd/serf/command/agent/config.go file handles complex YAML/JSON configuration parsing, and flag_slice_value.go handles custom CLI flag types. Configuration bugs are high-impact and affect all users. Currently, config_test.go and flag_slice_value_test.go exist but likely don't cover malformed input, type mismatches, and OS-specific path handling (given cross-platform support for Linux/Mac/Windows).

• [ ] Expand cmd/serf/command/agent/config_test.go with tests for malformed JSON/YAML, missing required fields, and conflicting configuration options
• [ ] Add tests for environment variable interpolation and override behavior in config loading
• [ ] Expand cmd/serf/command/agent/flag_slice_value_test.go to test comma/semicolon delimiters, quoted values, and empty inputs
• [ ] Add OS-specific config path tests (Windows UNC paths, Linux $HOME expansion) in platform-specific test files

Add missing GitHub Actions workflow for cross-platform release testing

The repo supports Linux, Mac OS X, and Windows but .github/workflows/ only contains check.yml and website.yml. There's no explicit cross-platform build/test validation workflow. The .release/ directory suggests release infrastructure exists, but a public CI workflow validating builds on all three platforms before release would catch platform-specific bugs early. This is especially important for agent commands (cmd/serf/command/*) that may have OS-specific behavior.

• [ ] Create .github/workflows/release-test.yml that triggers on tags and tests serf agent build on ubuntu-latest, macos-latest, and windows-latest
• [ ] Include steps to validate key commands: serf agent, serf members, serf event, serf query on each platform
• [ ] Add step to test mDNS discovery (cmd/serf/command/agent/mdns.go) on each platform since DNS behavior varies
• [ ] Add step to build and validate serf client (client/rpc_client.go) binary compatibility across platforms

• Add missing tests for cmd/serf/command/agent/mdns.go and cmd/serf/command/agent/syslog.go to match test coverage of other agent modules; these files have no corresponding _test.go files.
• Document the event handler protocol in docs/ (currently missing): subprocess communication format, environment variables passed, exit code semantics, and callback examples.
• Implement missing RPC commands: add 'serf stats' and 'serf metrics' commands that call into agent/ipc.go to expose internal gossip metrics and memberlist state.

• High · Outdated Go Version — go.mod (go 1.19). The project specifies Go 1.19 in go.mod, which reached end-of-life in September 2023. Using outdated Go versions exposes the project to known security vulnerabilities in the Go runtime and standard library that have been patched in newer versions. Fix: Update to Go 1.21 or later (current stable version). Ensure all dependencies are compatible with the new version.
• High · Vulnerable Cryptography Dependency - golang.org/x/crypto — go.mod (golang.org/x/crypto v0.33.0). The project depends on golang.org/x/crypto v0.33.0 indirectly. While this is a recent version, x/crypto has historically contained vulnerabilities. Regular updates are necessary to maintain security. Fix: Regularly monitor and update golang.org/x/crypto to the latest version. Configure dependabot to automatically detect new versions of security-critical packages.
• Medium · Outdated DNS Library — go.mod (github.com/miekg/dns v1.1.56). The project depends on github.com/miekg/dns v1.1.56, which is behind the current stable versions. DNS libraries are critical for security as they handle network protocol parsing. Fix: Update miekg/dns to the latest stable version (currently in v1.1.x+ range). Review changelog for security fixes.
• Medium · Potential RPC Interface Exposure — cmd/serf/command/agent/ipc.go, client/rpc_client.go. The codebase contains RPC client/server implementations (rpc_client.go, ipc.go) for inter-process communication. If not properly secured, these could expose sensitive operations or data. The file 'client/rpc_client.go' and agent IPC handlers need careful authentication and authorization checks. Fix: Ensure all RPC endpoints require proper authentication. Implement rate limiting on RPC calls. Verify that IPC socket permissions are restrictive (mode 0600 or 0700). Audit all RPC methods for privilege escalation risks.
• Medium · Event Handler Potential Code Injection — cmd/serf/command/agent/event_handler.go, cmd/serf/command/agent/ipc_event_stream.go. The event handler system (event_handler.go, ipc_event_stream.go) processes external events. If event payloads are not properly sanitized before being passed to external handlers or logged, this could lead to injection vulnerabilities. Fix: Implement strict input validation and sanitization for all event payloads. Use parameterized logging where possible. Avoid executing or interpreting event data as code.
• Medium · Syslog Integration Security — cmd/serf/command/agent/syslog.go, cmd/serf/command/agent/log_writer.go. Syslog integration is present (syslog.go, log_writer.go) which could expose sensitive information if not configured correctly. Syslog messages may contain credentials, tokens, or other sensitive data. Fix: Implement log filtering to prevent sensitive data (passwords, tokens, API keys) from being logged. Use secure TLS connections for remote syslog. Ensure syslog messages are properly formatted and cannot contain newline injection attacks.
• Medium · Missing Security Headers in Agent Configuration — cmd/serf/command/agent/config.go. The agent configuration (config.go) doesn't appear to have explicit security-focused settings for TLS/encryption. Service orchestration tools should enforce secure communication by default. Fix: Ensure TLS is enforced by default for all inter-node communication. Provide clear configuration options for certificate pinning. Document security best practices in configuration examples.
• Low · Dependency Version Pinning — go.mod. While dependencies are pinned to specific versions (good practice), some indirect dependencies may not be receiving regular security updates. The go.mod file shows many transitive dependencies that should be monitored. Fix: Implement automated dependency scanning with tools like 'go list -u -m all'. Set up Dependabot to automatically create PRs for vulnerable dependencies.

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.