### Run Project Setup Script

Source: https://github.com/colemurray/background-agents/blob/main/CONTRIBUTING.md

Execute the setup script to install dependencies, build packages, and configure git hooks. This is the quickest way to get a working development environment.

```bash
bash .openinspect/setup.sh
```

--------------------------------

### Session Setup and Snapshot Restoration Flow

Source: https://github.com/colemurray/background-agents/blob/main/docs/HOW_IT_WORKS.md

Illustrates the performance difference between the first session for a repository, which involves setup costs like cloning and installing dependencies, and subsequent sessions that restore from a snapshot for faster startup.

```mermaid
graph TD
    A[First session] --> B(Clone);
    B --> C(Install/Build);
    C --> D(Start Runtime);
    D --> E([Snapshot]);
    E --> F(Work);

    G[Later sessions] --> H([Restore Snapshot]);
    H --> I(Quick sync);
    I --> J(Start Runtime);
    J --> K(Work);
```

--------------------------------

### Setup Script for Package Installation

Source: https://github.com/colemurray/background-agents/blob/main/README.md

This script is used for provisioning and runs during image builds and fresh session startups. It installs Node.js and Python dependencies.

```bash
# .openinspect/setup.sh
#!/bin/bash
npm install
pip install -r requirements.txt
```

--------------------------------

### Install and Run Linear Bot Locally

Source: https://github.com/colemurray/background-agents/blob/main/packages/linear-bot/README.md

Steps to install dependencies, build the project, and start the local development server for the linear-bot package.

```bash
cd packages/linear-bot
npm install
npm run build
wrangler dev  # Local development
```

--------------------------------

### Sandbox Lifecycle: Fresh Start

Source: https://github.com/colemurray/background-agents/blob/main/docs/HOW_IT_WORKS.md

Illustrates the sequence of events when a new sandbox session is created without a prior snapshot. This includes sandbox creation, git synchronization, optional setup and start scripts, and agent initialization.

```mermaid
graph TD
    A[Sandbox Created] --> B(Git Sync\n(clone));
    B --> C{Setup Script\n(optional)};
    C --> D{Start Script\n(optional)};
    D --> E(Agent Start\n(OpenCode));
    E --> F[Ready];
    C -.-> G(.openinspect/setup.sh);
    D -.-> H(.openinspect/start.sh);
```

--------------------------------

### Install npm Dependencies

Source: https://github.com/colemurray/background-agents/blob/main/CONTRIBUTING.md

Installs all project dependencies using npm. This is a common step in local development setup.

```bash
npm install
```

--------------------------------

### Install Wrangler CLI

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Installs the Wrangler CLI globally using npm for initial R2 bucket setup.

```bash
npm install -g wrangler
```

--------------------------------

### Navigate and Copy Terraform Example Files

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Navigate to the production environment directory and copy example Terraform configuration files to their active counterparts.

```bash
cd terraform/environments/production

# Copy the example files
cp terraform.tfvars.example terraform.tfvars
cp backend.tfvars.example backend.tfvars
```

--------------------------------

### Install and Configure `next-themes`

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Installs the `next-themes` package and wraps the application with `ThemeProvider` in `src/app/layout.tsx`. This enables system-aware theme switching.

```bash
npm install -w @open-inspect/web next-themes
```

--------------------------------

### Install and Build Packages

Source: https://github.com/colemurray/background-agents/blob/main/CLAUDE.md

Commands to install project dependencies and build all or specific packages.

```bash
npm install
npm run build                                    # all packages
npm run build -w @open-inspect/shared            # shared only (build first!)
```

--------------------------------

### Install Local Packages

Source: https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/README.md

Install the 'sandbox-runtime' package and development dependencies for the project.

```bash
pip install -e ../sandbox-runtime
pip install -e ".[dev]"
```

--------------------------------

### Install Python and uv

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Installs Python 3.12+ and uv using Homebrew. The Modal CLI is installed via uv sync.

```bash
brew install python@3.12 uv
```

--------------------------------

### Install Node.js

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Installs Node.js version 22 using Homebrew.

```bash
# Node.js >= 22 (for building workers)
brew install node@22
```

--------------------------------

### Create Local Environment File

Source: https://github.com/colemurray/background-agents/blob/main/docs/SETUP_GUIDE.md

Copy the example environment file to create a local configuration for the web application.

```bash
cp packages/web/.env.example packages/web/.env.local
```

--------------------------------

### Install Modal Dependencies and Sync

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Install Modal deployment dependencies, including sandbox_runtime, from the repository root.

```bash
# Install Modal dependencies and sync
cd packages/modal-infra && uv sync --frozen && cd -
```

--------------------------------

### Install Modal CLI

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Installs the Modal CLI using pip.

```bash
# Modal CLI (for Modal deployments)
pip install modal
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Clone your fork of the repository, install Node.js dependencies, build the shared package, and install Python dependencies for Modal deployment.

```bash
# Clone your fork
git clone https://github.com/YOUR-USERNAME/background-agents.git
cd background-agents
npm install

# Build the shared package (required before Terraform deployment)
npm run build -w @open-inspect/shared

# Install Python dependencies for Modal deployment (includes sandbox-runtime)
cd packages/modal-infra && uv sync --frozen && cd -
```

--------------------------------

### Check Prerequisites

Source: https://github.com/colemurray/background-agents/blob/main/docs/SETUP_GUIDE.md

Verify that Node.js, npm, and Git are installed and meet the minimum version requirements.

```bash
node -v
npm -v
git --version
```

--------------------------------

### Routing Rules Example

Source: https://github.com/colemurray/background-agents/blob/main/docs/integrations/SLACK.md

Administrators can map keywords to specific repositories to automate request routing. This example shows rules for 'frontend' and 'api'.

```text
frontend → acme/web-app
```

```text
api → acme/backend
```

--------------------------------

### Install Dependencies

Source: https://github.com/colemurray/background-agents/blob/main/packages/control-plane/README.md

Installs project dependencies using npm. Ensure Node.js 22+ is installed.

```bash
cd packages/control-plane
npm install
```

--------------------------------

### Run Web App Locally

Source: https://github.com/colemurray/background-agents/blob/main/docs/SETUP_GUIDE.md

Start the local development server for the web application.

```bash
npm run dev -w @open-inspect/web
```

--------------------------------

### Install Terraform

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Installs Terraform version 1.9.0 or later using Homebrew.

```bash
# Terraform >= 1.9.0
brew install terraform
```

--------------------------------

### Bootstrap Daytona Infrastructure

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Install the Daytona Python package and run the bootstrap script to seed the named base snapshot for Daytona sandboxes. This is required for initial setup when using Daytona as a sandbox provider.

```bash
cd packages/daytona-infra
pip install daytona   # or: uv pip install daytona
python -m src.bootstrap --force
```

--------------------------------

### Python Modal-Infra Workflow - Install

Source: https://github.com/colemurray/background-agents/blob/main/docs/SETUP_GUIDE.md

Install the modal-infra package and its development dependencies, including the sandbox-runtime sibling package.

```bash
# alternative (install sandbox-runtime sibling package first)
pip install -e ../sandbox-runtime
pip install -e ".[dev]"
```

--------------------------------

### Example Agent Notification Command

Source: https://github.com/colemurray/background-agents/blob/main/docs/integrations/SLACK.md

This is an example of a command that can be used to trigger agent notifications to a Slack channel.

```text
When you finish, post a short summary to #eng-updates.
```

--------------------------------

### Development Commands for Background Agents

Source: https://github.com/colemurray/background-agents/blob/main/packages/web/README.md

Install dependencies, run the development server, perform type checking, and build the project for production using npm commands.

```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build
```

--------------------------------

### Record and Upload Video Workflow

Source: https://github.com/colemurray/background-agents/blob/main/packages/sandbox-runtime/src/sandbox_runtime/skills/record-video/SKILL.md

This script demonstrates the complete workflow for recording a browser interaction and uploading it as a video artifact. It includes opening the page, setting the viewport, starting and stopping the recording, and using ffprobe to extract metadata for upload.

```bash
set -e
agent-browser open "$URL"
agent-browser set viewport 1512 982
agent-browser snapshot -i

STARTED_AT_MS=$(date +%s%3N)
agent-browser record start /tmp/opencode/demo.mp4
recording_started=1
cleanup_recording() {
  if [ "${recording_started:-0}" = "1" ]; then
    agent-browser record stop || true
  fi
}
trap cleanup_recording EXIT

interaction_exit_code=0
agent-browser click "[data-testid=settings]" || interaction_exit_code=$?
agent-browser wait 1000 || interaction_exit_code=$?

agent-browser record stop
recording_started=0
trap - EXIT

ENDED_AT_MS=$(date +%s%3N)
PROBE_JSON=$(ffprobe -v error -print_format json -show_streams -show_format /tmp/opencode/demo.mp4)
DURATION_MS=$(node -e 'const p=JSON.parse(process.argv[1]); const v=(p.streams||[]).find((s)=>s.codec_type==="video")||{}; const d=Number(v.duration ?? p.format?.duration); console.log(Math.max(1, Math.round(d * 1000)));' "$PROBE_JSON")
DIMENSIONS=$(node -e 'const p=JSON.parse(process.argv[1]); const v=(p.streams||[]).find((s)=>s.codec_type==="video")||{}; console.log(JSON.stringify({width:Number(v.width),height:Number(v.height)}));' "$PROBE_JSON")
upload-media /tmp/opencode/demo.mp4 \
  --artifact-type video \
  --caption "What this recording verifies" \
  --source-url "$URL" \
  --duration-ms "$DURATION_MS" \
  --recording-started-at "$STARTED_AT_MS" \
  --recording-ended-at "$ENDED_AT_MS" \
  --dimensions "$DIMENSIONS" \
  --truncated false \
  --has-audio false
exit "$interaction_exit_code"
```

--------------------------------

### OAuth Authorization

Source: https://github.com/colemurray/background-agents/blob/main/packages/linear-bot/README.md

Initiates the OAuth installation flow for the Linear Bot.

```APIDOC
## GET /oauth/authorize

### Description
Starts the OAuth 2.0 authorization code grant flow to install the bot.

### Method
GET

### Endpoint
/oauth/authorize
```

--------------------------------

### Install Base Dependencies

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Installs core dependencies required for the project and shadcn integration. `@radix-ui/react-slot` is specifically needed for the `asChild` pattern in shadcn components.

```bash
npm install -w @open-inspect/web clsx tailwind-merge class-variance-authority
npm install -D -w @open-inspect/web @radix-ui/react-slot
```

--------------------------------

### Install Development Dependencies with uv

Source: https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/README.md

Use uv to synchronize frozen development dependencies, automatically resolving the sandbox-runtime. This is the recommended method.

```bash
uv sync --frozen --extra dev
```

--------------------------------

### Configure Terraform Variables

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Navigate to the production environment directory, copy example configuration files, and edit them with your specific values.

```bash
cd terraform/environments/production

# Copy example files and fill in values
cp terraform.tfvars.example terraform.tfvars
cp backend.tfvars.example backend.tfvars

# Edit with your values
vim terraform.tfvars
vim backend.tfvars
```

--------------------------------

### Install and Run Daytona Bootstrap Script

Source: https://github.com/colemurray/background-agents/blob/main/packages/daytona-infra/README.md

Installs the Daytona Python package and runs the bootstrap script to seed a Daytona base snapshot. Re-run when sandbox runtime or toolchain changes.

```bash
cd packages/daytona-infra
pip install daytona  # or: uv pip install daytona
python -m src.bootstrap --force
```

--------------------------------

### Prompt Queuing Example

Source: https://github.com/colemurray/background-agents/blob/main/docs/HOW_IT_WORKS.md

Illustrates how prompts are queued when a new prompt is sent while the agent is still processing a previous one. Prompts are processed in the order they are received.

```text
Prompt 1 (processing) ──▶ Prompt 2 (queued) ──▶ Prompt 3 (queued)
```

--------------------------------

### Create Sandbox via HTTP API

Source: https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/README.md

Example using curl to send a POST request to create a new sandbox, including authentication and content type headers.

```bash
curl -X POST "https://${WORKSPACE}--open-inspect-api-create-sandbox.modal.run" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-123",
    "repo_owner": "your-org",
    "repo_name": "your-repo",
    "control_plane_url": "https://your-control-plane.workers.dev",
    "sandbox_auth_token": "your-token"
  }'
```

--------------------------------

### Start Coding Session via Slack Mention

Source: https://github.com/colemurray/background-agents/blob/main/docs/integrations/SLACK.md

Initiate a coding session by mentioning the Open-Inspect bot in a Slack channel with your request. The bot will then process the request.

```text
@Open-Inspect fix the failing checkout tests in acme/web
```

--------------------------------

### GitHub Bot Development Commands

Source: https://github.com/colemurray/background-agents/blob/main/packages/github-bot/README.md

Essential commands for setting up and maintaining the GitHub Bot project. Includes dependency installation, building, testing, type checking, and linting.

```bash
# Install dependencies (from repo root)
npm install
```

```bash
# Build
npm run build -w @open-inspect/github-bot
```

```bash
# Run tests (46 tests)
npm run test -w @open-inspect/github-bot
```

```bash
# Type check
npm run typecheck -w @open-inspect/github-bot
```

```bash
# Lint
npm run lint -w @open-inspect/github-bot
```

--------------------------------

### Start a Coding Session via Mention

Source: https://github.com/colemurray/background-agents/blob/main/docs/integrations/LINEAR.md

Mention the OpenInspect agent in a Linear issue comment to initiate a coding session and request implementation with a pull request.

```text
@OpenInspect please implement this issue and open a pull request
```

--------------------------------

### Initialize shadcn/ui

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Runs the shadcn/ui initialization command to create the `components.json` configuration file.

```bash
npx shadcn@latest init
```

--------------------------------

### Health Check HTTP API

Source: https://github.com/colemurray/background-agents/blob/main/packages/modal-infra/README.md

Example using curl to perform a GET request for a health check on the Modal service.

```bash
curl "https://${WORKSPACE}--open-inspect-api-health.modal.run"
# {"success": true, "data": {"status": "healthy", "service": "open-inspect-modal"}}
```

--------------------------------

### Extract Installation ID from GitHub URL

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

After installing the GitHub App, the Installation ID can be found in the URL of the installation settings page.

```text
https://github.com/settings/installations/INSTALLATION_ID
```

--------------------------------

### Initialize and Apply Terraform (Phase 1)

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Initialize Terraform with backend configuration and apply the first phase of the deployment, which creates workers without bindings.

```bash
cd terraform/environments/production

# Initialize Terraform with backend config
terraform init -backend-config=backend.tfvars

# Deploy (phase 1 - creates workers without bindings)
terraform apply
```

--------------------------------

### Initialize Terraform with R2 Backend

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Initialize Terraform, configuring the R2 backend by either referencing a configuration file or passing values directly as arguments.

```bash
# Initialize with R2 backend config file
terraform init -backend-config=backend.tfvars

# Or pass values directly:
terraform init \
  -backend-config="access_key=YOUR_R2_ACCESS_KEY_ID" \
  -backend-config="secret_key=YOUR_R2_SECRET_ACCESS_KEY" \
  -backend-config='endpoints={s3="https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com"}'
```

--------------------------------

### Record Browser Interaction Video

Source: https://github.com/colemurray/background-agents/blob/main/packages/sandbox-runtime/src/sandbox_runtime/skills/agent-browser/SKILL.md

Record browser interactions using agent-browser record start and stop. The recording is saved to an MP4 file. Ensure to pair start and stop commands, and use trap for cleanup. Interaction commands should be placed between start and stop.

```bash
set -e
agent-browser open "http://127.0.0.1:3000/checkout"
agent-browser set viewport 1440 900
agent-browser snapshot -i
STARTED_AT_MS=$(date +%s%3N)
agent-browser record start /tmp/opencode/checkout-flow.mp4
recording_started=1
trap 'if [ "${recording_started:-0}" = "1" ]; then agent-browser record stop || true; fi' EXIT

interaction_exit_code=0
agent-browser click "[data-testid=continue]" || interaction_exit_code=$?
agent-browser wait 1000 || interaction_exit_code=$?

agent-browser record stop
recording_started=0
trap - EXIT
ENDED_AT_MS=$(date +%s%3N)
exit "$interaction_exit_code"
```

--------------------------------

### Initialize Terraform with Backend Configuration

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Re-run Terraform init command with backend configuration to resolve initialization issues.

```bash
terraform init -backend-config=backend.tfvars
```

--------------------------------

### Cron Expression Examples

Source: https://github.com/colemurray/background-agents/blob/main/docs/AUTOMATIONS.md

Examples of valid 5-field cron expressions for scheduling tasks. Note that the minimum schedule interval is 15 minutes, and six-field expressions are not supported.

```cron
*/15 * * * *
```

```cron
0 9 * * *
```

```cron
30 14 * * 1-5
```

```cron
0 0 1 * *
```

--------------------------------

### Initialize Terraform Backend with R2 Credentials

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Use this command to initialize the Terraform backend, specifically configuring it for R2 object storage using access and secret keys provided as environment variables.

```bash
terraform init \
  -backend-config="access_key=$R2_ACCESS_KEY_ID" \
  -backend-config="secret_key=$R2_SECRET_ACCESS_KEY"
```

--------------------------------

### Startup Script for Docker Services

Source: https://github.com/colemurray/background-agents/blob/main/README.md

This script handles the runtime startup of services, such as launching Docker containers. It runs for every non-build session startup.

```bash
# .openinspect/start.sh
#!/bin/bash
docker compose up -d postgres redis
```

--------------------------------

### GitHub App Token Generation Flow

Source: https://github.com/colemurray/background-agents/blob/main/packages/github-bot/README.md

The bot generates a GitHub App installation token through a multi-step process involving a private key, JWT, and the installation access token. This process uses Cloudflare Workers' crypto.subtle API.

```text
Private key → JWT (RS256, 10-min expiry) → Installation access token (1-hour TTL)
```

--------------------------------

### Launch OpenCode

Source: https://github.com/colemurray/background-agents/blob/main/docs/OPENAI_MODELS.md

Use this command to launch the OpenCode application locally. This is the first step in obtaining OpenAI OAuth credentials.

```bash
opencode
```

--------------------------------

### Check Modal CLI Version

Source: https://github.com/colemurray/background-agents/blob/main/terraform/README.md

Verify that the Modal CLI is installed and accessible by checking its version.

```bash
modal --version
```

--------------------------------

### Commit Attribution Example

Source: https://github.com/colemurray/background-agents/blob/main/docs/HOW_IT_WORKS.md

Shows how commit authorship is displayed when the agent makes changes. This format is standard for Git.

```git
Author: Jane Developer <jane@example.com>
Committer: Open-Inspect <bot@open-inspect.dev>
```

--------------------------------

### Check Modal CLI and Show Token

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Verify Modal CLI is working and display the token from the packages/modal-infra directory.

```bash
# Check Modal CLI is working (from packages/modal-infra)
cd packages/modal-infra
uv run modal token show
```

--------------------------------

### Get Verification Commands from Terraform

Source: https://github.com/colemurray/background-agents/blob/main/docs/GETTING_STARTED.md

Retrieve the necessary commands for verifying deployment components directly from Terraform outputs.

```bash
# Get the verification commands from Terraform
terraform output verification_commands
```

--------------------------------

### Add shadcn/ui Select Component

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Use this command to add the shadcn/ui Select component to your project. Ensure `@radix-ui/react-select` is installed.

```bash
npx shadcn@latest add select
```

--------------------------------

### Mentioning Bot in Channel

Source: https://github.com/colemurray/background-agents/blob/main/docs/integrations/SLACK.md

To start a session from a Slack channel, invite the bot and then mention it with the desired task and repository name.

```text
@Open-Inspect update the billing docs in acme/api
```

--------------------------------

### Configure `components.json` for shadcn/ui

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Sets up the `components.json` file to align with the project's structure and preferences, including Tailwind CSS configuration and component aliases.

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "hooks": "@/hooks",
    "lib": "@/lib"
  }
}
```

--------------------------------

### Add Shadcn UI Component

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Use this command to add a new Shadcn UI component to your project. Ensure you have the shadcn/ui CLI installed.

```bash
npx shadcn@latest add <component-name>
```

--------------------------------

### Add shadcn/ui Button Component

Source: https://github.com/colemurray/background-agents/blob/main/docs/shadcn-ui-integration-plan.md

Use this command to add the shadcn/ui Button component to your project. No additional dependencies are needed if `@radix-ui/react-slot` is already installed.

```bash
npx shadcn@latest add button
```