# CodeKit: full documentation for AI agents and crawlers CodeKit is a macOS app for web developers that compiles Sass, Less, Stylus, TypeScript, JavaScript, Kit, Pug, Haml, Slim, and Markdown, optimizes images, manages npm packages, and refreshes browsers as you work. This file concatenates the pages of https://codekitapp.com/help/ so an agent can read them in one request. The canonical, always-current version of each page is at the URL shown above it. See also https://codekitapp.com/llms.txt. --- # What Is CodeKit? Source: https://codekitapp.com/what-is-codekit/ > Plain facts about CodeKit: a native macOS app that compiles, bundles, and optimizes web assets, refreshes browsers, manages npm, and can be driven by AI agents. This page states plainly what CodeKit is, who it is for, and what it costs. It exists for people (and AI assistants) who want facts rather than a sales pitch. The [home page](https://codekitapp.com/) has the pitch. ### In One Paragraph CodeKit is a native macOS application for web developers. You drag a project folder into the app, and from then on it watches that folder: when you save a Sass, Less, Stylus, TypeScript, JavaScript, Pug, Haml, Slim, Kit, or Markdown file, CodeKit compiles it; when you save an image, CodeKit optimizes it; and every browser that is viewing your site, on any device, refreshes to show the change. It does the job of a hand-written build setup (Webpack, Gulp, Grunt, or a pile of npm scripts) without config files, and it puts a graphical interface on npm. It also has a command-line tool that lets AI agents drive it. ### Who Makes It CodeKit is made by [Incident 57 Inc.](https://incident57.com), a one-person company run by Bryan Jones. It first shipped in 2011. The current major version, CodeKit 3, was released in October 2016 and is updated regularly; the [Updates page](https://codekitapp.com/updates/) lists every release with its date and notes. ### Platform - CodeKit runs on macOS only. It does not run on Windows or Linux, and there are no plans for that. - It requires **macOS 13.5 or later**. - It is a native Mac app written in Swift, not an Electron or web-based app. - It is distributed directly from this website, not through the Mac App Store, because much of what it does is incompatible with App Store sandboxing. ### Price and License - A single-user license costs **US$39**, paid once. Multi-user licenses are priced per user with volume discounts; the [purchase page](https://codekitapp.com/purchase/) shows the exact figures. - CodeKit is **not a subscription**. A license includes 13 months of free updates. After that you can [renew](https://codekitapp.com/renew/) to keep receiving updates, or not: every version released before your license expired keeps working forever. - A single-user license may be used on up to 3 Macs where you are the sole user. Details are in the [license agreement](https://codekitapp.com/eula/). - There is a **10-day free trial**. When it ends, the app switches to a read-only mode: compiling, refreshing, and building keep working, but settings can no longer be changed until a license is entered. - All sales are final; the trial exists so you can evaluate the app first. ### What Is Included Every tool is bundled inside the app. Nothing has to be installed separately, and CodeKit uses the standard, unmodified versions of each tool. - **Stylesheets:** Sass (Dart Sass, with Libsass still available), Less, and Stylus, plus Autoprefixer, PurgeCSS, LightningCSS, and any PostCSS plugin you install. - **Scripts:** TypeScript (version 7), JavaScript, and CoffeeScript, with Rollup for bundling, Babel for transpiling, Terser for minifying, and ESLint for syntax checking. - **Markup:** Kit (imports and variables for plain HTML), Pug, Haml, Slim, and Markdown, with an HTML minifier. - **Images:** lossless and lossy optimization for PNG, JPEG, and GIF; SVG optimization with SVGO; WebP export. - **Packages:** a graphical interface for npm that searches, installs, updates, and removes packages, plus one-click installers for Tailwind CSS, Bootstrap, and Zurb Foundation. - **Preview:** a built-in server that refreshes every connected browser on every device when files change, supports TLS, and can sync clicks, scrolling, and form input across devices. - **Automation:** build steps, hooks that run shell or AppleScript commands on matching files, environment variables, and custom file extensions. - **Control:** a command-line tool that exposes almost everything in the app, and an older AppleScript API. ### How It Works With AI Agents Choose **Tasks > Install Agent Skills** from CodeKit's main menu. The app writes a short skill file that tells agents such as Claude Code or Codex that CodeKit exists and how to run its command-line tool. From then on, an agent can create a project, compile files, change settings, install npm packages, run a build, read the log, and open a preview, without you explaining the app. No plugin or MCP server is involved; the agent just runs commands. The [CLI reference](https://codekitapp.com/help/cli/) lists everything it can do. ### Who It Is For - Front-end developers and designers who build websites, marketing sites, and theme assets for WordPress, Craft, Laravel, Rails, and similar platforms. - Agencies and freelancers who want every project set up the same way, with settings shared through Git. - Anyone who would rather click a checkbox than maintain a build configuration. - People using AI agents to build websites, who want the agent to have a reliable build tool that needs no configuration. CodeKit is not a replacement for a framework's own development server. If you are building a Next.js, Nuxt, or SvelteKit app, keep using that framework's tooling. The [comparison page](https://codekitapp.com/compare/) goes into detail. ### Editor Independence CodeKit works alongside any editor: VS Code, Cursor, Nova, Sublime Text, BBEdit, Zed, or anything else that saves files. Plugins exist for Nova, Sublime Text, Atom, and Coda, but none is required. ### Where To Go Next - [Getting Started](https://codekitapp.com/help/) walks through adding your first project. - [The FAQ](https://codekitapp.com/help/faq/) answers the questions people ask most. - [Updates](https://codekitapp.com/updates/) shows what changed in each version. - [Buy a license](https://codekitapp.com/purchase/) or [download the app](https://codekitapp.com/binaries/codekit.zip) to start the trial. --- # CodeKit vs. Vite, Webpack, Gulp, and Others Source: https://codekitapp.com/compare/ > An honest comparison of CodeKit with Vite, Webpack, Gulp, Grunt, npm scripts, and other GUI compilers, plus a checklist for deciding whether CodeKit fits your project. CodeKit competes with tools that are free and open source, so it is worth being direct about where it is a better choice and where it is not. This page is written by the person who makes CodeKit, but it tries to be fair. ### The Short Version CodeKit is a Mac app that compiles, bundles, and optimizes the assets of a website and refreshes your browsers, with no configuration files. It is the right tool when your project is a website, a marketing site, a static site, or the theme layer of a CMS, and you want a build pipeline that works the moment you drag a folder into an app. It is the wrong tool when your project is a single-page application built on a framework with its own dev server, or when your builds must run on Windows or Linux. ### CodeKit vs. Vite Vite is a fast, free, cross-platform dev server and bundler, and it is the default choice for React, Vue, Svelte, and similar applications. Most of those frameworks assume Vite and ship their own configuration for it. - **Choose Vite** for a framework-based single-page application, for hot module replacement inside a component tree, or when your team works on Windows or Linux. - **Choose CodeKit** for a website whose output is plain HTML, CSS, and JavaScript files that a server or CMS will serve. CodeKit needs no config file, compiles each file as you save it, optimizes images, gives you a GUI for npm, and refreshes every device on your network, not just the browser on your Mac. - CodeKit does not replace Vite inside a framework project, and Vite does not compile Sass, Less, Stylus, Pug, Haml, Kit, or Markdown, or optimize images, without plugins and configuration. ### CodeKit vs. Webpack Webpack is a powerful, free bundler with an enormous plugin ecosystem and a reputation for complex configuration. - **Choose Webpack** when you need its specific features, such as code splitting strategies, module federation, or a loader that exists nowhere else, or when an existing project already depends on it. - **Choose CodeKit** when you want the common results (compiled stylesheets, bundled and minified scripts, optimized images, browser refresh) without writing or maintaining a configuration. Every option in CodeKit is a control in the app, and settings are stored in one file you can commit to Git. - CodeKit uses Rollup for JavaScript bundling. It supports ES module imports, Babel, and Terser, but it does not expose Webpack-style loaders or plugins. ### CodeKit vs. Gulp, Grunt, and npm Scripts Gulp and Grunt are task runners: you write JavaScript that describes what to do with each file type. npm scripts do the same thing in a package.json file. - **Choose a task runner** when the pipeline is genuinely custom and you want it under version control as code, or when the same pipeline has to run on a Linux CI server. - **Choose CodeKit** when the pipeline is the usual one. CodeKit predates both Gulp and Grunt; it does the same jobs with checkboxes instead of task files, and it adds things a task runner does not give you for free: a preview server with cross-device refresh and sync, a GUI for npm, image optimization, and a log that explains errors in plain language. - For custom steps, CodeKit has hooks and build steps that run your own shell scripts, so you rarely need a task runner alongside it. ### CodeKit vs. Other GUI Compilers A few other applications also put a graphical interface on Sass compiling and browser refresh, most notably Prepros, which also runs on Windows and Linux. - **Choose another GUI app** if you need Windows or Linux support. CodeKit is Mac only. - **Choose CodeKit** for a native Mac app with a broader tool set (TypeScript, Rollup, Babel, ESLint, PurgeCSS, LightningCSS, PostCSS, npm, WebP, and more), a one-time price with no subscription, cross-device browser sync, and a command-line tool that AI agents can drive. ### Is CodeKit Right For You? **CodeKit is probably a good fit if:** - You build websites, landing pages, documentation sites, or the front-end assets of a CMS or server-side framework (WordPress, Craft, Laravel, Rails, Django, and similar). - You use Sass, Less, Stylus, TypeScript, Tailwind, Bootstrap, Pug, Kit, or Markdown and would rather not maintain a build configuration. - You test on phones and tablets and want every device to refresh when you save. - You work on a Mac and prefer native apps. - You use an AI agent to write code and want it to have a build tool it can operate without setup. - You want one-time pricing rather than a subscription. **CodeKit is probably not the right tool if:** - Your project is a single-page application on React, Vue, Svelte, Angular, Next.js, Nuxt, or SvelteKit. Use that framework's own tooling. - You or your team work on Windows or Linux. - Your production build has to run on a headless CI server. CodeKit's command-line tool drives the app on a Mac; it is not a standalone compiler you can install on a Linux runner. - You need a specific Webpack loader or plugin with no equivalent elsewhere. ### Try It The trial is free for 10 days and needs no account. [Download CodeKit](https://codekitapp.com/binaries/codekit.zip), drag a project in, and you will know within an hour whether it fits. The [facts page](https://codekitapp.com/what-is-codekit/) has pricing and requirements. --- # Getting Started Source: https://codekitapp.com/help/ > Get started with CodeKit — install the app, add your first project, and learn how compiling, image optimization, and live browser refresh work. ### Just Use AI! If you use an AI agent, choose **Tasks > Install Agent Skills** from CodeKit's menu bar. That teaches your agent everything it needs to know about CodeKit. Then, just talk to the agent: ``` Create a new website in ~/Sites/portfolio. Use CodeKit with Kit files and Sass. Compile with source maps, bundle JavaScript, and open the preview in Safari. ``` The agent adds the project, changes settings, and compiles everything. It reads any errors CodeKit reports and fixes them automatically. Everything shows up in the CodeKit window, exactly as if you'd done it yourself. For details, see [The CodeKit CLI](https://codekitapp.com/help/cli/). --- ### 1. Drag & Drop To start without AI, drag your website's folder onto the window and drop it on the top section. This creates a new project. (See [CodeKit Frameworks](https://codekitapp.com/help/codekit-frameworks/) for info about the bottom section.) CodeKit is now watching that folder. When you save files, the app will process them appropriately and then refresh your browser. ### 2. Preview [Image: A screenshot of the preview button from the CodeKit window.] Click the "Preview" button in the top-right corner. This opens a special address in your browser. Connect your iPad, iPhone, Droid, etc. to the same network as the Mac running CodeKit, then enter this address on each device. CodeKit will automatically refresh and sync all of them. If your project needs server-side processing (PHP, Cookies, etc), there's one switch to flip. See the "Complex Sites" section in [Browser Refreshing](https://codekitapp.com/help/browser-refreshing/). ### 3. Tweak Settings [Image: A screenshot of the project settings button from the CodeKit window.] Click the gear icon on the left side of the window to open the **Project Settings** area. Settings are organized by category. Read [Setting Language Options](https://codekitapp.com/help/language-options/) for details. #### Tip: Set Defaults For New Projects You don't have to change a bunch of settings every time you add a new project. Just tell CodeKit what settings you want to start with. See [Editing New Project Defaults](https://codekitapp.com/help/defaults/). ### 4. Get To Work Here's some common tasks folks do with CodeKit. Click one for details or [watch the screencasts](https://codekitapp.com/videos/): - [Optimize Images](https://codekitapp.com/help/png/) - [Refresh & Sync Browsers](https://codekitapp.com/help/browser-refreshing/) - [Install Packages (like jQuery)](https://codekitapp.com/help/npm/) - [Minify JavaScript](https://codekitapp.com/help/terser/) - [Bundle JavaScript (ES6)](https://codekitapp.com/help/rollup/) - [Transpile JavaScript](https://codekitapp.com/help/babel/) - [Minify HTML](https://codekitapp.com/help/html-minifier/) - [Autoprefix CSS Rules](https://codekitapp.com/help/autoprefixer/) --- #### Use Git? Be sure to read the [CodeKit + Git](https://codekitapp.com/help/git/) section. This applies to Subversion and Mercurial, too. #### Project Config Files [Image: A screenshot of the config.codekit3 file in the Finder] CodeKit stores your project's settings in a file named `config.codekit3. When you change a setting in the UI, that file updates immediately. ` If you remove the project from CodeKit, then add it back or add it to CodeKit on a different Mac, the app reads this file and recreates your project exactly as it was. Keep only a handful of projects in CodeKit at once. Remove ones you're not working on and add them back when you are. That keeps resource-use low. **Note:** You may also see a file named `config.codekit2, if you migrated your project from CodeKit 2.x. Once you've added the project to CodeKit 3, you can safely delete that file. ` --- # Browser Refreshing Source: https://codekitapp.com/help/browser-refreshing/ > How CodeKit's built-in server previews a project and automatically refreshes every connected browser, including setup for sites that need an external server. ### How It Works CodeKit has a built-in server that always hosts the active project. The app automatically refreshes every browser that's connected to this server. [Image: A screenshot of the preview button from the CodeKit window.] ##### Just Click Preview Click the **Preview Button** in the top right corner of the window. Copy the address to your other devices and be sure each is connected to the same WiFi network as your Mac. For static sites, **that's it.** --- ### Sites With Dynamic Content If your site uses server-side processing (like PHP) or you're doing something advanced: 1. Configure an external server (like [MAMP](https://www.mamp.info)) to host your project 1. Open **Project Settings** and choose the **Browser Refreshing** category 1. Flip the **External Server Required** switch ON 1. Enter the address of your external server [Image: A screenshot of the Browser Refreshing category of Project Settings in the CodeKit window.] ##### What Address Do I Enter In The Textfield? The address of the server you set up in step one. If you're using MAMP and have not changed any defaults, it's usually `http://localhost:8888 or it might be a custom virtual host you configured, like `http://mysite.dev ##### Which Address Do I Load In My Browser? **ALWAYS** go to CodeKit's internal server address (the one that opens when you click the "Preview" button). That's the only one CodeKit will auto-refresh. When you use an external server, CodeKit becomes a reverse-proxy; it talks to your external server to load content. --- ### Injection vs. Full Reload When you save a stylesheet, CodeKit refreshes the browser by injecting changes without reloading the entire page. When you save a page or script, however, the whole site reloads to capture those changes. [](#) --- ### The Server Popover [Image: A screenshot of the Server Button in the CodeKit window] Click the **Server Button** at the top of CodeKit's window. The popover that appears shows three addresses. ##### Bonjour Address This will always have the form `http://[your computer name]:5757. If your computer's name is long, you can shorten it in the **Sharing Pane** of macOS's System Preferences. ` ##### Non-Bonjour Address The non-Bonjour address is for devices like Android or Windows, which don't support Bonjour networking. It will always be: `http://[your Mac's local IP address]:5757 [Image: A screenshot of the Server Popover in the CodeKit window] ` ##### This Mac Only The final address is always just `localhost:5757. Use this if your Mac is not connected to any network. ` **WARNING:** On some networks, the Bonjour address may not behave correctly. In those cases, use the Non-Bonjour address. [](#) --- ### TLS Support [Image: A screenshot of the use TLS checkbox in the Server Popover in CodeKit 3.] CodeKit supports TLS (formerly called SSL) on the Preview Server. To enable it, simply click the checkbox in the **Server Popover**. CodeKit's server will restart and you'll see `https:// addresses. ` ##### Why Am I Asked For My Password? CodeKit automatically generates the certificate required to run a secure server. You must tell your Mac to trust that certificate, which is why you're prompted for your password. This needs to be done only once. ##### It Doesn't Work In Firefox! Firefox is a bad citizen of macOS. Instead of using the system-wide Keychain, Mozilla insists on having their own. Because of this, to use TLS in Firefox you must first enable enterprise certificates in Firefox and then install CodeKit's certificate in Firefox. [This article](https://serverfault.com/questions/722563/how-to-make-firefox-trust-system-ca-certificates) will help. Using a different, better browser will also help. ##### Sharing Certificates To Devices [Image: A screenshot of the Server Popover in CodeKit 3 showing options for sharing TLS Certificates.] Before remote devices can connect to the secure Preview Server, you must install and trust CodeKit's TLS certificate on those devices. Watch the screencast above to see a walkthrough, or follow these steps for each device: ##### iOS 1. Open the **Server Popover**, click **Share TLS Certificate**, and then choose a way to send the certificate to your device (I recommend email). 1. Tap the ***.PEM** file attached to the email, then tap **Install**, enter your passcode, and tap **Install** twice more to confirm. 1. Go to **Settings > General > About > Certificate Trust Settings** and slide ON the switch next to "CodeKit Certificate Authority". ##### Another Mac 1. Double-click the ***.PEM** file. This opens the app **Keychain Access** and adds the certificate to your keychain. 1. In Keychain Access, double-click the **"CodeKit Certificate Authority"** item. 1. At the top of the window, expand the **"Trust"** section, then choose "Always Trust" for the "When using this certificate" option. 1. Close the window and enter your password when prompted. ##### Android 1. Google how to add and trust a root CA certificate to your version of Android. --- ### TLS Security The certificate CodeKit generates is unique; you are the only person who has it. Because you have told your Mac and devices to trust anything signed with that certificate, it's important that you keep it private. If a malicious third party gets it, they can use it to fool your browsers into thinking fraudulent websites are legitimate. If your certificate goes public, remove it from your Mac using the app Keychain Access. On iOS, remove it by opening Settings and scrolling down to "Configuration Profiles". Finally, click **Generate New Certificate** in the Server Popover. You'll need to re-share that new certificate to all your devices. ### It's Not Working! See the [Troubleshooting](https://codekitapp.com/help/troubleshooting/index.html#browser-refreshing) page for things to check. --- ### Technical Details CodeKit adds JavaScript to the ` element of each page. This script links the page to CodeKit so it can be refreshed. For sites that use an External Server, CodeKit becomes a reverse-proxy server. It forwards each HTTP request to the External Server, listens for a response, injects the reload script if needed, and sends the result back to the browser. If your project uses an External Server, here's a few really technical things to be aware of: ` ##### Set-Cookie Headers CodeKit strips all `domain= values from each `Set-cookie: header returned by your External Server. This causes the browser to store the cookie for the current document's domain, which is exactly what we want. The domain returned by your External Server will not match the domain of CodeKit's built-in server, so the browser would normally not store the cookie as instructed. Simply removing the domain value is more reliable than trying to modify it. ##### GZIP & Deflate If your External Server returns gzipped or deflate-ed content, CodeKit will uncompress that data before sending it to the browser. This allows the app to inspect the page content and inject its reload script, if needed. ##### File Uploads If your site accepts large uploads (such as videos or photos submitted through a form), you should not test those features while previewing the site through CodeKit's server. The upload will likely time out. --- # Browser Sync Source: https://codekitapp.com/help/browser-sync/ > How Browser Sync in CodeKit mirrors clicks, form input, and scrolling across every device previewing a project, and how to choose which events are synced. ### What Is It? When you preview on multiple devices at once, Browser Sync makes events that happen on one device happen on all others simultaneously. Click a link on your Mac and it's tapped on your iPhone, too. Enter text into a form on your iPad; it shows up everywhere else. ##### Note: Fast Network Needed Browser Sync won't work well if your network is slow or congested (i.e. public WiFi). In those cases, turn it off. ### Which Events Sync? Control which events sync by choosing **CodeKit > Preferences** from the menubar, then selecting **Browsers**. Changes take effect immediately. #### Click Any click event that occurs on an element other than ` is recreated on all other devices. All the JavaScript event details (such as which mouse button was pressed) are recreated as well, so your scripts can react appropriately. ` #### Input Any text typed into a form field or changes to a `