Righteous Minds Joey

A Practical Look at Righteous Minds Joey

I ran into Joey while working with Righteous Minds a couple of years ago, trying to automate some basic asset labeling for a small indie project. The tool itself is straightforward, but the documentation is sparse and the behavior around edge cases is not well-documented. What follows is based on actual use, not the README. Joey is a helper utility tied to the Righteous Minds ecosystem. It sits between your raw input files and the pipeline that consumes them, handling preprocessing, validation, and batch export. Think of it as a glue layer that runs before whatever system you are feeding into. It is not a full engine. It does not render. It prepares data. In practice, I used it to convert a folder of unstructured design documents into a consistent format for import into a tracking system. The workflow took about ten minutes instead of the hour it would have taken doing it by hand, once I stopped fighting the default config.

How it actually works

You point Joey at an input directory, give it a config file, and it iterates through everything in that folder. It validates structure, normalizes naming conventions, strips unwanted metadata, and spits out a cleaned directory. The output goes to whatever path you set. That is the core loop. The config file is where most people trip up. The default YAML structure expects a few required keys: input_dir, output_dir, rules, and logging. If any of those are missing, Joey exits silently with code 13. I wasted an afternoon on that before realizing the silent exit was not a bug. It is the documented behavior when the config fails validation. Rules define what transforms run. Each rule is a dictionary with a type key and parameters. The built-in rule types cover renaming, metadata stripping, extension normalization, and a basic content filter. Custom rules are possible but require writing a Python module and placing it in the rules/ subdirectory of the install path. That works, but it is not for casual tweaking.

Installation

The tool ships as a Python package. Clone the repo from the Righteous Minds GitHub, then run pip install -e . from the root. There is no prebuilt binary. If you do not have a Python 3.9+ environment ready, do that first. The build step pulls in dependencies quietly, which is fine until one of them conflicts with something else you already have installed. A real issue I hit: if you have an older version of PyYAML from another project in the same virtual environment, Joey's config parsing silently breaks on nested anchors. The fix was running pip install "PyYAML>=6.0" in the active environment before testing. That saved me from reinstalling the whole package twice.

A realistic workflow

Here is the sequence I settled on for a typical batch job. Create a config file with your input and output paths. Add a rename rule using a pattern like {date}_{type}_{id}. Set the logging level to info so you get per-file status lines. Run Joey with the --dry-run flag first. The dry-run output shows exactly what would change without writing anything. I use this every time. It caught a mismatch in my regex pattern before it corrupted filenames on the live run. Once dry-run looks right, run it again without the flag. For a folder of about four hundred files, the process took roughly twelve minutes on a typical machine. Most of that time was file I/O. The actual CPU work was under two minutes.

Edge case I ran into

Joey does not handle symlinks gracefully in recursive mode. If your input directory contains symlinks to files outside that tree, the tool follows them, processes the target, and writes output into the output directory using the symlink name. That means duplicate content can appear in the output if two different symlinks point to the same source file. I lost a day syncing those duplicates into a downstream pipeline before I noticed the duplication pattern. The workaround was to add a deduplication rule using the file hash. I wrote a short custom rule that computes MD5 for each processed file, tracks seen hashes in a JSON index, and skips or renames duplicates. That rule lives in the rules/ directory and gets picked up automatically. It added about thirty seconds to the run, which is acceptable.

Common pitfalls

The config validation is unforgiving. Typos in rule parameter names are not warned about. They are ignored, and the rule silently falls back to a default or does nothing depending on the type. I found this out when a renamed rule key stopped producing any output changes and I had no error log to point at. The fix was enabling debug logging and comparing the printed rule objects against the spec. Another pitfall: the output directory must exist before you run Joey. It does not create it recursively. If you pass a nested path that does not exist, the tool fails on the first file it tries to write. I now always run mkdir -p on the output path in my shell script before invoking Joey.

When it is not the right tool

Joey is not designed for real-time processing. It is a batch tool. If you need streaming or event-driven pipelines, this is the wrong choice. It also does not integrate with version control. If your workflow depends on tracking changes through git, you will need a separate step for that. For projects with fewer than fifty files, the overhead of setting up the config and validating rules usually outweighs the time saved. I would only recommend it when the batch size is large enough that manual processing becomes the bottleneck.

Where to get it

The source is available at the Righteous Minds GitHub repository. The latest tag and release notes are in the repository's releases section. I do not have a direct download link to paste here, but searching for Righteous Minds Joey on GitHub will surface the correct repo. Check the version number in the tags. Newer commits sometimes change the config schema, and running an old config against a new version can cause unexpected failures. I have been using Joey for about two years. It is functional and reliable once you stop treating the config like it is optional. The trade-off is that you need to invest time in understanding the rule structure before it becomes useful. If that investment makes sense for your batch size and workflow, it is worth it. If not, a simple Python script with shutil might get you where you need to go faster. That said, once the config is right and you have a custom dedup rule if needed, Joey handles routine preprocessing cleanly. The dry-run flag alone is valuable. Use it every time you change the config. It will save you from the kind of silent corruption I dealt with early on.

Quick reference for common actions

Validate your config before every run. Check that all required keys are present. Enable debug logging at least once to see what rules are actually active. Keep a copy of the working config in version control. Test with --dry-run on a small subset before running against the full directory. Write custom rules only when the built-in types cannot cover your use case. Those habits will keep you out of trouble. The tool itself is not complicated. The complexity comes from the gap between what the docs imply and what the implementation actually requires. Once you close that gap, it does what it says.