1. welcome to cirQlar!
Build your own circular command center for macOS – with circles, extensions, and shortcuts arranged exactly the way you think and work.
cirQlar is a circular (duh?) launcher for macOS that keeps your most important apps, folders, files, and shortcuts close to hand. It lives where you need it, and stays out of the way when you don’t.
This guide walks through the core concepts in order: circles, extensions, the portal and the key settings that make cirQlar feel like your own tool.
2. first launch
Getting oriented the first time cirQlar appears.
After completing the first onboarding and granting the necessary permissions, you will call in cirQlar by double tapping the left Command-key (⌘). CirQlar appears from the center of your cursor..
- The circle opens under your cursor so you stay focused where you work.
- Each icon in the circle is a slot you can assign to an app, folder, file, or shortcut.
- Use the settings gear icon to open preferences and start customizing.
3. circles - basics
Primary circles, pages, and how items are arranged.
A circle is a radial layout of items. You can have multiple circles, each with pages: for example, a work circle, a creative circle, and an app-specific circle.
- Open Settings ▸ Circles.
- Select the circle you want to configure.
- Use Add App… or Add Folder/File… to fill empty slots.
- You can add several pages to a circle, these pages are indicated by an arc shape next to the center settings icon.
4. circle groups & extensions
Group related apps and shortcuts behind a single icon.
- Open Settings ▸ Circles and locate the app you want to extend.
- Click Extend next to the app to open the extension editor.
- Add additional apps, folders/files, or shortcuts to this group.
- Use the up/down controls to reorder, and the trash icon to remove items.
- Back in the circle, click the extendable app (shown by a small arc next to the icon): its extensions animate out in an arc following the main circle.
5. folders & files in circles
Add project folders, documents, or anything you often use.
- Open Settings ▸ Circles and choose the relevant circle and page.
- Click Add Folder/File… and pick a folder or file from Finder.
- cirQlar stores the path and shows the system icon for that item in the circle.
- Clicking the item opens the folder or file directly in Finder or its default app.
You can also add folders/files as extensions behind an extendable item, using the same Add Folder/File… option in the extension editor.
6. command central
Your high-level control panel for cirQlar.
Command Central gives you an interface to create and manage shortcuts or key sequences. You can assign a shortcut to a circle slot, and then trigger it by clicking the slot in the circle.
- Open it from Settings ▸ Circles ▸ Command Central.
- Add the shortcuts or key sequences you want to use.
- Choose name, icon and color for the shortcut or key sequence.
- Click the save button to add the shortcut or key sequence to the Command Central.
- Trigger the shortcut from the circle just like any other item.
7. cirQlar! how, or when? what?
cirQular developed split personalities during development.
While double tap Command-key (⌘) by default activates the primary circle, you can also use Control-key (⌃) and/or Option-key (⌥) to activate additional circles. This is useful if you want to use cirQlar for different tasks, and not rely on several pages in one circle.
Aaaaaaand, what? more? Yes! You can choose to activate app specific pages. This is useful if you want to use cirQlar for different tasks, but in specific apps.
Okay, let’s recap:
- In Settings ▸ Circles, navigate through the top tabs to activate alternative circles.
- Both Option and Control circles can have several pages.
- Pages with App Specific enabled will only show when the set application is active. Most popular use case it to have app specific pages set on alternative modifier keys, such as Option and Control.
8. settings & fine-tuning
Make cirQlar feel like it was designed personally for you.
In Settings, you can fine-tune various aspects of cirQlar’s behavior and appearance. Here’s a quick, no it actually really long, overview:
- Circle opening behavior – choose where the circle opens from. From the center of your cursor, or from where ever you want on your screen? You choose!
- Circle closing behavior – choose how and when circles close after you launch something. May it be automatically, after a short delay, or never, to keep your favourite circle of tools open all the time?
- Extension indicators – toggle the subtle arc around extendable apps on or off. Show it, or hide it, it’s your choice. The behaviour stays the same.
- Circle range can be set using the intuitive handles which controls both range and placement of the added items.
- Appearance – adjust subtle visual details to match your macOS setup. Light, dark, system, or something in between?
- Icon shapes – choose between round and rectangular icons. Rectangular is the default, but you can change it to round if you prefer.
- Icon sizes – adjust the size of the icons in the circles. Small, medium, large, or something in between?
- Show app names – show the name of the app in the circle for easy recognition, or hide it to keep it clean and minimal.
- Show running indicator – show a running indicator in the circle to indicate that the app is running.
- Enable arc colors – enable custom arc colors for the circles for either visual separation between pages, or to make it more visually appealing.
- PRESETS! – You can save your favourite circle configurations as presets, and load them back later. You can also share them with your friends, or keep them to yourself because they are THAT awesome muuuhahahahahaa!
9. the Portal
How on earth does this have anything to do with cir..sshhhhhh.. Carry on..
If it was not obvious already, cirQular was developed with a focus on simplicity and efficiency. But what if you want to do more? What if you want to quickly move files between locations, or maybe not quickly but stored for accessing later? That’s where the Portal comes in.
- In Settings ▸ Portal, you enable this little sneaky fellow.
- For most MacBooks, the Portal lives behind the notch, and for desktops, it lives in the top center of your screen, kind of exactly the same as with laptops but why not over explain everything ever?
- However Portal can come in two different shapes, either as the above mentioned Overlay triggered from the top center, or from both the Menubar and from Settings.
With Portal, you can quickly drag and drop folders and files, then choose where to move them, may it be new folder/folderssss, or airdrop them likes it’s hawth 
Choose to move all files, or just a selected few, basically just how you want to.
At the top you’ll find different tabs with three outstanding ones;
ZONES
Zones let you setup custom targets, useful for often used targets that let you stay in the flow without opening several finder windows.
BUT!! even more powerful is the ability to customize their behavior;
Drop a file onto a zone that runs an Automator workflow, shell script, or Shortcut. E.g. “Resize & Optimise” or “Upload to CDN”.
Zones learn file patterns. Drop a PDF once to “Invoices” — the next PDF from the same app auto-routes there with a confirmation nudge.
BOARD
Board is acting as our personal second memory, a persistent, scrollable clipboard history that stays in Portal.
Copy or Pin frequent items (code snippets, files, URLs) for one-click paste.
VAULT
Vault allow you to drop files into an encrypted vault zone. Files are encrypted via macOS CryptoKit on arrival, stored safely, and unlocked with Touch ID.
10. tips & workflows
A few patterns that are commonly used.
- Use one circle as a “Sequential” “I do this every day” circle. Use it to add your daily tasks, and to trigger them by clicking the slot in the circle.
- Group “noisy” tools (chat, email, socials) behind a single extendable hub.
- Keep project-specific folders as extensions under your main editor or IDE.
- Create a “focus” page with only 3–5 essential apps, no extensions.
- Create the most overly packed circle you can imagine, and have all your sectretly stored workflows in it, ooooooonly for you to enjoy.
11. troubleshooting
Common issues and how to resolve them quickly.
THE CIRCLE(S) DOES NOT APPEAR
- Check that cirQlar is running in the menu bar and check which circles are enabled in Settings.
SHORTCUTS ARE NOT BEING TRIGGERED
- Verify accessibility permissions in macOS System Settings ▸ Privacy & Security.
FOLDERS OR FILES DOES NOT OPEN
- Ensure the file paths are still valid (for example, external drives are connected).
