Hama.bundle's only two release tags are a decade old and named as prose

The only two tags are a decade old, and neither is a version number

The release list has two entries and they are worth reading as a pair. One is tagged as the first release, described as version-independent packages, in April 2016. The other is tagged as a beta, described as a major re-write test release, in February 2017. So the first tag's version information is in its descriptive suffix and the second tag's is a word meaning an unstable build, and the descriptive suffix for the second one contains a spelling error that has been part of the tag name ever since. Neither tag parses as a version, which means there is no way to ask this repository what version is installed. The maintenance signal you have instead is the last push, which is in mid-2026, so the code is being touched while the release history stayed still a decade ago.

The code is under Contents/ and the Plex identity is a different name

The top level of the tree has four entries: a directory called Contents, a plugin descriptor, the licence, and the readme. There is no source directory in the conventional sense because this is a plugin bundle rather than a library, and the descriptor is the file the media server reads to know what the plugin is. Inside the data directory the agent writes to, the path carries the plugin identifier with the vendor prefix the server expects, which is a different name from both the repository and the project. The readme also credits the original author and dates their contribution to a specific version in 2015, so the project's own account of its history starts with someone else. From there the provenance branches twice more: the mapping files belong to a third party and are used with his stated approval, and a separate fork of that mapping work exists specifically for this agent.

Three mapping files are fetched from a host name that is not the raw host

The agent downloads three mapping files at runtime, and the page gives the download address for each. Two of them are given as raw file addresses on a host written as a shortened form of the raw content domain, and the third is given as a link on the same shortened host. The working host for serving a repository's raw files is the longer form; the shorter one is not the same host and is not the one the readme links to elsewhere. So the mapping files, which are what the agent needs to convert an AniDB identifier into a television database identifier and a studio, are fetched from an address that should be checked before you rely on it. If those three downloads silently fail, the failure does not look like a download failure: it looks like an agent that cannot match anything.

The title database is fetched over plaintext, and cached for a week

The largest data file is the AniDB title database, and the address given for it, and for its API reference page, is unencrypted. So is the permalink format the agent uses inside its own error reports, which point back to an AniDB query page over the same scheme. The caching model is a three-tier fallback and it is worth knowing the order: the internet first, using the media server's cache for a week, then a local copy, then a copy bundled as a resource, and the downloaded file is written into the agent's data folder so it survives a connection failure. A week of server cache plus a local copy means a stale title list is the normal case rather than the exceptional one, which is fine for a metadata agent and means a newly aired series will not match until the cache turns over.

The error reports are the contribution pipeline

This is the part of the design worth stealing. When the agent cannot complete a match, instead of logging a line it writes a named HTML report, and the page lists the report types: posters missing on one side, summaries missing, mapping entries missing a particular identifier, studio logos missing, season posters missing. Each report contains a permalink straight to the relevant page on the source database, so a user who hits the failure does not have to reconstruct the identifier by hand to file it. The stated purpose is to make it easier for the community to update the source databases and to add missing entries, and it names the benefit as being for everyone's sake. So a broken install is also a contribution. The corollary is that the reports are a maintenance queue: a site with old mapping files generates a lot of them, and nothing in the agent acts on them.

The report examples in the readme are wrapped in italics so they render as prose

Two of the report examples are meant to show the contents of a generated file, and both are formatted as inline code containing a block of preformatted text. The readme wraps each one in underscores, which is markdown for italics, so the opening and closing underscores render as literal characters and the whole example collapses into a run of prose rather than appearing as a file sample. It is a small formatting slip and it matters here more than it usually would, because this example is the only place the report format is shown at all.

<pre><code>anidbid: 266 | Title: 'Case Closed' | AniDB and anime-list are both missing the studio</code></pre>

The report itself carries a link to the source record as well as the identifier and the title, so the shape is a row of fields rather than a sentence, and the italics around it are obscuring exactly the thing a reader needs to see.

Posters are de-duplicated by using a rank field as a rotation index

Two mechanisms prevent a series from getting the same poster as another one, and both lean on data the agent does not own. The mapping file assigns a poster to each AniDB identifier, and the readme says the purpose is to avoid poster duplicates. Separately, the position of an entry in the mapping is used to rotate which poster a series gets, so two related series sharing a franchise pick different artwork rather than the same poster. That is a clever use of an ordering field for something it was not designed for, and it has an obvious failure mode: if the mapping file is regenerated with a different order, every series in the affected range changes artwork. The studio preference follows the same pattern, taking the studio from the mapping file first and falling back to AniDB, with the reason given, which is that it is often missing there.

Enabling local assets routes you through a settings path labelled legacy

Local subtitles, trailers, theme songs, backgrounds and season posters are handled by a separate agent that the media server ships, not by this one, and it is disabled for this agent by default. The readme gives the exact click path, and that path runs through a menu the server's own naming now marks as legacy. So a first-time configuration involves enabling an agent through a deprecated UI location, placing that agent before this one in the list so local files win, and following a naming convention table for eight kinds of local asset. Two further notes in the same area are candid about unfinished work: the author asks for season-zero extras to be handled as trailers, and points out that trailers can also be supplied as a URL for the server to fetch, which the agent does not yet do, so anyone without a local trailer file has no path today.

Editorial conclusion

Hama.bundle fits someone running Plex who wants anime metadata matched by AniDB identifier rather than by filename, and who is willing to install a separate scanner alongside it. Three things to know. The mapping files it depends on are fetched from a host name that is not the raw content host, so check those three downloads work before you rely on a match. The title database arrives over an unencrypted connection, which is worth knowing if you care about what your server trusts. And the two tags tell you nothing about what you have installed, because neither is a version number and both are a decade old.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. ZeroQI/Hama.bundle on GitHub