docs: add project readme

Author: engels74

README.md

@@ -0,0 +1,79 @@
+<div align="center">
+  <img src="docs/logo.svg" alt="Logo" width="256" height="256">
+  <h3 align="center">Claude Island</h3>
+  <p align="center">
+    A macOS menu bar app that brings Dynamic Island-style notifications to Claude Code CLI sessions.
+    <br />
+    <br />
+    <a href="https://github.com/engels74/claude-island/releases/latest" target="_blank" rel="noopener noreferrer">
+      <img src="https://img.shields.io/github/v/release/engels74/claude-island?style=rounded&color=white&labelColor=000000&label=release" alt="Release Version" />
+    </a>
+    <a href="#" target="_blank" rel="noopener noreferrer">
+      <img alt="GitHub Downloads" src="https://img.shields.io/github/downloads/engels74/claude-island/total?style=rounded&color=white&labelColor=000000">
+    </a>
+  </p>
+</div>
+
+## Features
+
+- **Notch UI** — Animated overlay that expands from the MacBook notch
+- **Live Session Monitoring** — Track multiple Claude Code sessions in real-time
+- **Permission Approvals** — Approve or deny tool executions directly from the notch
+- **Chat History** — View full conversation history with markdown rendering
+- **Auto-Setup** — Hooks install automatically on first launch
+
+## About This Fork
+
+This is a fork of the original [claude-island](https://github.com/farouqaldori/claude-island) by farouqaldori.
+
+Key improvements in this fork:
+
+- **Code quality** — Strict linting with SwiftFormat, SwiftLint (70+ rules), pre-commit hooks, and modern Swift concurrency (`@Observable`, `Sendable`, structured concurrency)
+- **Bug fixes** — Various stability and reliability improvements
+- **Merged upstream PRs** — See [merged pull requests](https://github.com/engels74/claude-island/pulls?q=is%3Apr+is%3Amerged+) for integration details
+
+## Requirements
+
+- macOS 15.6+
+- Claude Code CLI
+
+## Install
+
+Download the latest release from [GitHub Releases](https://github.com/engels74/claude-island/releases/latest) or build from source:
+
+```bash
+xcodebuild -scheme ClaudeIsland -configuration Release build
+```
+
+## Installation
+
+### First Launch (Gatekeeper Bypass Required)
+
+Since Claude Island uses ad-hoc signing (not notarized), macOS will block the first launch.
+
+#### Option 1: System Settings (Recommended)
+
+1. Download and open the DMG from [GitHub Releases](https://github.com/engels74/claude-island/releases/latest)
+2. Drag Claude Island to Applications
+3. Try to open the app — it will be blocked
+4. Go to **System Settings → Privacy & Security**
+5. Find "Claude Island was blocked" and click **Open Anyway**
+6. Click **Open** in the confirmation dialog
+
+#### Option 2: Terminal
+
+```bash
+xattr -d com.apple.quarantine "/Applications/Claude Island.app"
+```
+
+This is only required on first launch. Auto-updates via Sparkle work normally.
+
+## How It Works
+
+Claude Island installs hooks into `~/.claude/hooks/` that communicate session state via a Unix socket. The app listens for events and displays them in the notch overlay.
+
+When Claude needs permission to run a tool, the notch expands with approve/deny buttons—no need to switch to the terminal.
+
+## License
+
+Apache 2.0