opencode-island 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-island contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# opencode-island
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A macOS **Dynamic Island** for [OpenCode](https://opencode.ai).
+
+It floats on the right edge of your screen and tells you what every session and
+agent on your machine is doing — and lets you answer a permission prompt
+without ever leaving the window you are working in.
+
+![The island expanded, showing a running session](docs/panel.png)
+
+- **Closed**, it is a thin vertical tab on the right edge with the status
+  reading down its spine.
+- **Open** it (click it) and it becomes a drawer listing the sessions running
+  right now, with their subagents nested underneath.
+- **Approvals** turn the whole island warning orange, open it by themselves,
+  and can be answered in place.
+- **Live** — the last ten words the agent is saying scroll down the closed tab
+  as they arrive.
+
+---
+
+## Requirements
+
+| | |
+|---|---|
+| macOS | 13 or newer |
+| OpenCode | 2.2.7 or newer (the GUI plugin API) |
+| Node | 20.19 or newer (only if you build from source) |
+
+The island is a macOS-only plugin: it uses an Electron window that floats
+above full-screen apps and every Space.
+
+## Install
+
+### With the OpenCode CLI (recommended)
+
+```sh
+opencode plugin add opencode-island
+```
+
+That installs the package and adds it to your global OpenCode config.
+Restart the desktop app and the island appears on the right edge of your
+primary display.
+
+To remove it again:
+
+```sh
+opencode plugin remove opencode-island
+```
+
+The CLI also takes a Git specifier, which builds the plugin from source:
+
+```sh
+opencode plugin add github:hamzasoussi53/opencode-island
+```
+
+### From source
+
+```sh
+git clone https://github.com/hamzasoussi53/opencode-island
+cd opencode-island
+npm install --ignore-scripts
+npm run build
+ln -s "$PWD" ~/.config/opencode/plugins/opencode-island
+```
+
+`--ignore-scripts` skips Electron's ~100 MB binary download. The plugin only
+needs Electron's type declarations to build; the desktop app supplies the
+runtime. A plain `npm install` works too, it just downloads the binary as
+well.
+
+## Use
+
+### The closed tab
+
+The tab sits on the right edge, vertically centred. It shows one line:
+
+- `2 agents working` — how many agents are busy right now
+- `1 approval needed` — somebody is waiting for you
+- `Idle` — nothing is running
+
+The dotted grip at the **top** moves the tab: press and drag it up or down and
+it slides along the edge, staying where you leave it.
+
+The grip at the **bottom** changes how long the bar is: drag it and the bar
+grows or shrinks downwards, its top staying put.
+
+Click anywhere else on the tab to open the island.
+
+### The expanded island
+
+The drawer lists only the sessions that are running **now** — idle sessions
+stay out of the way. Each row shows:
+
+| | |
+|---|---|
+| The agent | which agent is running it |
+| The phase | `THINKING`, `WRITING`, `WORKING`, `WAITING` or `RETRYING` |
+| The title | what the session is about |
+| The tool | the tool running right now, if any |
+| The answer | the last words the agent said, as they stream in |
+| The clock | how long the session has been going |
+
+Subagents appear indented under the session that spawned them.
+
+### The bottom bar
+
+| Control | What it does |
+|---|---|
+| ☀️ 🌙 🖥 | Light, dark or follow the system appearance |
+| 👆 | Click-through: the island stops taking clicks, except its grip, so you can still open it |
+| ☰ | Show the latest session's work in the closed tab instead of the summary |
+
+### Approvals
+
+When an agent asks for permission, the island turns warning orange and opens
+itself. Three buttons answer it in place:
+
+- **Allow once** — this one call
+- **Always allow** — this tool for the rest of the session
+- **Deny**
+
+Answering closes the island again.
+
+## How it works
+
+The plugin has two halves, and the split is what makes it survive.
+
+**The server half** (`src/index.ts`) is an ordinary OpenCode plugin. It does
+nothing on its own; it exists so the desktop app discovers the package and
+reads its GUI bundle.
+
+**The GUI half** (`src/gui.tsx`) runs in the desktop app's **main process**.
+That is the important part: a window-hosted plugin would stop when the last
+app window closes, which is exactly when you want to know that an agent is
+stuck on a permission prompt. From main, the plugin also reaches the app's own
+server, so it sees the sessions of **every project** on your machine, not just
+the one you have open.
+
+```
+src/gui.tsx          the plugin: follows the app's server, owns the state
+src/model.ts         turns the server's event stream into sessions and phases
+src/state.ts         the JSON the island renders
+src/window.ts        the Electron window: placement, dragging, resizing
+src/island/app/      the island UI: React 19, Tailwind v4 and shadcn/ui
+src/island/preload.cjs  the bridge between the page and the window
+```
+
+The island page is built by its own Vite pass into a single self-contained
+HTML file, which is then inlined into the plugin bundle. At runtime the
+island makes no network requests of its own and loads nothing from disk.
+
+The window is frameless, transparent and always on top. It is sized by the
+page: the page measures itself and asks the window for that size, and the
+window animates to it as a drawer sliding out of the screen edge. The island
+never takes focus when it appears.
+
+## Develop
+
+```sh
+npm install         # --ignore-scripts also works, and skips Electron's binary
+npm run dev         # build the island, then watch the plugin bundle
+npm run typecheck   # the plugin and the island, separately
+npm run check       # the streaming tail helpers
+```
+
+The desktop app hot-reloads the plugin when `dist/gui-experimental.cjs`
+changes, so `npm run dev` is enough to see most edits. You must restart the
+app after changing anything that runs in the main process (`src/gui.tsx`,
+`src/window.ts`, `src/model.ts`).
+
+The island UI lives in `src/island/app`. It is a separate Vite build with its
+own TypeScript config, because the plugin's own JSX is Solid and the island's
+is React.
+
+## Limits
+
+- macOS only, and the primary display only.
+- The island's spot along the edge, its appearance and its switches are
+  remembered for the session only; they reset when the app restarts.
+- The island shows what the app's server knows. A session that never
+  announces itself stays invisible.
+
+## License
+
+MIT. See [LICENSE](LICENSE).