Prerequisites

Everything you need to set up before running Oversight. Most of these are one-time setup steps.

Required Tools

Tool	Minimum Version	Purpose
Node.js	>= 20	Runtime for the server and runner
pnpm	>= 9	Package manager (workspaces)
git	Any recent	Repo cloning and PR branch checkout
Claude CLI	Latest	AI execution engine for the runner

Node.js

Oversight requires Node.js 20 or later. Check your version:

shell

node --version
# v20.x.x or higher

Install via nodejs.org, nvm, or your system package manager.

pnpm

Oversight uses pnpm workspaces to manage its monorepo (server, web, shared packages). Install pnpm globally:

shell

npm install -g pnpm

Claude CLI

The runner executes tasks using the Claude CLI. Install it and verify it works:

shell

# Install Claude CLI (see https://docs.anthropic.com/en/docs/claude-cli)
claude --version

Why Claude CLI? The runner spawns Claude in non-interactive mode to perform code reviews, generate fixes, and analyze diffs. It uses your locally installed plugins, skills, and MCP servers — giving it full context about your development environment.

Required Accounts

GitHub Account + Token

Oversight accesses GitHub to fetch PRs, issues, diffs, and engagement data. You have two options for authentication:

OAuth (recommended) — the runner opens a browser for GitHub login on first start. No token needed.
Personal Access Token — set GITHUB_PAT in your .env file. Useful for headless or CI environments.

If using a PAT, it needs these scopes:

repo — full access to private repositories
read:org — read organization membership (if using org repos)

Supabase Project

Oversight stores all data (repos, analyses, tasks, settings) in Supabase. You need:

A Supabase project (free tier works)
The project URL and keys from your Supabase dashboard

From your project’s Settings > API page, grab:

Project URL — your Supabase instance URL
anon / public key — for the frontend
service_role key — for the server and runner (keep this secret)

Optional Integrations

Notion

Oversight can sync code review results to Notion. If you want this, create an internal integration at notion.so/my-integrations and grant it write access to your target page.

GitHub OAuth App

For multi-user setups where each user authenticates via GitHub, register an OAuth application in your GitHub settings and provide the client ID and secret.

Environment Variable Reference

The complete list of environment variables used by Oversight:

Variable	Required	Description
`SUPABASE_URL`	Yes	Your Supabase project URL
`SUPABASE_ANON_KEY`	Yes	Supabase anonymous/public key (frontend + runner auth)
`SUPABASE_SERVICE_ROLE_KEY`	Yes	Supabase service role key (server + runner)
`VITE_SUPABASE_URL`	Yes	Same as SUPABASE_URL (Vite requires the prefix)
`VITE_SUPABASE_ANON_KEY`	Yes	Same as SUPABASE_ANON_KEY (Vite requires the prefix)
`GITHUB_PAT`	No	GitHub Personal Access Token (fallback if not using OAuth)
`GITHUB_OAUTH_CLIENT_ID`	No	GitHub OAuth app client ID
`GITHUB_OAUTH_CLIENT_SECRET`	No	GitHub OAuth app client secret
`RUNNER_USER_ID`	No	Explicit Supabase user ID (skips auto-detection)
`NOTION_API_KEY`	No	Notion integration token for review sync
`COPILOTKIT_MODEL`	No	Model for the AI copilot endpoint (default: claude-opus-4-6)
`OVERSIGHT_REPO_DIR`	No	Persistent directory for repo cache (default: temp dir)
`OVERSIGHT_CLI`	No	Force a specific CLI adapter: `claude` or `codex`
`PORT`	No	Server listen port (default: 3001)

Next Steps

Quick Start — clone, configure, and run Oversight
Overview — understand the architecture and capabilities