AISLANDDownload

Documentation

Install AISLAND, open your island and connect your first agent.
For preview release 0.3.75.

Install and launch

The app runs without a separate runtime. Claude Code, Codex, WorkBuddy and Antigravity hooks require Python 3.9+. The SDKs require Node.js 20+ or Python 3.9+.

macOS · Apple Silicon

  1. Visit the download page, open the DMG and drag AISLAND to Applications.
  2. Launch AISLAND from Applications.
  3. The Mac build supports Apple silicon.

A Mac with a notch displays the Floating bar just below it, matching its width. Other displays place the bar below the menu bar.

The desktop follows your appearance settings. macOS uses AppKit switches. Windows uses Microsoft Fluent UI and system window controls.

Windows · x64

  1. Open the x64 installer and follow the prompts.

On Windows the Floating bar sits at the top of the selected display. Hover over the floating bar to expand it.

Choose a compact style

On either platform, open Settings → Appearance → Collapsed style and choose Island or Floating bar. The compact bar shows a blue line on the left and the AISLAND wordmark on the right. Hover over either to expand a rounded panel from that spot. Move away to close it. Set Collapsed opacity for the idle Island or Floating bar and Expanded panel opacity for its task panel. Each ranges from 30% to 100%. When upgrading, both start at your previous percentage.

The Mac preview is distributed without Apple notarization. The Windows installer has no Authenticode publisher signature. Your system may ask you to confirm the source. Check the release URL and download checksum. The Windows installer is tested on a Windows desktop for hover, keyboard access and clicks around the minimized island.

AISLAND stays in the menu bar or system tray when you close its window. Choose Quit from the tray menu to exit.

Connect Claude Code

  1. Open Integrations and install the Claude Code connection. Python 3.9+ is required.
  2. In your project terminal, run claude. Restart an existing session or use /hooks to inspect the configuration.
  3. Start a task. Its status appears in the island, and approvals and answers return to that Claude Code session.

Installation preserves your hooks, model and permission choices. Actions require explicit approval. Offline or expired requests return to Claude Code. Review plans in the terminal.

Manage conversations

In All agents, expand an agent and open the menu beside a conversation. You can remove the conversation from the island and add it back from the same menu. To erase its local record, choose the delete action, check the name in the confirmation dialog and confirm. An archived conversation can be restored to the island from its menu in Archived. External agents keep their original conversations. Deleting a chat created in AISLAND with Ollama also removes its local transcript.

Codex and Antigravity

Open the setup assistant in Integrations. Check Python and Codex, then install the hooks. The assistant backs up existing configuration and preserves permission policies.

Codex desktop

  1. Choose Install Codex integration and wait for setup to finish.
  2. Open the review terminal. In Codex, enter /hooks and review the AISLAND · Codex entry before trusting it.
  3. Return to AISLAND and check again. Once the hook is trusted, restart Codex and start a task.

The integration reports progress, tools, approvals, completion and interruptions. Answer questions and review plans in Codex. The CLI can load the same user hooks. Opening Codex from the island activates the app.

When Codex owns a session, its API may refuse another writer. AISLAND keeps your instruction and reports that it has not been sent.

Antigravity

Install the Antigravity integration, restart the application and start a new task. Progress, tools and background task status appear in the island. Handle permissions and questions in Antigravity.

Launch at login

Launch at login and Check integrations at startup are independent options, both initially off. Startup checks inspect configuration and open the assistant if needed. You approve hooks yourself.

Install the desktop app before enabling launch at login. Approve the login item in system settings if prompted. macOS may restrict unsigned builds.

Configured means the hook is installed. The event receipt confirms a real connection. Setup scripts and configuration stay on your computer.

Connect your agent

Connect with a single instruction

  1. In Integrations, choose Copy setup instructions.
  2. Paste the instructions into a local agent that can read files and execute commands.
  3. Return to AISLAND. The assistant confirms the connection when the agent replies.

The instructions include the SDK path and setup details. Connection verification creates no sample task. Progress, approval handling and background dispatch each require the corresponding agent capability.

Install an SDK manually

Start AISLAND and copy the SDK to your project. It reads the current user's local connection information. No external dependency or AI service key is required.

Node.js

Save this example as connect.mjs alongside agent-island.mjs and run node connect.mjs.

import { AgentIsland } from './agent-island.mjs';

const island = new AgentIsland({
  agent: 'My Agent', title: 'Review the project'
});

await island.start('Review the project…');
await island.tool('Read', 'Task update README.md');
await island.complete('Task update');

Python

Save this example as connect.py alongside agent_island.py in the same folder. Run python3 connect.py (on Windows, you can also use py connect.py).

from agent_island import AgentIsland

island = AgentIsland(
    agent="My Agent", title="Review the project"
)

island.start("Review the project…")
island.send("tool.start", tool="Read",
            content="Task update README.md")
island.complete("Task update")

Local HTTP API

AISLAND writes the endpoint and access token to ~/.agent-island/connection.json. On Windows, ~ refers to your user directory. The default port is 24678. If it is busy, AISLAND selects an available port. The SDK rereads the file before each request.

Other languages can send events to POST /v1/events with Authorization: Bearer <token>. See the local protocol.

Approvals and questions

Submit a command, description and diff for review. Your agent executes the operation after receiving approval.

const result = await island.approve({
  title: 'Task update',
  command: 'echo "Hello from AISLAND"',
  content: 'Task update'
});

if (result.decision === 'allow') {
  await island.complete('Task update');
} else {
  await island.complete('Task update');
}

Approvals expire after about ten minutes. Disconnects, restarts and session endings do not approve a request. Treat errors and cancel as a refusal to proceed.

The Node.js SDK also includes ask() for single, multiple or freeform answers, plan() for plan review, and usage() for reported usage. See the full example for a two-way exchange. Python clients can call send() for additional protocol events.

More agent integrations

Ollama

Start Ollama on your computer with a local chat model installed. In Connections, select Connect Ollama, choose the model and send a message. The response appears as it streams. Use the same conversation branch for follow-ups. Each branch keeps its own chat history. Conversations started in other Ollama clients stay in those clients. Ollama chat API

OpenCode

Choose OpenCode in Connections, install the local plugin, then start a new OpenCode session. Task activity appears under its own branch in the island. Continue the task and answer permission requests in OpenCode. OpenCode plugins

GitHub Copilot CLI

Choose GitHub Copilot CLI in Connections, connect the hooks and start a new local CLI session. Follow its progress on the island while you work in another window. Send new instructions and review permissions in the original terminal. GitHub Copilot hooks

Gemini CLI, Cursor, MiniMax Code and Zhipu GLM

Gemini CLI and Cursor report task events, tool status and final replies through hooks. Install the integration and start a new session. Approvals and follow-ups remain in the original application. The Gemini web app is a separate product.

MiniMax Code uses local Plugin V1 hooks. Install the official client and mcode command, then select Connect under MiniMax Code. AISLAND checks the plugin directory, backs up previous versions and avoids overwriting unrelated plugins. Manual setup is available. Start a real task to confirm events. Approvals, questions and follow-ups remain in MiniMax Code. MiniMax Design is separate.

Claude Code sessions using GLM are identified by their reported model and keep their original conversation. The Zhipu Qingyan client has a separate listing. Reading its chats and sending background instructions still require hardware verification.

Existing Doubao desktop and Grok conversations do not currently support progress sync or background follow-ups.

The new adapters have passed isolated hook and local bridge checks. Account-level verification remains pending. Vendor references: Gemini CLI Hooks, Cursor Hooks, MiniMax Hooks, Zhipu setup guide.

Feature support

Send follow-ups from the status control at the right of each conversation branch.

In 0.3.35, collapsed groups show the agent and a disclosure arrow. Active sessions have a flowing blue track. Expand a group to see its branches.

Branch height reflects activity. Active tasks get more room. Completed and idle sessions use narrower branches. The agent icon occupies less than two thirds of the total branch height.

FeatureAvailability in 0.3.75
Desktop island, hover and multiple displaysAvailable
Mac notch positioning and entry hapticsAvailable on supported Force Touch trackpads
Sound and motionChoose Glass, Drift or Felt in Startup & notifications. Use Preview to hear an event at your chosen volume. Visual cues follow Reduce Motion.
Grouped sessions, follow-ups and activity historyAvailable
Approvals, questions, plan review and reported usageAvailable
Node.js, Python and HTTP integrationsAvailable
Claude Code HooksStatus, permissions and questions supported. Review plans in the terminal.
Codex / AntigravityHook support varies by agent. See trust and setup steps above.
Setup assistant and startup checksEnvironment checks, hook trust status and optional launch at login
Automatic account quota collection, SSH, mobile push and automatic updatesUnavailable

AISLAND uses Electron and React with a native Mac panel. The island opens from the Mac notch safe area or from the top center of a Windows or external display.

Privacy and data

The local bridge listens only on 127.0.0.1. Requests require the local token. Browser-origin requests are rejected. Keep connection.json private.

Session text and operation previews are stored in ~/.agent-island/state.json. Records are retained for seven days by default. Expired records are removed at startup. Open the data folder from Preferences.

AISLAND runs locally by default with no telemetry. When you enable mobile sync, summaries and instructions are encrypted on-device with AES-256-GCM before passing through your Cloudflare relay.

The website uses GitHub Pages and GitHub Releases for hosting and downloads. It has no account system or embedded analytics. GitHub processes hosting logs under its privacy statement.

Mobile sync and controls

For self-hosting, download the sync service package and follow its README to configure Workers and D1.

  1. In Settings → Mobile & Remote, choose Generate phone pairing code.
  2. Open AISLAND on your phone, choose Scan to connect, point the camera at the desktop QR code, then tap Connect. With the hosted service, you can also enter the four groups of four characters shown on your computer. With a self-hosted relay, scan or paste the full link.
  3. Invitations expire after ten minutes. Choose Show phone pairing code on the computer to reopen the invitation or renew an expired code. You can also open the mobile web app or download the Android APK.
  4. Enable sending tasks and changing keep-awake settings separately on your computer.

Keep the computer running and online. With the mobile app open, changes from your computer arrive as they happen. If a live connection is unavailable, the app checks periodically. The 0.2.0 self-hosted relay also uses periodic updates. Offline devices show the last synced state. Check the computer's receipt to confirm delivery.

Home Screen widgets

After pairing in the native app, add an AISLAND widget from your Home Screen. On iOS, choose the small widget for working agents or the medium widget for the task list. On Android, resize the widget to fit your launcher. Widgets show the most recent synced tasks and the update time. Android can refresh widgets in the background on the launcher’s schedule. Open AISLAND for live updates.

Workers and D1 use free-tier quotas. Sync may pause when those quotas run out. AI subscriptions remain with their providers. Native iOS builds use SwiftUI on iOS 17+ and system Liquid Glass controls on iOS 26+. A public native iOS release is pending.

Send a follow-up

Hover over the status at the end of a branch. Check the agent and conversation in the input panel, then type and send your instruction. If a turn is running, AISLAND saves one follow-up for that conversation and waits for it to finish. You can withdraw the instruction while it is waiting in AISLAND.

Codex can accept the instruction into its own conversation queue. Claude Code resumes the original session through its Agent SDK. WorkBuddy requires an accessible desktop window. If receipt is unclear, check the original conversation before submitting again.

Connect WorkBuddy

  1. Open Settings → Integrations → WorkBuddy and choose Connect.
  2. Review the hooks in WorkBuddy, then start a session. Existing sessions may need a restart.
  3. Start a task to see its event receipt and timestamp. Configured indicates that the configuration was written.

WorkBuddy reports tasks, tools and completion. On macOS with WorkBuddy 5.11.3, background follow-ups verify the conversation and message before delivery. Keep the main window open and grant Accessibility permission when prompted.

Troubleshooting

My phone reads the QR code but won’t connect

Open Mobile & Remote on your computer and show a fresh pairing code. If macOS asks for Keychain access, choose Allow so AISLAND can read its saved pairing key. If access was denied, retry in Mobile & Remote. On your phone, scan it and choose Connect to computer within ten minutes. If the desktop shows an existing connection, use the phone app or browser that claimed it. Disconnect that device first if you intend to replace it.

The SDK cannot find connection.json

Open AISLAND and check the local connection in Integrations. Run the SDK on the same computer and under the same user. For a custom data directory, set AGENT_ISLAND_HOME to that directory.

The island appears on the wrong display

Open the dashboard from the island or the tray menu and check your display and placement settings. Disconnecting a display moves the island to an available one.

Trackpad feedback is missing

Enable trackpad feedback in Appearance & Interaction. Rest your finger on a Force Touch trackpad and choose Try it. The default is a single crisp pulse. Trackpad feedback is independent of sound.

The terminal does not activate

macOS may request Automation access for Terminal or iTerm2. Windows may restrict focus changes in elevated or full-screen windows. If a session cannot be located, open its project directory from the integration.

Report an issue

Use GitHub Issues to share the operating system, app version and steps to reproduce. Remove tokens, personal paths and sensitive project details from screenshots and logs.