The Potential of Ruby's ri Command for Coding Agents

This article is translated by AI, if have any corrections please let me know.

Recently, the Hono framework launched the Hono CLI tool, and I quickly created a Hono Plugin for Claude Code, adding Agent Skill support for querying documentation using Hono CLI.

At the same time, I realized that the ri (Ruby Information) command, which I rarely use, provides similar capabilities to the Hono CLI. Therefore, I created the Ruby Plugin ahead of schedule to provide the ri skill.

Context

Context plays a crucial role in the quality of content generation in current LLM (Large Language Model) applications.

This is because when we can provide sufficient information to the LLM, it becomes easier to identify the relevant keywords for subsequent content generation. When a Coding Agent encounters uncertain usage during coding, being able to autonomously search documentation through tools significantly increases the probability of writing correct code.

However, using search tools isn’t always precise, as results often mix various personal opinions or incorrect information. In such cases, the “official documentation” provided by packages becomes an extremely high-quality reference standard. It’s far better to verify official documentation first and then decide whether to search for more references, rather than relying on search engines directly.

Under this premise, using the ri command as the first option is ideal. For example, if we want to confirm the standard usage of Array#map, we only need to execute ri Array#map to get the correct information without consuming too much context.

Limitations

However, there are still some limitations when using ri. In some simple tests, it’s difficult to get Coding Agents (such as Claude Code) to naturally choose the ri skill for documentation queries, rather than relying on search or using the #source_location method to read the source code directly.

In Claude Code, the Agent Skill description is already quite prescriptive, but the inherent uncertainty of LLMs still makes it hard to ensure ri gets priority for documentation lookup. Perhaps better descriptions may emerge in the future, or LLM improvements may help address this.

The current compromise is to provide a /ruby:info command that explicitly instructs the use of the ri skill to query documentation.

/ruby:info how to use expect in rails params

This first uses ri expect to check for a related ActionController::Parameters#expect method, then uses ri 'ActionController::Parameters#expect' to read the documentation and explain it to the user.

On the other hand, it’s still unclear whether ri prioritizes the versions defined in the Gemfile, and whether all packages installed through bundle install include ri documentation by default. These factors limit the ability to leverage this long-existing tool effectively with LLMs.

Potential

Overall, using ri is a far more efficient and precise solution than searching for information online, both in terms of speed and Token consumption.

However, it’s subject to many limitations. For instance, the Ruby ecosystem has both RDoc and YARD systems. While RDoc can parse YARD content, its presentation can be limited, and we need to confirm whether this affects how ri reads documentation.

Thanks to Stan Lo’s contributions, RDoc’s HTML rendering has become very user-friendly. We should make better use of Ruby’s native RDoc to write documentation for packages.

Additionally, during testing, many packages couldn’t display documentation properly. Even when certain methods existed, there were sometimes usage issues, or the system lacked documentation saved in the ri format. These issues all limit the ability of LLMs to directly use ri to verify documentation.

It would be beneficial if ri could support automatic detection of the current directory. This would make it more developer-friendly when using Coding Agents to maintain Gems, allowing the agent to start with documentation rather than searching source code, which is much faster than using ls.