Actions and Tags drives Zotero from events, and its test script is still the placeholder npm ships
Customize your Zotero workflow.
At a glance
- What is it?
- This Zotero plugin, also known as Zotero Tag, attaches actions to eleven Zotero events and runs one of five operations when they fire, including arbitrary custom scripts shared in community discussions. The mechanics are documented well, down to the warning that a recorded keyboard shortcut may never reach the plugin. The gaps are in the packaging: no test suite, a placeholder test script, and an environment file that documents a release tool the build no longer uses.
- Who is it for?
- Actions and Tags is a good fit if your Zotero use has a rule in it, the kind of thing you keep meaning to do by hand every time an item arrives, and if you are willing to treat community scripts as code you did not write. Three things to weigh.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- windingwind/zotero-actions-tags2,874 ★ · +37
| Repository | 2026-10-02 | 2026-11-15 |
|---|---|---|
| windingwind/zotero-actions-tags | 2.8k | 2.9k |
37 Stars in the last 44 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Eleven events, and the example pairs one event with another
An action is defined by an event, an operation, some data and an optional shortcut, and the event vocabulary is the part that decides what is possible. Eleven are listed. Five concern items and their content: createItem when an item is created, openFile when an item is opened, closeTab when an item is closed, createAnnotation when an annotation is created, and changeAnnotationColor when an annotation's colour is changed. Three concern appending rather than creating: appendAnnotation, appendNote, and createNote. The last three are about the application itself: programStartup, described as triggered when the Zotero client or this plugin starts, mainWindowLoad and mainWindowUnload. The bundled example, called unread, uses that vocabulary as a pair rather than singly, tagging an item when it enters the library and removing the tag when the item is closed.
Five operations, and one of them runs code you did not write
The operation decides what happens. There are five. addTag adds tags to the target item, removeTag takes them off, and toggleTag adds them if absent and removes them if present, which is the one to reach for when the same action has to work in both directions. otherAction runs other actions by name, and customScript runs a script. The data field changes meaning with the operation: comma separated tags for the tag operations, script code for a custom script, and the names of the target actions each on its own line for otherAction. There is a small affordance for the multi line case, a button in the edit popup that opens an editor for multi line data, since a script or a list of action names will not fit on one line. The practical weight here is on customScript: that operation is what turns the plugin from an automation switch into an extension point, and the page fills it with scripts contributed through community discussions.
A recorded shortcut may still never arrive
The shortcut field can record a combination by pressing it, which is convenient, and the page then attaches a caveat that is worth reading before you rely on it. Shortcut availability depends on your operating system and window manager. Even if a shortcut is recorded successfully, it may fail if event propagation is intercepted before reaching the plugin. Some combinations, especially the arrow keys, may behave inconsistently across contexts, and the worked example given is a combination that works in the In Reader menu but not somewhere else, with the sentence cut off before it names the other place. That is the honest shape of this feature: the plugin records what you press, but delivery is negotiated with whatever else is in the keyboard path, and the failures are silent.
The test script is npm's placeholder, and the type check lives in the build
The manifest settles the testing question in one line. The test script is the placeholder npm generates for a new package, echoing an error that no test is specified and exiting with a failure. So running the test command fails by design, and there is no test directory in the tree either. What the project does check is types: the build script runs the TypeScript compiler in no emit mode before handing off to the scaffolder's build, so every build is a type check whether anyone intended that or not. That is a reasonable trade for a plugin of this size, and it is worth knowing which guarantee you actually have. Anything verified about behaviour, such as whether an action fires on the event you expected, has to come from using the plugin.
Two update manifests in the tree mean there is a beta channel
The repository carries an addon directory and two update manifests, update.json and update-beta.json, which is how a Zotero plugin publishes more than one channel. Releases move quickly when they do: v2.5.2 on 27 May 2026, then v2.6.0 on 23 August and v2.6.1 on the following day. The last push to the default branch is dated 24 August 2026, minutes before the v2.6.1 release timestamp on the same day, so that tag and the branch tip are effectively the same moment. The default branch is master. Installation itself is manual rather than managed: download the .xpi from a release, open Tools and then Addons in Zotero, use the gear icon in the top right, choose Install Add-on from file, select the file, and restart Zotero from the extensions list where the plugin now appears.
The add-on ID uses a domain that has nothing to do with the author
The manifest configuration block is where a fork has to make a decision. The add-on is named Actions and Tags for Zotero, its add-on ID is zoterotag at the euclpts.com domain, the short reference is zoterotag, the instance name is ActionsTags, and preferences live under an extensions.actionsTags prefix. None of those identifiers contain the author's GitHub handle, even though the repository and the package are both under it. That matters because the add-on ID is the identity Zotero uses when it records the plugin in a profile and when it checks for updates, so a fork that changes the ID will appear as a separate add-on alongside the original, and one that keeps it will overwrite the original on update. The same block also names the package description as three words, action it, tag it, sorted, which is the shortest statement of intent in the repository.
The env file documents a release tool the scripts no longer call
The development environment file is the most interesting document in the tree, because it has drifted. It holds the Zotero binary path, with a note that the path delimiter is escaped for win32 and that the macOS shape is the zotero executable inside the application bundle. It holds a profile path, with instructions for creating one by starting the profile manager with the -p flag, and a data directory field that is left empty so Zotero starts with its default data. A kill command variable sits commented out with a note that per platform commands are already built into the tool. Then there is a GitHub token, commented, described as being for release-it to create releases and upload assets. The manifest's release script, however, calls the scaffolder's release command, not release-it. So one of the two documents describes a release path that the package no longer uses, and anyone setting up publishing from the env file alone will be reading a stale instruction.
Two runtime dependencies, and a lint stack a generation behind
At runtime the plugin depends on two packages: a YAML parser and the Zotero plugin toolkit. Everything else is development tooling, and the versions there show their age in a way worth noting. ESLint is pinned in the 8 series while the typescript-eslint plugin and parser sit in the 6 series, next to TypeScript in the 5.9 range and Prettier in the 3.9 range. Prettier and ESLint are wired together as one lint command that formats and then fixes, with an ESLint configuration that turns on the recommended rules plus the typescript-eslint recommendations and the prettier config to keep the two from fighting. The build tooling around that is a scaffolding package, a watcher command line tool, a runner for parallel commands and a cross environment variable shim. It is a conventional TypeScript plugin layout, and the version spread is the kind of thing that gets upgraded in one pass or not at all.
Editorial conclusion
Actions and Tags is a good fit if your Zotero use has a rule in it, the kind of thing you keep meaning to do by hand every time an item arrives, and if you are willing to treat community scripts as code you did not write. Three things to weigh. Shortcuts are best effort, since the page says a recorded combination may still fail when something intercepts the event before the plugin sees it, so keep a right click menu route for every action you depend on. Custom scripts run inside your library with your privileges, so read the script before you paste it. And accept that this has no test suite, which for a plugin that edits your bibliographic data means keeping Zotero's own library backup habits rather than relying on the project.
Frequently asked questions
What does the Zotero Actions and Tags plugin do with no configuration?
It ships an example called unread that tags an item when it enters the library, whether created, imported or saved by the connector, and removes the tag when the item is closed. The tag appears as /unread in the Tags tab of the right panel.
Which events can trigger a Zotero Actions and Tags action?
Eleven: createItem, openFile, closeTab, createAnnotation, createNote, appendAnnotation, appendNote, changeAnnotationColor, programStartup, mainWindowLoad and mainWindowUnload. They cover item and content lifecycle, appending notes and annotations, and application startup and window load.
What operations can a Zotero Actions and Tags action perform?
Five: addTag, removeTag, toggleTag, otherAction and customScript. The data field holds comma separated tags for the tag operations, script code for a custom script, and the names of the target actions each on its own line for otherAction.
Does zotero-actions-tags have automated tests?
No. The test script in the manifest is the placeholder that prints an error saying no test is specified and exits with a failure, and the tree has no test directory. The build script does run the TypeScript compiler in no emit mode before the scaffolder build, so builds are type checked.
How do I install the Zotero Actions and Tags plugin?
Download the .xpi from a release, then in Zotero open Tools and Addons, click the gear icon, choose Install Add-on from file, select the downloaded file, and restart Zotero from the extensions list. The page notes that Firefox users have to right click the file and save it before the install dialog can see it.
Does zotero-actions-tags publish a beta channel?
The tree carries two update manifests, update.json and update-beta.json, alongside an addon directory, which is how a plugin publishes more than one channel. Recent releases were v2.5.2 in May 2026, v2.6.0 on 23 August and v2.6.1 on 24 August.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/windingwind-zotero-actions-tags)Star history chart for your README
[](https://hysenlabs.com/projects/windingwind-zotero-actions-tags)Was this useful?