Better Hub Documentation

Better Hub is a platform designed to re-imagine code collaboration for both humans and AI agents. It provides an enhanced interface for GitHub workflows, focusing on speed and usability. Key features include:

• Repo overview: A cleaner layout featuring README rendering, a file tree, and an activity feed.
• PR reviews: Support for inline diffs, AI-powered summaries, and review comments.
• Issue management: Tools for faster triage, filtering, and acting on issues.
• Ghost (AI assistant): An integrated assistant that can review PRs, navigate code, triage issues, and write commit messages. Toggle Ghost using ⌘I.
• Command center: A central hub to search repos, switch themes, and navigate the platform using ⌘K.
• CI/CD status: Visibility into workflow runs and branch comparisons.
• Security advisories: Tracking of vulnerabilities on a per-repo basis.
• Keyboard-first design: Most actions are accessible via keyboard shortcuts.
• Browser extension: A Chrome and Firefox extension that adds an "Open in Better Hub" button directly onto GitHub pages.

The PRDetailLayout switches between three primary layout modes based on the props provided:

1. Conflict Resolution Mode: If conflictPanel is provided, the layout switches to a full-width view where the infoBar is at the top and the conflictPanel occupies the remaining space. The split-view and side-panels are ignored.
2. Desktop Split View: The default mode for large screens. It features a resizable split between the diffPanel (left) and a side panel (right). The side panel can toggle between conversation and overview tabs.
3. Mobile Tabbed View: On small screens, the layout switches to a bottom-tabbed interface where users toggle between the diffPanel (Files) and the conversationPanel (Chat).

Key Behaviors:

• Split Persistence: The width ratio between the code and conversation panels is saved to sessionStorage under the key pr-split-adjusted.
• Tab State: The active side-panel tab (conversation or overview) is synchronized with the URL ?tab= search parameter.
• Navigation Integration: Listens for the ghost:navigate-to-file event to automatically expand the code panel when navigating to a file from the overview.

When interacting with the AI command endpoint, the following behavioral rules apply to the model's output:

UI Rules

• Rich UI Rendering: Tool results are automatically rendered as rich UI components. The AI should not repeat tool output as text or markdown.
• Brief Commentary: After calling a tool, the AI should only provide a brief 1-sentence commentary. The UI handles the primary display.
• Conciseness: All text responses must be extremely short (1-2 sentences maximum).

Action Rules

• Confirmation: Destructive actions (e.g., delete repo, close issue) or sensitive actions (e.g., mergePullRequest) require the AI to ask for user confirmation first.
• Low-Risk Actions: Actions like starRepo, unstarRepo, forkRepo, watchRepo, or unwatchRepo should proceed directly without asking.
• Missing Details: If creating issues or PRs, the AI must ask for missing required details (like title or body).
• Context Awareness: When performing actions on a repository, the AI should check the pageContext first. If a repo entity is present, the user is likely referring to that repository and the AI should not ask for clarification.

Better Hub uses a Redis instance for data and a REST wrapper (redis-rest) to expose Redis via HTTP.

Redis Service:

• Uses redis:7-alpine.
• Data is persisted in the redis_data volume.

Redis REST Service (redis-rest):

• Uses hiett/serverless-redis-http:latest.
• Connectivity: Exposed on host port 8079 (listening on 127.0.0.1).
• Environment Variables:
  • SRH_MODE: Set to env.
  • SRH_TOKEN: The authentication token for the REST API. Defaults to local_token if ${SRH_TOKEN} is not provided.
  • SRH_CONNECTION_STRING: Set to redis://redis:6379 to connect to the internal Redis service.

services:
  redis:
    image: redis:7-alpine
    container_name: better-hub-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data

  redis-rest:
    image: hiett/serverless-redis-http:latest
    container_name: better-hub-redis-rest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8079:80"
    environment:
      SRH_MODE: env
      SRH_TOKEN: ${SRH_TOKEN:-local_token}
      SRH_CONNECTION_STRING: redis://redis:6379
    depends_on:
      - redis

To initialize Sentry on the server in a Next.js environment, use Sentry.init(). This configuration ensures that error tracking and performance monitoring are active during production requests.

Key configuration behaviors in this setup:

• Environment Control: Sentry is only enabled when process.env.NODE_ENV is set to production.
• DSN Selection: The Data Source Name (DSN) is pulled from process.env.SENTRY_DSN, falling back to process.env.NEXT_PUBLIC_SENTRY_DSN.
• Tracing: tracesSampleRate is set to 0.2 in production to manage volume, and 1 (100%) in non-production environments.
• PII Protection: sendDefaultPii is set to false. Additionally, a beforeSend hook is used to redact sensitive information from request headers (matching patterns like authorization, cookie, token, secret, password, pat, apikey, or api_key) and to clear all request cookies to prevent leaking sensitive user data.

import * as Sentry from "@sentry/nextjs";

const SENSITIVE_PATTERNS = /authorization|cookie|token|secret|password|pat|apikey|api_key/i;

Sentry.init({
	enabled: process.env.NODE_ENV === "production",
	dsn: process.env.SENTRY_DSN ?? process.env.NEXT_PUBLIC_SENTRY_DSN,
	tracesSampleRate: process.env.NODE_ENV === "production" ? 0.2 : 1,
	enableLogs: true,
	sendDefaultPii: false,
	beforeSend(event) {
		if (event.request?.headers) {
			for (const key of Object.keys(event.request.headers)) {
				if (SENSITIVE_PATTERNS.test(key)) {
					event.request.headers[key] = "[REDACTED]";
				}
			}
		}
		if (event.request?.cookies) {
			event.request.cookies = {};
		}
		return event;
	},
});

The postgres service uses postgres:16-alpine. It is configured to allow up to 300 connections via the max_connections=300 command.

Environment Variables:

• POSTGRES_USER: Defaults to postgres.
• POSTGRES_PASSWORD: Defaults to postgres if not provided via the ${POSTGRES_PASSWORD} environment variable.
• POSTGRES_DB: Set to better_hub.

Connectivity:

• The database is mapped to host port 54320 (listening on 127.0.0.1).
• Data is persisted in the postgres_data volume.

services:
  postgres:
    image: postgres:16-alpine
    container_name: better-hub-postgres
    restart: unless-stopped
    command: postgres -c max_connections=300
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
      POSTGRES_DB: better_hub
    ports:
      - "127.0.0.1:54320:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data