1.1.0 released, and a discussion about the future

[Chris Jones]

Hey folks

After a fairly inactive year, I'm pleased to announce that Hammerspoon 1.1.0 is now available with a few useful fixes/additions.

The larger discussion that needs to be had, is about the future of the project.

For the majority of its decade of life, and despite many very welcome contributions from dozens of people, the vast bulk of the maintenance work has been carried by three people - asmagill, latenightfilms and myself. I think I can speak for all three of us by saying that we have enjoyed the work very much, and enjoyed seeing the modest success that Hammerspoon has achieved.

However, it is also very much the case that in the last few years, our collective contributions have fallen to the lowest level we've ever seen. In part this is because of the demands of real life, but (at least in my case) it's also true that a very large and complicated project built from Objective C is no longer particularly attractive to work on.

Hammerspoon was built from the bones of a project called Mjolnir, which intended to be only the core Lua wrapper, with all functionality distributed separately. We felt that was the wrong choice and decided to build a "batteries included" version, and I think it would be fair to say that we succeeded very much at that. Unfortunately, we told ourselves at the time that third party modules would still be important, so we kept all of the functionality of Hammerspoon in separate small libraries, which has meant it has remained a very complicated project to build and distribute (meaning extra work for us, and a much higher barrier of entry for new contributors).

In the past we did some explorations to see what it would be like to write individual Hammerspoon extensions in Apple's more modern development language, Swift. It works, it's perfectly possible to do, but it brings some snags with the way "LuaSkin" (the surprisingly large amount of code we've written to bridge between Lua and Objective C) works. It also doesn't change the underlying architecture of separate libraries. For a while I tried to pursue an idea of building a separate Swift framework to contain all of the actual functionality of Hammerspoon, which the extensions would then bridge into Lua, but it only ever seemed to make things more complicated, not less.

So, some months ago I started out experimenting with a radically different approach - rebuild the app from scratch in Swift, with no support for third party libraries, and rather than having to rebuild LuaSkin too, I used Apple's own "JavaScriptCore" framework (the one that WebKit uses to execute JavaScript in Safari). It is nowhere near complete, and there are some design decisions I still have my doubts about, but fundamentally this looks to me like an option to bring Hammerspoon into the modern era of macOS apps, and make it dramatically more approachable for other contributors.

The elephant in the room, obviously, would be the switch from Lua to JavaScript. I will be completely honest and say that I have never really liked Lua as a language, but I'm also not especially fond of JavaScript either. I used JSC for two reasons: 1) The framework is easy to use and we don't have to maintain it, 2) JavaScript is a much more widely used language than Lua is, particularly these days when so many web developers use Macs.

At this point, I don't know what the future actually looks like - do we keep going with just Hammerspoon v1? Do we try to keep v1 alive on maintenance mode while mostly working on v2? Do we deprecate v1 entirely and push everyone into a choice to move to v2?

I'd be very interested to hear your thoughts, and I wish you all a Merry Christmas!

--

Cheers,

Chris

[Chris Jones]

For anyone who is curious about the JavaScript version, I have published a very rough demo here: https://github.com/cmsj/Hammerspoon2/releases/tag/0.0.1

--

Cheers,

Chris

[M N]

Very interesting idea to move in the Swift/JavaScript direction. I see that there are many users who are more familiar with JavaScript and Swift.

At first glance, I have the following questions and ideas:

1. Do you have an HS2 config you could share to show some examples?

2. Are JavaScript packages (for example via npm) available for inclusion in the config ecosystem?

Moving to HS2

3. Can I run HS1 and HS2 at the same time, so that I can migrate script by script from Lua to the new HS2 JavaScript?

4. I am not sure whether it makes sense to add a legacy plugin, spoon, extension, or similar that needs to be installed, set up, or activated so that HS1 Lua code can also run in HS2. I understand that running legacy code in a new HS2 environment is a burden, so this would only be an option if it is easy to implement.

Converting

5. Maybe there could be a converter from Lua to JavaScript, or some instruction Markdown files for Claude Code?

I see that there are some tools related to points 4 or 5:

- https://github.com/fengari-lua/fengari
- https://github.com/fstirlitz/luaparse

[Von Welch]

Chris,

 First, let me thank you and the other maintainers and developers for creating and maintaining Hammerspoon. I use it heavily and it greatly increases my productivity. I also applaud you for thinking carefully about its future.

 I don't think I have any great wisdom for you. I will say that I think that despite the great talent the maintainers have, their number is limited and I think trying to maintain and develop two frameworks sounds like a large load and I would caution against that course. Too often I've seen V1 become frustrating in such situations as there is an expectation of support that isn't really met anymore. I expect if you were to make the plunge to a V2, I would follow along and ideally help with the alpha/beta testing.

 I'm a half-developer at best and I've always found the Hammerspoon framework too daunting to learn how to build and directly contribute to. My experiences with JavaScript make me want to run screaming, but admit I've only used it in hacky web browser client scenarios and never as parat of a serious development framework, so take my perspective for what it is.

Happy holidays,

Von

--
You received this message because you are subscribed to the Google Groups "Hammerspoon" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hammerspoon...@googlegroups.com.
To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/CAHWFm4fZn3n0%3DkdF62w4KuHz9-tqq98YBQMK%2BSkC8it-0XsUbw%40mail.gmail.com.

[Dave Knorr]

Much love to asmagill, latenightfilms and Cris Jones for keeping Hammerspoon going. I realize it’s a tremendous effort. I don’t have much to add as far as an opinion about the direction of development other than to say I’m in favor of having a program like Hammerspoon to access. I’m a half-baked hack at best, but I do have some experience with both javascript and Swift. I have gotten a lot of use from the current implementation of Hammerspoon and at this point would be quite lost without it.

As far as specs for any future development, there is a program for Windows users called PowerPro developed and maintained by Bruce Switzer. First introduced somewhere around win2000/winNT, it allows the user to customize actions and adds many enhancements. Particularly useful to me has been the ability to create individual scripted buttons that can perform just about anything the user has access to. Simple things like keeping track of clipboard snippets, to launching an entire suite of applications with pre-positioned windows and auto-logons to whatever accounts are needed. These buttons can be gathered into pallets. Pallets of buttons can be placed on specific application windows when they are open, or left for more global access on the main desktop. There are many other functions as well. I have not found a program with similar functionality; Hammerspoon comes closest.

Thanks again for all you do. Looking forward to HS2.

Dave

[linear...@gmail.com]

Much appreciation to Chris and the Hammerspoon maintainers! With Hammerspoon being mature, I think it's fine that it's not updated often. It still works well for me and I use it a lot.

Interestingly, I did look for "Hammerspoon with Javascript" back in 2018, when I just started using Hammerspoon. I was more familiar with Javascript and reluctant to learn Lua. I learned about Hammerspoon history and found that "Sdegutis built Zephyros (Ruby OSX automation, also other Lang support), then Phoenix (JavaScript OSX Automation), then Hydra (Lua based) which became Mjolnir, which is forked to Hammerspoon." So, Javascript had been tried before, and the Phoenix project still lives on at https://github.com/kasper/phoenix . I'm curious if you know about Phoenix's history before Hammerspoon and why it didn't work as well as Hammerspoon.

After learning Lua, I think Lua is a good choice for Hammerspoon because Lua is designed to be an embeddable language. It's reasonably easy to learn and relatively stable. Javascript is a more complex language. I'm now more comfortable with Lua than Javascript because Javascript has changed a lot for me. If the goal is to make MacOS API more accessible and programmable, I'd prefer a simple and stable language. 

However, I understand Objective-C is not maintainable, and that's why you want to try Swift. I'm not familiar with MacOS development to give a perspective on Swift vs. Objective-C. If Hammerspoon moves to Javascript, I think most Hammerspoon users are programmers themselves and can move their Lua code to Javascript without much problem. I'm looking forward to it if it brings more modern features and more contributors.

Thank you and Merry Xmas!

[Chris Jones]

Hey

On Wed, 24 Dec 2025 at 17:29, M N <niet...@gmail.com> wrote:

1. Do you have an HS2 config you could share to show some examples?

This is a very simple JS config I've been using while testing. It doesn't really do very much, but it might give some hints as to what it would look like:

console.log("Hey I'm an init.js");

const hyper = ["⌘", "⌥", "⌃", "⇧"];

function eventHandler(eventName, appObject) {

console.log("INIT.JS appWatcher eventHandler: " + eventName + " " + appObject.title);

}

hs.application.addWatcher("willLaunch", eventHandler);

hs.application.addWatcher("didLaunch", eventHandler);

hs.application.addWatcher("didTerminate", eventHandler);

const safari = hs.application.matchingBundleID("com.apple.Safari")

function handler(notification, element) {

console.log("AX event: " + notification + " on: " + element.title);

}

if (safari != null) {

hs.ax.addWatcher(safari, hs.ax.notificationTypes["windowCreated"], handler);

}

hs.hotkey.bind(hyper, "4", () => { console.log("HYPER 4"); }, null);

hs.hotkey.bind(hyper, "5", () => { console.log("HYPER 5 DOWN"); }, () => { console.log("HYPER 5 UP"); });

hs.alert.show("Hammerspoon 2 Config loaded\nAll systems operational.");

watcher = hs.ax._createObserver(safari.pid);

watcher.callback((watcher, element, notification) => { console.log("AX safari window creation: " + notification); });

watcher.addWatcher(safari.axElement(), "AXWindowCreated");

watcher.start();

 

2. Are JavaScript packages (for example via npm) available for inclusion in the config ecosystem?

So, this is an area where I am out of my depth. I do know that not all JS runtimes are created equal. For example, Node provides a lot of functionality that JavaScriptCore's basic ECMAScript environment does not.

So... I don't really know what npm usage would be like, and I will likely need to defer all of that to people more familiar with the JS world than me.

 

3. Can I run HS1 and HS2 at the same time, so that I can migrate script by script from Lua to the new HS2 JavaScript?

I don't think there's any realistic way we could release HS2 through the current repo and update stream, so I would expect it to be a completely separate "Hammerspoon 2.app" and therefore you could run them at the same time.

 

4. I am not sure whether it makes sense to add a legacy plugin, spoon, extension, or similar that needs to be installed, set up, or activated so that HS1 Lua code can also run in HS2. I understand that running legacy code in a new HS2 environment is a burden, so this would only be an option if it is easy to implement.

tbh this sounds like it would be an enormous amount of work and would almost force us to shoot for 1-1 API compatibility. I would like to use this as an opportunity to re-think and improve various parts of our API.

 

5. Maybe there could be a converter from Lua to JavaScript, or some instruction Markdown files for Claude Code?

It would certainly be interesting to see how well LLMs could do at converting!

--

Cheers,

Chris

[Chris Jones]

Hey

On Thu, 25 Dec 2025 at 09:28, linear...@gmail.com <linear...@gmail.com> wrote:

 Lua. I learned about Hammerspoon history and found that "Sdegutis built Zephyros (Ruby OSX automation, also other Lang support), then Phoenix (JavaScript OSX Automation), then Hydra (Lua based) which became Mjolnir, which is forked to Hammerspoon." So, Javascript had been tried before, and the Phoenix project still lives on at https://github.com/kasper/phoenix . I'm curious if you know about Phoenix's history before Hammerspoon and why it didn't work as well as Hammerspoon.

I'd actually forgotten about Zephyros and Phoenix and I'm glad to see that Phoenix is still going!

I'm not sure I can really speak to why Hammerspoon was able to grab more attention than Phoenix in our shared decade of both existing. Looking at their API docs, it might be because we have a wider range of integrations, but I'm really not sure. These things seem to be pretty much random sometimes.

Phoenix also looks to be using JavaScriptCore, and itself is still Objective C, so in some respects I'm proposing re-inventing some of what they have done as well as all of what Hammerspoon has done.

--

Cheers,

Chris

[Diego Zamboni]

Dear Chris,

I can only echo what others have said: THANK YOU to you, asmagill and latenightfilms for maintaining Hammerspoon and for making it such an awesome tool. It's one of the first tools I install on new Macs and I recommend it everywhere I can.

I understand your reasoning for modernizing it using new technologies and more mainstream languages. I myself learned Lua because of Hammerspoon. I have to admit I found it clunky at first but you get used to it :) I'm not fluent in JS but I'm sure I could learn it as well. I'm not afraid to try new things.

Ideally I would vote for option 2 ("keep v1 alive on maintenance mode while mostly working on v2"), but I'm aware even "maintenance mode" can be a burden on time and resources. I'm happy with whatever you decide.

Thanks again, and Merry Christmas to you and everyone here as well!

--Diego

--

[Miles Wirht]

I think the objective should be the feasibility of maintaining development into the far future. I think the move to Swift and the adoptation of CoreJS would remove a lot of development burden and make it a much easier project to contribute to. I think keeping in line with this, old hammerspoon should be dropped entirely, and the new version should be treated as a direct evolution. Issues on the old should be discarded unless applicable to the new,  but PR's appropriating the old still be reviewed on a need-based basis (Under an archival repository). 

Miles

On Dec 25, 2025, at 16:48, Diego Zamboni <di...@zzamboni.org> wrote:



To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/CAGY83EesbwZAHCg6J-%2Bf0Z%3DKYojPDMFv0Ybo_tW72xGYxAsNsQ%40mail.gmail.com.

[linear...@gmail.com]

It would be nice if the Hammerspoon 1 (Objective-C + Lua) can live along with Hammerspoon 2 (Swift + JS) until users are ready to switch. Some users have lots of Lua configs that are not easy to migrate to JS in a few days, so it's a gradual process.

If I understand from [1], Objective-C can be run along from Swift. Is it possible for Hammerspoon 2 has a legacy mode or a module that just import the entire HS1 Objective-C core and run it?

[1] https://developer.apple.com/documentation/swift/importing-objective-c-into-swift

Thanks!

[Chris Jones]

Technically that sort of thing is possible, but it would be so much work that I don't think it's a good idea. More reasonable, I think, would just be to run both versions of Hammerspoon at the same time while you migrate chunks of your configuration over.

Cheers,

Chris

--

You received this message because you are subscribed to the Google Groups "Hammerspoon" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hammerspoon...@googlegroups.com.

To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/70644c1e-907a-440c-a69f-ad82877121d5n%40googlegroups.com.

--

Cheers,

Chris

[Glenn Waters]

Thank you to Chris and all the maintainers.I truly appreciate this creation and the work that went into it, and, to its predecessors. Hammerspoon is the first app that I install on any MacOS machine.

Lua or Javascript - don't care. I will figure it out no matter which direction it goes.

My preference is that if Hammerspoon 2 goes ahead, that Hammerspoon 1 goes into maintenance mode until 2 is feature comparable enough to turn off 1. By maintenance mode I mean no new features just bug fixes and fixes required to run on new MacOS releases.

With respect to Phoenix, it does look fairly good, but is missing some things. My primary use case for Hammerspoon is launching apps using hotkey sequences and window sizing/placement. It replaces all those specialize window placement apps, hotkey launchers, and Karabiner Elements for me.

This is pretty much all of what I use at the moment (https://github.com/gwww/dotfiles/tree/main/.config/hammerspoon)

• hs.alert
• hs.application
• hs.eventtap
• hs.hotkey
• hs.window
• hs.screen

My question is would throwing some support behind Phoenix be worthwhile? Although it does not meet the goal of "modern" using Swift.

Also what about Typescript? Move to JS is fine, making Typescript first class in Hammerspoon would be even better. That said, once my config is written I don't tend to touch it much, so JS would be OK.

Thanks again!

To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/CAHWFm4dsnOe%3DJ524%2B_UmeJ2OjN8EMp0LaA-JfOCOhrYsFNGEeQ%40mail.gmail.com.

[Chris Jones]

Hey

Yeah, we probably should reach out to the Phoenix folk.

As for TypeScript, I don’t see a path for supporting it natively, but it’s very easy to use it in preference to JS and then compile to something HS2 can load:

https://github.com/cmsj/Hammerspoon2/blob/main/docs/TYPESCRIPT.md

Cheers,

--

Chris Jones

On 27 Dec 2025, at 16:29, Glenn Waters <gwwa...@gmail.com> wrote:



To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/9e4df472-bee2-42f0-b0ca-7bf7b0d6aca6%40app.fastmail.com.

[David Balatero]

One can also use TypeScript in JSDoc mode, and get checking in plain .js files!

To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/9B209A66-E551-4B3D-8E35-549899A3FEB4%40tenshu.net.

[M N]

cm schrieb am Donnerstag, 25. Dezember 2025 um 20:40:09 UTC+1:

Hey

On Wed, 24 Dec 2025 at 17:29, M N  wrote:

1. Do you have an HS2 config you could share to show some examples?

This is a very simple JS config I've been using while testing. It doesn't really do very much, but it might give some hints as to what it would look like:

 

Thanks for the snippet - this is a good starting point for me. Maybe a section with example init.js files would be nice to have in the repo.

 

2. Are JavaScript packages (for example via npm) available for inclusion in the config ecosystem?

So, this is an area where I am out of my depth. I do know that not all JS runtimes are created equal. For example, Node provides a lot of functionality that JavaScriptCore's basic ECMAScript environment does not.

So... I don't really know what npm usage would be like, and I will likely need to defer all of that to people more familiar with the JS world than me.

Yes, you are right - npm is more for Node. ChatGPT points out that some packages can be used, but they require bundling steps so they can be consumed. These steps are done outside of HS2, and the user is responsible for them.

The same applies to using TypeScript and or `bun` for the compilation steps I asked about. I am not sure whether this fully makes sense, but I would like to share the chats anyway.
- https://chatgpt.com/share/6950608b-65bc-800e-ae69-b8902c7e6416
- https://chatgpt.com/share/6950609b-8dd4-800e-8eb5-689534eaf879

That said, I think TypeScript support would be nice to have. At least providing .d.ts type definition files for IDE support would already be very helpful.

 

3. Can I run HS1 and HS2 at the same time, so that I can migrate script by script from Lua to the new HS2 JavaScript?

I don't think there's any realistic way we could release HS2 through the current repo and update stream, so I would expect it to be a completely separate "Hammerspoon 2.app" and therefore you could run them at the same time.

Running both at the same time sounds like a good solution.
 

 

4. I am not sure whether it makes sense to add a legacy plugin, spoon, extension, or similar that needs to be installed, set up, or activated so that HS1 Lua code can also run in HS2. I understand that running legacy code in a new HS2 environment is a burden, so this would only be an option if it is easy to implement.

tbh this sounds like it would be an enormous amount of work and would almost force us to shoot for 1-1 API compatibility. I would like to use this as an opportunity to re-think and improve various parts of our API.

That is a good point, and I also prefer the API to feel more JavaScript-ish.

Since HS1 and HS2 can run at the same time, such a "legacy" plugin is not really needed.
 

 

5. Maybe there could be a converter from Lua to JavaScript, or some instruction Markdown files for Claude Code?

It would certainly be interesting to see how well LLMs could do at converting!

I guess a good "Upgrade Your Scripts" manual would help a lot, so that an LLM can do this job well.
 

--

Cheers,

Chris

[David Balatero]

Agreed about providing d.ts files. These are basically compiled artifacts that the TS compiler can emit when distributing a library as JS, so that type information is not lost as a result of the TS -> JS compilation.

To the extent that Hammerspoon 2 implements itself in JS, those core libraries can actually be written in TypeScript and compiled to JS. This will both allow the core HS2 project to have typed JS, as well as maybe provide .d.ts definition files for free.

Best,

David

--

You received this message because you are subscribed to the Google Groups "Hammerspoon" group.

To unsubscribe from this group and stop receiving emails from it, send an email to hammerspoon...@googlegroups.com.

To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/2921768b-f904-4c81-9a6d-f781b0dfaaban%40googlegroups.com.

[Chris Jones]

See https://github.com/cmsj/Hammerspoon2/tree/main/docs :)

Cheers,

--

Chris Jones

On 28 Dec 2025, at 03:15, David Balatero <dbal...@gmail.com> wrote:



To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/899c26dd-b028-4d17-8060-ae9dcb896cc9%40app.fastmail.com.

[Glenn Waters]

I just tried to install on MacOS 15 and it said MacOS 26 is required :(. I'm hoping to avoid MacOS 26 as long as I can.

Anyway, I was hoping to start playing around with Hammerspoon 2 and see what it feels like to write some of my config using JS/TS.

Chris, how are you feeling about the direction after the discussion on the list? What kind of architectural and design concerns do you have? Is it worth opening up Discussions to advance some of the discussions?

I'd love to help but have a high barrier to starting. I've never written anything for the Mac using ObjC or Swift. Have not used XCode (but can probably figure that one out quick enough) - although when I loaded the project in today it wants me to sign in and also complained about a certificate - I'll come back to it later. I did run a couple of lines of your code through ChapGPT and Gemini to see how it works. I suspect if I can get up and running I might be able to start on something simple.

Is is correct to assume that some of the new API will be written in JS and shipped as a "core" library? For example, I saw reference in your code that the menuBar API could be written using the AX API (https://github.com/cmsj/Hammerspoon2/tree/main/Modules#example-building-on-hsax)

[Chris Jones]

Hey

There’s a newer release in the GitHub repo that should run on Sequoia 🙂

I’m very heartened by the responses here and on Reddit, and once I’m done with my Xmas vacation I’ll push on some more with the HS2 work.

hs.ax can interact with menu bars, but not create anything, same as HS1.

Cheers,

--

Chris Jones

On 1 Jan 2026, at 21:44, Glenn Waters <gwwa...@gmail.com> wrote:



--
You received this message because you are subscribed to the Google Groups "Hammerspoon" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hammerspoon...@googlegroups.com.

To view this discussion, visit https://groups.google.com/d/msgid/hammerspoon/43803ebf-2e98-4c9d-b086-27af5594996e%40app.fastmail.com.

[Chris Jones]

Oh, I misread your question…

I’m going to write as little of HS2 in JS as possible and keep as much of it in Swift as I can, because so prefer working in Swift!

Cheers,

--

Chris Jones

On 2 Jan 2026, at 21:50, Chris Jones <cm...@tenshu.net> wrote:

Hey

[Glenn Waters]

Well! This is a good match. I'm reasonably comfortable in JS/TS - enough to contribute, so if there are bits you would like in JS I'd be happy to try and contribute!

Thanks for the new release... see if I can try it out tomorrow.,