skepsis - GitLite

KO | EN

gitlite — search

#python #go #android #deep-learning #linux #docker #windows #awesome #cli #kubernetes #awesome-list #pytorch #security #open-source

skepsis

(★ 124)

Local web UI for code review

File Explorer

Download Latest Version (.zip)

- settings.json
- - ci.yml
  - license-check.yml
  - release.yml
- comment.ts
- commentSyntax.test.ts
- commentSyntax.ts
- diff.test.ts
- diff.ts
- displayCommand.test.ts
- displayCommand.ts
- fileContents.ts
- main.test.ts
- main.ts
- settings.test.ts
- settings.ts
- testUtil.ts
- viewed.ts
- reviewComments.test.ts
- reviewComments.ts
- types.ts
- App.tsx
- main.tsx
- styles.css
- vite-env.d.ts
.gitattributes
.gitignore
.licenserc.yaml
.oxfmtrc.json
.oxlintrc.json
CLAUDE.md
cli.ts
index.html
LICENSE
package-lock.json
package.json
README.md
tsconfig.json
tsdown.config.ts
vite.config.ts

# Installation Guide

1. Get the code

git clone https://github.com/oxidecomputer/skepsis

Downloads the entire project code from GitHub to your computer.

cd skepsis

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

Node.js Node.js must be installed to use npm.

npm install --global @oxide/skepsis

Installs the package published on the npm registry globally — no need to clone the source.

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Node.js

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install --global @oxide/skepsis

Installs the package published on the npm registry globally — no need to clone the source.

cd skepsis && npm install

Moves into the project folder you just downloaded.

npm run ci

Type this command into your terminal and run it.

npm version patch --no-git-tag-version # or minor/major — bumps package.json

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# skepsis

> [σκέψις](https://www.perseus.tufts.edu/hopper/text?doc=Perseus:text:1999.04.0057:entry=ske/yis): viewing, perception by the senses. Examination, speculation, consideration.

A fully local browser-based code review UI. Review your (or your agent's) diff _before_ inflicting it on the world.

- GitHub-style split or unified diff view with syntax highlighting
- Mark files as viewed
- Inline review comments are written directly into source files as code comments
- Works with [jj](https://jj-vcs.dev/) and git (tries jj first, falls back to git)
- Vim-style navigation shortcuts (press `?` to see the list)

https://github.com/user-attachments/assets/698365ab-964c-4e38-a605-82bec4879f60

## Setup

Requires [Node.js](https://nodejs.org/) v22+.

Run it without installing:

```
npx @oxide/skepsis
```

`npx` may reuse a cached package version. To force the newest published
version, run:

```
npx @oxide/skepsis@latest
```

To install a persistent command:

```
npm install --global @oxide/skepsis
skepsis
```

Either way, you may want a shorter alias:

```
alias sk="npx @oxide/skepsis"
```

## Usage

Takes `-r`/`--revision`, `-f`/`--from`, and `-t`/`--to` flags for specifying
the commit range. The VCS is auto-detected. In jj mode, the flags are passed
straight to `jj diff`. In git mode, they have to be translated slightly. See the
examples below.

Each invocation picks a free port by default, so you can run multiple instances
simultaneously. To use a specific port, pass `--port`/`-p`:

```
skepsis --port 8080
```

Use `--host` as well if the server needs to be reachable from another machine:

```
skepsis --host 0.0.0.0 --port 8080
```

In `--dev` mode, `--port` sets the browser-facing Vite port; the proxied API
server continues to use a free port.

### jj examples

The examples use `skepsis`, the installed bin name. An `sk` alias works the
same way.

```
skepsis                          # review branch vs trunk, GitHub PR style
                                 # (jj diff --from 'fork_point(trunk() | @)')
skepsis -r @                     # review working copy only
skepsis -r 'mybranch..@'         # review a range
skepsis -f main -t @             # diff between two revisions
```

### git examples

Ranges passed with `-r` are passed through verbatim to `git diff`.

```
skepsis                          # review branch + working tree vs origin
                                 # (git diff --merge-base origin/HEAD; falls
                                 # back to origin/main, origin/master, main,
                                 # master)
skepsis -f main                  # diff since main: git diff main HEAD
skepsis -r main..my-branch       # review commits on my-branch
skepsis -r HEAD~5..HEAD          # review the last 5 commits
skepsis -f v1.2.0 -t v1.3.0      # compare two tags
skepsis --git                    # force git in a jj-colocated repo
```

## How it works

The CLI starts a local HTTP server that shells out to `jj diff`
or `git diff`, then serves the diff to a React frontend that uses
[`@pierre/diffs`](https://diffs.com/) to render it with syntax highlighting.

The npm package ships compiled CLI/server JavaScript plus a prebuilt frontend
bundle, so installing or running with `npx` does not build anything. In dev
mode (`--dev`), a Vite dev server runs alongside the API server with hot
reload from a source checkout.

### Comments

Review comments are inserted into the source files, so they show up in your VCS
diff and are visible to coding agents. They can be resolved (deleted) from the
UI. Comments are only enabled when the diff includes the working copy (e.g.,
a revset ending in `@` for jj, or an open-ended range ending at the working
tree for git), since that's where the inserted lines land. The default diff
in both modes ends at the working copy, so comments are enabled by default.

### Marking files viewed

Viewed state is stored per file in `~/.local/share/skepsis/` using the file's
content hash (the git object ID from the diff header). If the file changes, the
hash no longer matches and it automatically shows as unviewed again.

## Development

Clone the repo when working on skepsis itself:

```
git clone https://github.com/oxidecomputer/skepsis.git
cd skepsis && npm install
```

Running from a checkout requires Node v22.18+, since the CLI runs as
TypeScript directly via Node's built-in type stripping. Point an alias at the
clone to run it from any repo:

```
alias sk="node ~/repos/skepsis/cli.ts"
```

`--dev` runs a Vite dev server with hot reload alongside the API server:

```
sk --dev
```

Before committing changes, run:

```
npm run ci
```

## Versioning

- **patch** — bug fixes, dependency bumps, internal changes
- **minor** — new features: flags, keyboard shortcuts, UI capabilities
- **major** — breaking changes to anything scriptable or on disk: removed or
  renamed flags, changed flag defaults, changed `<review>` comment or
  viewed-state formats

## Releases

To publish a release, bump the version and land the change on `main`:

```
npm version patch --no-git-tag-version   # or minor/major — bumps package.json
jj commit -m 'v0.1.1'                    # land the bump on main via PR
```

On every push to `main`, CI checks whether the `package.json` version is
already on the registry. If not, it publishes and creates a matching [GitHub
release](https://github.com/oxidecomputer/skepsis/releases) like `v0.1.1` with
auto-generated notes listing the PRs merged since the previous release.

To publish a canary build of a PR, go to the [Release
workflow](https://github.com/oxidecomputer/skepsis/actions/workflows/release.yml),
click "Run workflow", and enter the PR number. It publishes the PR's head as
`<version>-canary.<pr>.<sha>` under the `canary` dist-tag and comments the
version on the PR.