CopilotKit Chat

Oversight embeds a CopilotKit-powered chat assistant that can interact with your analysis data via natural language. The assistant has access to frontend tools for filtering, sorting, launching reviews, generating plans, and more.

Architecture

The chat system consists of two parts:

• Server: A CopilotRuntime using @copilotkit/runtime/v2 with a built-in agent backed by Claude Opus. The runtime is bridged from Hono (CopilotKit's default) to Fastify via request hijacking.
• Client: Frontend tools registered via useFrontendTool from @copilotkit/react-core/v2. These tools give the assistant the ability to take actions in the UI and call oversight APIs.

The server endpoint is mounted at /api/copilotkit and handles all CopilotKit protocol traffic.

Available Tools

The following tools are available to the chat assistant. Each tool is a frontend action that the assistant can invoke based on natural language conversation.

filterItems

Filter the PR or Issue list by a keyword or phrase. Pass an empty string to clear the filter.

{ query: string }

Example: "Show me only PRs related to streaming"

sortItems

Sort the PR or Issue list by a field. Supports rank, author, title, age, and other fields. Pass an empty field to reset.

{
  field: string,     // e.g. "rank", "author", "title", "age"
  direction: string  // "asc" or "desc"
}

Example: "Sort PRs by age, newest first"

launchReview

Launch a Claude Code review on a specific PR. Creates a review task that the local runner picks up and executes.

{ prNumber: number }

Example: "Review PR #42"

triggerAnalysis

Run a new PR or Issue analysis on the selected repository. This scans all open items, ranks them by priority, and generates AI summaries.

{ kind: string }  // "pr" or "issue"

Example: "Run a fresh analysis of all open issues"

amendReview

Revise an existing PR review based on instructions. Only works when a review is currently open and completed in the peek panel.

{ instructions: string }

Example: "Focus the review more on security implications"

generatePlanFromObservation

Generate a cohesive implementation plan from an observation that references multiple issues. See Implementation Plans for details on plan structure.

{
  observation: string,
  issueNumbers: string,    // comma-separated: "42,45,51"
  syncToNotion?: boolean
}

Example: "Create a plan to address the error handling issues in #42, #45, and #51"

createNotionPage

Create a Notion page with custom content. Useful for saving analysis summaries, comparison reports, or any generated text to Notion for persistence.

{
  title: string,
  content: string  // Markdown body
}

Example: "Save this analysis summary to Notion as 'Q1 PR Health Report'"

executeDispatchToClaudeCode

Send an implementation plan to Claude Code for automated execution. Creates a branch, implements the plan, and opens a PR. See Dispatch to Claude Code for details.

{
  planMarkdown: string,
  branchName?: string
}

Example: "Execute the plan we just generated"

Server Configuration

Interacting with Analysis Data

The chat assistant has contextual awareness of the current UI state through CopilotKit's readable state. This means you can have conversations like:

• "What are the highest priority PRs?" — the assistant sees the ranked list
• "Filter to show only PRs by alice" — calls filterItems
• "Review the top-ranked PR" — calls launchReview with the right number
• "Generate a plan for the error handling issues" — calls generatePlanFromObservation
• "Dispatch that plan to Claude Code" — calls executeDispatchToClaudeCode after confirmation
• "Save this conversation summary to Notion" — calls createNotionPage

The tools compose naturally: generate a plan, review it in conversation, then dispatch it for execution — all without leaving the chat interface.