agent-hitl-island

Agent HITL Island Plugin Repository

This repository is structured for openplugin.

It contains one plugin:

plugins/agent-hitl-island/

The goal is not to build a website or a browser extension. The plugin adapts local agent HITL approvals, choice prompts, and text prompts in Codex CLI, Claude Code, and QoderWork into a dynamic-island style approval surface.

Install with openplugin

After publishing this repository on GitHub:

npx openplugin <owner/repo> --plugin agent-hitl-island

Target one client:

npx openplugin <owner/repo> --plugin agent-hitl-island --codex
npx openplugin <owner/repo> --plugin agent-hitl-island --claude
npx openplugin <owner/repo> --plugin agent-hitl-island --qoderwork

Repository layout

.agents/plugins/marketplace.json          # Codex marketplace metadata
.claude-plugin/marketplace.json           # Claude/openplugin marketplace metadata
plugins/agent-hitl-island/
  .claude-plugin/plugin.json              # openplugin discovery entry
  .codex-plugin/plugin.json               # Codex plugin manifest
  hooks/hooks.json                        # Claude Code hooks
  hooks/codex-hooks.json                  # Codex hooks
  hooks/qoderwork-hooks.json              # QoderWork hooks
  hooks/scripts/hitl-island-hook.mjs      # hook entrypoint
  hooks/scripts/display-island.mjs        # native macOS island UI

Local verification

npm run check
npm run demo

npm run demo shows the native approval island UI without needing an agent client.

The island is hidden during normal work. It appears only when a hook sees a permission request, a high-risk fallback tool call, or an input/choice tool such as AskUserQuestion.

On notched MacBook displays, the Swift UI reads the screen safe area and top auxiliary areas to align itself around the camera housing. The plugin does not control the physical notch; it uses a native overlay that visually grows from the notch and keeps text below the unsafe camera area. On external or non-notched displays it falls back to a top-center floating island.