TypeProf runs Ruby at the type level to explain what your code actually does

An interpreter whose output is a type, not a value

TypeProf is described as an experimental type-level Ruby interpreter for testing and understanding Ruby code, and the phrase carries more weight than it looks.

An ordinary Ruby interpreter runs your program and produces values. A type-level interpreter runs your program in a way where the values are types, and the output is a description of what the code does to those types. That is a different relationship between a program and its meaning, and it is why the tool is useful for understanding code rather than only running it.

The stated purpose is testing and understanding Ruby code, and the word experimental appears in the one-line description of the repository, not as a caveat appended later. The project lives under the ruby organisation, it is MIT licensed, and the current version is 0.33.2, published on 2026-09-29, after v0.33.1 on 2026-09-09 and v0.33.0 on 2026-09-03.

That version number is the first thing to look at when you are evaluating the project. A 0.33 release means the interface is still changing. The last push to the repository was on 2026-09-29, the same day as the newest tag, so the work is current, and the project is not archived.

The audience is therefore a Ruby developer or a Ruby team who want to see what a piece of code does to its types, rather than a team looking for a type checker to put in a merge gate.

The quick start is a gem, an extension and a config file

Installation is a single gem install.

gem install typeprof

TypeProf supports Ruby 3.3 or later, and that floor is a hard requirement rather than a suggestion.

The quick start then has three steps, and the first of them is not about the gem. You install the Ruby TypeProf extension for VSCode.

code --install-extension mame.ruby-typeprof

Second, you run typeprof --init in your project root, which creates a typeprof.conf.jsonc file. The README notes that other options are available and points at typeprof.conf.jsonc for the details, and the configuration file is present in the repository as an example of what that looks like.

Third, you reopen your project in VSCode. Reopening matters, because the extension is what surfaces the results, and the point of the tool is that you read the derived types in the editor rather than in a report.

So the workflow is a loop: configure, open, read, adjust the configuration, and repeat. The generated file is a JSON with comments, so it is meant to be edited by hand as part of the process.

What the repository is actually made of

The top level of the tree is a good map of the project.

There is lib/ for the library code, a sig/ directory for signatures, a tool/ directory that presumably holds the tooling that drives the analysis, a scenario/ directory, a test/ directory, doc/ for documentation, and bin/ for the executables. The packaging is a Gemfile with a lockfile, a Rakefile, and typeprof.gemspec, and the configuration example typeprof.conf.jsonc sits at the root next to the README and the LICENSE.

The devcontainer/ directory tells you that a containerised development environment is supported, and the .github/ directory holds the automation. The README's development section asks contributors to clone the repository, install the same VS Code extension, and open the project with code typeprof, which tells you the extension is not optional in the workflow even for people working on the tool itself.

The test setup is conventional Ruby. You install the bundle and run the tests through rake.

bundle install
bundle exec rake test

For finding your way around, the README links a slide deck of good first issues, which is an unusual and useful thing for a project to publish, and a document at doc/report_guide.md on how to report bugs and propose features. The scenario/ directory alongside test/ suggests the project distinguishes between its own test suite and larger end to end scenarios, which is the shape you would expect from a tool whose behaviour depends on real Ruby programs.

The configuration file is where you steer the analysis

typeprof --init writing a configuration file is the most important part of the quick start, because it means the tool is not a single fixed analysis but something you tune per project.

The README says other options are available and directs you to typeprof.conf.jsonc for the details, and that file is checked into the repository so you can read the option set before you generate your own.

The design choice worth noticing is that the configuration is JSON with comments, the .jsonc extension. That is the format VS Code understands natively for its own settings, so the same editor that renders the results also renders the configuration with syntax highlighting and completion. For a tool whose output is read in the editor, storing its input in the editor's own configuration format is a coherent decision rather than an arbitrary one.

The two extension steps in the quick start, the marketplace install and the reopen, also point to the same conclusion about the intended workflow. TypeProf is not designed to produce a file you read later. It is designed to annotate the code you are looking at, which is why the VS Code extension appears in the installation instructions rather than in a separate section, and why the development instructions for contributors install it too.

Interpreting types rather than checking them

The difference between a type checker and a type-level interpreter is the difference between two different jobs, and it explains both what TypeProf is good at and what it is not.

A checker takes a program and a set of declared types and decides whether they are consistent. It has to be told the types, or infer them syntactically, and it answers a yes or no question about the program as written.

An interpreter takes the program and runs it at the type level, deriving what the types actually become as the code executes. Nothing has to be declared in advance for the parts you care about. The output is a description of behaviour rather than a verdict about a declaration.

For testing and understanding code, that is the more useful direction. You can point it at a method you do not understand and see what it does to its arguments and its return value, without first writing down what you think those are. For a codebase where the signatures are missing, incomplete or wrong, that is a much better starting point than asking a checker to pass or fail.

The trade-off is that the tool needs code that can actually run. A method that depends on a database, a network call or a framework with heavy setup will not produce a meaningful type in isolation, and the more of your program is executed, the more of the surrounding world the interpreter has to model.

This is also why the configuration file is the control surface. Deciding what to analyse, what to stub and what to ignore is the practical work, and the tool is built to let you decide.

Experimental, and the Ruby floor that comes with it

Two constraints define what you can expect from TypeProf today.

The first is the version number. The project is on 0.33.x, which in Ruby gem convention means the public interface can still change between patch releases. Anyone pinning it in a production build is pinning something that has not promised to be stable, and the releases themselves, three of them in September 2026, show an active rate of change rather than a slow maintenance mode.

The second is the Ruby floor of 3.3. A type-level interpreter has to model the language it interprets, and it can only model the language version it was written against. Every Ruby release that changes the semantics of a method is a new thing to model, and a tool that lags behind the runtime will give you answers about a language you are no longer writing.

Those two facts together tell you where to put it. It is a good fit for a developer exploring a codebase, for a team trying to draft RBS signatures for code that has none, and for an experiment where being wrong is cheap. It is a poor fit for a service where a type error has to be caught at merge time and the answer must be the same on every machine.

The MIT licence makes the second use easy, since the code can be read, modified and vendored without restriction, and the LICENSE file in the repository is the place to confirm the terms.

When TypeProf is the wrong tool

Three situations rule it out.

The first is a team that needs a gate rather than a lens. If your requirement is that a pull request fails when a type is wrong, an experimental interpreter that derives types by running code is the wrong shape of tool, whatever its accuracy. A checker that fails the build and a tool that explains behaviour are different products, and only one of them can be a merge gate.

The second is code that cannot be run in isolation. If the method you want to understand calls out to a database, to a payment API or to a framework with heavy initialisation, the type-level interpreter has to model all of that, and the result is either a lot of configuration or no answer. For such code, reading the code and writing the signature by hand may genuinely be faster.

The third is a project on an older Ruby. The 3.3 floor is not negotiable in the gem, so a team still on Ruby 3.2 or earlier is looking at a different tool.

There is also a workflow cost that is easy to underrate. The quick start requires the VS Code extension, a generated configuration file and an editor reopen, and the configuration file is part of the answer. A team that works primarily outside VS Code, or that wants the analysis to run in CI, will be working against the shape of the tool rather than with it.

Where it fits, though, the value is high: it turns an unfamiliar method into a documented one, quickly, without the ceremony of writing types by hand.

Editorial conclusion

TypeProf fits a Ruby team that wants to understand unfamiliar code or test a type hypothesis before writing a signature by hand, because it derives types by interpreting the program rather than by pattern matching on syntax, and it comes with a VS Code extension so the results appear in the editor. It is the wrong tool for a build that must reject bad types, because the project describes itself as experimental and its 0.33 version numbers make no stability promise, and it is the wrong tool for a project still on Ruby older than 3.3. Before adopting it, run typeprof --init in a scratch project, read the generated typeprof.conf.jsonc, and check that the Ruby version on your CI machines meets the 3.3 floor.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. ruby/typeprof on GitHub