Getting Started

Start guide on using Optimal AI

Optimal AI helps engineering teams ship faster and build more reliably through two core products: - Optibot – AI code reviewers that analyze pull requests, catch issues early, and improve code quality automatically. - Insights – real-time analytics that track engineering productivity and surface actionable trends. Onboarding involves two parts: 1. Setting up Optibot Code Reviewer (GitHub Integration) 2. Setting up Insights for engineering analytics Follow this quick guide to get both running smoothly. Book a Personalized Walkthrough Get a live demo from our product team. We’ll walk you through Optibot installation, Insights setup, and common workflows from real teams. → Book a demo Explore the Optimal AI Learning Library Visit our YouTube channel for short walkthroughs, feature demos, and customer stories. You’ll find: - Real use cases from engineering teams using Optimal AI - Product updates and “what’s new” videos 💡 Pro tip: Every time we release a new feature, we post a quick demo video so you can see it in action right away. Set Up Optimal AI for Your Organization Once you’ve seen how it works, you can bring Optimal AI into your workflow in minutes. Step 1: Install Optibot Code Reviewer (GitHub Integration) Install Optibot using your work email and grant it access to your repositories. Setup takes less than 2 minutes. → Go to GitHub Setup Guide Step 2: Connect Insights Once Optibot is installed, you can enable Insights to start tracking metrics like PR Cycle Time, Activity, and Team Contributions. → Go to Insights Setup Guide Step 3: Add Slack Integration (Optional) Connect Slack to receive Optibot summaries, code review notifications, and weekly Insights digests directly in your channels. → Go to Slack Integration Guide See How Other Teams Use Optimal AI - How Prado scaled with Optibot - Why Artemis Ops uses Optimal AI for faster code reviews ✨ With Optimal AI, you’re empowering your team to code faster, review smarter, and ship securely.

Setting up your trial in Optimal AI | Optibot + Insights

This guide walks you through connecting your GitHub repos, activating Optibot, and exploring key Insights dashboards. Table of Contents 1. What “Activated” Looks Like 2. Prerequisites 3. Step-by-Step Onboarding (15–25 minutes) 4. First “Aha” Moments (what to check, when) 5. Quick Wins to Try This Week 6. Troubleshooting & Gotchas 7. FAQ 8. Need Help? 1) What “Activated” Looks Like You’re activated when: - Optibot installed on 1–2 active repos (fresh PRs are getting reviewed) - Insights connected to GitHub + Jira - Members added in Insights (so their metrics show) - Slack set up: shared support channel + notifications channel - You’ve seen Allocations → Distributions populate and one Optibot inline review + Slack ping (if your team is currently using Slack) 2) Prerequisites - GitHub org admin permissions - Jira admin (ability to create a service account or API token if you use Jira) - Slack permissions to install apps / create channels 3) Step-by-Step Onboarding (15–25 minutes) Step 1 — Install Optibot (GitHub App) 1. Open your Optibot install link (click here to access). 2. Choose your GitHub org → select 1–2 core repos (you can add more later). 3. Authorize and continue to the Optibot Dashboard. Tip: Pick repos with daily PR activity for fastest feedback. Step 2 — Create your Insights account (analytics) 1. Open the Insights Sign Up link. 2. Sign up with GitHub (not Sign In, on first run). 3. When asked which repos to monitor, select All or the set with active commits/PRs. Optibot and Insights can run independently, but together you’ll see agent impact + metrics side-by-side. Step 3 — Connect Slack (two parts) A. Shared Support Channel (with Optimal AI) Accept the invite from our team. This is your fastest path to help during trial. If you have not received an invite to slack, please email [email protected] to get you the invites. B. Optibot Notifications In Optibot → Connect Slack → pick or create a channel (e.g., #optibot-reviews). You’ll get messages when Optibot posts reviews/summaries and other info about your codebase. Step 4 — Add Members in Insights (critical) Insights → **Settings → **Members → add the engineers you want in dashboards. If a person isn’t added, their metrics won’t appear.. Step 5 — (Optional) Set up Teams in Insights - If you already use GitHub Teams, ping us to import them. - Or create teams in Insights and assign members for team-level views (Activity, PR Cycle Time by team). Step 6 — (Optional) Connect Jira to Insights If your team is a Jira user, follow these steps: 1. In Jira: Profile → Account Settings → Security → API tokens → create token. Prefer a service account (long-lived token; fewer expirations). 2. In Insights → Settings → Integrations** → Jira**: - Jira email (service/service-user or your email) - API token - Import users from Jira - Automatically integrate with Jira webhooks (if permissions allow) Jira email (service/service-user or your email) - Save. Notes: - Jira backfills historical data. - GitHub metrics populate from connection time forward (allow 24–48h for most views). Step 7 — (Optional) Connect Jira to Optibot Optibot → Integrations** → Jira** → reuse the same service account + token. Best practice: Include Jira ticket ID in branch names or PR titles (e.g., feat/ECOM-123-checkout). Step 8 — Validate Events & Notifications - Open/merge a small PR on a connected repo. - Confirm Optibot leaves an inline review + summary in GitHub. - Confirm a Slack notification appears. After Setup: 6) First Steps to Take in Platform Here are some things to play around with after set up: - **Insights → Investments → **Distributions See the mix of work across GitHub/Jira (bugs, hotfixes, features, dependencies, etc.). Within 24–48 Hours - PR Cycle Time — will populate as new PRs flow post-install. - Activity — becomes meaningful as members/teams are set. 7) Quick Wins to Try This Week 1. Set one guardrail Goal - Example: “Bugs ≤ 40% of work” or “Median PR size ≤ 300 LOC” - Insights → Goals → create threshold → attach to team/project. 2. Tune Review Flow with Optibot - Have Optibot review 3 fresh PRs. - Reply to its inline comments in GitHub (it supports back-and-forth conversation). - Use Slack notifs to keep reviewers unblocked. 3. Invite your VP Eng / Staff Eng to Insights - Add them in **Settings → **Members. 8) Troubleshooting & Gotchas - I don’t see metrics for someone. Add them in **Insights → Settings → **Members. (No member = no metrics.) - Teams are empty. Create teams in Insights or ask us to import from GitHub. - Slack isn’t posting. Re-connect Optibot → Slack and re-select the correct channel. - Jira data looks off / missing. Ensure GitHub + Jira profiles map to the same emails (or link Jira profiles in Insights). Prefer a service account token to avoid expiry. - PR views are empty. New PRs only populate PR Cycle Time; give it 24–48h after install. 9) FAQ Q: Do Optibot and Insights require each other? A: No. They work independently. Using both shows agent impact alongside team metrics. Q: Can you import GitHub Teams automatically? A: Yes, ask us in Slack; we’ll assist with import so team views populate. Q: How far back does data go? A: Jira backfills historical data. GitHub events count from the time of connection forward. Q: What’s the fastest path to value? A: Install Optibot on an active repo, add members in Insights, connect Slack, then open one small PR. Need Help? - Post in the shared Slack channel (fastest). - We also schedule a 30-min check-in mid way through the trial to review your data and set the right goals making sure you're gaining the most value. Screenshot Checklist - Insights Home with GitHub/Jira connected badges - Optibot → Install GitHub App (org/repo selector) - Insights → Sign Up (highlight “Sign up”) + Repo selection - Optibot → Slack integration (workspace + channel) - Insights → Settings → Members (add flow) - Insights → Teams (create/import) - Insights → Integrations → Jira (email/token + 2 checkboxes) - Optibot → Integrations → Jira (fields + save) - GitHub PR with Optibot inline comments (blur code) Slack notification from Optibot - Insights → Investments → Distributions (legend + % mix) - Insights → PR Cycle Time (median/time-in-stage) - Insights → Goals (create goal modal)

GitHub App Installation & Troubleshooting Guide - Optibot / Optimal Insights

Overview Before Optibot can review pull requests or measure engineering productivity, it needs permission to connect to your organization’s repositories via the Optibot & Optimal Insights GitHub App. This guide explains: - How to install the Optibot and Optimal Insights GitHub App - How to confirm they’re installed correctly - How to re-request the installation email if it’s missing - How to troubleshoot common setup issues You can install Optibot and Insights on multiple accounts (personal and organization). Each installation controls which repositories the app can access. Installation Flow 1. Open the installation link Optibot (Code Reviewer): https://github.com/apps/agent-optibot/installations/new Optimal Insights: https://github.com/apps/optimal-insights/installations/new 2. Choose where to install Select your organization or your personal account. 3. Select repository access - All repositories (recommended) - or Only selected repositories (manually choose repos) 4. Review requested permissions Confirm you’re comfortable granting access to read/write PRs, commits, and metadata. 5. Click Install or Request - Install → you have permission to complete it. - Request → only org owners can approve. GitHub will email them automatically. When you authorize a GitHub App, you’re granting it permission to act on behalf of your GitHub user (e.g. to write comments). 🟡 Note: Installation ≠ Authorization. Both may be required depending on org settings. Who Can Install the App - Organization Owner Can install Optibot across the entire org and grant repo access. - Repo Admin Can install Optibot only on repos you administer (if no org-level permissions required). - Org Member (no admin rights) Can request installation — GitHub will email the org owner for approval. If you see a “Request” button instead of “Install,” it means the organization owner must approve the installation. How to Verify Installation A. Organization Level 1. Go to GitHub → Organization Settings → Third-party Access → GitHub Apps 2. Confirm Agent Optibot and Optimal Insights appears in the list. 3. Click Configure to view: - Permissions granted - Repositories connected - Option to suspend/remove B. Repository Level 1. Go to Repo → Settings → Integrations → GitHub Apps 2. Confirm Optibot & Optimal Insights is listed. 3. Check if it has access to the correct repo(s). Didn’t Receive the Installation Email? If GitHub didn’t send (or you can’t find) the installation email: 1. Check spam/junk folders 2. Confirm you have org owner privileges — only owners receive approval emails 3. Visit Settings → Installed GitHub Apps to check if Optibot already appears 4. If not, visit the install URL again and reinstall manually. 👉 GitHub Official Guide – Installing a GitHub App from a third party 👉 Optimal Insights Signup 👉 Optibot (Code Review) Signup  5. Still blocked? Have your org owner follow the same link to approve directly Common Issues Troubleshooting Checklist Before activation calls, confirm all boxes are checked: - Org owner accepted the install invite - Optibot appears under “Installed GitHub Apps” - Correct repositories are selected - Permissions include read/write on PRs and metadata - App installed at org or repo level (not just personal) - Team knows who to contact if re-request needed If any of these are missing, share this doc and resolve before the call. Quick Reference Links - Installing a GitHub App (Official) - Viewing Installed Apps - Requesting App Installation from Org Owner - Dockstore GitHub Apps Troubleshooting Reference

Slack Integration

Stay informed without leaving Slack. Connect your Slack workspace to receive live notifications, pull-request updates, and weekly reports from Optibot directly in your team channels. 🧭 Overview Once connected, Optibot will automatically post updates in your selected Slack channel — including: - 🔍 Pull Request Reviews – see approvals, comments, and linked PRs as they happen. - 📊 Weekly Reports – get summarized repository insights every Friday at 5 PM PST. This integration keeps engineering teams aligned on progress without switching between GitHub, GitLab, and Slack. ⚙️ How to Connect Slack 1. Go to Slack Integration Settings In your Optibot dashboard, open Settings → Integrations → Slack Integration, then click Integrate with Slack. 2. Authorize in Slack You’ll be redirected to Slack to approve permissions for Optibot. Click Allow to grant access. Optibot will be able to: - View basic workspace and channel info - Post messages in conversations 3. Select a Default Channel After authorization, return to Optibot to choose the Slack channel where notifications should appear. Use the dropdown search to filter and select your preferred channel. 4. Confirmation in Slack Once the integration is complete, you’ll see a welcome message in the selected channel: “👋 Hello! Optibot was installed in this channel. From now on, I’ll be posting information about all my interactions with your code here.” 🔁 What You’ll Receive 🧩 PR Review Notifications Each time a pull request is reviewed by Optibot, a detailed message is sent to Slack showing: - Repository name - PR title and link - Review outcome (✅ Approved / ❌ Not Approved) - Any code review comments 📅 Weekly Summary Reports Every Friday at 5 PM PST, Optibot automatically posts a weekly summary to your Slack channel. This report highlights: - Total PRs reviewed - Average cycle time - Top-performing repositories - Key metrics comparing before vs. after Optibot adoption

Optimal Insights

Get a complete view of how your engineering team ships — from delivery speed to AI-assisted development. Insights connects directly to GitHub, analyzes your real activity data, and turns it into actionable metrics so you can spot friction, measure progress, and ship faster. 🚀 PR Cycle Time Measure how fast your team moves from first commit to merge. The PR Cycle Time dashboard shows where time is spent in your pull request workflow — from creation to review to merge. It helps you identify slowdowns and track improvements across teams, repos, or individual developers. Key Metrics - Average Cycle Time – Total time from first commit to merge. - Excellent badge appears when under 24 hours. - Time to Open – From first commit to PR creation. - Time in Review – Duration the PR waits for review and approval. - Time to Merge – From PR open to merge into the target branch. - Merged to Staging – How many PRs reached staging environments. Each metric updates automatically and compares against the previous period (↑ or ↓ indicators). Filters and Views - Teams vs. Individuals – Switch between team-wide or contributor-level insights. - Repositories – Focus on one or multiple repos (e.g. insights-app-be). - Date Range – Analyze over 7, 14, 30, or 90-day windows to track trends. The dashboard refreshes every few hours so you’re always seeing current data. Average Cycle Time Graph The line chart visualizes how your team’s cycle time changes over time: - The green line tracks daily performance. - The dotted line shows the benchmark from the previous period. Use it to spot delivery spikes, bottlenecks, or gradual process improvements. Pull Request Table Each row shows a PR with details like: - Author - Reworks % - Check Failure Rate - PR Size (lines changed) - Time to Open / Merge / Review Quick filters highlight what needs attention: - Longest Review Time – Stuck reviews. - Most Discussions – High comment volume. - Most Check Failures – CI/CD instability. Column controls (⋮) let you toggle data points like Reviewer, Assignee, or Jira issues. ⚡ AI Insights Instantly understand what changed — and why. The AI Insights side panel automatically analyzes the page you’re on (like PR Cycle Time or Activity) and provides an executive summary. What It Shows - TL;DR Summary – Explains what shifted (e.g., longer open times but faster merges). - Activity Trends – Week-over-week % changes in each metric. - Notable Contributors – Who or what drove those changes (e.g., “optibot-dev[bot] active in reviews”). This helps engineering leads skip raw data analysis and jump straight to decision-making. Pro tip: open it weekly before sprint reviews — it’s like having a built-in engineering analyst. 🕓 Activity Visualize your team’s engineering rhythm. The Activity view shows commits, reviews, merges, and comments across a timeline — giving you a visual heartbeat of your team’s workflow. How It Works Each developer appears as a row; each bubble represents activity for that day. The bigger the bubble, the more events occurred. Color codes: - ⚪ Commit – Code pushed to the repository - 🔵 PR Open – New pull request created - 🟡 PR Review – Pull request reviewed - 🟢 Merge Commit – Pull request merged into the main branch - 🔴 Comment – Review comment added on a pull request Hovering on any bubble reveals exact counts: PRs reviewed: 1 • PRs opened: 2 • PRs merged: 1 • Comments: 1 • Commits: 2 Switch between Week and Month views or zoom to see team-level vs. individual activity. Why It Matters - Spot midweek review peaks and Friday slowdowns. - Balance review load across engineers. - Detect burnout or under-utilization patterns early. 🤖 AI Adoption Measure how AI tools impact your engineering workflow. The AI Adoption dashboard tracks real usage and engagement with AI coding tools like GitHub Copilot and Claude 3.7. Core Metrics - Overall Code Acceptance Rate – % of AI-suggested code merged. - Average Chat Interactions per Day – How often engineers engage AI assistants. - Top Performing Model by Acceptance – The AI model producing the most accepted code. - Highest Acceptance by Language – Which language benefits most (e.g., Python). - Average Daily Engagement Rate – % of developers actively using AI tools. Below, the Copilot User Engagement chart shows daily active vs. engaged AI users over time. Why It Matters This dashboard connects productivity metrics to AI usage — revealing whether tools like Copilot are actually helping teams ship faster or just increasing noise. 💡 Pro Tips - Enable AI Insights on every major dashboard for context-aware summaries. - Standardize GitHub labels to improve Distributions and Allocations data. - Compare time windows (7-day vs 30-day) to measure process improvements. - Encourage reviewers to spread feedback load — visible in Activity view. - Track AI Adoption alongside PR Cycle Time to measure real ROI of Copilot. 🧭 Troubleshooting - No data yet? Wait a few hours after connecting GitHub; Insights backfills automatically. - Missing PRs or repos? Verify permissions include read + metadata access. - Empty AI Adoption view? Ensure AI telemetry is enabled in connected IDEs or extensions.