guard/listen
60.3
Adequate · 6 November 2026
2k
lines of production code
Ruby
primary language
4
measurements over time
What this system is
This system is a Ruby gem designed to monitor file system changes across multiple operating systems, including Linux, macOS, Windows, and BSD. It provides a unified interface for detecting file additions, modifications, and removals by leveraging native OS-specific adapters or a polling fallback. The library manages the lifecycle of these listeners through a state machine and offers configuration options for filtering events and handling edge cases like symlinks.
How it got here
2012 — v3.10.1 architecture rewrite and CI migration
5 changes.
The project underwent a significant architectural rewrite for version 3.10.1, replacing the Celluloid-based implementation with a new Finite State Machine and backend adapter system. Concurrently, the gem was renamed from Listener to Listen, and the continuous integration pipeline was migrated from Travis CI to GitHub Actions with updated RuboCop configurations.
2013 — adapter rewrite and test coverage
5 changes.
The project rewrote its file-watching adapter architecture to replace the Celluloid-based implementation with a cleaner, platform-specific structure using native OS event loops. Comprehensive RSpec test suites were added to verify the new modular components, adapter lifecycle, and core file-watching functionality across different operating systems.
2014–2015 — Event architecture refactoring
7 changes.
This period focused on restructuring the library's core event handling and configuration systems. Key changes included introducing a finite state machine for lifecycle management, centralizing options into dedicated config classes, and implementing robust symlink loop detection. The work was supported by comprehensive test coverage for the new event subsystem and listener configuration.
Features
Added bin/listen script with signal handling
A new executable script, bin/listen, has been added to the project. It initializes the Listen CLI and includes specific signal handling for the INT signal (Ctrl-C) to ensure the listener stops cleanly, with a check to avoid issues on JRuby.
bin · high confidence
Behavioural changes
Introduce Listener::Config for centralized file-watching options
The library now includes a dedicated \Listener::Config\ class to manage file-watching settings. This change centralizes configuration options such as \debug\, \wait\_for\_delay\, \relative\, \force\_polling\, and \polling\_fallback\_message\ into a single structure, replacing the previous approach of passing these options directly to the listener. Users can now configure these behaviors through a unified config object, which also handles filtering options for specific adapters and the silencer component.
lib/listen/listener · high confidence
Introduce Silencer::Controller for managing listener filters
A new \Silencer::Controller\ class has been added to manage listener silencing rules. This component allows users to dynamically update ignore and only filters via methods like \append\_ignores\, \replace\_with\_bang\_ignores\, and \replace\_with\_only\, ensuring that independent listener filters are preserved and correctly reconfigured during updates.
lib/listen/silencer · high confidence
Listen gem v3.10.1: complete rewrite with new architecture
The lib/listen directory has been completely rewritten for version 3.10.1, introducing a new internal architecture that replaces the previous Celluloid-based implementation. This change introduces a new Finite State Machine (FSM) for managing listener states (initializing, backend\_started, processing\_events, paused, stopped), a new Backend class for adapter selection and configuration, and a new Change class (renamed from previous change handling) that uses an invalidate method to manage file system snapshots. The Silencer component now handles ignore/only patterns with regex support, and the QueueOptimizer squashes and reinterprets file system events (handling editor rename operations). The CLI has been updated to use Thor, and the library now includes a dedicated Logger module with configurable debug levels and adapter warning behaviors. This is a significant architectural shift that changes internal implementation details while maintaining the public API for listening to file changes.
lib/listen · high confidence
Migrate CI to GitHub Actions and update RuboCop configuration
The project has replaced Travis CI with GitHub Actions for continuous integration, removing the \.travis.yml\ file and adding a new \.rubocop.yml\ that sets the target Ruby version to 3.0.4 and enforces stricter style guidelines (e.g., single quotes, specific naming conventions). The Rakefile has been updated to include RuboCop checks in the default task and introduces a new \Releaser\ class to manage publishing gems to RubyGems and creating GitHub releases via the command line. Additionally, the \Guardfile\ now runs RuboCop alongside RSpec, and the \README\ has been overhauled to reflect the new project name 'Listen', updated badges, and current usage instructions.
(repo-wide) · high confidence
Refactored directory entry handling and symlink loop detection
The library now uses a dedicated \Listen::Record::Entry\ class to manage directory and file metadata, including size and modification time, and introduces a \SymlinkDetector\ to explicitly detect and abort on symlink loops. This change ensures consistent behavior across JRuby and MRI by handling \ENOTDIR\ errors uniformly and prevents infinite loops when watching directories containing symlinks that point back to themselves or already watched paths.
lib/listen/record · high confidence
Refactored event processing loop and state management
The event handling subsystem has been restructured to improve reliability and clarity. A new Finite State Machine (FSM) now manages the listener's lifecycle with explicit states (pre\_start, starting, started, stopped), replacing the previous implicit logic. The background processing loop has been extracted into a dedicated \Event::Processor\ class, which uses a queue-based wakeup mechanism instead of sleep/wakeup polling to handle events more efficiently. Additionally, a new \Event::Config\ class centralizes configuration options, and the \Event::Queue\ class now validates event types and paths before queuing. These changes ensure that the listener starts reliably within a timeout and handles stop requests more gracefully.
lib/listen/event · high confidence
Rename library from Listener to Listen
The gem has been renamed from 'Listener' to 'Listen'. This involves moving the main entry point to lib/listen.rb, deleting the old lib/listener.rb and lib/listener/version.rb files, and updating the module namespace from Listener to Listen. Users will need to update their require statements and references from Listener to Listen.
lib · high confidence
Rewritten adapter architecture with platform-specific implementations
The file-watching adapters have been completely rewritten to replace the previous Celluloid-based implementation with a new, cleaner structure. This introduces a shared \Base\ adapter class and dedicated platform adapters for Linux (inotify), macOS (FSEvents), Windows (wdm), BSD (kqueue), and a cross-platform polling fallback. The new design improves thread safety, error handling, and performance by using native OS-specific event loops where available, while providing a unified interface for change detection across all supported operating systems.
lib/listen/adapter · high confidence
Test coverage
Added acceptance tests for file system change detection; Added comprehensive test coverage for Listen core components; Added comprehensive test coverage for adapter components; Added specs for Listen class initialization and stop functionality; Added test coverage for the new Listen::Event subsystem; Added tests for Listen::Listener::Config; New test support infrastructure for acceptance and platform-specific specs; Updated RSpec configuration and added test helpers.
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 61 → 60 (-0.5)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 71 → 71 (+0.0)
- Architecture 87 → 87 (+0.0)
- Maturity 48 → 48 (+0.0)
- Readiness 67 → 67 (+0.1)
- Security 86 → 79 (-7.1)
Resolved (4)
- Inconsistent naming and semantics for silencing/ignoring paths. The public API exposes both ignore and ignore! on the Listener, while the internal Silencer.Controller uses append_ignores and replace_with_bang_ignores. The distinction between 'append' vs 'replace' and the use of ! for mutation is not unified across the silencing interface.
- Inconsistent naming for the 'only' filtering operation. The public Listener API uses only, while the internal Silencer.Controller uses replace_with_only. This creates confusion about whether only replaces existing filters or appends to them.
- Off-boarding risk: anonymized user #1
- Outdated: gems
New (1)
- Off-boarding risk: anonymized user #1
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
guard/listen was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 6fbde9f05fb06fdcac329481499172ff1d33757d — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.