Getting started

Install CoIsland

1. Download CoIsland, open the disk image and drag CoIsland into Applications.
2. Open it. No window opens and no icon joins the Dock: CoIsland lives in two places.

• The menu bar icon, an island with its palm tree: Settings…, Check All Now, Acknowledge All, Open Watches Folder and Quit CoIsland.
• The island, a small pill on the right edge of your screen that opens when the pointer reaches it. Its gear opens Settings too.

The first time, a short welcome shows you around: where the island lives, which edge it hangs from, your licence and your first tool. Then a tour has you open the island, create a demo monitor, and work its alert: acknowledge it, add a note, hand it to an agent (a replay, no AI runs) and resolve it. The demo leaves nothing behind. CoIsland also creates ~/.coisland/watches, where it saves every monitor as a .sql file.

Add your licence, when you want every monitor

CoIsland Community needs no licence. To run every monitor:

1. Buy Lifetime. Your key shows on the next page, and in the email from licences@coisland.app.
2. Paste it in the welcome’s licence step, or in Settings › Licence, and click Activate.

Without a key, CoIsland Community runs the 2 monitors you created first; a key runs all of them. One key covers 2 Macs, with every update, for good.

Add a connector

A connector is one account on one tool: the account your monitors run on.

1. Open Settings › Connectors and click Add Connector (the + in the corner once you have one).
2. Pick the tool and fill in its form. Every field has a hint, and Connector name, the name your monitors use, fills itself in.
3. Click Test connector. It signs in and saves nothing: Connected shows the account it found, Failed the reason. Then click Add Connector.

Each tool’s guide says which token to create and where:

• Gmail
• GitHub
• Jira
• Sentry
• Snowflake
• HTTP / JSON
• Stripe
• Calendar
• Vercel
• Linear
• PagerDuty
• All 39→

Already use the Snowflake CLI or Cortex Code? On its first start, CoIsland imports the connections in their connections.toml that sign in with a programmatic access token, under the same names. Later, Import from Snowflake CLI in the Snowflake form fills it from one. CoIsland only reads that file.

Create a monitor

A monitor asks one tool one question on a schedule.

1. Open Settings › Monitors, click Add Monitor (the + in the header once you have monitors) and choose where it runs. A tool without a connector says Add a connector first and opens its form.
2. Pick one of the tool’s monitor types, or a ready-made one under Or start from an example, which fills in the title and the query.
3. Check Title and Runs on (Default is the tool’s default connector), then click Test: it runs once and says how much matches now, such as “2 rows match now”. Nothing is saved or alerted.
4. Choose Alert when: New rows appear (on GitHub or Jira, issues, review requests and so on), or a count crosses a threshold such as count > 0.
5. Choose Check every (15 minutes by default, up to 30 days) and a Sound (None keeps it silent), then click Create Monitor.

The first check runs at once and, with New rows appear, only records what already matches: those rows never alert, and every row that starts matching later does. A threshold has no quiet first check: it fires once when it becomes true, and again only after it has cleared.

SELECT query_id, name, error_message, scheduled_time
FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(
    SCHEDULED_TIME_RANGE_START => DATEADD('hour', -1, CURRENT_TIMESTAMP())))
WHERE state = 'FAILED'

Every monitor is saved as a .sql file you can also edit by hand: see Watch files.

See it in the island

Move the pointer onto the pill at the edge of your screen: the island opens into a column of rings, one per monitor.

• The ring fills as the next check comes closer. The number under it is how many rows or items match, with +N while some are new; new ones turn it yellow.
• Hover a ring for its card: the monitor, its connector and interval, the time to the next check, the new rows first, then the latest matches, and a button for each agent switched on in General › AI Agents (Claude, Codex and Cortex until you switch one off).
• Click a ring to open its newest new alert, or the monitor’s page when it has none. Press and hold it to mark its new rows as seen.
• When a row starts matching, the island opens on its own for five seconds and plays the monitor’s sound once.

Your first four monitors are set to Always in the notch; later ones to Only when it alerts, and join the island while they have new rows or an error. Change it from the menu next to a monitor’s name in Monitors. When more monitors want a ring than fit, a last ring counts the others and opens the list.

To move the island, open it, press the hand above its rings and drag it to the left, top or bottom edge. Option-drag slides it along its edge, and a click on an empty part of the open island pins it open. With more than one display, it stays on the main one, the one with the menu bar, whichever window is in front; pick another in Settings › General › Notch.

Your first alert

Each time a monitor fires, CoIsland raises an alert. Open it from the ring, or from Settings › Alerts, which keeps the 500 newest, grouped by day, with a filter by status and a search.

• Expected, Observed and Detected: the rule, what the check saw instead, and when.
• Rows that fired it, as they read at that moment, with Copy CSV. A GitHub or Jira alert shows its issues, pull requests or runs.
• Details: the monitor, the status, the rule and the connector.
• Activity: a log that starts with “Raised by” the monitor. Type in Add a note and press Return to add to it.

An alert is New until you click Acknowledge, then Resolve when it is handled; a resolved alert can be reopened, and each change goes into the activity log. Holding a monitor’s ring acknowledges its new alerts, and Acknowledge All in the menu bar does it for every monitor.

Want help with it? Work on this with an agent, at the foot of the alert page, starts Claude Code, Codex or Cortex Code in a terminal under the alert, the whole alert as its first message: its facts, the monitor’s query, the rows or items and the activity. Claude Code and Codex start in their auto modes: each fixes what is safe and asks you before anything destructive. None of them acknowledges or resolves the alert: you do. An agent that is not installed sends you to General › AI Agents; see Agents.