earl-bot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d920b59998a582669ec68fa575d136973e407d257948be9d2636ce4f96f3c12
+  data.tar.gz: 8791905132f6793c8524722e5c444cc6b69399dd838e2a64cc361d84f1e8bdb2
+SHA512:
+  metadata.gz: '08270a52ad3c2a47df4abd30ce4e116dbacc65a4cdec0631908c577456aa62963e09535c4549750da61faad654f81e0a6596caca37798570ccc33aac155dbb39'
+  data.tar.gz: b35cc27ffaef9b382cea42313f7bb237c250e52083c563d383abb2f06be0557a60c76e9c6cb6e3656805ac3fa543aae79ee77d6303532a980d513f0927d5d180

data/.ruby-version

@@ -0,0 +1 @@
+ruby-4.0.1

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-24
+
+Initial public release. EARL has been in active personal use since June 2025,
+running ~96 commits of development before this first tagged release.
+
+### Added
+
+- **Core bot** — WebSocket connection to Mattermost, message routing, and Claude CLI spawning
+- **Streaming responses** — first text chunk creates a post, subsequent chunks update via debounced PUT
+- **Session persistence** — follow-up messages in same thread reuse the same Claude context; sessions survive restarts
+- **Permission approval** — tool use gated by Mattermost emoji reactions via MCP sidecar server
+- **Persistent memory** — markdown-based memory files (SOUL.md, USER.md, daily notes) injected into Claude sessions
+- **Memory MCP tools** — `save_memory` and `search_memory` for Claude to manage its own memory
+- **Heartbeat scheduler** — cron, interval, and one-shot (`run_at`) scheduled tasks that spawn Claude sessions
+- **Heartbeat MCP tool** — `manage_heartbeat` for Claude to CRUD heartbeat schedules at runtime
+- **Tmux session supervisor** — Mattermost as control plane for all running Claude sessions (EARL-managed and standalone)
+- **Tmux MCP tool** — `manage_tmux_sessions` for Claude to list, capture, approve, spawn, and kill tmux sessions
+- **GitHub PAT MCP tool** — Safari automation for creating fine-grained GitHub personal access tokens
+- **Commands** — `!help`, `!stats`, `!stop`, `!kill`, `!compact`, `!cd`, `!permissions`, `!heartbeats`, `!usage`, `!context`, `!sessions`, `!session`, `!restart`, `!spawn`, `!update`, `!escape`
+- **Dev/prod environments** — simultaneous dev and prod instances with separate config, bots, and channels
+- **Claude HOME isolation** — EARL's Claude sessions use an isolated config directory
+- **Thread context** — new sessions in existing threads get Mattermost transcript for context
+- **Message queuing** — per-thread message queue for busy sessions
+- **Graceful shutdown** — SIGINT/SIGTERM pauses sessions; SIGHUP restarts in-place
+- **Install script** — `earl-install` sets up config dirs, clones prod repo, creates wrapper
+
+### Changed
+
+- Converted from Rails application to standalone Ruby gem (`earl-bot`)
+- Replaced Rails test infrastructure with plain Minitest
+- Simplified Gemfile from 92 lines (Rails + ~30 gems) to gemspec + 1 runtime dependency
+
+[0.1.0]: https://github.com/ericboehs/earl/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,260 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**EARL** (Eric's Automated Response Line) is a Ruby CLI bot that connects to Mattermost via WebSocket, listens for messages in configured channels, spawns Claude Code CLI sessions, and streams responses back as threaded replies.
+
+This is a standalone Ruby gem (`earl-bot`) with one runtime dependency (`websocket-client-simple`).
+
+Reference implementation: [claude-threads](https://github.com/anneschuth/claude-threads) (TypeScript/Bun).
+
+## Environments
+
+EARL supports dev and prod running simultaneously with separate config, bots, and channels.
+
+| | Production | Development |
+|--|-----------|-------------|
+| **Config root** | `~/.config/earl/` | `~/.config/earl-dev/` |
+| **Repo checkout** | `~/.local/share/earl/` (stable clone) | `~/Code/ericboehs/earl/` (working copy) |
+| **Start command** | `earl` (from `~/bin/earl`) | `exe/earl` (from repo, direnv loads `.envrc`) |
+| **Bot account** | `@earl` | `@earl-dev` |
+| **Detection** | `EARL_ENV` unset or `production` | `EARL_ENV=development` via direnv |
+
+Config root is derived from `EARL_ENV` via `Earl.config_root`. All file paths (sessions, memory, heartbeats, MCP configs, allowed tools) are relative to the config root.
+
+## Running
+
+```bash
+# Development (from repo checkout, direnv sets EARL_ENV=development)
+exe/earl
+
+# Production (from ~/bin wrapper, uses ~/.local/share/earl/)
+earl
+
+# Restart a running instance (sends SIGHUP via PID file)
+exe/earl restart   # dev
+earl restart       # prod
+```
+
+Requires env vars (see `<config_root>/env` or `.envrc`):
+- `EARL_ENV` — Environment: `production` (default) or `development`
+- `MATTERMOST_URL` — Mattermost server URL
+- `MATTERMOST_BOT_TOKEN` — Bot authentication token
+- `MATTERMOST_BOT_ID` — Bot user ID (to ignore own messages)
+- `EARL_CHANNEL_ID` — Default channel to listen in
+- `EARL_CHANNELS` — Multi-channel config (comma-separated `channel_id:/working/dir` pairs, e.g. `chan1:/path1,chan2:/path2`)
+- `EARL_ALLOWED_USERS` — Comma-separated usernames allowed to interact
+- `EARL_SKIP_PERMISSIONS` — Set to `true` to use `--dangerously-skip-permissions` instead of MCP approval
+- `EARL_CLAUDE_HOME` — Custom HOME for Claude subprocesses (default: `<config_root>/claude-home`)
+
+Optional config files (under `<config_root>/`):
+- `heartbeats.yml` — Heartbeat schedule definitions
+- `memory/` — Persistent memory files (SOUL.md, USER.md, daily notes)
+- `earl.pid` — PID file for running instance (used by `earl restart`)
+- `sessions.json` — Session persistence store
+- `allowed_tools/` — Per-thread tool approval lists
+- `tmux_sessions.json` — Tmux session metadata persistence
+- `claude-home/` — Default working directory for Claude subprocesses (project-level CLAUDE.md lives here)
+- `env` — Environment variables for launchd/wrapper (secrets, config)
+- `logs/` — stdout/stderr logs when running via launchd
+
+## Setup
+
+```bash
+exe/earl-install
+```
+
+On first run this creates env files for both environments — fill in secrets and re-run. On subsequent runs it:
+1. Creates config dirs for both dev (`~/.config/earl-dev/`) and prod (`~/.config/earl/`)
+2. Copies default Claude project config to both `claude-home/` dirs
+3. Clones the repo to `~/.local/share/earl/` (prod)
+4. Creates `~/bin/earl` wrapper script (prod)
+
+### Claude Project Directory
+
+Claude subprocesses spawned by EARL use `<config_root>/claude-home/` as their default working directory (when no channel-specific working dir is configured). This lets EARL have its own project-level `CLAUDE.md` without polluting other repos. Claude uses the real `$HOME` for global config and credentials. Override with `EARL_CLAUDE_HOME` env var.
+
+## Architecture
+
+```
+exe/
+  earl                          # Entry point
+  earl-install                  # Setup script: config dirs, prod clone, ~/bin/earl wrapper
+  earl-permission-server        # MCP permission server (spawned by Claude CLI as subprocess)
+bin/
+  ci                            # CI pipeline runner
+  claude-context                # Context window usage helper (spawned by !context command)
+  claude-usage                  # Claude usage helper (spawned by !usage command)
+  coverage                      # Coverage report generator
+~/bin/earl                      # Production wrapper (generated by exe/earl-install)
+lib/
+  earl.rb                       # Module root, requires, shared logger, env/config_root
+  earl/
+    version.rb                  # Earl::VERSION
+    config.rb                   # ENV-based configuration
+    logging.rb                  # Shared logging mixin
+    formatting.rb               # Shared number formatting helpers
+    permission_config.rb        # Shared permission env builder
+    tool_input_formatter.rb     # Shared tool display formatting
+    mattermost.rb               # WebSocket + REST API client
+    mattermost/api_client.rb    # HTTP client with retry logic
+    claude_session.rb           # Single Claude CLI process wrapper
+    claude_session/
+      stats.rb                  # Usage statistics tracking (Struct)
+    session_manager.rb          # Maps thread IDs -> Claude sessions
+    session_manager/
+      persistence.rb            # Session pause/resume persistence
+      session_creation.rb       # Session creation and resume logic
+    session_store.rb            # Persists session metadata to disk
+    streaming_response.rb       # Mattermost post lifecycle (create/update/debounce)
+    message_queue.rb            # Per-thread message queuing for busy sessions
+    command_parser.rb           # Parses !commands from message text
+    command_executor.rb         # Executes !help, !stats, !stop, !kill, !escape, !compact, !cd, !permissions, !heartbeats, !usage, !context, !sessions, !session, !update, !restart, !spawn
+    command_executor/
+      constants.rb              # Help table, dispatch map, script paths
+      lifecycle_handler.rb      # !restart, !update handlers
+      heartbeat_display.rb      # !heartbeats display formatting
+      session_handler.rb        # !sessions, !session subcommand handlers
+      spawn_handler.rb          # !spawn handler
+      stats_formatter.rb        # !stats display formatting
+      usage_handler.rb          # !usage, !context handlers
+    question_handler.rb         # AskUserQuestion tool -> emoji reaction flow
+    question_handler/
+      question_posting.rb       # Question post creation and cleanup
+    runner.rb                   # Main event loop, wires everything together
+    runner/
+      idle_management.rb        # Idle session detection and cleanup
+      lifecycle.rb              # Startup, shutdown, restart logic
+      message_handling.rb       # Incoming message processing
+      reaction_handling.rb      # Emoji reaction event processing
+      response_lifecycle.rb     # Claude response streaming callbacks
+      service_builder.rb        # Dependency construction
+      startup.rb                # Channel resolution, initial logging
+      thread_context_builder.rb # Thread transcript for new sessions
+    cron_parser.rb              # Minimal 5-field cron expression parser
+    heartbeat_config.rb         # Loads heartbeat definitions from YAML
+    heartbeat_scheduler.rb      # Runs heartbeat tasks on cron/interval/one-shot schedules; auto-reloads config
+    heartbeat_scheduler/
+      config_reloading.rb       # Auto-reload config on file change
+      execution.rb              # Heartbeat task execution
+      heartbeat_state.rb        # Per-heartbeat mutable state (Data.define)
+      lifecycle.rb              # Start/stop/pause/resume lifecycle
+    tmux.rb                     # Tmux shell wrapper (list sessions/panes, capture, send-keys, wait-for-text)
+    tmux/
+      parsing.rb                # Tmux output parsing helpers
+      processes.rb              # Process detection on TTYs
+      sessions.rb               # Session/pane listing
+    tmux_session_store.rb       # JSON persistence for tmux session metadata
+    tmux_monitor.rb             # Background poller: detects questions/permissions in tmux panes, forwards via Mattermost reactions
+    tmux_monitor/
+      alert_dispatcher.rb       # Mattermost alert posting
+      output_analyzer.rb        # Pane output state detection
+      permission_forwarder.rb   # Permission prompt forwarding
+      question_forwarder.rb     # Question prompt forwarding
+    safari_automation.rb        # Safari AppleScript automation for GitHub PAT creation
+    mcp/
+      config.rb                 # MCP server ENV-based config
+      handler_base.rb           # Base class for MCP tool handlers
+      server.rb                 # JSON-RPC 2.0 MCP server over stdio
+      approval_handler.rb       # Permission approval via Mattermost reactions
+      memory_handler.rb         # save_memory / search_memory MCP tools
+      heartbeat_handler.rb      # manage_heartbeat MCP tool (CRUD heartbeat schedules)
+      tmux_handler.rb           # manage_tmux_sessions MCP tool (list, capture, approve, spawn, kill)
+      github_pat_handler.rb     # GitHub PAT creation via Safari automation
+    memory/
+      store.rb                  # File I/O for persistent memory (markdown files)
+      prompt_builder.rb         # Builds system prompt from memory store
+```
+
+### Message Flow
+
+```
+User posts in channel
+  -> Mattermost WebSocket 'posted' event
+  -> Runner checks allowlist
+  -> CommandParser checks for !commands
+     -> If command: CommandExecutor handles it (!help, !stats, !kill, !cd, !restart, !sessions, !session, !spawn, etc.)
+     -> If message: MessageQueue serializes per-thread
+  -> SessionManager gets/creates ClaudeSession for thread
+     -> Resumes from session store if available
+     -> Builds MCP config for permission approval
+     -> Injects memory context via --append-system-prompt
+  -> For new sessions in existing threads: fetches Mattermost thread transcript for context
+  -> session.send_message(text) writes JSON to Claude stdin
+  -> Claude stdout emits events (assistant, result, system)
+     -> on_text: StreamingResponse creates POST or debounced PUT
+     -> on_tool_use: StreamingResponse shows tool icon + detail
+     -> on_tool_use(AskUserQuestion): QuestionHandler posts options, waits for reaction
+     -> on_complete: final PUT with stats footer, process next queued message
+  -> User sees threaded reply in Mattermost
+```
+
+### Key Details
+
+- **WebSocket events**: `data.post` is a nested JSON string requiring double-parse
+- **Claude CLI**: spawned with `--input-format stream-json --output-format stream-json --verbose`
+- **Permissions**: Default uses `--permission-prompt-tool mcp__earl__permission_prompt --mcp-config <path>` for interactive approval via Mattermost reactions. Set `EARL_SKIP_PERMISSIONS=true` for `--dangerously-skip-permissions`.
+- **Streaming**: first text chunk creates a POST, subsequent chunks do PUT with 300ms debounce
+- **Sessions**: follow-up messages in same thread reuse the same Claude process (same context window)
+- **Session persistence**: sessions are saved to `~/.config/earl/sessions.json` and resumed on restart
+- **Shutdown**: SIGINT/SIGTERM triggers graceful shutdown: stops background services, pauses all sessions, then exits.
+- **Restart**: `!restart` (Mattermost), `SIGHUP` (signal), or `earl restart` (CLI). In prod, runs `git pull --ff-only` first (non-fatal on failure). Pauses sessions, then `Kernel.exec` replaces the process in-place. Sessions resume on boot. PID file at `<config_root>/earl.pid` enables CLI restart.
+- **Memory**: Persistent facts stored as markdown in `~/.config/earl/memory/`. Injected into Claude sessions via `--append-system-prompt`. Claude can save/search via MCP tools.
+- **Heartbeats**: Scheduled tasks (cron/interval/one-shot via `run_at`) that spawn Claude sessions, posting results to configured channels. One-off tasks (`once: true`) auto-disable after execution. Config auto-reloads on file change. Claude can manage schedules via the `manage_heartbeat` MCP tool.
+- **Tmux MCP tool**: `manage_tmux_sessions` tool exposes tmux session control to spawned Claude sessions. Actions: list, capture, status, approve, deny, send_input, spawn (requires Mattermost confirmation), kill.
+- **Tmux Session Supervisor**: Mattermost becomes a control plane for all running Claude sessions (both EARL-managed and standalone tmux-based). `!sessions` lists all tmux panes running Claude with per-pane status. Detection uses `list_all_panes` + `claude_on_tty?` (ps-based TTY check). `!session <name> approve/deny` remotely handles Claude CLI permission dialogs. `!session <name> status` shows AI-summarized state. `!spawn "prompt"` creates new Claude sessions in tmux. TmuxMonitor runs a background poller that detects questions and permission prompts in tmux panes and forwards them to Mattermost for reaction-based handling.
+- **Thread context**: When a Claude session is first created for a thread that already has messages (e.g., from `!` commands and EARL replies), the Mattermost thread transcript (up to 20 posts) is prepended so Claude has context for follow-up messages.
+
+## Testing with Mattermost MCP
+
+A Mattermost MCP server can be configured in `.mcp.json` (gitignored) for integration testing while EARL is running.
+
+**Available tools:** `mcp__mattermost__send_message`, `mcp__mattermost__get_channel_messages`, `mcp__mattermost__search_messages`, `mcp__mattermost__list_channels`, etc.
+
+**Example workflow — send a message and check EARL's reply:**
+```
+# Send a message to EARL (starts a new thread)
+mcp__mattermost__send_message(channel_id: "<your-channel-id>", message: "Hello EARL")
+
+# Or reply in an existing thread
+mcp__mattermost__send_message(channel_id: "<your-channel-id>", message: "!usage", reply_to: "<root_post_id>")
+
+# Read recent messages to see EARL's response
+mcp__mattermost__get_channel_messages(channel_id: "<your-channel-id>", limit: 5)
+```
+
+## Development Commands
+
+- `bin/ci` — Run full CI pipeline (7 steps: RuboCop, Reek, Bundler audit, Semgrep, Actionlint, Minitest, Coverage)
+- `rubocop` — Ruby style checking
+- `rubocop -A` — Auto-fix style violations
+- `bundle exec rake test` — Run test suite
+- `semgrep --config=r/ruby --metrics=off lib/` — Run Semgrep security scan manually
+
+## Code Quality
+
+This project uses **vanilla RuboCop, Reek, and Semgrep** with minimal global configuration. Do not:
+
+- Add `# rubocop:disable` inline comments — fix the code instead
+- Add `# :reek:` inline annotations — refactor to eliminate the smell
+- Add per-class or per-method exclusions to `.rubocop.yml` or `.reek.yml`
+- Raise thresholds or disable detectors to work around warnings
+- Use `# nosemgrep` unless the finding is a verified false positive (e.g., `Open3` with array-form arguments)
+
+Global Reek overrides (in `.reek.yml`):
+- `UtilityFunction: public_methods_only: true` — private helpers may operate on other objects
+- `TooManyStatements: max_statements: 10` — raised from default 5
+- `TooManyMethods: max_methods: 20` — raised from default 15
+
+If a linter flags something, refactor the code to satisfy it. Common Reek fixes:
+- **FeatureEnvy**: Extract accessed fields into locals, use `values_at`, or move logic onto the data object
+- **TooManyStatements**: Extract helper methods to stay under 10 statements
+- **DuplicateMethodCall**: Extract repeated calls into a local variable
+- **ControlParameter**: Replace with predicates, hash dispatch, or polymorphism
+- **DataClump**: Bundle traveling parameters into Structs or Data.define objects
+
+## Commit Messages
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/) specification.

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "overcommit", require: false
+end

data/Gemfile.lock

@@ -0,0 +1,177 @@
+PATH
+  remote: .
+  specs:
+    earl-bot (0.1.0)
+      websocket-client-simple (~> 0.9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    bundler-audit (0.9.3)
+      bundler (>= 1.2.0)
+      thor (~> 1.0)
+    childprocess (5.1.0)
+      logger (~> 1.5)
+    concurrent-ruby (1.3.6)
+    docile (1.4.1)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.2.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.3.1)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.15.0)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    event_emitter (0.2.6)
+    iniparse (1.5.0)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.27.0)
+    mutex_m (0.3.0)
+    overcommit (0.68.0)
+      childprocess (>= 0.6.3, < 6)
+      iniparse (~> 1.4)
+      rexml (>= 3.3.9)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    reek (6.5.0)
+      dry-schema (~> 1.13)
+      logger (~> 1.6)
+      parser (~> 3.3.0)
+      rainbow (>= 2.0, < 4.0)
+      rexml (~> 3.1)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rubocop (1.84.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    thor (1.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    websocket (1.2.11)
+    websocket-client-simple (0.9.0)
+      base64
+      event_emitter
+      mutex_m
+      websocket
+    zeitwerk (2.7.5)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  bundler-audit (~> 0.9)
+  earl-bot!
+  minitest (~> 5.0)
+  overcommit
+  rake (~> 13.0)
+  reek (~> 6.0)
+  rubocop (~> 1.0)
+  rubocop-rake (~> 0.7)
+  simplecov (~> 0.22)
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  bundler-audit (0.9.3) sha256=81c8766c71e47d0d28a0f98c7eed028539f21a6ea3cd8f685eb6f42333c9b4e9
+  childprocess (5.1.0) sha256=9a8d484be2fd4096a0e90a0cd3e449a05bc3aa33f8ac9e4d6dcef6ac1455b6ec
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  dry-configurable (1.3.0) sha256=882d862858567fc1210d2549d4c090f34370fc1bb7c5c1933de3fe792e18afa8
+  dry-core (1.2.0) sha256=0cc5a7da88df397f153947eeeae42e876e999c1e30900f3c536fb173854e96a1
+  dry-inflector (1.3.1) sha256=7fb0c2bb04f67638f25c52e7ba39ab435d922a3a5c3cd196120f63accb682dcc
+  dry-initializer (3.2.0) sha256=37d59798f912dc0a1efe14a4db4a9306989007b302dcd5f25d0a2a20c166c4e3
+  dry-logic (1.6.0) sha256=da6fedbc0f90fc41f9b0cc7e6f05f5d529d1efaef6c8dcc8e0733f685745cea2
+  dry-schema (1.15.0) sha256=0f2a34adba4206bd6d46ec1b6b7691b402e198eecaff1d8349a7d48a77d82cd2
+  dry-types (1.9.1) sha256=baebeecdb9f8395d6c9d227b62011279440943e3ef2468fe8ccc1ba11467f178
+  earl-bot (0.1.0)
+  event_emitter (0.2.6) sha256=c72697bd5cce9d36594be1972c17f1c9a573236f44303a4d1d548080364e1391
+  iniparse (1.5.0) sha256=36a165e98d8a250b7631c4a7f9afba32af78f089970cd6446a39771189c761f1
+  json (2.18.1) sha256=fe112755501b8d0466b5ada6cf50c8c3f41e897fa128ac5d263ec09eedc9f986
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
+  mutex_m (0.3.0) sha256=cfcb04ac16b69c4813777022fdceda24e9f798e48092a2b817eb4c0a782b0751
+  overcommit (0.68.0) sha256=bfbcd26388e024e10a3d720f03077bc9389fe7c3beac360263b6c77926bcc8d0
+  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
+  parser (3.3.10.2) sha256=6f60c84aa4bdcedb6d1a2434b738fe8a8136807b6adc8f7f53b97da9bc4e9357
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  reek (6.5.0) sha256=d26d3a492773b2bbc228888067a21afe33ac07954a17dbd64cdeae42c4c69be1
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rubocop (1.84.2) sha256=5692cea54168f3dc8cb79a6fe95c5424b7ea893c707ad7a4307b0585e88dbf5f
+  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  rubocop-rake (0.7.1) sha256=3797f2b6810c3e9df7376c26d5f44f3475eda59eb1adc38e6f62ecf027cbae4d
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  websocket (1.2.11) sha256=b7e7a74e2410b5e85c25858b26b3322f29161e300935f70a0e0d3c35e0462737
+  websocket-client-simple (0.9.0) sha256=f9a37c5e4922b35a711e21e6d73ed1e25892efa47d183203ab2f5beb4e563109
+  zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd
+
+BUNDLED WITH
+  4.0.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Eric Boehs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# EARL
+
+**Eric's Automated Response Line** — a Ruby CLI bot that connects to Mattermost via WebSocket, listens for messages in configured channels, spawns Claude Code CLI sessions, and streams responses back as threaded replies.
+
+## Installation
+
+```bash
+gem install earl-bot
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "earl-bot"
+```
+
+## Quick Start
+
+```bash
+# Configure environment
+cp .envrc.example .envrc  # or use ~/.config/earl/env
+# Fill in MATTERMOST_URL, MATTERMOST_BOT_TOKEN, etc.
+
+# Run directly
+earl
+
+# Or install dev + prod environments
+earl-install
+```
+
+## Running as a Service
+
+EARL can run as a persistent service for automatic startup and crash recovery.
+
+**Prerequisite:** [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) must be installed and authenticated.
+
+```bash
+earl-install
+```
+
+On first run this creates `~/.config/earl/env` — fill in your secrets and re-run. On subsequent runs it sets up config dirs, clones the prod repo, and creates a wrapper script.
+
+## Features
+
+- **Streaming responses** — first text chunk creates a post, subsequent chunks update via debounced PUT
+- **Session persistence** — follow-up messages in the same thread reuse the same Claude context window; sessions survive restarts
+- **Permission approval** — tool use is gated by Mattermost emoji reactions (or skip with `EARL_SKIP_PERMISSIONS=true`)
+- **Memory** — persistent facts stored as markdown, injected into Claude sessions and manageable via MCP tools
+- **Heartbeats** — scheduled tasks (cron/interval/one-shot) that spawn Claude sessions on a schedule
+- **Tmux supervision** — Mattermost becomes a control plane for all running Claude sessions (EARL-managed and standalone)
+- **Claude HOME isolation** — EARL's Claude sessions use an isolated config directory, separate from the user's personal `~/.claude/`
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `MATTERMOST_URL` | Mattermost server URL |
+| `MATTERMOST_BOT_TOKEN` | Bot authentication token |
+| `MATTERMOST_BOT_ID` | Bot user ID (to ignore own messages) |
+| `EARL_CHANNEL_ID` | Default channel to listen in |
+| `EARL_ALLOWED_USERS` | Comma-separated usernames allowed to interact |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `EARL_MODEL` | Override Claude model (e.g., `sonnet`, `opus`, `haiku`) |
+| `EARL_CHANNELS` | Multi-channel config (`channel_id:/working/dir` pairs) |
+| `EARL_SKIP_PERMISSIONS` | Set to `true` to skip permission prompts |
+| `EARL_CLAUDE_HOME` | Custom HOME for Claude subprocesses (default: `~/.config/earl/claude-home`) |
+| `EARL_DEBUG` | Enable debug logging |
+
+## Commands
+
+Users can send commands in Mattermost messages:
+
+| Command | Description |
+|---------|-------------|
+| `!help` | Show available commands |
+| `!stats` | Show session statistics |
+| `!stop` | Stop current response |
+| `!kill` | Kill Claude session for this thread |
+| `!compact` | Compact the session context |
+| `!cd <path>` | Change working directory |
+| `!sessions` | List all Claude sessions (EARL + tmux) |
+| `!session <name> status/approve/deny` | Manage tmux sessions |
+| `!spawn "prompt"` | Spawn a new Claude session in tmux |
+| `!usage` | Show Claude usage |
+| `!context` | Show context window usage |
+| `!heartbeats` | List scheduled heartbeats |
+
+## Development
+
+```bash
+bin/ci                # Full CI pipeline (rubocop + reek + tests + coverage)
+rubocop -A            # Auto-fix style violations
+bundle exec rake test # Run test suite
+```
+
+See [CLAUDE.md](CLAUDE.md) for detailed architecture documentation.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/bin/README.md

@@ -0,0 +1,21 @@
+# Developer Tools
+
+This directory contains scripts to help developers and AI assistants maintain code quality and run tests efficiently.
+
+## Key Scripts
+
+### `ci`
+Comprehensive CI pipeline that runs all checks and tests in sequence:
+RuboCop, Reek, Bundler audit, Semgrep, Actionlint, Minitest, and coverage reporting.
+
+### `coverage`
+Generates test coverage reports to help identify untested code.
+
+### `watch-ci`
+Monitors GitHub Actions CI status for the current branch, exiting on pass or fail.
+
+### `rubocop`
+Wrapper that explicitly sets the config path for consistent behavior.
+
+### `claude-context` / `claude-usage`
+Helpers spawned by `!context` and `!usage` bot commands.