Project

earl-bot

0.0
No release in over 3 years
There's a lot of open issues
earl-botericboehs/earlHomepageDocumentationSource CodeBug Tracker
EARL (Eric's Automated Response Line) connects to Mattermost via WebSocket, listens for messages, spawns Claude Code CLI sessions, and streams responses back as threaded replies.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
127
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
1980-01-02
Latest release
1980-01-02
 Issues
Open Issues
3
Closed Issues
7
Total Issues
10
Issue Closure Rate
70%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
3
Merged Pull Requests
22
Pull Request Acceptance Rate
88%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-02-25
Reverse Dependencies
0

 Dependencies

Development

bundler-audit
~> 0.9
minitest
~> 5.0
rake
~> 13.0
reek
~> 6.0
rubocop
~> 1.0
rubocop-rake
~> 0.7
simplecov
~> 0.22

Runtime

websocket-client-simple
~> 0.9
 Project Readme

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

gem install earl-bot

Or add to your Gemfile:

gem "earl-bot"

Quick Start

# 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

CLI Subcommands

Command Description
earl Start the bot (default)
earl home Print the claude-home directory path
earl exec <cmd> [args...] Run a command inside the claude-home directory
earl restart Send SIGHUP to a running EARL instance
earl update Pull latest code and bundle install

Examples:

# Jump into EARL's Claude project directory
cd $(earl home)

# Launch Claude CLI in EARL's project context
earl exec claude

# Resume a specific Claude session
earl exec claude --resume <session-id>

# List EARL's Claude project config
earl exec ls -la .claude/

Running as a Service

EARL can run as a persistent service for automatic startup and crash recovery.

Prerequisite: Claude CLI must be installed and authenticated.

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

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 for detailed architecture documentation.

License

This project is licensed under the MIT License.