Ctrlk
Sign inVisit bito.aiVideo Library
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Install AI Architect (self-hosted)

Deploy AI Architect in your own infrastructure for complete data control and enhanced security

This guide walks you through installing Bito's AI Architect as a self-hosted service in your own infrastructure. Self-hosting gives you complete control over where your code knowledge graph resides and how AI Architect accesses your repositories.

Why choose self-hosted deployment? Organizations with strict data governance requirements, air-gapped environments, or specific compliance needs benefit from running AI Architect within their own infrastructure. Your codebase analysis and knowledge graph stay entirely within your control, while still providing the same powerful context-aware capabilities to your AI coding tools.

What you'll accomplish: By the end of this guide, you'll have AI Architect running on your infrastructure, connected to your Git repositories, and ready to integrate with AI coding tools like Claude Code, Cursor, Windsurf, and GitHub Copilot through the Model Context Protocol (MCP).

Deployment options

AI Architect can be deployed in three different configurations depending on your team size, infrastructure, and security requirements:

a. Personal use (with your LLM keys)

Set up AI Architect on your local machine for individual development work. You'll provide your own LLM API keys for indexing, giving you complete control over the AI models used and associated costs.

Best for: Individual developers who want codebase understanding on their personal machine.

b. Team / shared access (with your LLM keys)

Deploy AI Architect on a shared server within your infrastructure, allowing multiple team members to connect their AI coding tools to the same MCP server. Each team member can configure AI Architect with their preferred AI coding agent while sharing the same indexed codebase knowledge graph.

Best for: Development teams that want to share codebase intelligence across the team while managing their own LLM costs.

c. Enterprise deployment (requires Bito Enterprise Plan)

Deploy AI Architect on your infrastructure (local machine or shared server) with indexing managed by Bito. Instead of providing your own LLM keys, Bito handles the repository indexing process, simplifying setup and cost management.

Best for: Organizations that prefer managed indexing without handling individual LLM API keys and costs.

Note: All deployment options are self-hosted on your infrastructure — your code and knowledge graph remain under your control.

Prerequisites

a. Required accounts and tokens

1

Bito API Key (aka Bito Access Key)

You'll need a Bito account and a Bito Access Key to authenticate AI Architect. You can sign up for a Bito account at https://alpha.bito.ai, and create an access key from Settings -> Advanced Settings

2

Git provider

We support the following Git providers:

  • GitHub

  • GitLab

  • Bitbucket

  • Azure DevOps

So, you'll need an account on one of these Git providers to index your repositories with AI Architect.

3

Git Access Token

A personal access token from your chosen Git provider is required. You'll use this token to allow AI Architect to read and index your repositories.

  1. GitHub Personal Access Token (Classic): To use GitHub repositories with AI Architect, ensure you have a CLASSIC personal access token with repo access. We do not support fine-grained tokens currently.

  2. GitLab Personal Access Token: To use GitLab repositories with AI Architect, a token with API access is required.

  3. Bitbucket Access Token: To use Bitbucket repositories with AI Architect, you need API Token or HTTP Access Token depending on your Bitbucket setup.

    1. Bitbucket Cloud (API Token): You must provide both your token and email address.

    2. Bitbucket Self-Hosted (HTTP Access Token): You must provide both your token and username.

  4. Azure DevOps (cloud) Personal Access Token with Full access: The token must be created for the Azure DevOps organization whose repositories you want to index.

    1. View Guide

4

LLM API keys

Bito's AI Architect uses Large Language Models (LLMs) to build a knowledge graph of your codebase.

LLM API keys are required for self-managed AI Architect deployments. Provide an API key for the LLM provider you plan to use, such as:

  • Anthropic (Claude)

  • OpenAI (GPT)

  • Portkey

  • Google Vertex AI

  • Azure AI

  • Novita

  • AWS Bedrock

  • Google Gemini

  • Local OpenAI-compatible (bring your own server)

What you need to configure Google Vertex AI:

  • A GCP service-account key JSON with Vertex AI access

  • The GCP project ID

  • A region (e.g. us-central1)

What you need to configure Azure AI:

  • The Azure AI API key

  • The endpoint URL (e.g. https://<resource>.openai.azure.com)

What you need to configure Local OpenAI-compatible:

  • The base URL of your OpenAI-compatible /v1 endpoint (for example https://llm.internal:8000/v1)

  • The exact model name served by your endpoint (recommended: claude-haiku-4.5)

  • An API token — optional; sent as a Bearer token if provided, and can be left blank for keyless local servers

The endpoint must be reachable from inside the AI Architect containers: for a server running on the same host, use http://ai-architect-local:<port>/v1 instead of localhost, 127.0.0.1, or 0.0.0.0; for remote servers, use a private-network or VPN-resolvable hostname. Supported servers include vLLM, Ollama, LM Studio, LocalAI, TGI, and llama.cpp.

Testing with GitHub Copilot as your local endpoint? See How to test against the GitHub Copilot Bridge (VS Code) below.

AI Architect supports Portkey integration for custom proxy configurations.

With an Anthropic API key, indexing costs are typically $0.15 - $0.30 per MB of indexable code (source files only; binaries, archives, and images are skipped).

Teams of up to five members can use AI Architect for free with their preferred coding agents by using their own LLM API keys. Larger teams require Bito Enterprise Plan, which includes bundled LLM tokens. Further, if you want to power Bito Code Review Agent with AI Architect, you will need Bito Enterprise Plan regardless of the size of the team.

To use Bito-hosted LLM instead (no LLM keys required from you), contact support@bito.ai about the Bito Enterprise Plan.

How to test against the GitHub Copilot Bridge (VS Code)

Overview. The Copilot Bridge extension exposes GitHub Copilot’s models inside VS Code as an OpenAI-compatible /v1 endpoint. Register it as the Local OpenAI-compatible provider above to test AI Architect against Copilot’s models without a separate LLM API key.

1. Install the extension. Install thinkability.copilot-bridge (repo: larsbaunwall/vscode-copilot-bridge). Ensure GitHub Copilot and Copilot Chat are installed and signed in — the bridge proxies the VS Code Language Model API and needs an active Copilot seat.

2. Configure (open Settings with Cmd+, on macOS or Ctrl+, on Windows/Linux, then search “bridge” — or edit settings.json directly):

  • "bridge.enabled": true

  • "bridge.port": 8000 — pin it (default 0 = random port, which breaks a stable baseURL)

  • "bridge.token": "<your-token>" — REQUIRED; an empty token blocks all API access

  • "bridge.maxConcurrent": 4 — default 1 serializes AI Architect’s calls

3. Start it. Command Palette → Copilot Bridge: Enable (and Copilot Bridge: Status to confirm the port). After changing settings, re-run Enable or Developer: Reload Window.

4. Verify the bridge directly:

Note an exact model id from /v1/models (e.g. claude-sonnet-4.6, gpt-5.4).

b. System requirements

AI Architect can be installed on your local machine for individual use, or on a shared server that your entire team can connect to. When installed on a server, multiple developers can configure their AI coding tools (such as Claude Code, Cursor, Windsurf, etc.) to use the same MCP server, sharing access to the indexed codebase.

The AI Architect supports the following operating systems:

  • macOS

  • Unix-based systems (Ubuntu, Debian, RHEL, or similar distributions)

  • Windows (via WSL2)

Shared servers (for team deployments)

  • On-premise physical servers - Bare metal Linux servers in your data center

  • On-premise virtual machines - VMware, Hyper-V, Proxmox, KVM, or other virtualization platforms

  • Cloud virtual machines - AWS EC2, Google Cloud Compute Engine, Azure VMs, DigitalOcean Droplets, or similar cloud instances

1

Hardware specifications

Tier
Repositories
vCPU
Memory
Storage

Minimum

up to 25

12 cores

24 GB

500 GB

Ideal

25 – 100

16 cores

48 GB

1.5 TB

Enterprise

100+

32+ cores

128+ GB

2 – 4 TB+

Notes:

  • Large repositories: Increase memory and storage by 50% above the tier baseline when any single repository exceeds 5 GB.

  • Indexing workload: Indexing generates transient CPU and memory peaks above steady-state usage. The resources listed above include the headroom required to absorb these peaks; do not size below the tier minimums.

  • Persistent storage: Automatically configured during installation using Docker volumes or Kubernetes PersistentVolumeClaims.

  • Production security: Restrict access via firewall rules and front the deployment with a reverse proxy (e.g., Nginx) with HTTPS enabled.

AI Architect automatically detects available system resources during setup and configures optimal resource allocation for its Docker containers. For most deployments, the automatic configuration provides good performance. However, you can manually adjust these settings to fine-tune performance or accommodate specific workload requirements.

To view the active values:

To change a limit, edit the corresponding line in .env-bitoarch and apply:

Keep total allocated memory under ~75% of host memory to leave room for indexing bursts and the OS page cache.

2

WSL2 is required for Windows users

If you're running Windows, Windows Subsystem for Linux 2 (WSL2) must be installed before proceeding.

To install WSL2:

  1. Open PowerShell or Command Prompt as Administrator

  2. Run the following command:

  1. Set up your Ubuntu username and password when prompted.

3

Supported deployment modes

AI Architect supports two deployment modes. Choose the option that fits your infrastructure:

Mode
Use case
Requirements

Docker (Compose)

Single-host deployments, evaluation, smaller teams

Docker Engine and Docker Compose. Install Docker Desktop — includes both.

Kubernetes (Helm)

Production deployments requiring high availability and horizontal scaling

A pre-configured Kubernetes cluster on your infrastructure. For testing in a single laptop or local machine, create a local cluster using KIND (Kubernetes in Docker) — see the Kubernetes Deployment Guide.

4

Docker Desktop / Docker Service (required)

Docker Compose is required to run AI Architect.

The easiest and recommended way to get Docker Compose is to install Docker Desktop.

Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI which are Docker Compose prerequisites.

Install Docker Desktop

Configuration for Windows (WSL2):

If you're using Windows with WSL2, you need to enable Docker integration with your WSL distribution:

  1. Open Docker Desktop

  2. Go to Settings > Resources > WSL Integration

  3. Enable integration for your WSL distribution (e.g., Ubuntu)

  4. Click Apply

5

Kubernetes cluster (required for Kubernetes based deployment method)

For production environments:

During the setup process given below, if you choose Kubernetes as your deployment method, you must have an existing Kubernetes cluster set up and running.

Ensure your Kubernetes cluster have the following required tools:

  • kubectl (Kubernetes command-line tool)

  • helm (Kubernetes package manager)

For testing and development:

For testing purposes, you can create a local Kubernetes cluster using KIND (Kubernetes in Docker). KIND allows you to run Kubernetes clusters in Docker containers.

Install KIND:

  • macOS:

  • Linux:

Note: Before creating a KIND cluster, verify Docker has sufficient resources:

Required: Minimum 4 CPUs and 8GB RAM

If resources are insufficient, increase Docker Desktop resources (Preferences → Resources) and restart Docker.

Setting up a test cluster with KIND

Create a KIND cluster with proper port mappings for service access:

Note: Services use ClusterIP for secure, internal-only access. External access is configured via Ingress Controller on ports 80/443.

Verify cluster

Installation guide

1

Install AI Architect

Before proceeding with the installation, ensure Docker Desktop / Docker Service or Kubernetes cluster is running on your system. If it's not already running, launch it and wait for it to fully start before continuing.

Open your terminal:

  • Linux/macOS: Use your standard terminal application

  • Windows (WSL2): Launch the Ubuntu application from the Start menu

Execute the installation command:

The installation script will:

  • Download the latest Bito AI Architect package

  • Extract it to your system

  • Initialize the setup process

Installing dependencies:

The AI Architect setup process will automatically check for required tools on your system. If any dependencies are missing (such as jq, which is needed for JSON processing), you'll be prompted to install them. Simply type y and press Enter to proceed with the installation.

2

Configuration

Download the install.default.yaml file, then rename it to install.yaml and place it at ~/.bitoarch/install.yaml on your machine.

Open the file and update the configuration with your details by following the inline instructions.

Providing your Bito API key and Git credentials is required for the setup to work.

Note: Refer to the Prerequisites section for details on how to obtain these.

Alternatively, follow the on-screen prompts to configure your deployment. You'll provide the following information:

Select AI Architect deployment method:

Choose how you want to deploy Bito's AI Architect. We support two deployment methods:

  1. Docker Compose: Deploys AI Architect using Docker Compose.

  2. Kubernetes: Deploys AI Architect to an existing Kubernetes cluster. Choose this option if you have an existing Kubernetes cluster running and want to leverage Kubernetes for orchestration, scaling, and management.

    • Note: The setup script will automatically deploy AI Architect services to your Kubernetes cluster in the bito-ai-architect namespace.

If you have a Kubernetes cluster:

  1. Ensure it's running

  2. Verify the current Kubernetes context: kubectl config current-context

  3. Check connectivity: kubectl cluster-info

If you don't have a Kubernetes cluster:

  1. Select Docker Compose (option 1)

You'll need to provide the following details when prompted:

Note: Refer to the Prerequisites section for details on how to obtain these.

  • Bito API Key (required) - Enter your Bito Access key and press Enter.

  • Git provider (required):

    You'll be prompted to choose your Git provider:

    1. GitLab

    2. GitHub

    3. Bitbucket

    4. Azure DevOps

    Enter the number corresponding to your Git provider and press Enter.

  • Is your Git provider self-hosted or cloud-based?

    • Type y for enterprise/self-hosted instances (like https://github.company.com) and enter your custom domain URL

    • Type n for standard cloud providers (github.com, gitlab.com, bitbucket.org)

    Press Enter to continue.

  • Git Access Token (required) - Enter personal access token for your Git provider and press Enter.

  • Enable Git Insights? (optional) - Bito analyzes commit history to surface engineering activity insights. Learn more

    • Type y to enable Git insights.

    • Type n to skip it.

    Press Enter to continue.

  • Enable Ticket Tracker Insights? (optional) - Links Jira ticket activity to engineering work for richer insights. Learn more

    • Type y to enable ticket tracker insights.

    • Type n to skip it.

    Press Enter to continue.

    If you have enabled ticket tracker insights, you need to provide the following details:

    • Atlassian site URL — the URL you visit in the browser (e.g. https://acme.atlassian.net — NOT the api.atlassian.com/ex/jira/... form)

    • Email for Jira API

    • Jira API token

    • Select host type

      • (1) cloud

      • (2) self

    Your Jira credentials will be validated. Upon successful validation, available Jira projects will be fetched that are accessible with your Jira credentials. Enter projects which you want to index (comma/space separated, e.g. 1,3,5 or 1-4 or 'all'). Press Enter to keep current selection (or skip if none configured).

  • Enable Confluence integration? (optional) - Adds Confluence as docs source for richer ticket-link context. Learn more

    • Type y to enable Confluence integration.

    • Type n to skip it.

    Press Enter to continue.

    If you have enabled Confluence integration, you need to provide the following details:

    • Confluence URL (e.g. https://acme.atlassian.net):

  • Configure Insights Lookback Period - Number of days of history to analyze.

    • By default, the lookback days for Git and Jira are 180 days. You can also set your own number of days based on your team's requirements.

  • Configure LLM API keys (required) - Choose which AI model provider(s) to configure:

    1. Anthropic

    2. OpenAI

    3. Portkey

    4. Google Vertex AI

    5. Azure AI

    6. Novita

    7. AWS Bedrock

    Enter the number corresponding to your AI model provider, then provide your API key when prompted.

    After adding a provider, you'll be asked: "Do you want to configure another provider?"

    • Type y to add additional providers (recommended for better coverage and fallback options).

    • Type n when you're done adding LLM providers.

    Press Enter to continue.

  • Generate a secure MCP access token? - You'll be asked if you want Bito to create a secure token to prevent unauthorized access to your MCP server:

    • Type y to generate a secure access token (recommended)

    • Type n to skip token generation

    Press Enter to continue.

  • Configure SSO? - Optionally enable Single Sign-On (SSO) authentication. Choose between Bito authentication (OAuth via your Bito workspace) or Enterprise IdP (SAML/OIDC via your corporate identity provider). See SSO Authentication for more details.

3

Add repositories

Once your Git account is connected successfully, Bito automatically detects your repositories and populates the /usr/local/etc/bitoarch/.bitoarch-config.yaml file with an initial list. Review this file to confirm which repositories you want to index — feel free to remove any that should be excluded or add others as needed. Once the list looks correct, save the file, and continue with the steps below.

For versions older than 1.4.0, configuration file can be found in installation directory.

Below is an example of how the .bitoarch-config.yaml file is structured:

After updating the .bitoarch-config.yaml file, you have two options to proceed with adding your repositories for indexing:

  1. Auto Configure (recommended)

    • Automatically saves the repositories and starts indexing

    • If needed, edit the repo list before selecting this option

  2. Manual Setup

    • You have to manually update the configuration file and then start the indexing. Below we have provided complete details of the manual process.

Once you select an option, your Bito MCP URL and Bito MCP Access Token will be displayed. Make sure to store them in a safe place, you'll need them later when configuring MCP server in your AI coding agent (e.g., Claude Code, Cursor, Windsurf, GitHub Copilot (VS Code), etc.).

To manually apply the configuration, run this command:

4

Start indexing

Once your repositories are configured, AI Architect needs to analyze and index them to build the knowledge graph. This process scans your codebase structure, dependencies, and relationships to enable context-aware AI assistance.

Start the indexing process by running:

Note: Indexing process will take approximately 3-10 minutes per repository. Smaller repos take less time.

Once the indexing is complete, you can configure AI Architect MCP server in any coding or chat agent that supports MCP.

5

Check indexing status

Run this command to check the status of your indexing:

Example output:

What each section represents:

  • Configured Repositories: Shows how many repositories are added in your config file for indexing.

  • Repository Index Status: Shows the indexing progress for each individual repository.

  • Workspace Index Progress: Shows the status of indexes that combine and process information across multiple repositories.

  • Overall Status: Provides a single summary indicating whether indexing is still running, completed successfully, or failed.

6

Check MCP server details

To manually check the MCP server details (e.g. Bito MCP URL and Bito MCP Access Token), use the following command:

If you need to update your Bito MCP Access Token, use the following command:

Replace <new-token> with your new secure token value.

Important: After rotating the token, you'll need to update it in all AI coding agents (Claude Code, Cursor, Windsurf, etc.) where you've configured this MCP server.

Update repository list and re-index

Edit /usr/local/etc/bitoarch/.bitoarch-config.yaml file to add/remove repositories.

To apply the changes, run this command:

Start the re-indexing process using this command:

SSO Authentication

AI Architect supports Single Sign-On (SSO) authentication for secure, multi-user access to the MCP server. SSO runs entirely on-prem — no authentication traffic leaves your environment except for identity provider federation (if Enterprise IdP is configured) and Bito API calls for SSO configurations.

Authentication modes

AI Architect supports three authentication modes:

Mode
Provider
How it works

Bearer Token

None (SSO disabled)

Static MCP access token passed in the request header. This is the default mode.

Bito Authentication

Bito

OAuth flow validated via your Bito workspace. Ideal for teams already using Bito.

Enterprise IdP

Enterprise IdP

OAuth flow federated to your corporate SAML/OIDC identity provider (e.g., Okta, Azure AD, Google Workspace).

Note: If Enterprise IdP is selected but not yet configured, the system automatically falls back to Bito authentication until the IdP setup is complete.

Setting up SSO during installation

SSO is configured during the setup process. When prompted with "Configure SSO?", you can choose one of the following options:

  1. Enterprise IdP (SAML/OIDC)

    • The setup process generates a configuration URL for your identity provider

    • Open the URL in your browser and configure your IdP (e.g., Okta, Azure AD, Google Workspace) with the provided details. Learn more

    • Return to the setup and verify the connection

  2. Bito Authentication

    • Enables OAuth authentication using your Bito workspace credentials

    • No additional IdP configuration is required

Note: You can also configure or reconfigure SSO at any time after installation using the bitoarch sso setup command.

Configuring SSO after installation

If you skipped SSO during initial setup or want to change your SSO configuration, you can use the following CLI commands:

Set up or reconfigure SSO:

This command will guide you through the SSO configuration process, including choosing between Enterprise IdP and Bito authentication.

Check SSO status:

Displays the current SSO configuration and IdP connection status.

Managing SSO

Enable SSO

Re-enable SSO after it has been temporarily disabled:

Disable SSO

You can disable SSO either temporarily or permanently:

You will be prompted to choose:

  • Temporary disable — Turns off SSO authentication but preserves your IdP configuration. You can re-enable it later with bitoarch sso enable.

  • Permanent disable — Removes the IdP configuration entirely and resets SSO settings. You will need to run bitoarch sso setup again to reconfigure.

Rotate SSO management key

Rotate the SSO tenant management key for security purposes:

Important: After rotating the key, SSO services will restart automatically. Active sessions may need to re-authenticate.

SSO session configuration

SSO sessions are configurable with the following defaults:

Setting
Default
Description

Session duration

360 minutes (6 hours)

How long a session remains valid

Refresh token TTL

300 minutes (5 hours)

How long a refresh token remains valid

Max concurrent sessions

2

Maximum number of concurrent sessions per user

Note: Session settings can be customized through environment variables in the .env-bitoarch configuration file.

Accessing services (Kubernetes-based deployment)

Port-forwards are exposed on all network interfaces (0.0.0.0) and are accessible from any machine on the network.

Local access (from the Kubernetes host machine)

Network access (from other machines on your network)

Get the host machine's IP address:

From another machine on the network:

Security considerations

Important security notes:

  • Port-forwards use HTTP (not HTTPS) - traffic is unencrypted

  • Services are accessible from any machine that can reach the host

For production internet-facing deployments:

  • Use firewall rules to restrict access to trusted IPs

  • Consider using Kubernetes Ingress with TLS/SSL

  • Implement VPN for remote access

  • Use network policies to limit pod-to-pod traffic

Alternative: Kubernetes Ingress (production)

For production deployments, configure a Kubernetes Ingress Controller with TLS/SSL instead of using port-forwards. This provides secure HTTPS access with proper certificate management.

Setting up AI Architect MCP in coding agents

Now that AI Architect is installed and your repositories are indexed, the next step is to connect it to your AI coding tools (such as Claude Code, Cursor, Windsurf, GitHub Copilot, etc.) through the Model Context Protocol (MCP).

Quick setup (recommended)

Save time with our automated installer! We provide a one-command setup that automatically configures AI Architect for all compatible AI coding tools on your system.

The automated installer will:

  • Detect all supported AI tools installed on your system

  • Configure them automatically with your MCP credentials

  • Get you up and running in seconds instead of manually configuring each tool

👉 Try our Quick MCP Integration Guide for automated setup across all your tools.

Manual setup

If you prefer hands-on control over your configuration or encounter issues with automated setup, we provide detailed step-by-step guides for each supported AI coding tool:

Each guide walks you through the complete manual configuration process for that specific tool.

Plugins

Plugins add optional capabilities — like answering questions in Slack or analyzing Jira tickets — on top of your self-hosted AI Architect installation. Each plugin is a self-contained service you install, configure, and remove with a single command. Installing, updating, or removing a plugin never affects the base platform, its databases, or your indexed repositories.

Available plugins

Plugin
What it does
Integrates with

Slack AI Assistant (ai-assistant)

Ask AI Architect about your codebase, architecture, and repositories and get grounded answers directly in your Slack channels.

Slack

Bito Task Analyzer (task-analyzer)

Analyzes new and updated Jira tickets and posts its findings back as comments — either on every change or on @bito mention.

Jira

Plugins are offered during installation once the base platform is healthy, and you can manage them any time with the bitoarch plugin commands:

Full setup, configuration, and troubleshooting steps for each plugin are in the Plugins guide.

Configuring AI Architect for Bito AI Code Review Agent

Now that you have AI Architect set up, you can take your code quality to the next level by integrating it with Bito's AI Code Review Agent. This powerful combination delivers significantly more accurate and context-aware code reviews by leveraging the deep codebase knowledge graph that AI Architect has built.

Why integrate AI Architect with AI Code Review Agent?

When the AI Code Review Agent has access to AI Architect's knowledge graph, it gains a comprehensive understanding of your entire codebase architecture — including microservices, modules, APIs, dependencies, and design patterns.

This enables the AI Code Review Agent to:

  • Provide system-aware code reviews - Understand how changes in one service or module impact other parts of your system

  • Catch architectural inconsistencies - Identify when new code doesn't align with your established patterns and conventions

  • Detect cross-repository issues - Spot problems that span multiple repositories or services

  • Deliver more accurate suggestions - Generate fixes that are grounded in your actual codebase structure and usage patterns

  • Reduce false positives - Better understand context to avoid flagging valid code as problematic

Getting started with AI Architect-powered code reviews

  1. Log in to Bito Cloud

  2. Open the AI Architect Settings dashboard.

  3. In the Server URL field, enter your Bito MCP URL

  4. In the Auth token field, enter your Bito MCP Access Token

Need help getting started? Contact our team at support@bito.ai to request a trial. We'll help you configure the integration and get your team up and running quickly.

Insights

Insights features analyze commit history, Jira tickets, and Confluence docs to surface engineering activity metrics. They run independently of code indexing and are optional.

Insights provides deep visibility into your engineering organization by analyzing three data sources.

  • Git insights analyze commit history to identify code health risks, knowledge concentration, development patterns, and team velocity.

  • Ticket tracker insights analyze Jira tickets to understand strategic direction, feature intent, code stability risks, and architectural design issues.

  • Docs insights analyze Confluence documentation to correlate design decisions with implementation.

Together, these insights help engineering leaders identify risks like bus factor vulnerabilities, quality concerns, delivery bottlenecks, and strategic alignment gaps.

Key insights metrics

Health score

The health score is an overall repository health metric ranging from 0 to 100, based on five weighted factors. A score of 90-100 indicates strong health across all dimensions with minimal risks. Scores between 70-89 suggest some concerns requiring attention, such as low test investment or moderate bus factor. Scores of 50-69 represent significant risks requiring immediate action, like a bus factor of 1 or zero test coverage. Below 50 indicates critical vulnerabilities threatening project continuity.

The five factors that contribute to the health score are:

  • Bus factor (30% weight): This measures knowledge concentration risk. A bus factor of 1 means a single contributor owns more than 50% of commits or code, creating a single-point-of-failure risk. A bus factor of 2-3 indicates moderate concentration that is manageable but fragile, while a bus factor of 4 or higher shows healthy distribution with well-distributed knowledge. When you encounter a bus factor of 1, implement pair programming, knowledge transfer sessions, and distribute code reviews to mitigate the risk.

  • Velocity trend (20% weight): This tracks development momentum based on commit frequency over time. An increasing trend indicates healthy engagement and momentum. While velocity should be monitored, small sample sizes can skew results, so track trends over time rather than relying on single data points.

  • Bugfix ratio (20% weight): This represents the percentage of commits that are bug fixes. Lower ratios between 0-15% indicate higher quality, while higher ratios may signal quality concerns. This metric helps you understand whether your team is spending too much time fixing bugs versus building new features.

  • Author diversity (15% weight): This measures the number of unique contributors to the repository. Higher diversity reduces knowledge concentration risk and indicates a healthier, more resilient team. Low diversity combined with a low bus factor is a warning sign that knowledge is too concentrated.

  • Test investment (15% weight): This tracks the percentage of commits dedicated to testing. Industry best practice is 15-20%. Zero test investment, as seen in some sample data, indicates unquantified risk and reliance on manual verification. Prioritize test coverage, especially for high-churn files, to improve this metric.

Hotspots

Hotspots identify files with high churn rates that may indicate instability or areas needing refactoring. Each hotspot shows the change count, unique authors, churn score, line ownership percentages, and rename history count. Hotspots are categorized by severity: critical (top 5%), high (top 15%), medium (top 40%), and low (bottom 60%). Critical hotspots are files in the highest churn percentile and should be prioritized for refactoring or test coverage. High hotspots have elevated churn and should be monitored closely. Medium hotspots represent moderate churn, which is normal for active development areas. Low hotspots are stable files with low risk.

Themes

Themes are thematic groupings of related work across directories. Each theme includes the commit count, impact level, tech stack identification, representative commits, dark work analysis, and intent breakdown. Themes help you understand what types of work are happening in your repository and how they relate to each other. For example, a theme like "Notification Delivery Hardening" might represent a coordinated effort to enhance reliability and observability. The dark work component of themes identifies commits not linked to Jira tickets, which may represent untracked feature work, legitimate infrastructure changes, or work requiring investigation.

Dark work analysis

Dark work identifies commits not linked to Jira tickets. A high dark work percentage above 30% indicates significant work not tracked in tickets, which may suggest process gaps. A medium percentage of 10-30% shows some untracked work that should be reviewed to determine if it represents legitimate infrastructure changes. A low dark work percentage below 10% indicates good tracking discipline where most work is ticket-linked. Understanding dark work helps you improve ticket tracking discipline and ensure all important work is properly tracked and planned.

Contributor analysis

Contributor analysis provides per-author breakdowns including commit count and percentage, archetype classification (builder, maintainer, etc.), top files worked on, intent mix (feature vs. docs vs. refactor), and active period. This helps you understand who is doing what in your repository and identify knowledge concentration risks. For example, if one contributor has 75% of commits and is classified as the primary builder, this represents a significant bus factor risk that should be addressed through knowledge transfer and ownership distribution.

Feature intent reports

When you enable ticket tracker insights, you receive feature intent reports that provide strategic analysis including product direction, investment portfolio by cluster and category, top strategic initiatives with detailed context, cross-initiative dependency mapping, epic health dashboard with completion percentages, and requirements quality scoring. These reports help you understand strategic alignment, identify critical path blockers, and assess the quality of your requirements. Each initiative includes context on WHY it matters, WHAT it involves, WHERE it's being implemented, current STATUS, associated RISKS, DEPENDENCIES, key quotes from stakeholders, customer impact, success metrics, and confidence levels.

Code stability risk reports

Code stability risk reports provide technical risk analysis including a risk matrix by severity (CRITICAL, HIGH, MEDIUM, LOW), recurring bug patterns with confidence scores and root cause attribution, per-repository incident analysis with learnings, silent failure inventory, regression-prone areas, and per-repository risk profiles with 6-dimensional health scoring. These reports help you identify recurring bug patterns like self-hosted deployment fragility, concurrency bottlenecks, LLM provider fallback issues, code quality gaps, and security vulnerabilities. The reports also include failure cascade diagrams showing how failures propagate through the system, which is valuable for understanding systemic risks.

Architecture & design risk audits

Architecture and design risk audits provide structural analysis including repository risk maps with bug counts, bug density by cluster, per-repository risk profiles with health scores, dimensions, dependencies, known issues, architectural patterns, and bottlenecks. The audits also include failure cascade diagrams, design debt inventory with effort sizing, and customer impact mapping. These audits help you understand which repositories have the highest risk, identify design debt that needs to be addressed, and understand how architectural decisions impact system reliability.

During installation

The installer prompts for each insights feature. You can pre-seed configuration via ~/.bitoarch/install.yaml to skip prompts by uncommenting the insights: section and filling in values.

After installation

Managing Jira project scope

Credential rotation

Atlassian API tokens

Generate API tokens at id.atlassian.com/manage-profile/security/api-tokens. Provide the Confluence base URL without /wiki — the platform normalizes it automatically.

Best practices

Enable all three insight sources (Git, Jira, Confluence) for comprehensive visibility.

Review health scores weekly to catch emerging risks early. Address bus factor risks through knowledge transfer before they become critical. Use dark work analysis to improve ticket tracking discipline.

Correlate Git insights with Jira insights to understand implementation versus planning alignment.

Track trends over time—velocity trends, bug ratios, and health scores are more valuable as time-series data than as single snapshots. Use insights for planning—feature intent reports and dependency mapping inform roadmap decisions. Prioritize based on severity, focusing on CRITICAL and HIGH severity findings first.

Upgrading AI Architect

Upgrade your AI Architect installation to the latest version while preserving your data and configuration. The upgrade process:

  • Automatically detects your current version

  • Downloads and extracts the new version

  • Migrates your configuration and data

  • Seamlessly transitions to the new version

  • Preserves all indexed repositories and settings

Upgrade instructions

Option 1: Upgrade from within your installation (Recommended)

If you're running version 1.1.0 or higher, navigate to your current installation directory and run:

Option 2: Upgrade from external location

If you need to run the upgrade from outside your installation directory (useful for version 1.0.0), use the --old-path parameter:

Upgrade parameters

The upgrade script supports the following parameters:

Your data is safe: All repositories, indexes, API keys, and settings are automatically preserved during upgrade.

Important: You can only upgrade within the same deployment type. To switch from Docker Compose to Kubernetes or vice versa, you must use the bitoarch reset command, which will result in data loss.

Uninstall

Docker images are kept — docker image prune to reclaim.

Alternatively, you can also use the following curl command to uninstall AI Architect:

Troubleshooting guide

Collect diagnostics for support

If you're experiencing issues and need help from the Bito support team, use the built-in diagnostic tool to capture a full snapshot of your deployment in one step.

Live health sweep — runs a pass/warn/fail check across all services and prints results to your terminal:

The --section flag accepts the following values:

Value
What it checks

prereqs

System prerequisites (Docker/Kubernetes, required tools)

install

Installation state and file integrity

filesystem

Disk space, volume mounts, log directories

config

Configuration files and environment variables

services

Container/pod status, health, and resource usage

connectivity

Service-to-service and network reachability

cert

TLS/SSL certificate validity

Support bundle — collects logs, service status, configuration (with secrets redacted), database health, and indexing state into a single shareable archive:

The command auto-detects whether you're running Docker Compose or Kubernetes. On completion it prints:

The resulting .tar.gz file is saved to ~/.bitoarch/diagnostics/ by default.

To save the bundle to a different location, use the --output parameter:

Example:

Manual troubleshooting commands

Commands specific to Kubernetes-based deployment

Available commands

For complete reference of AI Architect CLI commands, refer to Available commands.

PreviousInstall AI Architect (Bito-hosted)
NextStandalone mode (for individuals)

Last updated