User Guide

A detailed guide to every feature and setting in Kagemusha

Getting Started
Settings Reference Browser Engine Tab Bar Chrome Extensions Notifications Incognito Mode Show in Dock Quit Confirmation Tab Restore Window Handling Quick Setup User-Agent URL Rules Space Mode Template Profile
Managing Apps
Other Settings

1. Getting Started

Create from a Preset

Kagemusha ships with over 200 built-in service presets. Gmail, Slack, Notion, ChatGPT, YouTube, and other popular web services come with pre-configured icons and URLs, so you can create an app in seconds.

  1. Launch Kagemusha and click "Create App"
  2. Browse or search the preset list for the service you want
  3. Adjust options as needed
  4. Click "Create"

Create from a Custom URL

Services not in the preset list — including internal company tools — can be added by entering a URL directly.

  1. Select the "Custom" tab
  2. Enter the URL (e.g. https://example.com)
  3. Enter an app name
  4. Optionally set an icon by dragging and dropping an image or using the file picker
  5. Adjust options and click "Create"

Options

You can configure various options when creating an app. Each option is explained in detail in the next chapter, "Settings Reference." All options can also be changed after the app is created.

2. Settings Reference

Browser Engine

Choose the browser that powers your app. Only browsers installed on your Mac will appear as options.

  • Chrome — The most stable option with the richest extension ecosystem. When in doubt, choose this
  • Brave — Built-in ad blocking and tracker prevention. Great for news sites and video streaming
  • Edge — Best compatibility with Microsoft 365. Copilot integration
  • Opera — Lightweight and memory-efficient. Built-in VPN
  • Vivaldi — Highly customizable. For power users
  • Chromium — The open-source base of Chrome. No extras, no bloat
  • Arc — Modern UI. Works well with Space mode
Kagemusha creates a symlink to the browser's actual binary, so when you update the browser, your apps automatically get the update too. The browser itself is never modified.

Tab Bar

Toggle whether the browser's tab bar (address bar + tabs) is shown in the app.

  • ON — The address bar and tabs are visible. Useful when you need to manage multiple tabs or check URLs
  • OFF (default) — The tab bar is hidden, showing only the web content. This gives the app a native look and feel
When you set multiple URLs via Quick Setup, the tab bar is automatically turned ON. If Quick Setup is used with the tab bar OFF, the URLs load as background tabs with no visible way to switch between them.

Chrome Extensions

Enable Chrome Web Store extensions inside your app.

  • ON — An extensions sidebar appears on launch, letting you install and use extensions from the Chrome Web Store
  • OFF (default) — Extensions are disabled

Each app has its own isolated profile, so you can install different extensions per app. For example, a translation extension for your translation app and DevTools for your development dashboard.

Notifications

Display the website's push notifications as native macOS notifications.

  • ON — Notification permission is automatically granted. Receive Gmail new-mail alerts, Slack mentions, and more through the macOS Notification Center
  • OFF (default) — Notification requests from the website are automatically denied

Once enabled, you can fine-tune notification behavior (style, sound, etc.) per app in macOS System Settings > Notifications.

Incognito Mode

Always launch the app in incognito (private) mode.

  • ON — Browsing history, cookies, and site data are never saved. The session is cleared every time you close the app
  • OFF (default) — The app launches in normal mode. Login sessions and browsing history are preserved
How this differs from profile isolation: Kagemusha automatically creates an independent profile for each app, so even with incognito OFF, cookies and data are completely isolated from the browser and other apps. Incognito mode is for when you want the app itself to retain no data at all.

Show in Dock

Control whether the app icon appears in the macOS Dock.

  • ON (default) — The icon is always visible in the Dock. You can switch to the app with ⌘+Tab, and restore the window by clicking the Dock icon after closing it
  • OFF — The icon does not appear in the Dock. The app shows only in the menu bar. Suitable for utility-type apps that run in the background

Quit Confirmation

Show a confirmation dialog when you press ⌘Q to quit the app.

  • ON — A "Do you really want to quit?" dialog appears. Useful for preventing accidental quits during work
  • OFF (default) — The app quits immediately with no confirmation. Best for quick closing

Tab Restore

Automatically restore the tabs and scroll positions from your last session when the app launches.

  • ON (default) — Everything is restored exactly as you left it. Resume work instantly
  • OFF — The app always starts fresh from the configured home URL

Window Handling

Control how the app handles new windows (popups) when links are clicked. Choose from three modes:

  • Block All — No new windows are ever opened. All links open in the current window. Use this to completely prevent unwanted popups
  • Smart (default, recommended) — Only allows necessary popups like OAuth login flows and blocks ads and unnecessary popups
  • Allow All — All new window requests are permitted. Use this if you experience popup-related issues
"Smart" is the best choice for most users. It lets essential popups through — like Google OAuth sign-in — while blocking the rest. Switch to "Allow All" if you run into popup issues.

Quick Setup

Open multiple URLs as tabs when the app launches. Access several related services from a single app.

How to configure:

  1. Open the "Quick Setup" section in the app settings
  2. Click "Add URL"
  3. Enter URLs you want to open (you can add multiple)
  4. Drag and drop to reorder the tabs

Example setups:

  • Work bundle — Gmail + Google Calendar + Google Drive in one app
  • Dev tools — GitHub + CI/CD dashboard + documentation site
  • News feed — Hacker News + TechCrunch + TradingView
We recommend turning the Tab Bar ON when using Quick Setup. Without it, switching between multiple tabs is difficult.

User-Agent

Change the User-Agent string sent to servers. This controls how websites identify your browser and device.

  • Default — Uses the standard User-Agent of the selected browser engine
  • iPhone — Sends an iPhone Safari User-Agent. Useful for accessing mobile versions of websites, which are often lighter and faster
  • Android — Sends an Android Chrome User-Agent
  • iPad — Sends an iPad Safari User-Agent. Use this for tablet-optimized layouts
  • Custom — Enter any User-Agent string manually. For specialized requirements

URL Rules

Restrict which URLs can be accessed within the app. Two types of rules are available: whitelist (allow list) and blacklist (block list).

Whitelist (Allow List)

Only allows access to specified domains or paths; everything else is blocked. Useful for locking down business apps to approved sites.

Blacklist (Block List)

Blocks access to specified domains or paths; everything else is allowed. Use this to block specific external sites or ad domains.

Syntax:

  • example.com — Matches the entire domain (including subdomains)
  • *.example.com — Matches subdomains only
  • example.com/path/* — Matches a specific path prefix

Examples:

  • Whitelist company.slack.com and company.atlassian.net for an internal tools app
  • Blacklist ad tracking domains on a news reader app

Space Mode

Combine multiple web services into a single app window with a sidebar for switching between them. While a regular app is "1 app = 1 service," a Space is "1 app = multiple services."

How it differs from Quick Setup:

  • Quick Setup — Multiple tabs in the same window. Switch via the tab bar. All tabs share one profile (cookies and login sessions)
  • Space Mode — Switch via sidebar icons. Each service has its own independent view with a clean, tab-bar-free interface. The profile is shared across the entire Space

How to create a Space:

  1. On the "Create App" screen, select "Space" mode
  2. Add services from presets or enter custom URLs
  3. Set an icon for each service (auto-fetched or custom)
  4. Set the overall Space app name and icon
  5. Click "Create"

Example Spaces:

  • Work Space — Gmail + Google Calendar + Slack + Notion
  • Social Space — X + Instagram + Threads + Bluesky
  • Video Space — YouTube + Netflix + Prime Video
  • Dev Space — GitHub + Vercel + Supabase + ChatGPT

Template Profile

Save a pre-logged-in browser session as a "template" and apply it to new apps. This eliminates the need to sign in to each app individually.

Creating a template:

  1. Open the "Template Profile" section in Kagemusha settings
  2. Click "Create New Template"
  3. Enter a template name (e.g. "Google Account A")
  4. A browser window opens — sign in to the services you need
  5. Close the window when done — the profile is saved automatically

Applying a template:

  1. In the app creation or editing screen, select "Template Profile"
  2. Choose an existing template — the login data (cookies) will be copied to the new app
Once created, the new app operates as an independent profile. Changes to the template after the fact do not affect existing apps.

3. Managing Apps

Editing an App

Select any app from the main screen to change its settings. All options except the browser engine can be modified after creation. Changes take effect the next time the app is launched.

Changing the Icon

App icons can be changed at any time. Drag and drop a new image or use the file picker. Square images automatically receive the macOS-standard superellipse corner radius.

Deleting an App

Apps you no longer need can be deleted from the list. Deleting removes both the app bundle (.app) and its profile data. This action cannot be undone.

Automatic Browser Sync

Apps created by Kagemusha reference the browser binary via a symlink, so browser updates are automatically reflected in your apps. No manual action is required.

4. Other Settings

Language

Kagemusha supports Japanese and English. Switch languages in the "General" section of the settings screen.

Theme (Appearance)

Choose from Light, Dark, or Auto (follows the macOS system setting). Change it in the "General" section of settings.

Default App Options

Customize the default settings applied when creating new apps. Save your preferred option combinations to avoid configuring them every time.

Dock Shortcut

Set up Kagemusha's built-in Dock Launcher, which displays all your apps in a grid. Launch any app with a single click or keyboard shortcut. Background color and opacity are customizable.

Data Export / Import

Export Kagemusha configuration data (app list, settings, license info, etc.) to a file and import it on another Mac.

  • Export — Click "Export" in the "Data Management" section of settings to save a JSON configuration file
  • Import — Load an exported JSON file via "Import" to restore your settings
Profile data (cookies and login sessions) is not included in exports. Use the Template Profile feature to migrate login sessions.
← Back to top