human-agent-review-tool

A globally installed CLI (review-tool) that serves a local browser dashboard for human review of Git-tracked files. No project dependency, build step, or runtime npm dependencies. Requires Node.js 20+ and Git.

Install

npm install --global review-tool
# or
pnpm add --global review-tool

If you use a scoped package name, substitute that name in the installation command; the executable remains review-tool.

To install this unpublished package, run from this package directory:

npm pack
npm install --global ./review-tool-0.1.0.tgz
# or
pnpm add --global ./review-tool-0.1.0.tgz

If pnpm reports that its global bin directory is missing, run pnpm setup and restart your terminal.

Usage

cd /path/to/your/repository
review-tool
review-tool -h
review-tool --theme=light
review-tool --theme dark --port 8080 /path/to/another/repository

Open the printed URL in a browser. The server listens only on 127.0.0.1. Ctrl+C stops it. Dark is the default theme. -v/--version prints the version. Paths containing spaces must be quoted.

The dashboard retains the supplied script's search, status filters, progress, notes, and Cursor editor links (Cursor must be installed to open those links). It tracks working-tree contents of tracked regular files, excluding symlinks, submodules, deleted files, and the state file itself. It does not review untracked files or display diffs. Refresh the browser to see filesystem changes.

The Git root is found automatically, including when launched from a nested directory. Review state is saved in .repo-review.json at that root. A file changed since its review becomes stale/unreviewed. Notes are saved whenever you edit them (tab out of the note field); they persist across review statuses. Choosing Unreviewed clears only the review stamp, not an existing note. Clearing the note field removes the stored note. Run one instance per repository to avoid conflicting state writes.

Optionally commit .repo-review.json to share review state with others, or keep it local. Existing version 1 state files are supported; move any state file previously created in a subdirectory to the root if needed.

Ignore tool files in every repository

review-tool writes .repo-review.json (review state) and reads .reviewignore (optional file-review patterns). Both live at the Git repository root. If you do not plan to commit them, you can hide them in every repo on your machine with Git’s global exclude file. That file is never committed; it only affects your local git status.

One-time setup:

# Use a global ignore file (pick a path you already use, or this default)
git config --global core.excludesfile ~/.config/git/ignore
mkdir -p ~/.config/git
touch ~/.config/git/ignore

Add these lines to the file named by core.excludesfile (run git config --global core.excludesfile if you are unsure which file that is):

# review-tool
.repo-review.json
.reviewignore

Quick append (adjust the path if your excludes file differs):

excludes="$(git config --global core.excludesfile)"
mkdir -p "$(dirname "$excludes")"
touch "$excludes"
grep -qxF '.repo-review.json' "$excludes" 2>/dev/null || {
  printf '\n# review-tool\n.repo-review.json\n.reviewignore\n' >> "$excludes"
}

Verify from inside a repo where those files exist:

git check-ignore -v .repo-review.json .reviewignore

To track either file in a specific repository anyway, force-add it once: git add -f .repo-review.json or git add -f .reviewignore.

Per-repo alternative: add the same two paths to that repository’s .gitignore when you want the whole team to ignore them by default.

Ignore patterns

Create .reviewignore at the repository root. Blank lines and # comments are ignored. Patterns support *, **, and ?; a trailing slash excludes a root-relative directory. Patterns without a slash match basenames. These are simple globs, not full .gitignore semantics (no negation).

# Generated files
 dist/
*.lock
src/generated/**

Development and publishing

npm test
npm pack --dry-run

The package ships ordinary JavaScript and the complete embedded UI. End users do not need TypeScript or a dev installation.

The npm package name is review-tool. Add your chosen license and ownership/repository metadata, authenticate to npm, and run npm publish --access public when ready.