# Codexisland Macos Notch

> CodexIsland - Display AI usage limits (Claude Code & Codex) in your MacBook notch with Dynamic Island-style UI

- Skill: `aradotso/codexisland-macos-notch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aradotso/codexisland-macos-notch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso/codexisland-macos-notch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aradotso (https://skillmd.com/u/aradotso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aradotso/codexisland-macos-notch

---


# CodexIsland macOS Notch

> Skill by [ara.so](https://ara.so) — Codex Skills collection.

CodexIsland is a native macOS overlay that transforms your MacBook notch into a Dynamic Island-style live activity display for Claude Code and Codex usage limits. It shows 5-hour and weekly usage windows for both providers, estimates dollar spend and token throughput from local session logs, and provides a swipeable Cost screen—all while remaining local-first and credential-free.

## What CodexIsland Does

- **Dual-provider monitoring**: Tracks Claude (5h + 7d) and Codex (5h + 7d) usage limits in one notch overlay
- **Notch-native overlay**: Black pill aligned to the physical notch with squircle corners; falls back to menu-bar pill on non-notched Macs
- **Hover to peek**: Shows 5-hour percentage and reset headline for visible providers
- **Click to expand**: Opens full Usage/Cost panel with provider columns and chart controls
- **Swipeable screens**: Usage screen (live limits) + Cost screen (local log analysis for $ spend & tokens)
- **Five chart styles**: Ring, Bar, Stepped, Numeric, Sparkline
- **Local-first privacy**: Reads existing credentials from Claude Code/Codex; no API keys stored; no telemetry

## Installation

### Homebrew (Recommended)

```bash
brew install --cask ericjypark/tap/codexisland
```

The cask automatically strips the Gatekeeper quarantine attribute.

### Direct Download

1. Download `CodexIsland-X.Y.Z.dmg` from [GitHub Releases](https://github.com/ericjypark/codex-island/releases)
2. Drag `CodexIsland.app` to `/Applications`
3. Remove quarantine attribute (app is unsigned):

```bash
xattr -dr com.apple.quarantine /Applications/CodexIsland.app
```

### Manual Gatekeeper Bypass (No Terminal)

1. Drag app to `/Applications`
2. Try to open (macOS will block it)
3. Open **System Settings → Privacy & Security**
4. Scroll to bottom, find blocked CodexIsland message
5. Click **Open Anyway**, then re-launch

## First Run Authentication

CodexIsland reads existing credentials—no manual API key entry needed.

### Claude Setup

CodexIsland tries these sources in order:

1. `CLAUDE_CODE_OAUTH_TOKEN` environment variable
2. macOS Keychain item `Claude Code-credentials`
3. Refresh token from Anthropic's OAuth endpoint

**Prerequisites**:
```bash
# Run Claude CLI once to populate credentials
claude

# OR open Claude Desktop app
```

If authentication fails, the panel shows `auth required — run claude`.

### Codex Setup

CodexIsland reads `~/.codex/auth.json` created by the Codex CLI.

**Prerequisites**:
```bash
# Sign in to Codex/ChatGPT CLI
codex auth login
```

If the file or token is missing, the panel shows `no codex auth`.

## Using the App

### Basic Interaction

| Action | Result |
|--------|--------|
| Hover notch | Peek at current 5-hour usage |
| Click island | Expand full Usage/Cost panel |
| Swipe horizontally | Switch between Usage and Cost screens |
| Move away | Collapse island |
| Cmd-click panel | Cycle chart styles (Usage: Ring/Bar/Stepped/Numeric/Sparkline; Cost: USD/VALUE/TOKENS/TREND) |
| Click "synced Xs ago" | Force immediate refresh |
| Click gear icon | Open Settings |

### Chart Styles

**Usage Screen**:
- **Ring**: Circular progress indicator
- **Bar**: Horizontal bar chart
- **Stepped**: Stepped area chart
- **Numeric**: Large percentage numbers
- **Sparkline**: Minimal line chart

**Cost Screen**:
- **USD**: Dollar spend (today + month-to-date)
- **VALUE**: Spend vs. subscription value
- **TOKENS**: Total token throughput
- **TREND**: Token usage trend over time

### Token Counting Modes

**All Tokens** (default, matches `ccusage`):
- Counts every token type that crossed the wire
- Includes cache reads/writes

**Billable Only** (matches claude.ai stats):
- Input + output tokens only
- Excludes cache tokens

Toggle in Settings → Token Counting.

## Configuration

### Settings Panel

Access via gear icon in expanded panel. All settings persist to `UserDefaults`.

| Setting | Key | Values | Default |
|---------|-----|--------|---------|
| Chart Style | `MacIsland.chartStyle` | `ring`, `bar`, `stepped`, `numeric`, `spark` | `ring` |
| Cost Style | `MacIsland.costStyle` | `dollar`, `multi`, `tokens`, `spark` | `dollar` |
| Token Counting | `MacIsland.tokenCountMode` | `all`, `billable` | `all` |
| Refresh Interval | `MacIsland.refreshInterval` | `300`, `900`, `1800` (seconds) | `300` (5 min) |
| Low Power Mode | `MacIsland.lowPowerMode` | Boolean | `false` |
| Claude Visible | `MacIsland.claudeVisible` | Boolean | `true` |
| Codex Visible | `MacIsland.codexVisible` | Boolean | `true` |
| Launch at Login | Managed by `SMAppService` | Boolean | `false` |

### Refresh Intervals

Choose from Settings:
- **5 minutes** (default)
- **15 minutes**
- **30 minutes**

**Note**: Sub-5-minute polling is not available due to Anthropic's rate limits on `/api/oauth/usage`.

### Provider Visibility

Hide/show providers in Settings:
- Removes provider logo and column from island
- Keeps latest usage values in memory
- Re-showing does not require re-authentication

## Building from Source

### Requirements

- macOS 13+
- Xcode or Command Line Tools (Swift toolchain)

### Build Steps

```bash
git clone https://github.com/ericjypark/codex-island
cd codex-island
./build.sh
open build/CodexIsland.app
```

**No Xcode project or SwiftPM package**. `build.sh` compiles with `swiftc`, creates universal binary (arm64 + x86_64), and assembles `.app` bundle.

### Verification

Smoke test the build:

```bash
./scripts/verify.sh
```

Launches the binary for 1 second, then kills it if still alive.

### Release Packaging

```bash
npm install --global create-dmg
./release.sh
```

Creates `dist/CodexIsland-X.Y.Z.dmg` with ad-hoc codesigning.

## Code Architecture

### Key Components

```
Sources/
├── App.swift                    # SwiftUI app entry point
├── Cost/                        # Local log cost + token aggregation
├── Model/                       # Data models for usage/cost
├── Theme/                       # UI theming and colors
├── Update/                      # Sparkle auto-update wrapper
├── Usage/
│   └── UsageFetcher.swift      # Network fetcher for provider APIs
├── Views/                       # SwiftUI views for island/panels
└── Window/                      # Custom window management
```

### Network Surface (Privacy)

All network requests are in `Sources/Usage/UsageFetcher.swift`:

- **Claude**: `https://api.anthropic.com/api/oauth/usage`
- **Codex**: `https://chatgpt.com/api/usage`

Tokens are sent only as `Authorization` headers. No proxy server.

### Local Log Reading (Cost Screen)

Cost screen reads local session logs:

**Claude Code**:
- `~/.claude/projects/**/*.jsonl`
- `~/.config/claude/**/*.jsonl`
- `$CLAUDE_CONFIG_DIR/**/*.jsonl` (if set)

**Codex**:
- `~/.codex/sessions/`

All aggregation happens on-device. No log content is uploaded.

## Troubleshooting

### Authentication Issues

**Claude shows "auth required — run claude"**

```bash
# Option 1: Run Claude CLI
claude

# Option 2: Open Claude Desktop app (no command needed)

# Option 3: Set environment variable
export CLAUDE_CODE_OAUTH_TOKEN="your_token_here"
```

**Codex shows "no codex auth"**

```bash
# Sign in to Codex CLI
codex auth login

# Verify auth file exists
ls -la ~/.codex/auth.json
```

### Stale Values After Error

**Expected behavior**: `UsageStore` retains previous good values when a refresh fails (e.g., 429 rate limit). Prevents panel from showing 0% during temporary errors.

**Force refresh**:
- Click "synced Xs ago" in panel header
- Or wait for next scheduled poll (respects refresh interval setting)

### Rate Limiting

If you see persistent authentication errors:

1. Check refresh interval (Settings → Refresh Interval)
2. Increase to 15m or 30m to avoid Anthropic's rate limits
3. Click "synced Xs ago" to manually refresh when needed

### macOS Compatibility

**Non-notched Macs**: Falls back to 200×28 menu-bar pill
**Multiple monitors**: Prefers first display with safe-area insets (partial support)

### Gatekeeper Warnings

CodexIsland is unsigned (free open-source project):

```bash
# Remove quarantine attribute
xattr -dr com.apple.quarantine /Applications/CodexIsland.app

# Verify removal
xattr -l /Applications/CodexIsland.app
```

Or use manual bypass via System Settings (see Installation section).

## Advanced Usage

### Programmatic Access to Settings

Settings are stored in `UserDefaults` with domain `MacIsland`:

```bash
# Read current chart style
defaults read MacIsland chartStyle

# Set refresh interval to 15 minutes
defaults write MacIsland refreshInterval -int 900

# Enable Low Power Mode
defaults write MacIsland lowPowerMode -bool true

# Hide Codex provider
defaults write MacIsland codexVisible -bool false
```

### Auto-Updates (Sparkle)

CodexIsland uses Sparkle for auto-updates:
- Checks on launch + once per day
- EdDSA signature verification (no Apple Developer ID required)
- Toggle in Settings → Auto-Update

Appcast: `https://github.com/ericjypark/codex-island/releases`

### Launch at Login

Managed by `SMAppService.mainApp`:

```bash
# Enable via Settings UI or Terminal
# (No direct command-line control for SMAppService)
```

Access via Settings → Launch at Login toggle.

## Privacy Guarantees

- ✅ No app telemetry
- ✅ No crash reporting
- ✅ No third-party analytics
- ✅ No proxy server
- ✅ Credentials never stored by CodexIsland
- ✅ Tokens leave machine only as `Authorization` headers to official provider APIs
- ✅ Cost screen log aggregation is 100% on-device

## Example Workflow

```bash
# 1. Install
brew install --cask ericjypark/tap/codexisland

# 2. Authenticate Claude
claude

# 3. Authenticate Codex
codex auth login

# 4. Launch app
open /Applications/CodexIsland.app

# 5. Configure settings
# - Hover notch → Click island → Click gear icon
# - Set refresh interval: 15 minutes
# - Set chart style: Bar
# - Enable Launch at Login
# - Enable Low Power Mode (hides steady-state glow)

# 6. Use the island
# - Hover to peek at 5-hour usage
# - Click to expand full panel
# - Swipe right to see Cost screen ($ spend + tokens)
# - Cmd-click to cycle chart styles
# - Click "synced Xs ago" to force refresh
```

## Contributing

Repository: `https://github.com/ericjypark/codex-island`

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/codex-island
cd codex-island

# Build
./build.sh

# Test
./scripts/verify.sh

# Package DMG
./release.sh
```

CI/CD: `.github/workflows/release.yml` builds DMG and updates Homebrew tap on `v*` tags.