@obsfx/oversee 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -1
- package/bin/oversee.js +26 -9
- package/package.json +23 -7
package/README.md
CHANGED
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
|
|
6
6
|
## What is this tool about?
|
|
7
7
|
|
|
8
|
+
<img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/Screenshot%202026-10-24%20at%2003.09.55.png" alt="oversee" />
|
|
9
|
+
|
|
8
10
|
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.
|
|
9
11
|
|
|
10
12
|
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`.
|
|
@@ -23,6 +25,21 @@ npm i -g @obsfx/oversee
|
|
|
23
25
|
|
|
24
26
|
2. Or you can download standalone executables from the `releases` section.
|
|
25
27
|
|
|
28
|
+
### Platform notes
|
|
29
|
+
|
|
30
|
+
- **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:
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- **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.
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
xattr -d com.apple.quarantine ./oversee-darwin-arm64
|
|
40
|
+
chmod +x ./oversee-darwin-arm64
|
|
41
|
+
```
|
|
42
|
+
|
|
26
43
|
## How to Use
|
|
27
44
|
|
|
28
45
|
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.
|
|
@@ -35,4 +52,74 @@ npm i -g @obsfx/oversee
|
|
|
35
52
|
npx skills add obsfx/oversee
|
|
36
53
|
```
|
|
37
54
|
|
|
38
|
-
Then use the `/oversee-address` skill inside your agent, and it will take care of the rest.
|
|
55
|
+
Then use the `/oversee-address` skill inside your agent, and it will take care of the rest.
|
|
56
|
+
|
|
57
|
+
## Features
|
|
58
|
+
|
|
59
|
+
<table>
|
|
60
|
+
<tr>
|
|
61
|
+
<th>Feature</th>
|
|
62
|
+
<th>Preview</th>
|
|
63
|
+
</tr>
|
|
64
|
+
<tr>
|
|
65
|
+
<td valign="top" width="40%">
|
|
66
|
+
<b>Comment on lines</b>
|
|
67
|
+
<br><br>
|
|
68
|
+
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.
|
|
69
|
+
</td>
|
|
70
|
+
<td>
|
|
71
|
+
<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" />
|
|
72
|
+
</td>
|
|
73
|
+
</tr>
|
|
74
|
+
<tr>
|
|
75
|
+
<td valign="top" width="40%">
|
|
76
|
+
<b>Finish the review</b>
|
|
77
|
+
<br><br>
|
|
78
|
+
When you are done, finish the review. Its comments move into a review session that your agent can pick up.
|
|
79
|
+
</td>
|
|
80
|
+
<td>
|
|
81
|
+
<img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/finish-review.png" alt="Finish review confirmation" width="346" />
|
|
82
|
+
</td>
|
|
83
|
+
</tr>
|
|
84
|
+
<tr>
|
|
85
|
+
<td valign="top" width="40%">
|
|
86
|
+
<b>Your agent takes it from there</b>
|
|
87
|
+
<br><br>
|
|
88
|
+
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.
|
|
89
|
+
</td>
|
|
90
|
+
<td>
|
|
91
|
+
<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" />
|
|
92
|
+
</td>
|
|
93
|
+
</tr>
|
|
94
|
+
<tr>
|
|
95
|
+
<td valign="top" width="40%">
|
|
96
|
+
<b>Follow up in the UI</b>
|
|
97
|
+
<br><br>
|
|
98
|
+
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.
|
|
99
|
+
</td>
|
|
100
|
+
<td>
|
|
101
|
+
<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" />
|
|
102
|
+
<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" />
|
|
103
|
+
</td>
|
|
104
|
+
</tr>
|
|
105
|
+
<tr>
|
|
106
|
+
<td valign="top" width="40%">
|
|
107
|
+
<b>Go to definition</b>
|
|
108
|
+
<br><br>
|
|
109
|
+
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.
|
|
110
|
+
</td>
|
|
111
|
+
<td>
|
|
112
|
+
<img src="https://raw.githubusercontent.com/obsfx/oversee/refs/heads/assets/go-to-definition.png" alt="Definition popover for bytesPerSecond" width="500" />
|
|
113
|
+
</td>
|
|
114
|
+
</tr>
|
|
115
|
+
<tr>
|
|
116
|
+
<td valign="top" width="40%">
|
|
117
|
+
<b>Call flow</b>
|
|
118
|
+
<br><br>
|
|
119
|
+
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.
|
|
120
|
+
</td>
|
|
121
|
+
<td>
|
|
122
|
+
<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" />
|
|
123
|
+
</td>
|
|
124
|
+
</tr>
|
|
125
|
+
</table>
|
package/bin/oversee.js
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
'use strict'
|
|
3
3
|
|
|
4
|
-
const {
|
|
4
|
+
const { spawn } = require('node:child_process')
|
|
5
5
|
|
|
6
6
|
const platformPackage = `@obsfx/oversee-${process.platform}-${process.arch}`
|
|
7
7
|
const executable = process.platform === 'win32' ? 'oversee.exe' : 'oversee'
|
|
8
|
+
const forwardedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP']
|
|
9
|
+
const consoleSignalsReachChild = process.platform === 'win32'
|
|
8
10
|
|
|
9
11
|
let binaryPath
|
|
10
12
|
try {
|
|
@@ -18,15 +20,30 @@ try {
|
|
|
18
20
|
process.exit(1)
|
|
19
21
|
}
|
|
20
22
|
|
|
21
|
-
const
|
|
23
|
+
const child = spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' })
|
|
22
24
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
25
|
+
const relaySignal = (signal) => {
|
|
26
|
+
if (!consoleSignalsReachChild) {
|
|
27
|
+
child.kill(signal)
|
|
28
|
+
}
|
|
26
29
|
}
|
|
27
30
|
|
|
28
|
-
|
|
29
|
-
process.
|
|
30
|
-
} else {
|
|
31
|
-
process.exit(result.status ?? 1)
|
|
31
|
+
for (const signal of forwardedSignals) {
|
|
32
|
+
process.on(signal, relaySignal)
|
|
32
33
|
}
|
|
34
|
+
|
|
35
|
+
child.on('error', (error) => {
|
|
36
|
+
console.error(`oversee: failed to start ${binaryPath}: ${error.message}`)
|
|
37
|
+
process.exit(1)
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
child.on('exit', (code, signal) => {
|
|
41
|
+
for (const forwarded of forwardedSignals) {
|
|
42
|
+
process.off(forwarded, relaySignal)
|
|
43
|
+
}
|
|
44
|
+
if (signal) {
|
|
45
|
+
process.kill(process.pid, signal)
|
|
46
|
+
} else {
|
|
47
|
+
process.exit(code ?? 1)
|
|
48
|
+
}
|
|
49
|
+
})
|
package/package.json
CHANGED
|
@@ -1,7 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@obsfx/oversee",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Diff review and line annotation for git repositories, with a CLI for AI agents.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"agent-skills",
|
|
7
|
+
"agentic-ai",
|
|
8
|
+
"ai-agents",
|
|
9
|
+
"ai-code-review",
|
|
10
|
+
"annotation-tool",
|
|
11
|
+
"call-graph",
|
|
12
|
+
"claude-code",
|
|
13
|
+
"cli",
|
|
14
|
+
"code-review",
|
|
15
|
+
"developer-tools",
|
|
16
|
+
"diff-viewer",
|
|
17
|
+
"git",
|
|
18
|
+
"human-in-the-loop",
|
|
19
|
+
"language-server-protocol"
|
|
20
|
+
],
|
|
5
21
|
"license": "MIT",
|
|
6
22
|
"repository": {
|
|
7
23
|
"type": "git",
|
|
@@ -17,11 +33,11 @@
|
|
|
17
33
|
"node": ">=18"
|
|
18
34
|
},
|
|
19
35
|
"optionalDependencies": {
|
|
20
|
-
"@obsfx/oversee-darwin-arm64": "0.
|
|
21
|
-
"@obsfx/oversee-darwin-x64": "0.
|
|
22
|
-
"@obsfx/oversee-linux-arm64": "0.
|
|
23
|
-
"@obsfx/oversee-linux-x64": "0.
|
|
24
|
-
"@obsfx/oversee-win32-arm64": "0.
|
|
25
|
-
"@obsfx/oversee-win32-x64": "0.
|
|
36
|
+
"@obsfx/oversee-darwin-arm64": "0.2.0",
|
|
37
|
+
"@obsfx/oversee-darwin-x64": "0.2.0",
|
|
38
|
+
"@obsfx/oversee-linux-arm64": "0.2.0",
|
|
39
|
+
"@obsfx/oversee-linux-x64": "0.2.0",
|
|
40
|
+
"@obsfx/oversee-win32-arm64": "0.2.0",
|
|
41
|
+
"@obsfx/oversee-win32-x64": "0.2.0"
|
|
26
42
|
}
|
|
27
43
|
}
|