Turn a local web project — or any hosted web app — into a macOS Dock-launchable .app
bundle — a native window, its own Dock icon, and clean start/stop — without Electron, Tauri, or a rewrite.
Unofficial community project— not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. "Claude Code" and "Codex" are their respective owners' marks, named here only to say which assistants app-it plugs into. This is an independent open-source tool built by one developer.
*A real app-it build, in motion. Fjord is an ordinary local web project (node server.js); app-it turns it into a native macOS app — double-click launches it, the window opens with its own Dock icon, and ⌘Q quits the app *
and frees the dev-server port. The actual generated app, not a mockup.
Status — Working, in daily use. The launcher templates are battle-tested across 12+ real projects; v0.1.0
is the first standalone, marketplace-installable release. macOS only, by design.
Windows beta — macOS is in daily use; Windows is an early beta, now with its first real-hardware fixes but still needing more. A complete sibling plugin (plugins/app-it-windows/
), gated by a required windows-latest
CI job (build · PowerShell lint · manifest parse · icon round-trip), mirrors the macOS contract with Windows primitives. The author runs only macOS, so for a long time it had never touched real Windows hardware; that changed with #8, the first run on an actual Windows machine, and a run of fixes since — a real start, not a finish line. If you're on Windows and want to help harden it, the doorway is docs/WINDOWS.md.
Local-first — app-it reads your project on your machine to choose a launcher strategy. It uploads nothing, runs no telemetry, adds no runtime dependencies, and never touches your business-logic source. The only thing it produces is an .app
on your own Dock. For a hosted web app — a published Claude Artifact, a deployed dashboard, an internal tool — the supported networked path is explicit: wrap the hosted URL so the host handles login and keeps usage on each user's own account. See Privacy and Terms for the plain-language policy.
app-it
is an assistant-agnostic plugin/skill. It works with Claude Code and Codex, and builds a small, repeatable launcher around an existing local project or hosted web app so that double-clicking starts the right runtime, opens a native window, keeps the Dock icon as your app, and cleans up when you quit.
Not Electron, Tauri, or a native rewrite. It wraps your existing dev setup; it doesn't replace it, migrate it, or add a bundler to your dependency tree.Not a general signed distribution system. No notarization, no App Store, no auto-update, no installer. A wrapper around a hosted web app is self-contained enough to zip and share, but it is still an ad-hoc-signed local bundle; recipients must trust the bundle and sign in with their own account.Not cross-platform. macOS only — and on purpose. Windows is a genuinely different problem (WebView2,.lnk
,.ico
, SmartScreen), so it belongs in a separate plugin rather than a blurred promise. SeeCompatibility.Not a hosted service. Nothing runs in the cloud and there is no live demo to visit — the proof is the apps on your own Dock (the Stack further down is real).
WHAT YOU HAVE WHAT APP-IT DOES WHAT YOU GET
─────────────────────── ────────────────────── ───────────────────────────
a local web project inspects it from disk, YourApp.app on your Dock
Vite React, SvelteKit, picks a strategy, then · its own icon
Astro, Next, static, or ──▶ builds & signs a .app ──▶ · native window, one click
a hosted web app URL around a WebKit shell · ⌘Q quits & frees the port
Under the hood, app-it:
Inspects before it touches anything— project type, dev scripts, ports, browser-API needs, icon sources.** Picks a launcher strategy**— a native SwiftWKWebView
shell by default (so the Dock icon staysyours), Chrome--app
mode only when a project needs Chromium-only APIs.Wraps a hosted web app without shared secrets— setexternal_url
to a hosted link (for example, a published Claude Artifact); each user signs in within the app window and uses their own account.Copies proven, hard-won templates into the project rather than re-deriving fragile launcher logic each time.Builds and ad-hoc-signs a real— universal (arm64 + x86_64), Gatekeeper-friendly, with a generated.app
.icns
.Gets the lifecycle right— closing the window (⌘W / red-X) leaves the dev server warm for a ~250 ms re-launch; ⌘Q quits the appandfrees the port.Writes a report explaining every change and exactly how to undo it.
Finished app? There's a lighter companion.app-it
runs your project's dev server — perfect while you're still building. Once an app isdone, it doesn't need one: thecompanion serves the built output (app-it-static
dist/
,build/
,out/
, …) so a finished app costs ~15 MB instead of a dev server's ~300–700 MB. Same native window, same Dock Stack — reach for it only when an app is done.[How it works →]
- macOS.
- Claude Code or Codex for marketplace installation.
swiftc
(Xcode Command Line Tools) for the native WebKit shell —xcode-select --install
.python3
(also from the Xcode Command Line Tools) forapp-it-static
's server mode.- Chrome only if a project needs the Chrome fallback path.
Claude Code:
claude plugin marketplace add Christian-Katzmann/app-it
claude plugin install app-it@app-it
Codex:
codex plugin marketplace add Christian-Katzmann/app-it
codex plugin add app-it@app-it
Then, from inside any local web project, ask your assistant:
/app-it
Natural triggers work too: "make this clickable from the Dock", "give this an icon", "dockify this", "package this as a local app".
To wrap a hosted web app, point app-it at its URL rather than copied source. A Claude Artifact is the common case: use the hosted artifact link, since a raw .jsx
file works as an ordinary local React app only when it does not depend on Claude's hosted runtime (window.claude
, window.storage
, MCP prompts, or Claude-provided auth).
Optional: for finished apps, also install the lighter companion — claude plugin install app-it-static@app-it
(or codex plugin add app-it-static@app-it
), then run /app-it-static
.
claude plugin marketplace add /path/to/app-it
claude plugin install app-it@app-it
codex plugin marketplace add /path/to/app-it
codex plugin add app-it@app-it
Marketplace install is preferred. To copy just the skill folder:
./install.sh # auto-detects Claude Code and/or Codex, asks before overwrite
./install.sh --dry-run # show what it would do, write nothing
All additions are additive and reversible:
scripts/app-it.config.json
— single source of truth for the app(s)scripts/desktop-build.sh
,desktop-install.sh
,desktop-quit.sh
,desktop-doctor.sh
,desktop-verify.sh
,wrapper.swift
, …assets/<slug>-icon.png
or.svg
desktop/<App Name>.app/
(gitignored — regenerated by the build)docs/desktop-launcher.md
and anapp-it-report.md
decision logpackage.json
scripts:desktop:build
,desktop:install
,desktop:quit
,desktop:doctor
,desktop:verify
Installed apps land in ~/Applications/App It/
by default. Drag that folder to the right side of the Dock once and every future appified app appears in its Stack automatically. Override with APP_IT_INSTALL_DIR
.
By default, generated launchers use port_mode: "fallback"
so sibling local
apps can coexist by scanning upward from the preferred port. Use
port_mode: "fixed"
only when the app must stay on one exact localhost origin, such as browser storage or OAuth callbacks.
A real MyApps Stack, not a mockup. Every icon is an ordinary local web project app-it turned into a native app — its own icon, its own window, one click to launch. Do this a dozen times and your Dock fills itself.
app-it
only makes additive, reversible changes. It will not rewrite product logic, add runtime dependencies, require a terminal window to stay open, or assume an already-running dev server. It may start and stop local dev-server processes during verification. It never collects telemetry, sends project data anywhere, or handles secrets. See SECURITY.md.
./scripts/validate.sh
This is the one-command check: it validates manifest shape, shell syntax, template presence, plist syntax, Swift typechecking, and Claude plugin validation (when the claude
CLI is available). CI runs the same script on macos-latest
.
For launcher/runtime changes, also run the behavioral suite:
./scripts/test-fixtures.sh
It builds tiny fixture apps and checks the lifecycle app-it promises: bundle shape, runtime ports, ownership, doctor/verify JSON, warm reattach, and cleanup.
This repo is agent tooling, and agents are expected to work in it. Start with AGENTS.md — it names the non-obvious conventions (templates are canonical, trust disk over docs, the macOS-only boundary) and the safe first commands. Architectural decisions and their rejected alternatives live in docs/decisions/.
The app-it-static
companion was inspired by feedback from the r/ClaudeAI launch thread, and the project keeps growing on community help. Thanks to:
for pointing out that finished apps shouldn't need a full dev server, and that Vercel/PWA-style workflows are far lighter — the nudge that became "serve the build locally, not a dev server."TechExpert2910
for highlighting that deployed/static proof-of-concepts are often the standard workflow and are easier to share.K_M_A_2k
for the corporate-environment caveat: external hosting like Vercel isn't always approved, which is exactly why aVo_Mimbre
localstatic launcher earns its place even for finished projects.for becoming the Windows beta's real-hardware tester — the first proof it actually runs, then a run of fixes each traced and verified on a real Windows 11 box: the window title, theFirnschnee
app-it-host
label stuck in the taskbar right-click menu, and a graceful path when the WebView2 runtime is missing (offer the installer instead of a dead window).for hardening the native window so a restored frame can't open off-screen or postage-stamp sized, adding first-class Vite + React, SvelteKit, and Astro dev recipes, and — most recently — the URL-only launcher that wraps a hosted web app (a published Claude Artifact is the common case) in a Dock window: no local server, no shared secrets, each recipient signed into their own account.SohamKela
MIT — see LICENSE.