RubyCritic: aggregated code quality reports for Ruby projects

What problem RubyCritic addresses

Reek, Flog, and Flay are widely used Ruby static analysis tools that each target a different quality dimension. Reek detects code smells (design patterns known to make code harder to maintain). Flog measures method complexity by assigning a score to each Ruby construct. Flay identifies duplicated code. Running all three separately produces three separate outputs with different formats and different threshold concepts, which makes it difficult to track overall code quality over time.

RubyCritic solves this by running all three analyzers against the same codebase, combining their results into a single HTML report with a numeric quality score per file, and rolling those up into a project-wide score. Engineers can set a minimum passing score and compare scores between branches, making the combined metric usable as a CI gate.

What Reek, Flog, and Flay each contribute

Reek analyzes Ruby source files for named code smells such as long parameter lists, feature envy, and uncommunicative variable names. RubyCritic uses Reek's default configuration loading mechanism, so any existing .reek configuration file at the project root is honored automatically.

Flog scores every class and method based on the complexity of the Ruby constructs they contain. RubyCritic applies three configuration tweaks to the default Flog settings: the all option forces scores on all classes and methods rather than stopping at an internal threshold; the continue option prevents Flog from aborting when it encounters an unparseable file; and the methods option skips code outside of method definitions, which prevents false positives from Rails macros such as before_action and has_many.

Flay detects structural duplication across Ruby files. RubyCritic uses Flay's default configuration without modification.

A Ruby class from the README illustrates how the raw analyzer output is converted into the report:

class Dirty
  def awful(x, y)
    if y
      @screen = widgets.map {|w| w.each {|key| key += 3}}
    end
  end
end

This code would trigger Reek smells for nested iterators and an uncommunicative parameter name, a high Flog score for the branching and iteration, and potentially a Flay duplication match if the pattern appears elsewhere.

Installing RubyCritic and running a first report

Install via RubyGems:

gem install rubycritic

To add it to a Bundler-managed project, add the line to the Gemfile:

gem "rubycritic", require: false

Then install with:

bundle

Run analysis on the current directory:

rubycritic

To scope analysis to specific paths:

rubycritic app lib/foo.rb

By default, RubyCritic generates an HTML report and opens it in the browser. The report is saved to tmp/rubycritic unless a different path is set with -p. Use --no-browser to skip the automatic browser open, which is required for CI environments.

CI mode, branch comparison, and score thresholds

RubyCritic includes a CI mode activated with -m that analyzes only the diff between the current state and a base branch (main by default). This is faster than a full scan because only changed files are analyzed. The base branch can be overridden with -b.

A minimum score threshold for the entire project is set with -s:

rubycritic --minimum-score 95

A threshold for score decrease between two branches uses -t. This is used together with -b to ensure that a pull request does not lower the score below a set delta. These two flags work independently: -s gates the absolute score and -t gates the relative change.

A .rubycritic.yml configuration file at the project root can set all options persistently:

mode_ci:
  enabled: true
  branch: 'production'
branch: 'production'
path: '/tmp/mycustompath'
minimum_score: 95
formats:
  - console

The available output formats are html (the default), json, console, and lint. Console format writes results to standard output suitable for terminal review; lint format produces output compatible with linting tools. Custom formatters can be loaded with --custom-format path:classname.

Rake task integration

RubyCritic can be called from a Rake task using the provided RakeTask class:

require "rubycritic/rake_task"

RubyCritic::RakeTask.new

This creates a rake rubycritic task with default settings. A more detailed Rake task configuration supports setting the task name, file glob pattern, and command-line options directly through the task object. The Rake integration is the typical entry point for teams running quality checks as part of a rake test or rake ci pipeline.

The README also mentions guard-rubycritic as a Guard plugin that automatically re-runs analysis when Ruby files are modified. For continuous feedback during development rather than CI gating, this provides near-immediate quality feedback without running the full suite manually.

Where RubyCritic falls short

The quality score is a composite that combines smell count, Flog complexity, and Flay duplication into a single number per file. The aggregation makes it easy to track trends, but it obscures which underlying analyzer is driving a low score. A file with many Reek smells and a file with high Flog complexity can have identical scores, requiring a look at the HTML report to understand the actual issue.

RubyCritic's source control integration, which compares uncommitted changes against the last commit, supports only Git, Mercurial, and Perforce. The README includes a warning that if the code looks different than expected after running RubyCritic, the user should check their source control stash, implying the tool may interact with stash state in unexpected ways.

The last push to the repository was on 2026-06-24. The project does not publish GitHub releases; versioning is tracked through gem releases on RubyGems.org.

RuboCop is the most common Ruby analysis alternative. Where RubyCritic focuses on structural quality and complexity through Reek, Flog, and Flay, RuboCop enforces style conventions and detects a broader range of linting issues through a large set of configurable cops. The two tools are complementary rather than competing: RuboCop finds style violations and many correctness issues, while RubyCritic surfaces deeper design and complexity problems.

Editorial conclusion

RubyCritic is appropriate for Ruby teams who want a single score and report surface combining smell detection, complexity scoring, and duplication analysis. It is less useful for teams who already run Reek, Flog, and Flay individually and have separate thresholds per tool, since RubyCritic adds a combined score on top rather than replacing those workflows. Before adopting it in CI, verify that the minimum score threshold set with -s and the branch comparison threshold set with -t reflect the actual quality baseline of the project: the default minimum score is 0, which means any score passes without adjustment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. whitesmith/rubycritic on GitHub