@obsfx/oversee 0.0.0-stage → 0.2.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,125 @@
-# 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?
+
+<img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/Screenshot%202026-10-24%20at%2003.09.55.png" alt="oversee" />
+
+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.
+
+### Platform notes
+
+- **Windows PowerShell:** PowerShell's default execution policy blocks the `oversee.ps1` launcher that npm creates, with `running scripts is disabled on this system`. This happens to every npm CLI on Windows. Run `oversee` from `cmd`, call `oversee.cmd` from PowerShell, or allow local scripts for your user:
+
+```
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+- **macOS executables:** the macOS executables in `releases` are not notarized, so Gatekeeper blocks one that was downloaded through a browser. Remove the quarantine flag and make it executable before running it. npm installs and downloads with `curl` or `gh` are not affected.
+
+```
+xattr -d com.apple.quarantine ./oversee-darwin-arm64
+chmod +x ./oversee-darwin-arm64
+```
+
+## 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.
+
+## Features
+
+<table>
+  <tr>
+    <th>Feature</th>
+    <th>Preview</th>
+  </tr>
+  <tr>
+    <td valign="top" width="40%">
+      <b>Comment on lines</b>
+      <br><br>
+      Select a line or a range of lines in the diff and write your comment in markdown. The comment keeps a copy of the lines it points at, so it still makes sense after the code changes.
+    </td>
+    <td>
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/comment.png" alt="Writing a comment on lines 22-26 of a diff" width="500" />
+    </td>
+  </tr>
+  <tr>
+    <td valign="top" width="40%">
+      <b>Finish the review</b>
+      <br><br>
+      When you are done, finish the review. Its comments move into a review session that your agent can pick up.
+    </td>
+    <td>
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/finish-review.png" alt="Finish review confirmation" width="346" />
+    </td>
+  </tr>
+  <tr>
+    <td valign="top" width="40%">
+      <b>Your agent takes it from there</b>
+      <br><br>
+      The agent works through the CLI: it lists the finished reviews, reads the comments with their saved code, fixes what needs fixing, replies to questions and updates the review status.
+    </td>
+    <td>
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/agent-cli.png" alt="An agent running oversee review list, start, get, reply and close" width="500" />
+    </td>
+  </tr>
+  <tr>
+    <td valign="top" width="40%">
+      <b>Follow up in the UI</b>
+      <br><br>
+      Status changes and replies show up as notifications, even the ones that happened while the UI was closed. Replies sit under the comment they answer, inside the review session.
+    </td>
+    <td>
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/notifications.png" alt="Notifications for a closed review, an agent reply and a review in progress" width="500" />
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/agent-reply.png" alt="A finished review session with an agent reply under a comment" width="500" />
+    </td>
+  </tr>
+  <tr>
+    <td valign="top" width="40%">
+      <b>Go to definition</b>
+      <br><br>
+      Hold <code>Cmd</code> (<code>Ctrl</code> on Windows and Linux) over a symbol to see its definition, and click it to open the file in a tab. Language servers are installed on demand from the settings.
+    </td>
+    <td>
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/go-to-definition.png" alt="Definition popover for bytesPerSecond" width="500" />
+    </td>
+  </tr>
+  <tr>
+    <td valign="top" width="40%">
+      <b>Call flow</b>
+      <br><br>
+      The <code>Call flow</code> mode of the sidebar shows the changed functions as a call tree, so you can read a change in the order it runs. Clicking a function opens the line where it is called.
+    </td>
+    <td>
+      <img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/call-stack.png" alt="Call flow sidebar next to the diff, showing estimateRemainingMs at its call site" width="500" />
+    </td>
+  </tr>
+</table>

package/bin/oversee.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict'
+
+const { spawn } = require('node:child_process')
+
+const platformPackage = `@obsfx/oversee-${process.platform}-${process.arch}`
+const executable = process.platform === 'win32' ? 'oversee.exe' : 'oversee'
+const forwardedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP']
+const consoleSignalsReachChild = process.platform === 'win32'
+
+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 child = spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' })
+
+const relaySignal = (signal) => {
+  if (!consoleSignalsReachChild) {
+    child.kill(signal)
+  }
+}
+
+for (const signal of forwardedSignals) {
+  process.on(signal, relaySignal)
+}
+
+child.on('error', (error) => {
+  console.error(`oversee: failed to start ${binaryPath}: ${error.message}`)
+  process.exit(1)
+})
+
+child.on('exit', (code, signal) => {
+  for (const forwarded of forwardedSignals) {
+    process.off(forwarded, relaySignal)
+  }
+  if (signal) {
+    process.kill(process.pid, signal)
+  } else {
+    process.exit(code ?? 1)
+  }
+})

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@obsfx/oversee",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Diff review and line annotation for git repositories, with a CLI for AI agents.",
+  "keywords": [
+    "agent-skills",
+    "agentic-ai",
+    "ai-agents",
+    "ai-code-review",
+    "annotation-tool",
+    "call-graph",
+    "claude-code",
+    "cli",
+    "code-review",
+    "developer-tools",
+    "diff-viewer",
+    "git",
+    "human-in-the-loop",
+    "language-server-protocol"
+  ],
+  "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.2.0",
+    "@obsfx/oversee-darwin-x64": "0.2.0",
+    "@obsfx/oversee-linux-arm64": "0.2.0",
+    "@obsfx/oversee-linux-x64": "0.2.0",
+    "@obsfx/oversee-win32-arm64": "0.2.0",
+    "@obsfx/oversee-win32-x64": "0.2.0"
+  }
+}