Your project becomes a Mac app

What it is and why it matters

With Claude you built yourself a tool of your own, and every morning it's the same ritual: open the terminal, start the server (the program that runs the app on your computer), look for the right browser tab. And if you close the terminal by mistake, everything shuts down.

app-it is a free, open-source project (MIT license) that you add to Claude Code and that turns that project into a Mac app, with its own Dock icon and window. Double-click: the app starts the server by itself and opens a native window (WebKit, Safari's engine). With ⌘Q you also shut down the server and free the port (the number, like 5173, it answers on).

It doesn't rewrite your app: it adds a few files and leaves you a report to undo it. It's an unofficial project by an independent developer, not by Anthropic. And it's for your own use: it's not for putting the app on the App Store or selling it.

1. What you need first

• A Mac. In practice app-it is macOS only: the Windows branch is still experimental and I don't recommend it.
• The Xcode Command Line Tools, Apple's developer tools, which are needed to build the window. If you don't have them: type xcode-select --install in Terminal.
• Whatever your project already uses to start, installed and working: for example Node and its dependencies (npm install already done). app-it doesn't install anything for you.
• Claude Code, opened in the project folder.

The simplest test: if today you start the project by hand from the terminal and it works, you're ready. If it won't start by hand, app-it won't fix it: sort that out first.

2. Add it to Claude Code

app-it is a plugin, meaning a package of instructions and scripts for Claude Code. It isn't in Anthropic's official marketplace but in the project's own, on GitHub: first you add that one, then you install the plugin. Inside a Claude Code session:

1. Type /plugin marketplace add Christian-Katzmann/app-it. You add the project's catalog (the repository is github.com/Christian-Katzmann/app-it).
2. Type /plugin install app-it@app-it. It doesn't install right away: it opens the plugin's details with what it adds. Read them, then choose where to install it (for you, in every project, is perfectly fine).
3. If Claude Code asks you to, type /reload-plugins. From the terminal the same steps are claude plugin marketplace add and claude plugin install.

This goes for every third-party plugin: read what you install, because it can run scripts on your computer. app-it's code is public, and the project says it uploads nothing and collects no data.

3. Run /app-it on the project

Open Claude Code in the project folder and type /app-it (the full name is /app-it:app-it). It looks at the project, chooses how to build the app, builds it, installs it and tests it. This is how I write to it:

/app-it
Turn this project into a Mac app with its own icon.
Don't touch the app's logic.
At the end, explain the report to me in plain words: what kind of project you found, which port it runs on, which icon you used, which files you added and how to remove it all.
Also tell me what I need to check by hand.

The last line matters: Claude checks on its own that the server answers and that ⌘Q shuts it down, but you look at the window and the Dock icon yourself.

What it adds to your project

• A scripts/ folder with the scripts to build, install and quit the app, and the scripts/app-it.config.json file with the name, port and start command.
• An icon in assets/, either the one it finds in the project or a temporary one generated on your Mac.
• In package.json, the desktop:build, desktop:install, desktop:quit, desktop:doctor and desktop:verify commands.
• docs/desktop-launcher.md, the short instructions, and docs/desktop-launcher.app-it-report.md, the report with every change.

4. Use it every day

• First launch: if macOS won't open it, right-click the icon, Open, and confirm. The first launch is slower, because the server has to start from scratch.
• Closing the window with ⌘W or the red dot doesn't shut down the server: it stays on, so next time it reopens right away. To shut everything down and free the port you need ⌘Q, or Quit from the icon's menu in the Dock.
• If the preferred port is taken, the app usually picks a free one a little higher and writes it in the file ~/Library/Application Support/app-it/<app-name>/server.port.
• The app runs the server from the project folder, and it remembers where that folder is. If you move or delete it, the app stops working: put it back where it was, or run /app-it again in the new place.

A tip: drag the ~/Applications/App It/ folder to the right side of the Dock. It becomes a stack, and every app you create afterwards shows up there by itself. For a check, or to change the icon:

Check the app you created with app-it.
Run npm run desktop:doctor and tell me in plain words: which port the server really runs on, whether the installed icon is the right one and whether anything needs fixing.
Then use this image as the icon: [path to the image], rebuild and reinstall the app.
Don't touch the app's code.

5. When the app is finished: app-it-static

app-it keeps the development server running: handy while you work on it, but it weighs on the Mac's memory. For a finished tool there's a lighter sibling in the same marketplace, app-it-static: it builds the app once (the build, the final version of the files) and serves that. Same window, same stack in the Dock.

You install it with /plugin install app-it-static@app-it and run it with /app-it-static. The limit to know: it shows a snapshot of the build. If you change the code later, the app won't see it until you run npm run desktop:rebuild.

/app-it-static
This project is finished: I want a lightweight Mac app that serves the build, with no development server.
Before you start, tell me which build command you'll use and which folder the result ends up in, and wait for my OK.

Bonus: an app that's already online, like a Claude Artifact

app-it can also put a web address in a Dock window, like a published Claude Artifact. The window loads the link, you sign in with your account and usage stays on your plan. Give Claude the published link, not the copied code.

6. How to go back

Everything app-it adds can be removed, and the report says what. Have Claude do it starting from there, looking at the list first.

I want to remove app-it from this project.
Read docs/desktop-launcher.app-it-report.md and show me the list of files, folders and package.json lines that app-it added, plus the app installed in ~/Applications/App It/.
First shut the app down with npm run desktop:quit.
Don't delete anything until I give you the OK, and don't touch the app's code.

Common mistakes

• Running /app-it on a project that won't start by hand. If the window shows a server error, it's usually the project: fix it from the terminal, then rebuild the app.
• Closing with the red dot and thinking you've shut everything down. The server stays on: to stop it you need ⌘Q.
• Moving or renaming the project folder after creating the app. The app looks for it where it used to be.
• Sending the .app file to a friend as if it were a real app. It's only signed for your Mac, it isn't notarized by Apple, and without the project folder and its server it doesn't work.

Checklist

• The project starts by hand from the terminal
• The Xcode Command Line Tools are installed (xcode-select --install)
• I read the app-it plugin's details before installing it
• Claude explained the app-it report to me and what to check by hand
• The window shows my app and its icon is in the Dock
• ⌘Q shuts down the server and frees the port
• The ~/Applications/App It/ folder is in the Dock

Frequently asked questions