Quick Start

Get Oversight running locally in under five minutes. By the end of this guide you will have the dashboard open and your first repository analysis queued.

Before you start: make sure you have all the prerequisites installed — Node.js >= 20, pnpm >= 9, Claude CLI, and a Supabase project.

1. Clone the Repository

shell

git clone https://github.com/CopilotKit/oversight.git
cd oversight

shell

docker pull ghcr.io/copilotkit/oversight:latest
docker run -p 3001:3001 --env-file .env ghcr.io/copilotkit/oversight:latest

When using Docker, create a .env file in your current directory with the variables from step 2, then skip to step 4.

2. Configure Environment

Copy the example environment file and fill in your credentials:

shell

cp .env.example .env

Open .env and set the required values:

.env

# Supabase (required)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Frontend (same values, Vite requires the prefix)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJ...

# GitHub (optional — omit for browser OAuth login)
# GITHUB_PAT=ghp_...

# Server
PORT=3001

Where to find Supabase keys: go to your Supabase project dashboard, then Settings > API. Copy the Project URL, anon/public key, and service_role key. See Prerequisites for the full variable reference.

3. Install and Start

shell

pnpm install
pnpm dev

This starts both the Fastify server (port 3001) and the Vite dev server (port 5173) concurrently. The dashboard will be available at http://localhost:5173.

4. Start the Runner

In a separate terminal, start the task runner:

shell

pnpm runner

On first launch, the runner will:

Detect Claude CLI on your system (or fall back to Codex)
Identify your Supabase user (via RUNNER_USER_ID or auto-detection)
If no GITHUB_PAT is set, open a browser for GitHub OAuth login
Begin polling for queued tasks

Runner vs. Server: the server handles API requests and queues tasks. The runner picks up those tasks and executes them locally using Claude CLI. You need both running for full functionality.

5. Add a Repository

Open the dashboard at http://localhost:5173, sign in with GitHub, and add a repository to track. Enter the owner and name (e.g. CopilotKit/CopilotKit) and Oversight will begin its first analysis.

6. Your First Analysis

Once a repository is added, Oversight automatically queues an analysis. The runner will pick it up and:

Fetch all open PRs and issues from GitHub
Compute engagement signals (comment activity, review state, staleness)
Run Claude to triage and classify each item by priority and risk
Store results in Supabase, visible immediately in the dashboard

The analysis typically takes 30–90 seconds depending on how many open items the repository has. You can watch progress in real time on the dashboard.

What Next?

Now that Oversight is running, explore these areas:

Queue a review — click any PR in the dashboard and trigger a deep code review. The runner will clone the repo, check out the branch, and produce structured findings.
Enable Notion sync — set NOTION_API_KEY in your .env to sync review results to a Notion page.
Run in watch mode — use pnpm runner:watch for auto-restart on code changes during development.

Troubleshooting

Runner cannot find Claude CLI

Ensure claude is on your PATH. Run claude --version to verify. You can also force a specific CLI with OVERSIGHT_CLI=claude in your .env.

GitHub authentication errors

If the runner reports auth errors when fetching PRs, ensure your GITHUB_PAT has the repo scope, or re-authenticate via the browser OAuth flow by restarting the runner without a PAT set.

Supabase connection issues

Verify your SUPABASE_URL and keys are correct. The service role key is required for the server and runner; the anon key is used by the frontend.

Overview — understand the full architecture
Prerequisites — detailed setup instructions