@obsfx/oversee 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ömercan Balandı
+
+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,38 @@
-# Temporary Holding Version
 
-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.
+# oversee
+
+<img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/oversee.png" alt="oversee" width="200"/>
+
+## What is this tool about?
+
+As of October 2026, when I'm writing this README, after using Opus 5.5, I've become convinced that writing code manually has largely become an old-fashioned practice. These tools are faster than us and sometimes even smarter. They can go through an entire codebase using bash tools much faster than we can by manually reading code, and on top of that, they can complete well-specified tasks in much less time. It's not hard to see this from the work I've done over almost the last year.
+
+However, as a human, I still want to stay in the loop while developing tasks and products delegated to agents, especially at points where human intervention is still needed. The biggest reason for this is the concept of [**Cognitive Debt**, which Simon Willison](https://simonwillison.net/2026/Feb/15/cognitive-debt/) also talks about. I've noticed that if things get out of hand and I no longer understand what's going on under the hood, even at a high level, I start having difficulty making decisions about the product's next steps and future. Also, not correcting an agent at an early stage can lead to much bigger problems, like a snowball effect. One thing is certain: I used to experience these problems much more frequently with earlier versions of Opus with 200k context windows, and things are much better now. Still, I feel the need to read the output to avoid `Cognitive Debt`.
+
+That's exactly what **oversee** is for. What it does is very simple: it basically brings the GitHub PR experience to your local environment. Through a web-based UI, you can add **comments**, complete your **review**, and pass it to your agent through its CLI. This tool came out of my desire to have the same PR experience you'd have with a coworker, but locally, before pushing any code.
+
+**oversee** is a diff viewer and line annotation tool. I also refer to it as a **Human Intervention Interface**. It's written in Go and React. The UI is embedded into the Go binary. It also has LSP support for a few languages.
+
+## Installation
+
+1. You can install **oversee** globally through npm.
+
+```
+npm i -g @obsfx/oversee
+```
+
+2. Or you can download standalone executables from the `releases` section.
+
+## How to Use
+
+1. Run `oversee init` in the codebase where you want to use it. This command will create a `.oversee` directory where we store the review data. For persistence, the entire history is saved in a SQLite database inside this directory.
+2. Then run `oversee serve` to start the UI.
+3. After adding your comments, all you need to do is tell your agent that you have comments in `oversee`. Your agent is smart enough to figure out the rest.
+
+**But to make things easier, you can install the oversee skill.**
+
+```
+npx skills add obsfx/oversee
+```
+
+Then use the `/oversee-address` skill inside your agent, and it will take care of the rest.

package/bin/oversee.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict'
+
+const { spawnSync } = require('node:child_process')
+
+const platformPackage = `@obsfx/oversee-${process.platform}-${process.arch}`
+const executable = process.platform === 'win32' ? 'oversee.exe' : 'oversee'
+
+let binaryPath
+try {
+  binaryPath = require.resolve(`${platformPackage}/bin/${executable}`)
+} catch {
+  console.error(
+    `oversee: no prebuilt binary for ${process.platform}-${process.arch}.\n` +
+      `The optional dependency ${platformPackage} is missing. Reinstall without --no-optional, ` +
+      'or check that your platform is supported.',
+  )
+  process.exit(1)
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: 'inherit' })
+
+if (result.error) {
+  console.error(`oversee: failed to start ${binaryPath}: ${result.error.message}`)
+  process.exit(1)
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal)
+} else {
+  process.exit(result.status ?? 1)
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@obsfx/oversee",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Diff review and line annotation for git repositories, with a CLI for AI agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obsfx/oversee.git"
+  },
+  "bin": {
+    "oversee": "bin/oversee.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@obsfx/oversee-darwin-arm64": "0.1.0",
+    "@obsfx/oversee-darwin-x64": "0.1.0",
+    "@obsfx/oversee-linux-arm64": "0.1.0",
+    "@obsfx/oversee-linux-x64": "0.1.0",
+    "@obsfx/oversee-win32-arm64": "0.1.0",
+    "@obsfx/oversee-win32-x64": "0.1.0"
+  }
+}