> This is part 1 of 2 of the full documentation (pages 1–100 of 169).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.bito.ai/llms-full.txt/1
> Page index: https://docs.bito.ai/llms.txt

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bito.ai/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Welcome to Bito

[**Bito's Governor**](https://bito.ai/) cuts your coding agent bill in half while task quality holds.

Governor is a context-driven model router that sits between your AI coding tools (Claude Code, Cursor, Codex, etc.) and your LLM providers (Anthropic, OpenAI, Groq, etc.). It reduces the tokens each task consumes and the price you pay for every token.

Your developers keep their tools and their workflow. You point those tools at Governor with one base URL and one key, and every request after that costs less.

<p align="center"><a href="https://share.hsforms.com/19saOrqo5Sg2hewwKegHf3Qnibfq" class="button primary">Get access</a><a href="/governor/overview" class="button secondary">Learn more</a></p>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F2xWIrxUZ6YPcvoTj7OWO%2FBito%20Governor%20Context%20Engine%20Diagram.png?alt=media&amp;token=1fc5d1bb-0583-4ddd-9776-897b38a9958f" alt=""><figcaption></figcaption></figure>

## How Governor cuts agent spend

Agent spend equals the number of tokens multiplied by the price of each token. Governor reduces both numbers in one layer, so the savings multiply rather than add.

* **Fewer tokens, through the code context engine.** A coding agent spends most of its tokens searching your codebase for where a change belongs, and every file it reads gets billed again on each later step of the session. [Bito's context engine](https://bito.ai/product/context-engineering/) serves system context from a live [knowledge graph](/ai-architect/knowledge-graph) of your code, business context, and tribal knowledge, so your tools start each task already knowing your architecture and skip the discovery work.
* **Lower price per token, through the model router.** Governor scores how complex each request is and sends it to the best model for that work, reserving frontier models for the requests that need them. You define the routing tiers in your own words, set the routing direction and a price ceiling, and review every decision in shadow mode before it touches live traffic.

## Getting started

Get your team running on Bito Governor. Connect your LLM providers, set up routing and gateway keys, enable AI Architect, and point your coding tools at it.

{% stepper %}
{% step %}

### Choose where Governor runs

Governor runs either on Bito's infrastructure or inside your own network.

<table><thead><tr><th width="260" align="center">Deployment</th><th width="269.199951171875" align="center">Best for</th><th align="center">Guide</th></tr></thead><tbody><tr><td align="center"><strong>Bito-hosted</strong></td><td align="center">The fastest start, with no infrastructure to maintain. Most teams start here.</td><td align="center"><a href="/governor/set-up-bito-governor-bito-hosted">View setup guide</a></td></tr><tr><td align="center"><strong>Self-hosted with Docker</strong></td><td align="center">Data residency, egress, or regulatory requirements, on a single host.</td><td align="center"><a href="/governor/set-up-bito-governor-self-hosted-with-docker">View setup guide</a></td></tr><tr><td align="center"><strong>Self-hosted with Kubernetes</strong></td><td align="center">The same requirements, deployed into your own cluster with the Bito Governor Helm chart.</td><td align="center"><a href="/governor/set-up-bito-governor-self-hosted-with-kubernetes">View setup guide</a></td></tr></tbody></table>
{% endstep %}

{% step %}

### Add LLM providers, set up routing, and gateway keys

Add a provider account for each LLM provider you use, then add routes that map the model names your tools request to a provider account and model. Create one gateway key per team or tool, so you can revoke one without affecting the others.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FGSx6quYU9gV90XZBp6fP%2Fscrnli_G7fC8blK4aT5U8.png?alt=media&amp;token=3c829db5-8e73-4b48-892d-ba91ad1dc8cb" alt=""><figcaption><p>Add LLM provider account</p></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FJdeFHrcmdS7jnO16jxl7%2Fscrnli_NPZESPHr0AuN4i.png?alt=media&amp;token=e19d3a4e-ed44-4a2b-9a94-0d4149694492" alt=""><figcaption><p>Add routes</p></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FreXPRTrJCiRb6guoT8Ts%2Fscrnli_UVP583r47aXK1N.png?alt=media&amp;token=aa1c1157-8dbf-4e15-b2b7-092472af7ad0" alt=""><figcaption><p>Add gateway key</p></figcaption></figure>
{% endstep %}

{% step %}

### Turn on AI Architect and auto-routing

Enable the **AI Architect** feature to serve system context inside every request, and set an **Architect model** to a cost-efficient model, since that sub-agent captures most of the cost savings.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Ft30UjnBIXJ9w8SDpJklK%2Fscrnli_m64QrcokHAij6J.png?alt=media&amp;token=5f137249-10c6-43f0-b666-e3ce0ef7df3e" alt=""><figcaption></figcaption></figure>

Then hand an alias to the auto-router. A new router starts in shadow mode, so you can review what it would have done across a day of real traffic before you switch it on.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FJyzPc4teFKA5Xh383bYW%2Fscrnli_Fygtb92tHAOo68.png?alt=media&amp;token=c7f21255-9298-401f-b5dc-7b8ef98938d3" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIC6fWnF7Ulv2SVN9qicl%2Fscrnli_P79vhnWbf0RAz7.png?alt=media&amp;token=830db787-a494-41d1-9992-a4853b886de6" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Point your coding tools at Governor

For Claude Code, set two environment variables and start the tool.

```bash
export ANTHROPIC_BASE_URL="https://gateway.bito.ai"
export ANTHROPIC_AUTH_TOKEN="gw_sk_..."
claude
```

The **Documentation** page in the Governor admin UI gives copy-paste setup for Claude Code, Cursor, Cline, Continue, Aider, Codex CLI, GitHub Copilot CLI, Windsurf, Zed, and any OpenAI-compatible or Anthropic-compatible tool. To roll Governor out to a team, distribute the two variables through your existing developer environment tooling.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F9CUbOXmnd7luE4xmFN3A%2Fscrnli_6D3759RdLAFoJB.png?alt=media&amp;token=2bb3571d-25c3-45f4-a771-526a117b32ad" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## The context engine behind Governor

Governor draws its context from [Bito's code context engine](https://bito.ai/product/context-engineering/), a living knowledge graph of your repositories, modules, and APIs, combined with the tribal knowledge in your issue trackers and docs. Your team gets a shared, always-current understanding of the system, and makes that understanding available wherever engineering decisions are made:

* **In** [**Jira**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira) **and** [**Linear**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-linear), for feasibility analysis, technical design and scoping, and cross-repo impact assessment.
* [**In coding agents via MCP**](/ai-architect/quick-mcp-integration-with-ai-coding-agents), such as Claude Code, Cursor, and Codex, for grounded code generation, accelerated onboarding, and production issue triage.
* [**In pull requests**](/ai-code-reviews-in-git/overview) (GitHub, GitLab, Bitbucket) for codebase-aware AI code reviews.
* [**In Slack**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack) for on-demand architecture questions, incident triage, and team-wide access to codebase knowledge.
* [**In Confluence**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-confluence) for pulling design docs, RFCs, and runbooks into ticket analysis — and creating, updating, and commenting on pages from Jira or Slack.
* [**In chat agents**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents) (Claude.ai, Claude Desktop, ChatGPT) for conversational access to your codebase knowledge, system context, and architectural insights.

To set up AI Architect (code context engine) on its own, see:

* [Install AI Architect (Bito-hosted)](/ai-architect/installation/install-ai-architect-bito-hosted) (Fully managed by Bito — no infrastructure setup required)
* [Install AI Architect (self-hosted)](/ai-architect/installation/install-ai-architect-self-hosted) (Run AI Architect on your own infrastructure for maximum control)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FlpXpyiCNiTJSaRRERvXT%2FIllustration-Desktop-OPTION-1-FINAL-3X-1-1-ezgif.com-video-to-gif-converter%20(2).gif?alt=media&amp;token=45d06e6e-73ee-4f3e-a3b4-1299fc631260" alt=""><figcaption></figcaption></figure>

{% embed url="<https://www.youtube.com/watch?v=WARNvl57EaM>" %}

## AI Code Review Agent

[**Bito's AI Code Review Agent**](/ai-code-reviews-in-git/overview) runs system-aware code reviews on pull requests in GitHub, GitLab, and Bitbucket. You can also run it in your IDE and CLI.

* [Use in Git](/ai-code-reviews-in-git/overview) (GitHub, GitLab, Bitbucket)
* [Use in IDE](/ai-code-reviews-in-ide/overview) (VS Code, Cursor, Windsurf, JetBrains)
* [Use in CLI](/ai-code-reviews-in-cli/overview) (integrates seamlessly with AI coding agents like Cursor, Claude Code, Windsurf, and others.)

## Security

Bito does not store your code or use it to train AI models. Bito is SOC 2 Type II certified, and Governor stores every LLM provider key envelope encrypted. On a self-hosted deployment, the key that encrypts your provider credentials stays on your own host or cluster.

## Helpful resources

<table data-column-title-hidden data-view="cards"><thead><tr><th align="center"></th><th data-hidden></th><th data-hidden data-type="content-ref"></th><th data-hidden data-type="content-ref"></th><th data-hidden data-type="content-ref"></th><th data-hidden data-type="content-ref"></th><th data-hidden data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><mark style="color:$primary;"><strong>Governor</strong></mark></td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/governor/overview">Overview</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FNcJeES7abBWCmY3MBJyV%2FBito%20Governor.png?alt=media&amp;token=69d350e2-853d-474e-b8f2-f046b53e8320">Bito Governor.png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Code context engine</strong></mark></td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/ai-architect/overview">Overview</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FKfjIPU8lpdcKQMiY7EGz%2FUntitled%20design%20(19).png?alt=media&amp;token=62c60fc6-f75d-445a-8711-2d61fe444de0">Untitled design (19).png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>AI Code Review Agent</strong></mark></td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/ai-code-reviews-in-git/overview">Overview</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FUcdZ6vcK9gCjJTUaEDne%2FUntitled%20design%20(4).png?alt=media&amp;token=20b0eeb0-8004-45cd-9802-7fa0549aa4c4">Untitled design (4).png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Account and settings</strong></mark></td><td>Manage workspace and personalize Bito</td><td><a href="/help/account-and-settings/setting-ai-output-language">Setting AI output language</a></td><td><a href="/help/account-and-settings/managing-user-access-levels">Managing user access levels</a></td><td></td><td></td><td></td><td><a href="/help/account-and-settings">Account and settings</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F645WmCAHgOMYO87FSCRM%2FUntitled%20design%20(5).png?alt=media&amp;token=115732a3-d63e-4792-bdca-a9c50e4085f4">Untitled design (5).png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Billing and plans</strong></mark></td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/help/billing-and-plans">Billing and plans</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F4pl4GzipZ3Hn1o61AqGm%2FUntitled%20design%20(6).png?alt=media&amp;token=f81e2f72-ced4-42ce-86bc-0547a1ed138d">Untitled design (6).png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Privacy and security</strong></mark></td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/privacy-and-security">Privacy and security</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FFkH7cI5uaBk4mSFTyaaW%2FUntitled%20design%20(7).png?alt=media&amp;token=b6d74f19-950e-49d2-a79c-c154a668bada">Untitled design (7).png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Get support</strong></mark></td><td>Get support and learn about our security and privacy policy</td><td><a href="/help/support-and-questions/troubleshooting">Troubleshooting</a></td><td><a href="/privacy-and-security">Privacy and security</a></td><td></td><td></td><td></td><td><a href="/help/support-and-questions">Support and questions</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F6dVx3gGICbyTYJ2YWxO6%2FUntitled%20design%20(8).png?alt=media&amp;token=5e5eabea-119e-4007-b2f8-375948110131">Untitled design (8).png</a></td><td></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Changelog</strong></mark></td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/changelog">Changelog</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FFsF73C8pvf82gpl6dgBr%2FUntitled%20design%20(9).png?alt=media&amp;token=487a109b-e66d-4bb0-ad15-7fb45ab702b1">Untitled design (9).png</a></td><td></td></tr></tbody></table>

## Governor

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><mark style="color:$primary;"><strong>Bito-hosted Governor</strong></mark></td><td><a href="/governor/set-up-bito-governor-bito-hosted">Set up Bito Governor (Bito-hosted)</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FNcJeES7abBWCmY3MBJyV%2FBito%20Governor.png?alt=media&amp;token=69d350e2-853d-474e-b8f2-f046b53e8320">Bito Governor.png</a></td></tr><tr><td><mark style="color:$primary;"><strong>Self-hosted Governor with Docker</strong></mark></td><td><a href="/governor/set-up-bito-governor-self-hosted-with-docker">Set up Bito Governor (self-hosted with Docker)</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FeA1basLcX8vKc1rN48pr%2FBito%20Governor%20-%20docker.png?alt=media&amp;token=371cad4a-b5bb-485d-8549-e122f1d29234">Bito Governor - docker.png</a></td></tr><tr><td><mark style="color:$primary;"><strong>Self-hosted Governor with Kubernetes</strong></mark></td><td><a href="/governor/set-up-bito-governor-self-hosted-with-kubernetes">Set up Bito Governor (self-hosted with Kubernetes)</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fg7AFeeGTbQsdlq3NQwzW%2FBito%20Governor%20-%20kubernetes.png?alt=media&amp;token=a4df1d1f-14a8-40ac-b770-9d5ef248e50d">Bito Governor - kubernetes.png</a></td></tr></tbody></table>

## Code context engine

<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><mark style="color:blue;"><strong>Bito-hosted AI Architect</strong></mark></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F1nzhVrMmnlDSgPBjGrKI%2FUntitled%20design%20(20).png?alt=media&amp;token=7e3f84f3-395a-493c-bc8e-49c7d4e23081">Untitled design (20).png</a></td><td><a href="/ai-architect/installation/install-ai-architect-bito-hosted">Install AI Architect (Bito-hosted)</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Self-hosted AI Architect</strong></mark></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FcN5PxgUcfRku9UErlrI4%2FUntitled%20design%20(22).png?alt=media&amp;token=7c1cb981-e78c-4257-a1f5-211d7e418a2a">Untitled design (22).png</a></td><td><a href="/ai-architect/installation/install-ai-architect-self-hosted">Install AI Architect (self-hosted)</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>MCP integration with AI coding agents</strong></mark></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FC8KLSLkuVitYRvWbxjhW%2FUntitled%20design%20(21).png?alt=media&amp;token=d5253874-a176-4982-9c80-7424bea3e7c2">Untitled design (21).png</a></td><td><a href="/ai-architect/quick-mcp-integration-with-ai-coding-agents">Quick MCP integration with AI coding agents</a></td></tr></tbody></table>

## AI Code Review Agent

<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td align="center"><mark style="color:blue;"><strong>AI that understands your code</strong></mark></td><td><a href="https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/">https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FkPkq5LHtYSalDCHDTP46%2FUntitled%20design%20(10).png?alt=media&amp;token=97b4b970-e58b-462d-9377-25c37f87b75c">Untitled design (10).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Chat with AI Code Review Agent</strong></mark></td><td><a href="/ai-code-reviews-in-git/chat-with-ai-code-review-agent">Chat with AI Code Review Agent</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FuG3uzNArjISxQKaIwlD4%2FUntitled%20design%20(11).png?alt=media&amp;token=7717b4da-d5bd-4832-9be9-57cb317719e9">Untitled design (11).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Custom code review rules and guidelines</strong></mark></td><td><a href="/ai-code-reviews-in-git/implementing-custom-code-review-rules">Implementing custom code review rules</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FmHye90slz6w7KNJPrbMz%2FUntitled%20design%20(12).png?alt=media&amp;token=935b3f08-9c6f-4dfc-988b-492b12433484">Untitled design (12).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Code review analytics</strong></mark></td><td><a href="/ai-code-reviews-in-git/code-review-analytics">Code review analytics</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FAr3P1Q8iKedkGw5wc5dT%2FUntitled%20design%20(13).png?alt=media&amp;token=d3e29396-7b28-4209-bcaa-6d317aa865ed">Untitled design (13).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Supported programming languages and tools</strong></mark></td><td><a href="/ai-code-reviews-in-git/supported-programming-languages-and-tools">Supported programming languages and tools</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FEpQb5PwhjYZFMzJJs24Y%2FUntitled%20design%20(14).png?alt=media&amp;token=8df8c9f0-fde4-4b1b-9a5c-fadb13579edc">Untitled design (14).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Available commands</strong></mark></td><td><a href="/ai-code-reviews-in-git/available-commands">Available commands</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F8tpsZXZa5vaSR5DPd9Z4%2FUntitled%20design%20(17).png?alt=media&amp;token=cd3cb363-adb7-4e42-a2b9-7c31c6d89cf3">Untitled design (17).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>Agent settings</strong></mark></td><td></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FOYL9kSoRur4Z04t2bBcG%2FUntitled%20design%20(18).png?alt=media&amp;token=af2dac06-ba9a-4fb2-bfbe-622cc1d81a6e">Untitled design (18).png</a></td></tr><tr><td align="center"><mark style="color:blue;"><strong>FAQs</strong></mark></td><td><a href="/ai-code-reviews-in-git/faqs">FAQs</a></td><td><a href="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F3a9YUrociayAlAcP15ps%2FUntitled%20design%20(16).png?alt=media&amp;token=eae78693-6120-4390-a695-12bb5de793a6">Untitled design (16).png</a></td></tr></tbody></table>

## Video library

{% embed url="<https://www.youtube.com/@bitoai?sub_confirmation=1>" %}

## Need help?

If you have any questions, feel free to email us at [**support@bito.ai**](mailto:support@bito.ai)


# Quickstart

This guide will help you set up and start using Bito's AI-powered tools. Pick the product you want to set up from the list below, and you'll find everything you need to get started.

* [**Governor**](#governor): cut coding agent spend across Claude Code, Cursor, Codex, and other AI coding tools. Governor gives each request code context up front and routes it to the best model for the task.
* [**AI Architect**](#ai-architect): connect AI coding agents, Jira, Linear, Slack, Confluence, and chat agents to a living knowledge graph of your code, business context, and tribal knowledge.
* [**AI Code Reviews in Git**](#ai-code-reviews-in-git): get automated pull request reviews in GitHub, GitLab, and Bitbucket.

## Governor

{% stepper %}
{% step %}

### Prerequisites

To start with Bito-hosted Governor, request access by contacting us at <support@bito.ai>. Bito sets up your account and sends your Admin Token.
{% endstep %}

{% step %}

### Choose a deployment

Governor runs either on Bito's infrastructure or inside your own network.

|            Deployment           | Best for                                                             | Setup guide                                                                    |
| :-----------------------------: | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|         **Bito-hosted**         | The fastest start. Bito manages infrastructure and updates.          | [View setup guide](/governor/set-up-bito-governor-bito-hosted)                 |
|   **Self-hosted with Docker**   | Data residency, egress, or regulatory requirements on a single host. | [View setup guide](/governor/set-up-bito-governor-self-hosted-with-docker)     |
| **Self-hosted with Kubernetes** | Teams that run production services on their own cluster with Helm.   | [View setup guide](/governor/set-up-bito-governor-self-hosted-with-kubernetes) |

Before you start, have these ready:

* An API key for each LLM provider you plan to use, such as Anthropic, OpenAI, or Google.
* The exact model names your coding tools request. Model names are case sensitive.
* An AI Architect MCP URL and access token, if you plan to enable AI Architect. You can find both in your Bito account.
  {% endstep %}

{% step %}

### Add LLM providers, set up routing, and gateway keys

Sign in to the Governor admin UI with your Admin Token, then configure three things:

* **Accounts:** add each LLM provider API key and test the connection.
* **Routes:** map each model name your tools request to a provider account and upstream model. Add more than one target on the same alias for failover and load balancing.
* **Keys:** create one gateway key per team or tool, so you can revoke each one on its own. Keys start with `gw_sk_` and appear only once, so copy each key when you create it.
  {% endstep %}

{% step %}

### Enable AI Architect and auto-routing

In the Governor admin UI, open **Features** tab.

Enable the **AI Architect** feature to serve system context inside every request, and set an **Architect model** to a cost-efficient model, since that sub-agent captures most of the cost savings.

Then open **Routes** and turn on auto-routing for a model alias. The router sorts each request into a Simple, Medium, Complex, or Reasoning tier and sends it to the model you assign to that tier.

New routers start in Shadow mode, which records what the router would have done and estimates savings while live traffic keeps its original route. Leave the router in Shadow for about a day of real traffic, review the results, and then switch the mode to On. Read [Auto AI model routing](/governor/auto-ai-model-routing) for more details.
{% endstep %}

{% step %}

### Point your coding tools at Governor

Set your tool's base URL to Governor and its auth token to your gateway key.&#x20;

For Claude Code, set two environment variables and start the tool.

```shellscript
export ANTHROPIC_BASE_URL="https://gateway.bito.ai"
export ANTHROPIC_AUTH_TOKEN="gw_sk_..."
claude
```

The **Documentation** page in the Governor admin UI gives copy-paste setup for Claude Code, Cursor, Cline, Continue, Aider, Codex CLI, GitHub Copilot CLI, Windsurf, Zed, and any OpenAI-compatible or Anthropic-compatible tool. To roll Governor out to a team, distribute the two variables through your existing developer environment tooling.
{% endstep %}

{% step %}

### Verify your setup

Use **Test** in the admin UI to confirm route selection, send a sample request, and check that it appears in **Reports** with its model, tokens, and cost.

{% hint style="info" %}
For self-hosted deployments, the [Available commands](/governor/available-commands) page covers upgrades, backups, and workspace management.
{% endhint %}
{% endstep %}
{% endstepper %}

## AI Architect

{% stepper %}
{% step %}

### Prerequisites

[Bito's AI Architect](/ai-architect/overview) is currently invitation-only. To request access, contact <support@bito.ai>.
{% endstep %}

{% step %}

### Install AI Architect

Bito offers two deployment options for AI Architect.

* [**Bito-hosted**](/ai-architect/installation/install-ai-architect-bito-hosted) (Fully managed by Bito — no infrastructure setup required)
* [**Self-hosted**](/ai-architect/installation/install-ai-architect-self-hosted) (Run AI Architect on your own infrastructure for maximum control)

#### Bito-hosted

1. [Log in to Bito Cloud](https://alpha.bito.ai/) and connect your Git provider.
2. From the [Home](https://alpha.bito.ai/home) screen, click **Configure** next to **Set up AI Architect**, then select the repositories you want indexed.
3. Bito indexes your repositories, builds the underlying knowledge graph, and notifies you once your indexes are ready.

[**Guide for Bito-hosted AI Architect →**](/ai-architect/installation/install-ai-architect-bito-hosted)

#### Self-hosted

1. Download and install AI Architect with a single command.

   ```shellscript
   curl -fsSL https://aiarchitect.bito.ai/install.sh | bash
   ```
2. Configure AI Architect with your Git and LLM credentials.
3. Configure your repositories
4. Start indexing to build knowledge graph of your codebase
5. Get your MCP server URL and access token

[**Guide for self-hosted AI Architect →**](/ai-architect/installation/install-ai-architect-self-hosted)
{% endstep %}

{% step %}

### Connect Bito's AI Architect with your tools

AI Architect integrates with the tools you already use — from AI coding agents to project management and communication platforms.

#### Integrating with AI coding agents (Claude Code, Cursor, etc.) via MCP

Connect AI Architect to your AI coding agents using the one-command installer, which automatically configures Claude Code, Cursor, Windsurf, GitHub Copilot, and other compatible tools on your system.

[**Quick MCP integration guide →**](/ai-architect/quick-mcp-integration-with-ai-coding-agents)

***

#### Integrating with Jira

AI Architect integrates directly with your Jira workspace to bring codebase intelligence into the planning phase. When an Epic or Story is created, AI Architect automatically analyzes your codebase and past tickets to generate a structured plan — covering feasibility assessment, technical design, and story breakdown — directly inside Jira.

[**Jira integration guide →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira)

***

#### Integrating with Linear

Connect AI Architect with Linear to bring codebase-aware planning into your Linear workspace. AI Architect can analyze your codebase in the context of Linear issues to help teams move faster from planning to implementation.

[**Linear integration guide →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-linear)

***

#### Integrating with Slack

Bring AI Architect's codebase intelligence directly into your Slack workspace. Ask questions, get technical context, and collaborate on planning.

[**Slack integration guide →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack)

***

#### Integrating with Confluence

AI Architect can also connect to your Confluence workspace, treating your documentation as a first-class context source alongside your code and tickets.

When a Jira ticket has linked Confluence pages — RFCs, design docs, runbooks, acceptance criteria — AI Architect reads them automatically and grounds its implementation plan in what's already documented. You can also reference Confluence pages from Slack and ask AI Architect to create, update, or comment on pages from inside Jira or Slack.

This keeps planning, discussion, and documentation in sync — no tab-switching to copy context around.

[**Confluence integration guide →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-confluence)

***

#### Integrating with chat agents

AI Architect works with popular chat-based AI tools so you can query your codebase knowledge graph conversationally.

* [**Guide for Claude.ai (Web) →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-claude.ai-web)
* [**Guide for Claude Desktop →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-claude-desktop)
* [**Guide for ChatGPT (Web & Desktop) →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-chatgpt-web-and-desktop)

***

#### Integrating with Bito's AI Code Review Agent

AI Architect can work alongside Bito's AI Code Review Agent to provide richer, codebase-aware feedback on pull requests — combining live code review with deep knowledge of your system's architecture and history.

[**AI Code Review Agent integration guide →**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-bitos-ai-code-review-agent)
{% endstep %}
{% endstepper %}

## AI Code Reviews in Git

{% stepper %}
{% step %}

### Sign up for Bito

Create your account at [alpha.bito.ai](https://alpha.bito.ai/home/welcome) to get started.
{% endstep %}

{% step %}

### Connect your Git provider

Select your preferred Git platform and follow the guided setup to install the agent:

* [GitHub](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github)
* [GitHub (Self-Managed)](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github-self-managed)
* [GitLab](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab)
* [GitLab (Self-Managed)](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab-self-managed)
* [Bitbucket](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket)
* [Bitbucket (Self-Managed)](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket-self-managed)

Once installed, the agent will be linked to your repositories and ready to assist.
{% endstep %}

{% step %}

### Review pull requests

The AI agent will automatically review **new pull requests** and leave inline comments with suggestions.\
You can also **manually trigger a review** by commenting `/review` on any pull request.

[See full list of available commands](/ai-code-reviews-in-git/available-commands)
{% endstep %}

{% step %}

### Chat with the agent

You can reply to comments posted by the Bito AI agent in a pull request to ask follow-up questions or request clarification. The agent will respond with context-aware answers to help you understand the feedback better.

[Learn more](/ai-code-reviews-in-git/chat-with-ai-code-review-agent)
{% endstep %}

{% step %}

### Configure agent settings

To customize your agent, go to [Repositories](https://alpha.bito.ai/home/ai-agents/code-review-agent) and click the **Settings** button next to the relevant agent. From there, you can choose the review feedback mode, enable or disable automatic reviews, define custom guidelines to align with your team’s standards, and more.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endstep %}
{% endstepper %}


# Privacy and security

Bito doesn't read or store your code. Nor do we use your code for AI model training.

This document explains some of Bito's privacy and security practices.  Our [Trust Center ](https://trust.bito.ai)outlines our various accreditations (SOC 2 Type II) and our various security policies.  You can read our full Privacy Policy at <https://bito.ai/privacy-policy/>. &#x20;

## Bito AI

Security is top of mind at Bito, especially when it comes to your code. A fundamental approach we have taken is we do not store any code, code snippets, indexes or embedding vectors on Bito’s servers unless you expressly allow it.  You decide where you want to store your code, either locally on your machine, in your cloud, or on Bito’s cloud.  Importantly, our AI partners do not store any of this information.

All requests are transmitted over HTTPS and are fully encrypted.

**None** of your code or AI requests are used for AI model training. **None** of your code or AI requests are stored by our AI partners. Our AI model partners are OpenAI, Anthropic, and Google.  Here are their policies where they state that they do not store or train on data related to API access (we access all AI models via APIs):

1. OpenAI: <https://openai.com/enterprise-privacy/>&#x20;
2. Anthropic: <https://www.anthropic.com/uk-government-internal-ai-safety-policy-response/data-input-controls-and-audit>&#x20;
3. Google Cloud: <https://cloud.google.com/blog/products/ai-machine-learning/google-cloud-unveils-ai-and-ml-privacy-commitment> (5th paragraph)

The AI requests including code snippets you send to Bito are sent to Bito servers for processing so that we can respond with an answer.&#x20;

Interactions with Bito AI are auto-moderated and managed for toxicity and harmful inputs and outputs.

Any response generated by the Bito IDE AI Assistant is stored locally on your machine to show the history in Bito UI. You can clear the history anytime you want from the Bito UI.

## SOC 2 Type II Compliance

Bito is SOC 2 Type II compliant. This certification reinforces our commitment to safeguarding user data by adhering to strict security, availability, and confidentiality standards. SOC 2 Type II compliance is an independent, rigorous audit that evaluates how well an organization implements and follows these security practices over time.

Our SOC 2 Type II compliance means:

* **Enhanced Data Security**: We consistently implement robust controls to protect your data from unauthorized access and ensure it remains secure.
* **Operational Excellence**: Our processes are designed to maintain high availability and reliability, ensuring uninterrupted service.
* **Regular Monitoring and Testing**: We conduct continuous monitoring and regular internal reviews to uphold the highest security standards.

This certification is an assurance that Bito operates with a high level of trust and transparency, providing you with a secure environment for your code and data.

For any further questions regarding our SOC 2 Type II compliance or to request a copy of the audit report, please reach out to [**support@bito.ai**](mailto:support@bito.ai)

## Code Flow through Bito’s System

#### AI Code Review Agent

When you use the self-hosted/docker version that you have setup in your VPC, in the docker image Bito checks out the diff and clones the repo for static analysis and also to determine relevant code context for code review.  This context and the diff is passed to Bito's system.  The request is then sent to a third-party LLM (e.g., OpenAI, Google Cloud, etc.). The LLM processes the prompt and return the response to Bito. No code is retained by the LLM. Bito then receives the response, processes it (such as formatting), and returns it to your self-hosted docker instance.  This then posts it to your Git provider.  However, the original query is not retained, nor are the results.  After each code review is completed, the diff and the checked out repo are deleted. &#x20;

If you use the Bito cloud to run the AI Code Review Agent, it runs similarly to the self-hosted version.   Bito ephemerally checks out the diff and clones the repo for static analysis and to determine the relevant code context for code review.  This context and the diff is passed to Bito's system.  The request is then sent by Bito to a third-party LLM (e.g., OpenAI, Google Cloud, etc.). The LLM processes the prompt and return the response to Bito. No code is retained by the LLM.  Bito then receives the response, processes it (such as formatting), and posts it to your Git provider.  However, the original query is not retained, nor are the results.  After each code review is completed, the diff and the checked out repo are deleted. &#x20;

#### AI Chat and Code Completions

When we receive an AI request from a user, it is processed by Bito's system (such as adding relevant context and determining the Large Language Model (LLM) to use). However, the original query is not retained. The request is then sent to a third-party LLM (e.g., OpenAI, Google Cloud, etc.). The LLM processes the prompt and return the response to Bito. Bito then receives the response, processes it (such as formatting), and returns it to the user’s machine.

For enterprises, we have the ability to connect to your own private LLM accounts, including but not limited to OpenAI, Google Cloud, Anthropic, or third-party services such as AWS Bedrock, Azure OpenAI. This way all data goes through your own accounts or Virtual Private Cloud (VPC), ensuring enhanced control and security.

## Data and Business Privacy Policy

In line with Bito's commitment to transparency and adherence to data privacy standards, our comprehensive data and business privacy policy is integrated into our practices. Our complete Terms of Use, including the Privacy Policy, are available at <https://bito.ai/terms-of-use/>, with our principal licensing information detailed at <https://bito.ai/terms-of-service/>.

## Data Retention Policy

Our data retention policy is carefully designed to comply with legal standards and to respect our customers' privacy concerns. The policy is categorized into four levels of data:

1. **Relationship and Usage Meta Data:** This includes all data related to the customer's interaction with Bito, such as address, billing amounts, user account data (name and email), and usage metrics (number of queries made, time of day, length of query, etc.). This category of data is retained indefinitely for ongoing service improvement and customer support.
2. **Bito Business Data:** Includes customer-created templates and settings. This data is terminated 90 days after the end of the business relationship with Bito.
3. **Confidential Customer Business Data:** This includes code, code artifacts, and other organization-owned data such as Jira, Confluence, etc. This data is either stored on-prem/locally on the customer’s machines, or, if in the cloud, is terminated at the end of the business relationship with Bito.
4. **AI Requests:** Data in an AI request to Bito’s AI system. AI requests are neither retained nor viewed by Bito. We ensure the confidentiality of your AI queries; Bito and our LLM partners do not store your code, and none of your data is used for model training. All requests are transmitted via HTTPS and are fully encrypted.

## Sub-processor

Bito uses the following third-party services:  Amazon AWS, Anthropic, Clearbit, Github, Google Analytics, Google Cloud, HelpScout, Hubspot, Microsoft Azure, Mixpanel, OpenAI, SendGrid, SiteGround, and Slack for infrastructure, support, and functional capabilities.&#x20;

## Personal Data

Bito follows industry standard practices for protecting your e-mail and other personal details. Our password-less login process - which requires one-time passcode sent to your e-mail for every login - ensures the complete security of your account.&#x20;

## Slack Integration

The Bito Slack app has its own dedicated data handling page covering retention, deletion, LLM details, and uninstall procedures specific to Slack data.

→ [Slack App – Data Handling](/privacy-and-security/slack-app-data-handling)

***

If you have any questions about our security and privacy, please email [**support@bito.ai**](mailto:support@bito.ai)


# Slack App – Data Handling

This page details exactly how the Bito Slack app handles, stores, and processes your data. All policies stated here apply specifically to data flowing through the Bito Slack integration.

### Data Retention Policy

* **Conversational data** (messages sent to @Bito, slash command inputs, and AI responses) is not stored by Bito. Only logs are retained for **15 days** and are automatically deleted afterward.
* **Workspace metadata** (workspace ID, installer identity, app configuration): retained for the duration of the active installation.
* **Account-level data:** see the [general Privacy and Security page](/privacy-and-security).

Upon uninstallation, all data is permanently deleted except for logs. Logs are retained for **15 days** and then automatically deleted, except where retention is required by law.

### Data Archival / Removal Policy

We do not archive messages sent to @Bito, slash command inputs, or AI responses. Only logs are retained in AWS S3 for **15 days** and then automatically deleted.

### Data Storage Policy

* **Primary storage:** AWS, US-East region (default). EU residency available for Enterprise customers on request.
* **Encryption at rest:** AES-256
* **Encryption in transit:** TLS 1.2 or higher
* **Access controls:** RBAC with mandatory SSO + MFA for employees
* **Audit logs:** retained for 15 days
* **Third-party sharing:** Bito does not sell, rent, or share customer data for marketing.

### How to Request Data Deletion

1. Email [**support@bito.ai**](mailto:support@bito.ai) with subject **"Slack Data Deletion Request"**
2. Include workspace name, workspace ID, and admin verification
3. Bito verifies within **2 business days**
4. Deletion is completed within **2 weeks** of verification
5. Written confirmation is emailed on completion

Deletion covers all conversational data and workspace metadata in production systems. Backup purging follows the next rotation cycle.

### LLM (Large Language Model) Information

#### Which LLMs are used

Bito for Slack uses third-party LLMs selected by task and plan:

* **OpenAI**
* **Anthropic**

#### What data is sent to the LLM

* Your message content to @Bito
* Relevant thread context (only when @Bito is mentioned in a thread)
* System instructions

**Never sent:** Slack user emails/names beyond attribution, messages from channels where @Bito is not invited, private DMs not involving @Bito.

#### Training policy

**Your data is never used to train LLM models.** Bito's contracts with LLM providers explicitly prohibit use of customer prompts/outputs for training. Provider-side retention is limited to abuse-monitoring (typically ≤30 days) per their enterprise policies.

#### Data residency

LLM API calls are routed to **US endpoints** by default. Enterprise customers may request EU-only processing via <support@bito.ai>.

#### AI safeguards

* Visible AI disclaimer on responses
* Rate limiting and abuse detection
* LLM-vendor content moderation
* Feedback / human escalation via <support@bito.ai>

### AI Disclaimer

Bito for Slack is powered by large language models (LLMs). AI-generated responses may be **inaccurate, incomplete, biased, or outdated**. Treat outputs as informational suggestions, not as professional, legal, financial, medical, or compliance advice. Always verify critical information before acting on it.

Report inaccurate responses to [**support@bito.ai**](mailto:support@bito.ai).

### Uninstalling the Bito Slack App

1. In Slack, go to **Settings → Manage Apps → Bito → Remove**
2. Upon uninstallation, all data is permanently deleted except for logs. Logs are retained for **15 days** and then automatically deleted, except where retention is required by law.
3. To confirm or expedite deletion, email <support@bito.ai>

### Related

* [Bito Privacy and Security](/privacy-and-security)
* [Slack Integration Setup Guide](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack)
* [Get Support](/help/support-and-questions/getting-support)


# Overview

Governor cuts your agent bill in half by sending fewer tokens to cost-efficient AI models, while maintaining quality.

Governor is a context-driven model router that sits between your AI coding tools (Claude Code, Cursor, Codex, etc.) and the LLM providers (Anthropic, OpenAI, Groq, etc.). It reduces the tokens each task consumes and the price you pay for every token.

Governor combines [Bito's AI Architect](/ai-architect/overview) with a smart model router:

* **Bito's AI Architect** cuts the token count. It serves system context from a live [knowledge graph](/ai-architect/knowledge-graph) of your entire engineering system (code, business context, and tribal knowledge), so your tools skip the discovery work that consumes most of a task's tokens.
* **The model router** cuts the price per token. It uses the same knowledge graph to see how complex each request is, then sends it to the cost-efficient LLM that can handle it, because most requests do not need a frontier model.

Agent spend is tokens multiplied by price. Governor cuts both numbers, so the savings also multiply rather than add.

Nothing changes about how your team works. Point your coding tools at Governor with one base URL and one key, and everything else stays exactly as it is.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F2xWIrxUZ6YPcvoTj7OWO%2FBito%20Governor%20Context%20Engine%20Diagram.png?alt=media&amp;token=1fc5d1bb-0583-4ddd-9776-897b38a9958f" alt=""><figcaption></figcaption></figure>

## How Governor works

Governor is a drop-in endpoint. Your tools stay unchanged, your provider accounts stay yours, and you can connect Governor directly or through a gateway you already run.

Every request follows the same path:

1. **Authenticate.** Governor verifies the gateway key your tool sent.
2. **Add context.** AI Architect answers system questions inside the request, so the tool starts the task already knowing your architecture.
3. **Pick the model.** The router judges how complex the request is and selects a cost-efficient model that can handle it, within the policy you set.
4. **Call the provider.** Governor forwards the request to your own LLM provider account using your own credential.
5. **Record it.** Governor returns the response and logs the model used, tokens consumed, status, and cost.

## Deployment options

Governor runs either on Bito's infrastructure or inside your own network. Both use the same configuration model, so a workspace you build during an evaluation transfers to a self-hosted deployment without redesign.

1. [**Bito-hosted**](/governor/set-up-bito-governor-bito-hosted) is the faster path. Bito creates your workspace and issues an admin token, you configure providers and routes in the console, and Bito applies updates. Most teams start here to get a measurable result within a day.
2. [**Self-hosted**](/governor/set-up-bito-governor-self-hosted-with-docker) keeps everything inside your network. One command installs Governor and its database as Docker containers on a single host, and your provider credentials are encrypted with a key that never leaves that host. Choose this when data residency, network egress, or regulatory requirements prevent traffic from transiting a third-party service.

|                      | Bito-hosted                                       | Self-hosted                                        |
| -------------------- | ------------------------------------------------- | -------------------------------------------------- |
| Infrastructure       | Managed by Bito                                   | Your own host, running Docker                      |
| Setup                | Nothing to install, configure in the Bito UI      | One command installer                              |
| Provider credentials | Encrypted and stored by Bito                      | Encrypted under a key held on your host            |
| Updates              | Applied by Bito                                   | Applied by you                                     |
| Traffic path         | Your tools to Bito to your LLM provider           | Your tools to your host to your LLM provider       |
| Best for             | Fastest start, with no infrastructure to maintain | Data residency, egress, or regulatory requirements |


# Set up Bito Governor (Bito-hosted)

Get your team running on Bito-hosted Governor. Connect your LLM providers, set up routing and gateway keys, enable AI Architect, and point your coding tools at it.

[Bito Governor](/governor/overview) runs either on Bito's infrastructure or inside your own network. This page covers the Bito-hosted deployment. To run Governor inside your own network, see [Set up Bito Governor (self-hosted)](/governor/set-up-bito-governor-self-hosted-with-docker).

With Bito-hosted Governor, Bito operates the infrastructure and there is nothing for you to install. You configure your workspace in the Bito Governor admin UI at <https://gateway.bito.ai/admin/>, then point your AI coding tools at it.

Setup has four parts:

|      Setup parts     | Description                                                                                                                                                                                      |
| :------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Provider account** | Stores an API key for an LLM provider. Add an account for every provider you use.                                                                                                                |
|       **Route**      | <p>Which provider and model serve each request.<br><br>Maps a model alias your tools request to a provider account and an upstream model, and optionally hands the alias to the auto-router.</p> |
|    **Gateway key**   | Authenticates a coding tool to Governor.                                                                                                                                                         |
|      **Feature**     | A server-side capability that runs inside a request, such as [Bito's AI Architect](/ai-architect/overview). Optional.                                                                            |

## Prerequisites

You need the following:

* **Admin Token.** Contact <support@bito.ai> to set up Governor for the first time. Bito creates your account and sends you an Admin Token.
* **An API key for each LLM provider you use,** such as Anthropic, OpenAI, Groq, or Google. Governor sends requests to your own provider accounts.
* **The model names your coding tools request,** such as `claude-opus-4-8`. Model names are case sensitive.
* **AI Architect MCP URL and access token,** if you enable AI Architect. Both are available in your [Bito account](https://alpha.bito.ai/).

## Sign in

1. Go to <https://gateway.bito.ai/admin/>.
2. Enter your Admin Token.

The workspace opens on the **Dashboard**. The left sidebar contains the following pages: Dashboard, Documentation, Reports, Keys, Members, Accounts, Routes, Features, Limits, Prices, Test, and Audit.

Your Admin Token grants access to your own workspace only.

Most configuration pages contain a form at the top and a table of existing entries below it.

## Step 1: Add a provider account

A provider account stores one API key. Add an account for every provider you use, such as Anthropic, OpenAI, Groq, Fireworks, OpenRouter, Together, or Google. Add more than one account for the same provider when you hold several keys, for example one per team or environment.

1. In the left sidebar, click **Accounts**.
2. In the **Add account** form, complete the following fields:

| Field    | Description                                                                                                                                     |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| provider | The provider you are connecting.                                                                                                                |
| name     | A name for this account, for example `prod` or `my-vllm`. The name appears in routes, reports, and prices.                                      |
| key      | Your provider API key. Governor stores it envelope encrypted.                                                                                   |
| base url | The provider endpoint. The default is filled in for each provider. Override it for a proxy, a regional endpoint, or a self-hosted model server. |

3. Click **Add**.

The account appears in the **Accounts** table with the actions **edit**, **test**, **reveal**, and **remove**.

4. Click **test** on the new account. **test** checks the connection to the provider to verify the key and endpoint.

{% hint style="info" %}
To forward the credential supplied by the caller, leave the **key** field blank. This is passthrough mode.

Azure accounts can authenticate with an Entra ID service principal instead of an API key.
{% endhint %}

{% hint style="info" %}
**reveal** displays a stored provider key. Every use is recorded in the audit log.
{% endhint %}

#### Examples

<details>

<summary><strong>Expand to view examples</strong></summary>

Each example states a goal, then the values to enter in the **Add account** form.

#### Connect a provider

Add your organization's Anthropic key.

| provider  | name             | key                    | base url                  |
| --------- | ---------------- | ---------------------- | ------------------------- |
| anthropic | `prod-anthropic` | your Anthropic API key | leave the prefilled value |

Governor fills in **base url** when you select a provider. Change it only for a proxy, a regional endpoint, or a server you host yourself.

#### Separate production and staging spend

Bill staging traffic to a different key from production.

| provider  | name                | key                 | base url                  |
| --------- | ------------------- | ------------------- | ------------------------- |
| anthropic | `prod-anthropic`    | your production key | leave the prefilled value |
| anthropic | `staging-anthropic` | your staging key    | leave the prefilled value |

Add the provider twice under different names. Routes select an account by name, and reports show which account served each request, so spend separates cleanly.

#### Connect a model you host yourself

Send requests to a model running on your own inference server.

| provider | name      | key                                                | base url                      |
| -------- | --------- | -------------------------------------------------- | ----------------------------- |
| openai   | `my-vllm` | your server's key, or leave empty if it needs none | your inference server address |

Any server that implements the OpenAI API works here.

#### Forward the caller's own key

Apply routing and reporting to traffic without storing provider keys centrally.

| provider | name                 | key         | base url                  |
| -------- | -------------------- | ----------- | ------------------------- |
| openai   | `passthrough-openai` | leave empty | leave the prefilled value |

An account with no key runs in passthrough mode, where Governor forwards the credential the caller supplied.

</details>

## Step 2: Add a route

A route maps a model alias your coding tool requests to a provider account and an upstream model.

1. In the left sidebar, click **Routes**.
2. In the **Add route** form, complete the following fields:

<table data-search="false"><thead><tr><th align="center">Field</th><th>Description</th></tr></thead><tbody><tr><td align="center">alias</td><td>The model name your coding tool requests, for example <code>claude-opus-4-8</code> or <code>claude-*</code>. Enter <code>*</code> to match any model.</td></tr><tr><td align="center">provider</td><td>The provider that serves the request.</td></tr><tr><td align="center">account</td><td>The provider account used.</td></tr><tr><td align="center">model (or *)</td><td>The upstream model sent to the provider. Enter <code>*</code> to forward the model name the tool requested.</td></tr><tr><td align="center">api</td><td>The API dialect. Leave it on <strong>auto</strong> to follow the caller.</td></tr><tr><td align="center">priority</td><td>The failover tier. Lower numbers are used first. Default <code>0</code>.</td></tr><tr><td align="center">weight</td><td>The share of traffic within a tier. Default <code>1</code>.</td></tr><tr><td align="center">retries</td><td>Retry attempts for this target. Leave blank to use the gateway default.</td></tr><tr><td align="center">auto-route this alias</td><td>Adds the route, then opens auto-routing so you can say which models answer which kind of request. It starts as a dry run: every request is classified and recorded, and this route keeps answering until you turn routing on.<br><br>See <a href="/governor/auto-ai-model-routing">Auto AI model routing</a> for more details.</td></tr><tr><td align="center">backing group (internal)</td><td>Hides this route from your apps. They cannot ask for it by name and it does not appear in the model list, so only auto-routing can send traffic here. Use it for the models a router picks between, so nobody skips the router by asking for one directly.</td></tr></tbody></table>

3. Click **Add route**.

Routes are grouped by alias in the table below the form. Each group lists its targets with provider, model, account, priority, weight, retries, an enable toggle, and a health state. Priority, weight, and retries are editable inline.

Each group also carries a **Direct** and an **Auto** control. **Direct** sends every request for that alias to the targets you configured. **Auto** hands the alias to the auto-router, which picks a model for each request.

A target marked **cooling** is in a cooldown period after repeated failures. Governor sends its traffic to the next available target until it recovers.

#### Wildcard and exact aliases

An alias can be an exact model name such as `claude-opus-4-8`, or a wildcard such as `claude-sonnet-*` or `*`.

A route with `*` as both the alias and the upstream model passes every request through to the selected account unchanged.

Exact aliases take precedence over wildcards. A route for `claude-opus-4-8` is used instead of a `claude-*` route, and a `claude-*` route is used instead of `*`. This lets you run one catch-all route so that every model reaches a provider, then override selectively for the models you care about.

#### Failover and load balancing

Add the same alias again with a different provider account.

* Governor uses the lowest priority tier first.
* Within a tier, traffic is distributed by weight.
* Targets with the same priority receive requests in turn.
* If a provider returns errors, Governor sends the request to the next available target.

#### Auto-routing

An alias can answer from the targets you configured, or you can hand it to the auto-router, which classifies each request and picks a model for it. Select **auto-route this alias** when you add the route, or click **Auto** on the group in the routes table.

See [Auto AI model routing](/governor/auto-ai-model-routing) for more details.

#### Examples

<details>

<summary><strong>Expand to view examples</strong></summary>

Each example states a goal, then the values to enter in the **Add route** form.

#### Route every model to one provider

Send all traffic to a single account, without naming each model.

| alias | provider  | account          | model | priority |
| ----- | --------- | ---------------- | ----- | -------- |
| `*`   | anthropic | `prod-anthropic` | `*`   | 0        |

Type the asterisk in both fields. `*` in the alias matches any model, and `*` in the model field forwards the model name your tool sent. Add this route first, so that every request reaches a provider while you configure the rest.

#### Route a model family to one account

Send every version of Sonnet to an Azure account.

| alias             | provider | account      | model | priority |
| ----------------- | -------- | ------------ | ----- | -------- |
| `claude-sonnet-*` | azure    | `azure-prod` | `*`   | 0        |

The wildcard matches `claude-sonnet-5`, `claude-sonnet-4-5`, and later versions, so new releases need no new route. This alias is more specific than `*`, so it overrides the catch-all.

#### Fail over to a second provider

Serve Opus 5 from Anthropic, and switch to Azure while Anthropic is unavailable.

| alias           | provider  | account          | model           | priority |
| --------------- | --------- | ---------------- | --------------- | -------- |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-opus-5` | 0        |
| `claude-opus-5` | azure     | `azure-prod`     | `claude-opus-5` | 1        |

Add the alias once per account. Priority `0` takes all traffic. When those requests fail, Governor moves them to priority `1` until the primary account recovers.

#### Split traffic across two accounts

Spread Opus 5 traffic so that neither account reaches its rate limit.

| alias           | provider  | account          | model           | priority | weight |
| --------------- | --------- | ---------------- | --------------- | -------- | ------ |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-opus-5` | 0        | 3      |
| `claude-opus-5` | azure     | `azure-prod`     | `claude-opus-5` | 0        | 1      |

Equal priorities put both targets in the same tier, and the weights send three requests to Anthropic for every one to Azure. Set both weights to `1` for an even split.

#### Serve a request with a different model

Serve Opus 5 requests with a lower-cost model, with no change on any developer machine.

| alias           | provider  | account          | model             | priority |
| --------------- | --------- | ---------------- | ----------------- | -------- |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-sonnet-5` | 0        |

The alias is the model your tool requests. The model is what serves the request. Your tools continue to request Opus 5, and Governor serves those requests with Sonnet 5. Edit the route to reverse it.

</details>

{% hint style="info" %}
Before applying a model substitution across your workspace, run it against a representative set of your own tasks and compare results as well as cost.
{% endhint %}

## Step 3: Create a gateway key

A gateway key authenticates a coding tool to Governor. Provider keys stay in the Bito UI.

1. In the left sidebar, click **Keys**.
2. In the **Create key** form, enter a **name** that identifies the team or tool that will use the key.
3. Click **Create**.
4. Copy the key.

The key starts with `gw_sk_` and is displayed once. Governor stores keys hashed and cannot display them again.

The **Keys** table lists each key by ID, prefix, name, enabled status, and a **revoke** action.

{% hint style="info" %}
Create one key per team or tool so that you can revoke one without affecting the others.
{% endhint %}

## Step 4: Enable features

Features are server-side capabilities that Governor runs inside a request. Two features are available, and both are optional.

The **Features** table lists each enabled feature with its alias, state, whether a token is stored, and its MCP URL, with **edit**, **test connection**, and **disable** actions. Enabled features also appear as badges against each alias on the **Routes** page.

#### AI Architect

AI Architect serves system context from a live knowledge graph of your engineering system, covering code, business context, and tribal knowledge. Governor applies it inside each request, so your coding tools receive that context as they work.

1. In the left sidebar, click **Features**.
2. In the **Configure feature** form, select `ai_architect` from the **feature** list.
3. Complete the following fields:

<table data-search="false"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>alias</td><td>Leave blank to enable the feature across the workspace, or enter a route alias such as <code>claude-*</code> to scope it to that alias.</td></tr><tr><td>MCP URL</td><td>Your AI Architect MCP endpoint. If left empty, Governor falls back to a built-in stub.</td></tr><tr><td>Steering text</td><td>Overrides the default instructions Governor sends with AI Architect. Leave blank to use the default.</td></tr><tr><td>Tool allowlist</td><td>Restricts which AI Architect tools the model may call, one tool name per line. Leave empty to allow all.</td></tr><tr><td>Max hops</td><td>The hop budget for a single AI Architect lookup. Default <code>16</code>. See <a href="#max-hops">Max hops</a> below for more details.</td></tr><tr><td>Max hops per request</td><td>The combined hop budget across every AI Architect lookup in one request. Leave blank to use the gateway default.</td></tr><tr><td>Prompt-cache injection</td><td>Caches what Governor sends with AI Architect on Anthropic, so repeat hops bill at the cache-read rate. Leave on <strong>Use default</strong> to follow the gateway-wide setting.</td></tr><tr><td>Architect model (sub-agent)</td><td>Runs the AI Architect lookups on a cost-efficient sub-agent while the route model writes the answer, for example GPT-5.6 Luna or Gemini Flash Lite 3.5. Leave blank to run them on the request's own route model.<br><br>You must configure a sub-agent to capture most of the cost savings.</td></tr><tr><td>Run Architect in-loop (legacy)</td><td>Runs the AI Architect tools inline on the route model instead of the default sub-agent mode. Ignored when an Architect model is set.</td></tr><tr><td>Delegation pressure</td><td><p>How hard the assistant is pushed to consult AI Architect.</p><ul><li><strong>Balanced</strong> consults it when the assistant judges research worthwhile, which suits coding tools whose own file search competes for the same job.</li><li><strong>Aggressive</strong> tells the assistant to consult AI Architect first, before searching files itself, which suits chat-style products.</li></ul><p>Left unset it follows the <strong>Architect model</strong> setting above — Balanced with none pinned, Aggressive with one, because a pinned model makes research cheap enough to lean on; the unset option names whichever applies right now. Choosing a value explicitly overrides that link and holds even if the Architect model changes later.</p></td></tr><tr><td>Evidence format</td><td><p>What a finished research call hands back.</p><ul><li><strong>Prose</strong> returns a written answer with citations.</li><li><strong>Structured</strong> returns the same research as separate findings, each carrying a verbatim code excerpt with its file and line.</li></ul><p>Prose is recommended, and matched or beat Structured on accuracy in five test setups out of six while costing less in five out of six, because excerpts add to the size of every request. Choose Structured when you parse the findings yourself.</p><p></p><p>Default: Prose</p></td></tr><tr><td>Quality mode</td><td><p>Sets how deeply AI Architect researches a question.<br><br>Choose one of the following:</p><ul><li><strong>Use default:</strong> follows the gateway-wide setting.</li><li><strong>Normal:</strong> uses the standard prompts and hop budget. This is the default.</li><li><strong>High quality:</strong> researches deeper and more thoroughly, at roughly twice the AI Architect cost.</li></ul></td></tr><tr><td>Codebase context</td><td><p>Codebase context tells the assistant about your own codebase before it starts work.</p><p></p><p>This is the highest-impact setting on this form, and it is off by default.</p><p></p><ul><li><strong>Conventions</strong> sends a short summary of the repository the person is working in, covering how you handle errors and logging, how you name things, how you test, and your security and module boundaries. The summary is the same for every request, so it is inexpensive to send repeatedly, and in testing it roughly halved the cost of a coding session.</li><li><strong>Conventions + task research</strong> also reads the request, works out what kind of work it is, and looks that up before answering, covering where the change belongs, what it would break, which pattern to follow, and what is already underway.</li></ul><p></p><p>Default: Off</p></td></tr><tr><td>Include risk areas and in-flight work</td><td><p>Also tells the assistant about known risk areas, technical debt, and work currently underway in the part of the codebase the caller is working in. Carries no contributor names.</p><p></p><p>Available only when <strong>Codebase context</strong> is on.</p></td></tr><tr><td>MCP token</td><td>Your AI Architect access token. Leave blank to keep the token already stored.</td></tr></tbody></table>

**Task guidance**

Task guidance adds what only your indexed codebase can supply to three kinds of request. Each setting is off by default and applies only to the request type named.

| Field                    | What it adds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Guide what plans cover   | <p>When someone asks the assistant to plan or scope a change, it also covers what else the change would affect across your repositories, the patterns your code already follows, the business rules that constrain it, and the parts of the code that are risky to touch.</p><p></p><p>This makes plans more complete rather than more accurate, so it ensures the important ground is covered without making individual details more likely to be right.</p><p></p><p>In testing, plans that addressed those areas rose from about half to roughly four in five, with no slowdown.</p><p></p><p>Applies to planning, design, and implementation requests. Questions and troubleshooting are unaffected.</p> |
| Guide what reviews cover | <p>When someone asks what the codebase requires of a change they are about to make, the assistant also establishes which other repositories and services call the code being changed and would have to move with it, the convention the affected code is meant to follow, and the invariants the change could break.</p><p></p><p>The cross-repository part is the point, because call sites and conventions inside one repository are already searchable while a consumer in another service is not.</p><p></p><p>Applies to review requests only.</p>                                                                                                                                                      |
| Guide what triage covers | <p>When someone brings a bug or an outage, the assistant first checks what its local view cannot show, including whether an incident or alert is already firing for the services involved, what recently deployed in that area, and any issue already recorded against it.</p><p></p><p>Tracing the code is something the assistant can already do from the repository, while knowing that an alert has been firing since this morning is not.</p><p></p><p>Applies to bug reports and troubleshooting only.</p>                                                                                                                                                                                             |

4. Click **Enable**.

Changes apply to the next request. Users take no action.

{% hint style="info" %}
Setting **Architect model (sub-agent)** to a cost-efficient alias moves the AI Architect lookups off your main model while the route model still writes the answer. This reduces the cost of a request that takes several hops.
{% endhint %}

#### Max hops

Some questions require several passes to answer. A question about how your repositories connect requires Governor to retrieve the repository list, then look up the dependencies of each repository. Each pass is a hop.

Two settings cap this work, and both apply at the same time.

| Setting              | Scope                                               |
| -------------------- | --------------------------------------------------- |
| Max hops             | One AI Architect lookup.                            |
| Max hops per request | Every AI Architect lookup in one request, combined. |

A single request can trigger more than one lookup, so **Max hops per request** is what stops a complex request from running up cost through repeated lookups that each stay within their own limit.

Governor stops as soon as it has an answer, so both values are ceilings rather than fixed costs.

| Max hops     | Use                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------- |
| 16           | Default. Suitable for most workspaces.                                                            |
| 30 or higher | Workspaces with several hundred repositories, or teams that ask broad cross-repository questions. |

Raise **Max hops** if answers come back incomplete. Leave **Max hops per request** blank to use the gateway default, and set it when you want a firm ceiling on how much AI Architect work a single request can do. Each hop consumes tokens.

#### Reasoning downgrade

`reasoning_downgrade` lowers the reasoning effort of a request by exactly one level. Reasoning tokens bill at the output rate, so a lower level reduces the cost of the request.

1. In the left sidebar, click **Features**.
2. In the **Configure feature** form, select `reasoning_downgrade` from the **feature** list.
3. Leave **alias** blank to apply the feature across the workspace, or enter a route alias such as `claude-*` to scope it to that alias.
4. Click **Enable**.

Apart from **alias**, the `reasoning_downgrade` feature has no settings.

Governor leaves a request unchanged when it already uses the lowest or second-lowest reasoning level, or when it sends no reasoning at all.

## Step 5: Connect a coding tool

In the left sidebar, click **Documentation**. Your base URL is displayed at the top of the page, and the links below it jump to the four sections on the page.

| Section        | Contents                                                                                     |
| -------------- | -------------------------------------------------------------------------------------------- |
| Get started    | Your base URL, a field for your gateway key, and how to authenticate.                        |
| Use it         | Ready-made curl, Python, and JavaScript requests, and **Try it** for sending a live request. |
| Connect a tool | Copy-paste setup for each supported coding tool.                                             |
| Reference      | Endpoints, your route aliases, and how usage and cost are reported.                          |

To connect a coding tool:

1. In the **Get started** section, paste a gateway key into the key field. Every example on the page fills in with your base URL and key. To generate a key here, click **+ Create test key**.
2. In the **Connect a tool** section, select your tool.

Setup is provided for Claude Code, Claude Desktop, Cursor, Cline (VS Code), Continue (VS Code / JetBrains), Aider, Codex CLI, GitHub Copilot CLI, Windsurf, Zed, and any OpenAI-compatible or Anthropic-compatible tool.

For Claude Code, set two environment variables and start the tool:

```bash
export ANTHROPIC_BASE_URL="https://gateway.bito.ai"
export ANTHROPIC_AUTH_TOKEN="gw_sk_..."
claude
```

To configure a team, distribute these two variables using your existing developer environment tooling. If your traffic already passes through a central gateway, set them there instead.

Governor accepts requests on three endpoints:

| Path                   | Dialect                 | Used by                             |
| ---------------------- | ----------------------- | ----------------------------------- |
| `/v1/messages`         | Anthropic Messages      | Claude Code, Anthropic SDKs         |
| `/v1/chat/completions` | OpenAI Chat Completions | Codex, most OpenAI-compatible tools |
| `/v1/responses`        | OpenAI Responses        | OpenAI Responses API clients        |

Authenticate with `Authorization: Bearer <GATEWAY_KEY>` or `X-Api-Key: <GATEWAY_KEY>`. The same gateway key works for all three dialects.

Every response carries an `x-bito-routed-model` header naming the model that answered. Read that header rather than the `model` field inside the response body, because some providers return the model that was requested and others return the model that answered. The difference matters once auto-routing is on, since the model that answers may not be the one your tool asked for.

{% hint style="info" %}
Claude Code reports that its connectors are disabled when it runs through Governor, because the session authenticates against Governor rather than a Claude account. This message is expected. AI Architect continues to work, because Governor serves it from the server side.
{% endhint %}

#### Connect Claude Desktop

Once you configure Bito Governor as Claude Desktop's third-party inference gateway, every model request the app makes goes through Governor. That covers Chat, Cowork, and Code sessions. Your routes, auto-routing, limits, cost tracking, and AI Architect settings apply to all of them. Claude Desktop uses a settings window instead of environment variables, so the setup differs from Claude Code.

**Before you begin**

* Update Claude Desktop to the latest version. [Download Claude Desktop](https://claude.com/download).
* Create a gateway key for Claude Desktop, as described in Step 3. A separate key per tool lets you track usage and set limits for Claude Desktop on its own.
* Your gateway base URL is `https://gateway.bito.ai`.

{% hint style="info" %}
**What changes in Claude Desktop.** With Governor connected, Claude Desktop runs in third-party inference mode and stops using your claude.ai account for inference. Your existing chats and tasks don't appear in the sidebar, and connectors, skills, and plugins from your Claude account don't appear under **Settings**. The account label in the bottom-left corner changes to **\<your name> with Gateway connected**. This is expected.
{% endhint %}

**1. Turn on Developer Mode**

You only do this once on each machine. If you already see a **Developer** menu, skip to the next step.

1. Open Claude Desktop.
2. Open **Help** > **Troubleshooting** > **Enable Developer Mode**. On macOS, Help is in the menu bar. On Windows, it's in the application menu in the top-left corner.
3. Confirm the prompt. Claude Desktop restarts and a **Developer** menu appears.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIVfHCEL2iqGfQp8hYWN3%2Fscrnli_6NdzSz33G02ncF.png?alt=media&amp;token=8f5f5722-d5ca-4dac-bf5a-ccbbe8537527" alt=""><figcaption></figcaption></figure>

**2. Configure Governor as the gateway**

1. Open **Developer** > **Configure Third-Party Inference**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fpw9YkWTF2ICUjtucpgOh%2Fscrnli_66d2qLF5M06Q7z.png?alt=media&amp;token=032544c4-403c-4ae9-a564-95796685a2f2" alt=""><figcaption></figcaption></figure>

2. In the **Connection** section, enter these values:

| Field               | Value                     |
| ------------------- | ------------------------- |
| Inference provider  | **Gateway**               |
| Credential kind     | **Static API key**        |
| Gateway base URL    | `https://gateway.bito.ai` |
| Gateway API key     | Your `gw_sk_` gateway key |
| Gateway auth scheme | **Bearer** (the default)  |

3. Leave the remaining fields as they are. Governor doesn't need custom headers.
4. Click **Test Connection**. Continue when the result shows green.
5. Click **Save Changes**, then **Apply Changes**, and confirm the relaunch.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FtmXijNv4ZqKjBMGtjf3H%2Fscrnli_Ja7FJ76HB0yR88.png?alt=media&amp;token=f857b0c2-a568-407c-9886-6cc6fbf313e4" alt=""><figcaption></figcaption></figure>

**3. Verify the connection**

1. Check that the bottom-left corner reads **\<your name> with Gateway connected**.
2. Open **Code** and click the model picker. It lists the route aliases you created in Step 2.
3. Send a short prompt and confirm the request appears on the Governor **Dashboard**.
4. If AI Architect is enabled on the selected route, ask `List my indexed repositories`. Claude Desktop returns the repositories from your knowledge graph without running local `grep` or file searches.

{% hint style="info" %}
AI Architect applies per route, as you set it in Step 4. On a route without it, Claude falls back to searching files on the local machine. After you change a route or feature, wait about 30 seconds and start a new session before you test.
{% endhint %}

**Roll out to your team**

The steps above configure one machine. To apply the same configuration across your team, configure and test one machine, click **Export** in the **Configure Third-Party Inference** window, and deploy the resulting `.mobileconfig` (macOS) or `.reg` (Windows) file through your MDM tool. See Anthropic's guide to [deploying Claude Desktop with MDM](https://claude.com/docs/third-party/claude-desktop/mdm).

## Operate the Bito Governor

### Verify the configuration

1. **Check route selection.** In the left sidebar, click **Test**. Enter a model alias and click **Test**. Governor returns the route, provider, account, and lane it would use. No request is sent, so this costs nothing.
2. **Check auto-routing, if you set it up.** In the left sidebar, click **Routes**. On a routed alias, click **Classify a prompt**, enter a sample request, and confirm it lands in the tier you expect. No request is sent, so this costs nothing.
3. **Send a request.** In the left sidebar, click **Documentation**. In the **Use it** section, go to **Try it**. Paste a gateway key, select a model, type a prompt in the message box, and click **Run**. This sends a real, billable request to your provider.
4. **Query your own system.** From your coding tool, ask a question that requires knowledge of your repositories. A response naming your own services confirms AI Architect is active.
5. **Check the report.** In the left sidebar, click **Reports** and confirm the requests appear.

{% hint style="info" %}
For a wildcard alias such as `claude-*`, enter a concrete model that matches it, for example `claude-opus-4-8`.
{% endhint %}

### Set prices

Token prices produce the cost figures on the **Dashboard** and in **Reports**. Prices are expressed in `$/Mtok`, meaning US dollars per million tokens.

Global defaults are maintained by your gateway operator. Set a price here to override the default for your workspace, or to record a negotiated rate for one account. Governor resolves prices in this order: account, then workspace, then global.

1. In the left sidebar, click **Prices**.
2. In the **Set price** form, select the **vendor**.
3. Select an **account** to apply the price to that account only, or leave it on **all accounts** to apply the vendor rate across your workspace.
4. Enter the **model** name.
5. Enter **in**, **out**, and optionally **cache-read** and **cache-write** prices, all in `$/Mtok`.
6. Click **Set**.

The **Prices** table lists each price with its scope, vendor, model, rates, and source.

A model with no price reports token counts and a cost of zero. The **Dashboard** shows the number of unpriced requests per model in the **UNPRICED** column. Auto-routing also depends on these prices. A model with no price cannot be selected by a router, and both the routing direction and the price ceiling are evaluated against them.

### Set limits

Limits are applied per gateway key.

1. In the left sidebar, click **Limits**.
2. In the **Set limits** form, select a **key**.
3. Complete any of the following fields:

| Field            | Description                                   |
| ---------------- | --------------------------------------------- |
| rpm              | Maximum requests per minute.                  |
| tpm              | Maximum tokens per minute.                    |
| budget ($/month) | Monthly spend cap. Requires prices to be set. |
| max\_concurrency | Maximum concurrent requests.                  |

4. Click **Set**.

Leave a field blank to leave it unchanged. Enter `0` to remove a cap, which makes that limit unlimited.

{% hint style="info" %}
Setting a limit to `0` removes the cap rather than blocking the key. To stop a key entirely, disable it on the **Keys** page.
{% endhint %}

### Monitor usage and cost

#### Dashboard

The **Dashboard** shows spend and request volume for the last 30 days, with totals for requests, input tokens, output tokens, and cost. Use **Group by** to break the numbers down by model, alias, key, provider, account, detail, or feature.

The table below the chart lists requests, token counts, cost, and unpriced request count per model.

#### Reports

**Reports** is the raw event log, with one row per request, updated in near real time. Filter the log and export it with **Download CSV**.

Token counts are split into four buckets:

| Bucket   | Description                                                             |
| -------- | ----------------------------------------------------------------------- |
| in       | Fresh prompt tokens, excluding anything served from cache.              |
| cached   | Prompt tokens read from cache, billed at a lower rate.                  |
| cache\_w | Tokens written to the cache. On Anthropic this carries a small premium. |
| out      | All generated tokens, including reasoning tokens.                       |

The full prompt your tool sent is `in + cached + cache_w`. The buckets do not overlap, so nothing is counted twice.

Features make hidden calls inside a request and are reported separately. The base columns show the answer the caller received, and the feature columns show the feature's own usage. A request's total is base plus feature. Expand a row to see the split.

#### Measure the effect of AI Architect

Governor does not currently report savings against a baseline. To measure the effect:

1. Select a set of tasks your team runs regularly.
2. Disable AI Architect, run the tasks, and record cost per task from **Reports**.
3. Enable AI Architect and run the same tasks with the same tool and model.
4. Compare cost per task and confirm the tasks still complete correctly.

### Add members

1. In the left sidebar, click **Members**.
2. In the **Add team member** form, enter a **name** and select a **role**.
3. Click **Create**.

Each member signs in to the Bito UI with the token generated for them.

| Role            | Permissions                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| Member          | Manages their own gateway keys and views their own usage.                                     |
| Workspace admin | Full configuration access to the workspace, including routes, accounts, features, and limits. |

You can disable a member from the **Team** table. To change or disable a workspace admin, contact <support@bito.ai>.

### View the audit log

**Audit** records every configuration change and every secret reveal in your workspace, with the admin who performed it and a timestamp. The log is read only.

Give each person their own member token, so that the log identifies who made each change.

## Troubleshooting

<table data-search="false"><thead><tr><th>Symptom</th><th>Cause</th><th>Resolution</th></tr></thead><tbody><tr><td><code>401</code> from Governor with a gateway key</td><td>The gateway key is invalid or revoked.</td><td>Create a new key on the <strong>Keys</strong> page and update the tool configuration.</td></tr><tr><td><code>404</code> for a model</td><td>No route matches the requested alias.</td><td>Add a route for the exact model name, or add a <code>*</code> route.</td></tr><tr><td>Requests reach an unexpected model</td><td>An exact alias takes precedence over the <code>*</code> route.</td><td>Check the <strong>Routes</strong> page. Exact aliases override wildcards.</td></tr><tr><td>A route shows <strong>cooling</strong></td><td>The target failed repeatedly and is in a cooldown.</td><td>Check the provider account with <strong>test</strong> on the <strong>Accounts</strong> page. Traffic uses the next target until it recovers.</td></tr><tr><td>Cost column shows zero, or UNPRICED is high</td><td>The model has no price set.</td><td>Add prices for that model on the <strong>Prices</strong> page.</td></tr><tr><td>Budget limit has no effect</td><td>The model has no price set, or the limit is <code>0</code>.</td><td>Set prices, then set a positive budget. <code>0</code> means unlimited.</td></tr><tr><td>A key still works after setting limits to <code>0</code></td><td><code>0</code> removes the cap rather than blocking the key.</td><td>Disable the key on the <strong>Keys</strong> page.</td></tr><tr><td>AI Architect responses lack system context</td><td>The feature is disabled, scoped to a different alias, or the MCP URL is empty.</td><td>Open the <strong>Features</strong> page and check the alias, MCP URL, and token. An empty MCP URL falls back to a built-in stub.</td></tr><tr><td>Broad questions return incomplete answers</td><td>Governor reached the max hops budget.</td><td>Increase <strong>Max hops</strong>, and check <strong>Max hops per request</strong> if the request makes several AI Architect lookups.</td></tr><tr><td>Repeated <code>429</code> or <code>5xx</code></td><td>One provider account is rate limited or unavailable.</td><td>Add a second target on the same alias to enable failover.</td></tr><tr><td>Requests reach a model you did not configure for that alias</td><td>Auto-routing is on for the alias.</td><td>Open <strong>Routes</strong> and check the tier assignments, or click <strong>Direct</strong> to stop routing that alias.</td></tr><tr><td>A check that compares the requested model to the returned model fails</td><td>The <code>model</code> field in the response names the model that answered on some providers.</td><td>Read the <code>x-bito-routed-model</code> response header instead, which always names the model that answered.</td></tr><tr><td>Auto-routing is on but nothing is routed</td><td>The router is in shadow, or every tier is unusable.</td><td>Check the mode on <strong>Routes</strong>. A tier marked <strong>will not route</strong> has a model with no price, no deployment on the account, or one blocked by your routing direction.</td></tr><tr><td>Every request is classified simple</td><td>The LLM classifier is timing out, so the built-in scorer is deciding instead.</td><td>Raise the classifier <strong>timeout</strong>, or point <strong>classifier model</strong> at a faster route alias.</td></tr></tbody></table>

## What's next

* [Bito Governor overview](/governor/overview)
* [Set up Bito Governor (self-hosted with Docker)](/governor/set-up-bito-governor-self-hosted-with-docker) to run Governor on a single host with Docker
* [Set up Bito Governor (self-hosted with Kubernetes)](/governor/set-up-bito-governor-self-hosted-with-kubernetes)
* Contact <support@bito.ai> for configuration assistance.


# Set up Bito Governor (self-hosted with Docker)

Run Bito Governor inside your own network. Install it on a single host with Docker, configure your workspace, and point your coding tools at it, with all traffic staying local.

Install Bito Governor on one machine, sign in, connect your AI coding tools, and operate it. This is the **self-hosted, single-node** path (gateway + database on one box, via Docker). No source code or build tools needed — just Docker.

{% hint style="info" %}
**What Bito Governor is:** a gateway that sits between your AI coding tools (Claude Code, Cursor, Codex, …) and the LLM providers. You point your tools at *one* gateway URL + key; the gateway routes to the right provider, and meters usage and cost per workspace.
{% endhint %}

## Prerequisites

You need the following:

* **Docker** — Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux). That's the only prerequisite; the gateway and its database run as containers.
* **A free port** — the gateway serves on **8788** by default (set `PORT` to change it).
* **An API key for each LLM provider you use,** such as Anthropic, OpenAI, Groq, or Google. Governor sends requests to your own provider accounts.
* **The model names your coding tools request,** such as `claude-opus-4-8`. Model names are case sensitive.
* **AI Architect MCP URL and access token,** if you enable AI Architect. Both are available in your [Bito account](https://alpha.bito.ai/).

***

## Step 1: Install

Run the one-liner for your OS. It pulls the Bito Governor image, brings up the stack, generates its secrets, signs you in, and prints everything you need.

**Linux / macOS**

```bash
curl -fsSL https://gwinstall.bito.ai/latest/install-standalone.sh | bash
```

**Windows (PowerShell)**

```powershell
irm https://gwinstall.bito.ai/latest/install-standalone.ps1 | iex
```

Everything installs under a home directory — **`~/.bito-gateway`** (Windows: `%USERPROFILE%\.bito-gateway`). Set **`BITO_GW_HOME`** to install elsewhere.

{% hint style="info" %}
Prefer a native Linux service (systemd) instead of Docker? See `docs/dev/DEPLOY_RUNBOOK.md` in your bito-gateway installation folder.
{% endhint %}

## Step 2: What you get

When it finishes you'll see a **"ready" block** like this — **save what it tells you to**:

```
════════════════════════════════════════════════════════════════
  ✓ bito-gateway is ready
════════════════════════════════════════════════════════════════

  Data-plane URL:  http://<host>:8788          ← your tools connect here
  Admin UI:        http://<host>:8788/admin    ← sign in here

  🔑 KEEP SAFE — lose these and you can be permanently locked out of your data:
     • CRYPTO_ENV_KEK_KEY  the KEK — encrypts every provider key you store
     • admin token         gw_admin_…          ← your Admin UI login
     • DB password         stored in the config
     • the gateway key (gw_sk_…) is minted later in the Admin UI / quickstart
```

* The **admin token** (`gw_admin_…`) is your Admin UI login — copy it now (it's shown once).
* The **KEK** (`CRYPTO_ENV_KEK_KEY`) is the most important secret to back up: it encrypts every provider key you'll add. Losing it means the stored provider keys can't be decrypted. **Copy it to your password manager.**

## Step 3: Sign in to the admin UI

1. Go to **`http://<host>:8788/admin`**, replacing **`<host>`** with the address of the machine running Governor.
2. Enter the admin token you recorded in Step 2.
3. Create a workspace and open it — your tenant (like a team/project).

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Ftqcb42qDbM8ZXET6R71a%2Fscrnli_6m8OC5RBA454Nu.png?alt=media&amp;token=5d264668-f648-4823-9051-32d8a72b2941" alt=""><figcaption></figcaption></figure>

The workspace opens on the **Dashboard**. The left sidebar contains the following pages: Dashboard, Documentation, Reports, Keys, Members, Accounts, Routes, Features, Limits, Prices, Test, and Audit.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FCD72o1zTsd39AtgYDI37%2Fscrnli_zp2ysse2447CN9.png?alt=media&amp;token=4a3ae733-b564-4907-8bcc-6b4edafc7400" alt=""><figcaption></figcaption></figure>

Most configuration pages contain a form at the top and a table of existing entries below it. Complete Steps 4 to 9 in the admin UI.

{% hint style="info" %}
To perform the same configuration from a terminal instead, run `bito-gateway-ctl gwctl quickstart`.
{% endhint %}

## Step 4: Add a provider account

A provider account stores one LLM API key. Add an account for every LLM provider you use, such as Anthropic, OpenAI, Groq, Fireworks, OpenRouter, Together, Google, etc. Add more than one account for the same provider when you hold several keys, for example one per team or environment.

1. In the left sidebar, click **Accounts**.
2. In the **Add account** form, complete the following fields:

| Field    | Description                                                                                                                                     |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| provider | The provider you are connecting.                                                                                                                |
| name     | A name for this account, for example `prod` or `my-vllm`. The name appears in routes, reports, and prices.                                      |
| key      | Your provider API key. Governor stores it envelope encrypted under the key encryption key on your host.                                         |
| base url | The provider endpoint. The default is filled in for each provider. Override it for a proxy, a regional endpoint, or a self-hosted model server. |

3. Click **Add**.

The account appears in the **Accounts** table with the actions **edit**, **test**, **reveal**, and **remove**, and a toggle to enable or disable it.

4. Click **test** on the new account.

**test** checks the connection to the provider to verify the key and endpoint.

{% hint style="info" %}
To forward the credential supplied by the caller, leave the **key** field blank. This is passthrough mode.

Azure accounts can authenticate with an Entra ID service principal instead of an API key.
{% endhint %}

{% hint style="info" %}
**reveal** displays a stored provider key. Every use is recorded in the audit log.
{% endhint %}

#### Examples

<details>

<summary><strong>Expand to view examples</strong></summary>

Each example states a goal, then the values to enter in the **Add account** form.

#### Connect a provider

Add your organization's Anthropic key.

| provider  | name             | key                    | base url                  |
| --------- | ---------------- | ---------------------- | ------------------------- |
| anthropic | `prod-anthropic` | your Anthropic API key | leave the prefilled value |

Governor fills in **base url** when you select a provider. Change it only for a proxy, a regional endpoint, or a server you host yourself.

#### Separate production and staging spend

Bill staging traffic to a different key from production.

| provider  | name                | key                 | base url                  |
| --------- | ------------------- | ------------------- | ------------------------- |
| anthropic | `prod-anthropic`    | your production key | leave the prefilled value |
| anthropic | `staging-anthropic` | your staging key    | leave the prefilled value |

Add the provider twice under different names. Routes select an account by name, and reports show which account served each request, so spend separates cleanly.

#### Connect a model you host yourself

Send requests to a model running on your own inference server.

| provider | name      | key                                                | base url                      |
| -------- | --------- | -------------------------------------------------- | ----------------------------- |
| openai   | `my-vllm` | your server's key, or leave empty if it needs none | your inference server address |

Any server that implements the OpenAI API works here.

#### Forward the caller's own key

Apply routing and reporting to traffic without storing provider keys centrally.

| provider | name                 | key         | base url                  |
| -------- | -------------------- | ----------- | ------------------------- |
| openai   | `passthrough-openai` | leave empty | leave the prefilled value |

An account with no key runs in passthrough mode, where Governor forwards the credential the caller supplied.

</details>

## Step 5: Add a route

A route maps a model alias your coding tool requests to a provider account and an upstream model.

1. In the left sidebar, click **Routes**.
2. In the **Add route** form, complete the following fields:

<table data-search="false"><thead><tr><th align="center">Field</th><th>Description</th></tr></thead><tbody><tr><td align="center">alias</td><td>The model name your coding tool requests, for example <code>claude-opus-4-8</code> or <code>claude-*</code>. Enter <code>*</code> to match any model.</td></tr><tr><td align="center">provider</td><td>The provider that serves the request.</td></tr><tr><td align="center">account</td><td>The provider account used.</td></tr><tr><td align="center">model (or *)</td><td>The upstream model sent to the provider. Enter <code>*</code> to forward the model name the tool requested.</td></tr><tr><td align="center">api</td><td>The API dialect. Leave it on <strong>auto</strong> to follow the caller.</td></tr><tr><td align="center">priority</td><td>The failover tier. Lower numbers are used first. Default <code>0</code>.</td></tr><tr><td align="center">weight</td><td>The share of traffic within a tier. Default <code>1</code>.</td></tr><tr><td align="center">retries</td><td>Retry attempts for this target. Leave blank to use the gateway default.</td></tr><tr><td align="center">auto-route this alias</td><td>Adds the route, then opens auto-routing so you can say which models answer which kind of request. It starts as a dry run: every request is classified and recorded, and this route keeps answering until you turn routing on.<br><br>See <a href="/governor/auto-ai-model-routing">Auto AI model routing</a> for more details.</td></tr><tr><td align="center">backing group (internal)</td><td>Hides this route from your apps. They cannot ask for it by name and it does not appear in the model list, so only auto-routing can send traffic here. Use it for the models a router picks between, so nobody skips the router by asking for one directly.</td></tr></tbody></table>

3. Click **Add route**.

Routes are grouped by alias in the table below the form. Each group lists its targets with provider, model, account, priority, weight, retries, an enable toggle, and a health state. Priority, weight, and retries are editable inline.

Each group also carries a **Direct** and an **Auto** control. **Direct** sends every request for that alias to the targets you configured. **Auto** hands the alias to the auto-router, which picks a model for each request.

A target marked **cooling** is in a cooldown period after repeated failures. Governor sends its traffic to the next available target until it recovers.

#### Wildcard and exact aliases

An alias can be an exact model name such as `claude-opus-4-8`, or a wildcard such as `claude-sonnet-*` or `*`.

A route with `*` as both the alias and the upstream model passes every request through to the selected account unchanged.

Exact aliases take precedence over wildcards. A route for `claude-opus-4-8` is used instead of a `claude-*` route, and a `claude-*` route is used instead of `*`. This lets you run one catch-all route so that every model reaches a provider, then override selectively for the models you care about.

#### Failover and load balancing

Add the same alias again with a different provider account.

* Governor uses the lowest priority tier first.
* Within a tier, traffic is distributed by weight.
* Targets with the same priority receive requests in turn.
* If a provider returns errors, Governor sends the request to the next available target.

#### Auto-routing

An alias can answer from the targets you configured, or you can hand it to the auto-router, which classifies each request and picks a model for it. Select **auto-route this alias** when you add the route, or click **Auto** on the group in the routes table.

See [Auto AI model routing](/governor/auto-ai-model-routing) for more details.

#### Examples

<details>

<summary><strong>Expand to view examples</strong></summary>

Each example states a goal, then the values to enter in the **Add route** form.

#### Route every model to one provider

Send all traffic to a single account, without naming each model.

| alias | provider  | account          | model | priority |
| ----- | --------- | ---------------- | ----- | -------- |
| `*`   | anthropic | `prod-anthropic` | `*`   | 0        |

Type the asterisk in both fields. `*` in the alias matches any model, and `*` in the model field forwards the model name your tool sent. Add this route first, so that every request reaches a provider while you configure the rest.

#### Route a model family to one account

Send every version of Sonnet to an Azure account.

| alias             | provider | account      | model | priority |
| ----------------- | -------- | ------------ | ----- | -------- |
| `claude-sonnet-*` | azure    | `azure-prod` | `*`   | 0        |

The wildcard matches `claude-sonnet-5`, `claude-sonnet-4-5`, and later versions, so new releases need no new route. This alias is more specific than `*`, so it overrides the catch-all.

#### Fail over to a second provider

Serve Opus 5 from Anthropic, and switch to Azure while Anthropic is unavailable.

| alias           | provider  | account          | model           | priority |
| --------------- | --------- | ---------------- | --------------- | -------- |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-opus-5` | 0        |
| `claude-opus-5` | azure     | `azure-prod`     | `claude-opus-5` | 1        |

Add the alias once per account. Priority `0` takes all traffic. When those requests fail, Governor moves them to priority `1` until the primary account recovers.

#### Split traffic across two accounts

Spread Opus 5 traffic so that neither account reaches its rate limit.

| alias           | provider  | account          | model           | priority | weight |
| --------------- | --------- | ---------------- | --------------- | -------- | ------ |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-opus-5` | 0        | 3      |
| `claude-opus-5` | azure     | `azure-prod`     | `claude-opus-5` | 0        | 1      |

Equal priorities put both targets in the same tier, and the weights send three requests to Anthropic for every one to Azure. Set both weights to `1` for an even split.

#### Serve a request with a different model

Serve Opus 5 requests with a lower-cost model, with no change on any developer machine.

| alias           | provider  | account          | model             | priority |
| --------------- | --------- | ---------------- | ----------------- | -------- |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-sonnet-5` | 0        |

The alias is the model your tool requests. The model is what serves the request. Your tools continue to request Opus 5, and Governor serves those requests with Sonnet 5. Edit the route to reverse it.

</details>

{% hint style="info" %}
Before applying a model substitution across your workspace, run it against a representative set of your own tasks and compare results as well as cost.
{% endhint %}

## Step 6: Create a gateway key

A gateway key authenticates a coding tool to Governor. Provider keys stay in the Bito UI.

1. In the left sidebar, click **Keys**.
2. In the **Create key** form, enter a **name** that identifies the team or tool that will use the key.
3. Click **Create**.
4. Copy the key.

The key starts with `gw_sk_` and is displayed once. Governor stores keys hashed and cannot display them again.

The **Keys** table lists each key by ID, prefix, and name, with an enable toggle and a **revoke** action. Create one key per team or tool so that you can revoke one without affecting the others.

## Step 7: Enable features

Features are server-side capabilities that Governor runs inside a request. Two features are available, and both are optional.

The **Features** table lists each enabled feature with its alias, state, whether a token is stored, and its MCP URL, with **edit**, **test connection**, and **disable** actions. Enabled features also appear as badges against each alias on the **Routes** page.

#### AI Architect

AI Architect serves system context from a live knowledge graph of your engineering system, covering code, business context, and tribal knowledge. Governor applies it inside each request, so your coding tools receive that context as they work.

1. In the left sidebar, click **Features**.
2. In the **Configure feature** form, select `ai_architect` from the **feature** list.
3. Complete the following fields:

<table data-search="false"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>alias</td><td>Leave blank to enable the feature across the workspace, or enter a route alias such as <code>claude-*</code> to scope it to that alias.</td></tr><tr><td>MCP URL</td><td>Your AI Architect MCP endpoint. If left empty, Governor falls back to a built-in stub.</td></tr><tr><td>Steering text</td><td>Overrides the default instructions Governor sends with AI Architect. Leave blank to use the default.</td></tr><tr><td>Tool allowlist</td><td>Restricts which AI Architect tools the model may call, one tool name per line. Leave empty to allow all.</td></tr><tr><td>Max hops</td><td>The hop budget for a single AI Architect lookup. Default <code>16</code>. See <a href="#max-hops">Max hops</a> below.</td></tr><tr><td>Max hops per request</td><td>The combined hop budget across every AI Architect lookup in one request. Leave blank to use the gateway default.</td></tr><tr><td>Prompt-cache injection</td><td>Caches what Governor sends with AI Architect on Anthropic, so repeat hops bill at the cache-read rate. Leave on <strong>Use default</strong> to follow the gateway-wide setting.</td></tr><tr><td>Architect model (sub-agent)</td><td>Runs the AI Architect lookups on a cost-efficient sub-agent while the route model writes the answer, for example GPT-5.6 Luna or Gemini Flash Lite 3.5. Leave blank to run them on the request's own route model.<br><br>You must configure a sub-agent to capture most of the cost savings.</td></tr><tr><td>Run Architect in-loop (legacy)</td><td>Runs the AI Architect tools inline on the route model instead of the default sub-agent mode. Ignored when an Architect model is set.</td></tr><tr><td>Delegation pressure</td><td><p>How hard the assistant is pushed to consult AI Architect.</p><ul><li><strong>Balanced</strong> consults it when the assistant judges research worthwhile, which suits coding tools whose own file search competes for the same job.</li><li><strong>Aggressive</strong> tells the assistant to consult AI Architect first, before searching files itself, which suits chat-style products.</li></ul><p>Left unset it follows the <strong>Architect model</strong> setting above — Balanced with none pinned, Aggressive with one, because a pinned model makes research cheap enough to lean on; the unset option names whichever applies right now. Choosing a value explicitly overrides that link and holds even if the Architect model changes later.</p></td></tr><tr><td>Evidence format</td><td><p>What a finished research call hands back.</p><ul><li><strong>Prose</strong> returns a written answer with citations.</li><li><strong>Structured</strong> returns the same research as separate findings, each carrying a verbatim code excerpt with its file and line.</li></ul><p>Prose is recommended, and matched or beat Structured on accuracy in five test setups out of six while costing less in five out of six, because excerpts add to the size of every request. Choose Structured when you parse the findings yourself.</p><p></p><p>Default: Prose</p></td></tr><tr><td>Quality mode</td><td><p>Sets how deeply AI Architect researches a question.<br><br>Choose one of the following:</p><ul><li><strong>Use default:</strong> follows the gateway-wide setting.</li><li><strong>Normal:</strong> uses the standard prompts and hop budget. This is the default.</li><li><strong>High quality:</strong> researches deeper and more thoroughly, at roughly twice the AI Architect cost.</li></ul></td></tr><tr><td>Codebase context</td><td><p>Codebase context tells the assistant about your own codebase before it starts work.</p><p></p><p>This is the highest-impact setting on this form, and it is off by default.</p><p></p><ul><li><strong>Conventions</strong> sends a short summary of the repository the person is working in, covering how you handle errors and logging, how you name things, how you test, and your security and module boundaries. The summary is the same for every request, so it is inexpensive to send repeatedly, and in testing it roughly halved the cost of a coding session.</li><li><strong>Conventions + task research</strong> also reads the request, works out what kind of work it is, and looks that up before answering, covering where the change belongs, what it would break, which pattern to follow, and what is already underway.</li></ul><p></p><p>Default: Off</p></td></tr><tr><td>Include risk areas and in-flight work</td><td><p>Also tells the assistant about known risk areas, technical debt, and work currently underway in the part of the codebase the caller is working in. Carries no contributor names.</p><p></p><p>Available only when <strong>Codebase context</strong> is on.</p></td></tr><tr><td>MCP token</td><td>Your AI Architect access token. Leave blank to keep the token already stored.</td></tr></tbody></table>

**Task guidance**

Task guidance adds what only your indexed codebase can supply to three kinds of request. Each setting is off by default and applies only to the request type named.

| Field                    | What it adds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Guide what plans cover   | <p>When someone asks the assistant to plan or scope a change, it also covers what else the change would affect across your repositories, the patterns your code already follows, the business rules that constrain it, and the parts of the code that are risky to touch.</p><p></p><p>This makes plans more complete rather than more accurate, so it ensures the important ground is covered without making individual details more likely to be right.</p><p></p><p>In testing, plans that addressed those areas rose from about half to roughly four in five, with no slowdown.</p><p></p><p>Applies to planning, design, and implementation requests. Questions and troubleshooting are unaffected.</p> |
| Guide what reviews cover | <p>When someone asks what the codebase requires of a change they are about to make, the assistant also establishes which other repositories and services call the code being changed and would have to move with it, the convention the affected code is meant to follow, and the invariants the change could break.</p><p></p><p>The cross-repository part is the point, because call sites and conventions inside one repository are already searchable while a consumer in another service is not.</p><p></p><p>Applies to review requests only.</p>                                                                                                                                                      |
| Guide what triage covers | <p>When someone brings a bug or an outage, the assistant first checks what its local view cannot show, including whether an incident or alert is already firing for the services involved, what recently deployed in that area, and any issue already recorded against it.</p><p></p><p>Tracing the code is something the assistant can already do from the repository, while knowing that an alert has been firing since this morning is not.</p><p></p><p>Applies to bug reports and troubleshooting only.</p>                                                                                                                                                                                             |

4. Click **Enable**.

Changes apply to the next request. Users take no action.

{% hint style="info" %}
Setting **Architect model (sub-agent)** to a cost-efficient alias moves the AI Architect lookups off your main model while the route model still writes the answer. This reduces the cost of a request that takes several hops.
{% endhint %}

#### Max hops

Some questions require several passes to answer. A question about how your repositories connect requires Governor to retrieve the repository list, then look up the dependencies of each repository. Each pass is a hop.

Two settings cap this work, and both apply at the same time.

| Setting              | Scope                                               |
| -------------------- | --------------------------------------------------- |
| Max hops             | One AI Architect lookup.                            |
| Max hops per request | Every AI Architect lookup in one request, combined. |

A single request can trigger more than one lookup, so **Max hops per request** is what stops a complex request from running up cost through repeated lookups that each stay within their own limit.

Governor stops as soon as it has an answer, so both values are ceilings rather than fixed costs.

| Max hops     | Use                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------- |
| 16           | Default. Suitable for most workspaces.                                                            |
| 30 or higher | Workspaces with several hundred repositories, or teams that ask broad cross-repository questions. |

Raise **Max hops** if answers come back incomplete. Leave **Max hops per request** blank to use the gateway default, and set it when you want a firm ceiling on how much AI Architect work a single request can do. Each hop consumes tokens.

#### Reasoning downgrade

`reasoning_downgrade` lowers the reasoning effort of a request by exactly one level. Reasoning tokens bill at the output rate, so a lower level reduces the cost of the request.

1. In the left sidebar, click **Features**.
2. In the **Configure feature** form, select `reasoning_downgrade` from the **feature** list.
3. Leave **alias** blank to apply the feature across the workspace, or enter a route alias such as `claude-*` to scope it to that alias.
4. Click **Enable**.

Apart from **alias**, the feature has no settings.

Governor leaves a request unchanged when it already uses the lowest or second-lowest reasoning level, or when it sends no reasoning at all.

## Step 8: Connect a coding tool

In the left sidebar, click **Documentation**. Your own base URL is displayed at the top of the page, and the links below it jump to the four sections on the page.

| Section        | Contents                                                                                     |
| -------------- | -------------------------------------------------------------------------------------------- |
| Get started    | Your base URL, a field for your gateway key, and how to authenticate.                        |
| Use it         | Ready-made curl, Python, and JavaScript requests, and **Try it** for sending a live request. |
| Connect a tool | Copy-paste setup for each supported coding tool.                                             |
| Reference      | Endpoints, your route aliases, and how usage and cost are reported.                          |

To connect a coding tool:

1. In the **Get started** section, paste a gateway key into the key field. Every example on the page fills in with your base URL and key. To generate a key here, click **+ Create test key**.
2. In the **Connect a tool** section, select your tool.

Setup is provided for Claude Code, Claude Desktop, Cursor, Cline (VS Code), Continue (VS Code / JetBrains), Aider, Codex CLI, GitHub Copilot CLI, Windsurf, Zed, and any OpenAI-compatible or Anthropic-compatible tool.

To print the same setup from a terminal, run `bito-gateway-ctl gwctl connect` with your tool name. The command outputs configuration values and changes no state.

```bash
bito-gateway-ctl gwctl connect claude
# Supported values: claude | cursor | cline | continue | aider | codex | copilot | windsurf | zed | openai | anthropic
```

The output contains your data-plane URL and the required environment variables, with a `<YOUR_GATEWAY_KEY>` placeholder. Replace it with the key you created in Step 6.

For Claude Code, set two environment variables and start the tool:

```bash
export ANTHROPIC_BASE_URL="https://HOST:8788"
export ANTHROPIC_AUTH_TOKEN="gw_sk_..."
claude
```

Replace `HOST` with the hostname or address of the machine running Governor. To configure a team, distribute these two variables using your existing developer environment tooling. If your traffic already passes through a central gateway, set them there instead.

Governor accepts requests on three endpoints:

| Path                   | Dialect                 | Used by                             |
| ---------------------- | ----------------------- | ----------------------------------- |
| `/v1/messages`         | Anthropic Messages      | Claude Code, Anthropic SDKs         |
| `/v1/chat/completions` | OpenAI Chat Completions | Codex, most OpenAI-compatible tools |
| `/v1/responses`        | OpenAI Responses        | OpenAI Responses API clients        |

Authenticate with `Authorization: Bearer <GATEWAY_KEY>` or `X-Api-Key: <GATEWAY_KEY>`. The same gateway key works for all three dialects.

Every response carries an `x-bito-routed-model` header naming the model that answered. Read that header rather than the `model` field inside the response body, because some providers return the model that was requested and others return the model that answered. The difference matters once auto-routing is on, since the model that answers may not be the one your tool asked for.

{% hint style="info" %}
Claude Code reports that its connectors are disabled when it runs through Governor, because the session authenticates against Governor rather than a Claude account. This message is expected. AI Architect continues to work, because Governor serves it from the server side.
{% endhint %}

#### Connect Claude Desktop

Once you configure Bito Governor as Claude Desktop's third-party inference gateway, every model request the app makes goes through Governor. That covers Chat, Cowork, and Code sessions. Your routes, auto-routing, limits, cost tracking, and AI Architect settings apply to all of them. Claude Desktop uses a settings window instead of environment variables, so the setup differs from Claude Code.

**Before you begin**

* Update Claude Desktop to the latest version. [Download Claude Desktop](https://claude.com/download).
* Create a gateway key for Claude Desktop, as described in Step 6. A separate key per tool lets you track usage and set limits for Claude Desktop on its own.
* Your gateway base URL is `https://HOST:8788`, where `HOST` is the hostname or address of the Governor machine.

{% hint style="warning" %}
**Each user's machine must reach Governor.** Claude Desktop calls the gateway URL directly from the user's computer, so `HOST:8788` has to resolve and respond from there. Governor can sit on the public internet or inside your private network or VPN. Use the HTTPS address.
{% endhint %}

{% hint style="info" %}
**What changes in Claude Desktop.** With Governor connected, Claude Desktop runs in third-party inference mode and stops using your claude.ai account for inference. Your existing chats and tasks don't appear in the sidebar, and connectors, skills, and plugins from your Claude account don't appear under **Settings**. The account label in the bottom-left corner changes to **\<your name> with Gateway connected**. This is expected.
{% endhint %}

**1. Turn on Developer Mode**

You only do this once on each machine. If you already see a **Developer** menu, skip to the next step.

1. Open Claude Desktop.
2. Open **Help** > **Troubleshooting** > **Enable Developer Mode**. On macOS, Help is in the menu bar. On Windows, it's in the application menu in the top-left corner.
3. Confirm the prompt. Claude Desktop restarts and a **Developer** menu appears.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIVfHCEL2iqGfQp8hYWN3%2Fscrnli_6NdzSz33G02ncF.png?alt=media&amp;token=8f5f5722-d5ca-4dac-bf5a-ccbbe8537527" alt=""><figcaption></figcaption></figure>

**2. Configure Governor as the gateway**

1. Open **Developer** > **Configure Third-Party Inference**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fpw9YkWTF2ICUjtucpgOh%2Fscrnli_66d2qLF5M06Q7z.png?alt=media&amp;token=032544c4-403c-4ae9-a564-95796685a2f2" alt=""><figcaption></figcaption></figure>

2. In the **Connection** section, enter these values:

| Field               | Value                     |
| ------------------- | ------------------------- |
| Inference provider  | **Gateway**               |
| Credential kind     | **Static API key**        |
| Gateway base URL    | `https://HOST:8788`       |
| Gateway API key     | Your `gw_sk_` gateway key |
| Gateway auth scheme | **Bearer** (the default)  |

3. Leave the remaining fields as they are. Governor doesn't need custom headers.
4. Click **Test Connection**. Continue when the result shows green. If it fails, open `https://HOST:8788` in a browser on the same machine to confirm Governor is reachable.
5. Click **Save Changes**, then **Apply Changes**, and confirm the relaunch.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fe1x9HFLlecUDEYaSyqsZ%2Fscrnli_jnsi2NLQz2h7IM.png?alt=media&amp;token=d157867c-5f3c-4db4-ad59-dcb7536bd9a1" alt=""><figcaption></figcaption></figure>

**3. Verify the connection**

1. Check that the bottom-left corner reads **\<your name> with Gateway connected**.
2. Open **Code** and click the model picker. It lists the route aliases you created in Step 5.
3. Send a short prompt and confirm the request appears on the Governor **Dashboard**.
4. If AI Architect is enabled on the selected route, ask `List my indexed repositories`. Claude Desktop returns the repositories from your knowledge graph without running local `grep` or file searches.

{% hint style="info" %}
AI Architect applies per route, as you set it in Step 7. On a route without it, Claude falls back to searching files on the local machine. After you change a route or feature, wait about 30 seconds and start a new session before you test.
{% endhint %}

**Roll out to your team**

The steps above configure one machine. To apply the same configuration across your team, configure and test one machine, click **Export** in the **Configure Third-Party Inference** window, and deploy the resulting `.mobileconfig` (macOS) or `.reg` (Windows) file through your MDM tool. See Anthropic's guide to [deploying Claude Desktop with MDM](https://claude.com/docs/third-party/claude-desktop/mdm).

## Operate the Bito Governor

Day-to-day, use the **`bito-gateway-ctl`** command (installed on your PATH — Windows too, via a `.cmd` shim). It works from any directory:

```bash
bito-gateway-ctl status         # is it up?
bito-gateway-ctl health         # /healthz + a deep self-check (gwctl doctor)
bito-gateway-ctl logs           # follow the gateway logs (Ctrl-C to stop)
bito-gateway-ctl restart
bito-gateway-ctl stop           # stop, keep your data
bito-gateway-ctl start          # start again (also applies .env changes)
bito-gateway-ctl update         # pull a newer image and restart
```

**Run `gwctl` from the command line** (it lives inside the gateway container — this wrapper forwards to it):

```bash
bito-gateway-ctl gwctl quickstart              # interactive: workspace + key + account + route (the CLI version of §4)
bito-gateway-ctl gwctl connect claude          # print a tool's setup
bito-gateway-ctl gwctl admin create --role global   # add another admin
bito-gateway-ctl gwctl doctor                  # validate DB/schema/KEK
```

**Uninstall:**

```bash
bito-gateway-ctl uninstall           # remove the containers, KEEP your data (the DB volume + secrets)
bito-gateway-ctl uninstall --purge   # ALSO delete the DB volume + secrets (the KEK) — irreversible
```

{% hint style="info" %}
On the **native/systemd** install, use `sudo systemctl {start|stop|restart|status} bito-gateway` + `journalctl -u bito-gateway -f`, and `gwctl` is already on your PATH directly.
{% endhint %}

### Verify the configuration

1. **Check route selection.** In the left sidebar, click **Test**. Enter a model alias and click **Test**. Governor returns the route, provider, account, and lane it would use. No request is sent, so this costs nothing.
2. **Check auto-routing, if you set it up.** In the left sidebar, click **Routes**. On a routed alias, click **Classify a prompt**, enter a sample request, and confirm it lands in the tier you expect. No request is sent, so this costs nothing.
3. **Send a request.** In the left sidebar, click **Documentation**. In the **Use it** section, go to **Try it**. Paste a gateway key, select a model, type a prompt in the message box, and click **Run**. This sends a real, billable request to your provider.
4. **Query your own system.** From your coding tool, ask a question that requires knowledge of your repositories. A response naming your own services confirms AI Architect is active.
5. **Check the report.** In the left sidebar, click **Reports** and confirm the requests appear.

{% hint style="info" %}
For a wildcard alias such as `claude-*`, enter a concrete model that matches it, for example `claude-opus-4-8`.
{% endhint %}

### Set prices

Token prices produce the cost figures on the **Dashboard** and in **Reports**. Prices are expressed in `$/Mtok`, meaning US dollars per million tokens.

Global defaults are maintained by your gateway operator. Set a price here to override the default for your workspace, or to record a negotiated rate for one account. Governor resolves prices in this order: account, then workspace, then global.

1. In the left sidebar, click **Prices**.
2. In the **Set price** form, select the **vendor**.
3. Select an **account** to apply the price to that account only, or leave it on **all accounts** to apply the vendor rate across your workspace.
4. Enter the **model** name.
5. Enter **in**, **out**, and optionally **cache-read** and **cache-write** prices, all in `$/Mtok`.
6. Click **Set**.

The **Prices** table lists each price with its scope, vendor, model, rates, and source.

A model with no price reports token counts and a cost of zero. The **Dashboard** shows the number of unpriced requests per model in the **UNPRICED** column. Auto-routing also depends on these prices. A model with no price cannot be selected by a router, and both the routing direction and the price ceiling are evaluated against them.

### Set limits

Limits are applied per gateway key.

1. In the left sidebar, click **Limits**.
2. In the **Set limits** form, select a **key**.
3. Complete any of the following fields:

| Field            | Description                                   |
| ---------------- | --------------------------------------------- |
| rpm              | Maximum requests per minute.                  |
| tpm              | Maximum tokens per minute.                    |
| budget ($/month) | Monthly spend cap. Requires prices to be set. |
| max\_concurrency | Maximum concurrent requests.                  |

4. Click **Set**.

Leave a field blank to leave it unchanged. Enter `0` to remove a cap, which makes that limit unlimited.

{% hint style="info" %}
Setting a limit to `0` removes the cap rather than blocking the key. To stop a key entirely, disable it on the **Keys** page.
{% endhint %}

### Monitor usage and cost

#### Dashboard

The **Dashboard** shows spend and request volume for the last 30 days, with totals for requests, input tokens, output tokens, and cost. Use **Group by** to break the numbers down by model, alias, key, provider, account, detail, or feature.

The table below the chart lists requests, token counts, cost, and unpriced request count per model.

#### Reports

**Reports** is the raw event log, with one row per request, updated in near real time. Filter the log and export it with **Download CSV**.

Token counts are split into four buckets:

| Bucket   | Description                                                             |
| -------- | ----------------------------------------------------------------------- |
| in       | Fresh prompt tokens, excluding anything served from cache.              |
| cached   | Prompt tokens read from cache, billed at a lower rate.                  |
| cache\_w | Tokens written to the cache. On Anthropic this carries a small premium. |
| out      | All generated tokens, including reasoning tokens.                       |

The full prompt your tool sent is `in + cached + cache_w`. The buckets do not overlap, so nothing is counted twice.

Features make hidden calls inside a request and are reported separately. The base columns show the answer the caller received, and the feature columns show the feature's own usage. A request's total is base plus feature. Expand a row to see the split.

#### Measure the effect of AI Architect

Governor does not currently report savings against a baseline. To measure the effect:

1. Select a set of tasks your team runs regularly.
2. Disable AI Architect, run the tasks, and record cost per task from **Reports**.
3. Enable AI Architect and run the same tasks with the same tool and model.
4. Compare cost per task and confirm the tasks still complete correctly.

### Add members

1. In the left sidebar, click **Members**.
2. In the **Add team member** form, enter a **name** and select a **role**.
3. Click **Create**.

Each member signs in to the admin UI with the token generated for them.

| Role            | Permissions                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| Member          | Manages their own gateway keys and views their own usage.                                     |
| Workspace admin | Full configuration access to the workspace, including routes, accounts, features, and limits. |

You can disable a member from the **Team** table.

### View the audit log

**Audit** records every configuration change and every secret reveal in your workspace, with the admin who performed it and a timestamp. The log is read only.

Give each person their own member token, so that the log identifies who made each change.

***

### Back up

Two things, together, are your whole Bito Governor:

* **The database** — `mysqldump bito_gateway` on a schedule (it holds every workspace, key, account, route, and your encrypted provider secrets).
* **The KEK** (`CRYPTO_ENV_KEK_KEY`, in `~/.bito-gateway/.env`) — in your secrets manager. **A database dump alone can't be decrypted without it.**

***

## Troubleshooting

<table data-search="false"><thead><tr><th>Symptom</th><th>Cause</th><th>Resolution</th></tr></thead><tbody><tr><td><code>401</code> from Governor with a gateway key</td><td>The gateway key is invalid or revoked.</td><td>Create a new key on the <strong>Keys</strong> page and update the tool configuration.</td></tr><tr><td><code>404</code> for a model</td><td>No route matches the requested alias.</td><td>Add a route for the exact model name, or add a <code>*</code> route.</td></tr><tr><td>Requests reach an unexpected model</td><td>An exact alias takes precedence over the <code>*</code> route.</td><td>Check the <strong>Routes</strong> page. Exact aliases override wildcards.</td></tr><tr><td>A route shows <strong>cooling</strong></td><td>The target failed repeatedly and is in a cooldown.</td><td>Check the provider account with <strong>test</strong> on the <strong>Accounts</strong> page. Traffic uses the next target until it recovers.</td></tr><tr><td>Cost column shows zero, or UNPRICED is high</td><td>The model has no price set.</td><td>Add prices for that model on the <strong>Prices</strong> page.</td></tr><tr><td>Budget limit has no effect</td><td>The model has no price set, or the limit is <code>0</code>.</td><td>Set prices, then set a positive budget. <code>0</code> means unlimited.</td></tr><tr><td>A key still works after setting limits to <code>0</code></td><td><code>0</code> removes the cap rather than blocking the key.</td><td>Disable the key on the <strong>Keys</strong> page.</td></tr><tr><td>AI Architect responses lack system context</td><td>The feature is disabled, scoped to a different alias, or the MCP URL is empty.</td><td>Open the <strong>Features</strong> page and check the alias, MCP URL, and token. An empty MCP URL falls back to a built-in stub.</td></tr><tr><td>Broad questions return incomplete answers</td><td>Governor reached the max hops budget.</td><td>Increase <strong>Max hops</strong>, and check <strong>Max hops per request</strong> if the request makes several AI Architect lookups.</td></tr><tr><td>Repeated <code>429</code> or <code>5xx</code></td><td>One provider account is rate limited or unavailable.</td><td>Add a second target on the same alias to enable failover.</td></tr><tr><td>Requests reach a model you did not configure for that alias</td><td>Auto-routing is on for the alias.</td><td>Open <strong>Routes</strong> and check the tier assignments, or click <strong>Direct</strong> to stop routing that alias.</td></tr><tr><td>A check that compares the requested model to the returned model fails</td><td>The <code>model</code> field in the response names the model that answered on some providers.</td><td>Read the <code>x-bito-routed-model</code> response header instead, which always names the model that answered.</td></tr><tr><td>Auto-routing is on but nothing is routed</td><td>The router is in shadow, or every tier is unusable.</td><td>Check the mode on <strong>Routes</strong>. A tier marked <strong>will not route</strong> has a model with no price, no deployment on the account, or one blocked by your routing direction.</td></tr><tr><td>Every request is classified simple</td><td>The LLM classifier is timing out, so the built-in scorer is deciding instead.</td><td>Raise the classifier <strong>timeout</strong>, or point <strong>classifier model</strong> at a faster route alias.</td></tr></tbody></table>

## What's next

* The Admin UI **Documentation** tab — connection snippets for every tool, filled with your live URL/key, plus the API reference.
* `bito-gateway-ctl gwctl <command> -h` — help for any CLI command.
* [Bito Governor overview](/governor/overview)
* [Set up Bito Governor (Bito-hosted)](/governor/set-up-bito-governor-bito-hosted)
* [Set up Bito Governor (self-hosted with Kubernetes)](/governor/set-up-bito-governor-self-hosted-with-kubernetes)
* Contact <support@bito.ai> for configuration assistance.


# Set up Bito Governor (self-hosted with Kubernetes)

Run Bito Governor in your own Kubernetes cluster. Install it with the Bito Gateway Helm chart, expose it through your ingress controller, and point your coding tools at it.

Governor runs either on Bito's infrastructure or inside your own network. To have Bito run it for you, see [Set up Bito Governor (Bito-hosted)](/governor/set-up-bito-governor-bito-hosted). To run it on a single host with Docker rather than Kubernetes, see [Set up Bito Governor (self-hosted with Docker)](/governor/set-up-bito-governor-self-hosted-with-docker).

With Kubernetes, you install Governor from the Bito Gateway Helm chart. The chart defaults bring up the gateway, a MySQL database, and a valkey counter store, all on persistent volumes, so nothing outside your cluster is required.

Setup has four parts:

1. **Create a Secret.** Four credentials that the gateway reads at startup, including the key that encrypts your provider credentials.
2. **Install the chart.** One Helm command renders and applies every Kubernetes resource.
3. **Expose the gateway.** The install gives you a running gateway rather than a reachable one.
4. **Configure your workspace.** Add a provider account, a route, a gateway key, and any features you want, then connect your coding tools.

The steps below follow that order.

## Prerequisites

| Requirement        | Details                                                                                                                                                                                                                                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kubernetes cluster | Version 1.23 or later, running in your own environment                                                                                                                                                                                                                                                                                            |
| kubectl            | Installed, and pointed at the cluster you intend to install into.                                                                                                                                                                                                                                                                                 |
| Helm               | Version 3.14 or later. Helm 4 is also supported.                                                                                                                                                                                                                                                                                                  |
| Cluster context    | Run `kubectl config current-context` and confirm it names the target cluster. Every command below applies to whichever cluster your context selects.                                                                                                                                                                                              |
| Outbound access    | <p>Your cluster needs to reach two destinations:</p><ul><li><code>registry-1.docker.io</code>, to pull the <a href="https://hub.docker.com/r/bitoai/bito-gateway-helm">Helm chart</a>. Needed when you install and when you upgrade.</li><li>The endpoint of every LLM provider you configure. Needed whenever Governor serves traffic.</li></ul> |

Docker is not required on your own machine. Kubernetes runs the container images for you.

## Step 1: Create the namespace and Secret

The chart reads its credentials from a Kubernetes Secret that must already exist in the release namespace. The chart does not create it, so this comes first.

```shellscript
kubectl create namespace bito-gateway
```

```bash
kubectl create secret generic bito-gateway-secrets \
  --namespace bito-gateway \
  --from-literal=DB_PASSWORD="$(openssl rand -base64 24 | tr -d '/+=')" \
  --from-literal=CRYPTO_ENV_KEK_KEY="$(openssl rand -base64 32)" \
  --from-literal=MYSQL_ROOT_PASSWORD="$(openssl rand -base64 24 | tr -d '/+=')" \
  --from-literal=ADMIN_TOKEN="$(openssl rand -base64 32 | tr -d '/+=')"
```

Run the command as written. The `openssl` calls generate each value for you, so nothing in it needs replacing.

| Key                   | What it is                                                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `DB_PASSWORD`         | The password the gateway uses to reach its database.                                                                   |
| `CRYPTO_ENV_KEK_KEY`  | The key encryption key. It encrypts every provider credential Governor stores, and must be base64 of exactly 32 bytes. |
| `MYSQL_ROOT_PASSWORD` | The root password for the in-cluster MySQL database.                                                                   |
| `ADMIN_TOKEN`         | The bootstrap admin credential, used to sign in to the admin UI the first time.                                        |

{% hint style="info" %}
**Back up `CRYPTO_ENV_KEK_KEY` outside this cluster.** It encrypts every provider credential in your database. If you lose it, those credentials cannot be decrypted, including credentials in a database backup.

Never re-roll it against a database that already holds provider accounts.
{% endhint %}

{% hint style="info" %}
`DB_PASSWORD` reaches MySQL only once, when the database initializes on first boot. Changing it in the Secret afterwards leaves MySQL on the old password and the gateway on the new one, which produces an access-denied crash loop that a restart does not clear. Rotate the password inside MySQL first.
{% endhint %}

## Step 2: Install the chart

```bash
helm install gw oci://registry-1.docker.io/bitoai/bito-gateway-helm \
  --namespace bito-gateway \
  --set secrets.existingSecret=bito-gateway-secrets
```

`gw` is the release name. Choose any name you like. It prefixes every resource the chart creates, so a release named `gw` produces a deployment named `gw-bito-gateway`.

The command installs the newest published chart version. To pin a version for reproducible deployments, add `--version X.Y.Z`. Available versions are listed under the [Tags tab](https://hub.docker.com/r/bitoai/bito-gateway-helm/tags). To see what a version contains before installing it, run `helm show chart oci://registry-1.docker.io/bitoai/bito-gateway-helm`.

The install renders three Deployments, three Services, two PersistentVolumeClaims, and a provisioning Job.

{% hint style="info" %}
The Helm chart is published at [hub.docker.com/r/bitoai/bito-gateway-helm](https://hub.docker.com/r/bitoai/bito-gateway-helm).
{% endhint %}

{% hint style="info" %}
Helm reports `STATUS: deployed` before a single image is pulled, so a successful install command is not proof that Governor is running. Verify it yourself in Step 3.
{% endhint %}

#### Choose a values file

The chart ships example values files, each a complete starting point you copy and edit. Installing with no values file gives you the same result as `values-selfhosted.yaml`.

| File                        | Use it when                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `values-selfhosted.yaml`    | Start here. The defaults written out and explained, with the gateway, MySQL, and valkey all in-cluster on persistent volumes.  |
| `values-external-db.yaml`   | You have a managed database such as RDS, Cloud SQL, or Azure Database, with TLS and credentials from a Secret you already own. |
| `values-production-ha.yaml` | You want multiple replicas with a shared counter store.                                                                        |
| `values-single-node.yaml`   | Small or non-production, with your database already in the cluster.                                                            |
| `values-demo.yaml`          | Evaluating — in-cluster stores with **no persistent volume**; every restart loses all data                                     |

Unpack the chart to get them:

```bash
helm pull oci://registry-1.docker.io/bitoai/bito-gateway-helm --untar
```

```shellscript
ls bito-gateway-helm/values-*.yaml
```

Pass your file with `-f`:

```bash
helm install gw oci://registry-1.docker.io/bitoai/bito-gateway-helm \
  --namespace bito-gateway -f my-values.yaml
```

Put your settings in a file of your own rather than editing `values.yaml`, which ships inside the chart so that you can read what each setting does.

## Step 3: Verify the deployment

```bash
kubectl -n bito-gateway rollout status deploy/gw-bito-gateway --timeout=5m
```

```shellscript
kubectl -n bito-gateway get pods
```

Every pod reaches `Running`, apart from the provisioning Job, which reaches `Completed`.

Output:

```
NAME                                     READY   STATUS      RESTARTS   AGE
gw-bito-gateway-75f659b99c-chksx         1/1     Running     0          6m51s
gw-bito-gateway-mysql-586665659d-gvjhr   1/1     Running     0          6m51s
gw-bito-gateway-mysql-provision-vl7vg    0/1     Completed   0          6m51s
gw-bito-gateway-redis-6df545479b-8zpff   1/1     Running     0          6m51s
```

## Step 4: Expose the gateway

The install gives you a running gateway rather than a reachable one. Port forwarding is enough for a first look, and an Ingress is what your team connects to.

#### Port forward, for a first look

```bash
kubectl -n bito-gateway port-forward svc/gw-bito-gateway 8788:8788
```

The gateway is then available at `http://localhost:8788`, and the admin UI at `http://localhost:8788/admin/`. This reaches only your own machine, and only while the command runs.

#### Ingress, for your team

`values-selfhosted.yaml` carries four ready-to-uncomment Ingress presets, for **nginx**, **AWS ALB**, **GKE**, and **Azure AGIC**. Uncomment the one matching your ingress controller, set your host, and apply it with `helm upgrade`.

Point a DNS record at the load balancer address your controller provisions, and your team reaches Governor at that hostname.

{% hint style="info" %}
Raise the response timeout on your ingress controller. LLM responses stream for minutes, and a default timeout truncates answers mid-sentence. Each controller spells this differently, which is why the presets exist.
{% endhint %}

{% hint style="info" %}
A `/` path rule publishes the admin UI and admin API alongside the data plane. Scope the path to `/v1` to publish the data plane alone.
{% endhint %}

## Step 5: Sign in to the admin UI

1. Read your admin token back from the Secret. Kubernetes stores Secret values base64 encoded, so the `base64 -d` step decodes it.

```bash
kubectl -n bito-gateway get secret bito-gateway-secrets \
  -o jsonpath='{.data.ADMIN_TOKEN}' | base64 -d
```

2. Open the admin UI at your Ingress hostname, or at `http://localhost:8788/admin/` while port forwarding, and sign in with that token.
3. Create a workspace and open it — your tenant (like a team/project).

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FA2k4nioqZ5r5MnQn1tsX%2Fscrnli_6m8OC5RBA454Nu.png?alt=media&amp;token=016a4606-c950-468f-87fe-080ba549aabb" alt=""><figcaption></figcaption></figure>

The workspace opens on the **Dashboard**. The left sidebar contains the following pages: Dashboard, Documentation, Reports, Keys, Members, Accounts, Routes, Features, Limits, Prices, Test, and Audit.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FdlCFUJIqnYT4K8pYO18i%2Fscrnli_zp2ysse2447CN9.png?alt=media&amp;token=41c9b44a-fa47-4ceb-850f-a5b639bd445e" alt=""><figcaption></figcaption></figure>

Most configuration pages contain a form at the top and a table of existing entries below it. Complete Steps 6 to 11 in the admin UI.

#### Configure from the command line instead

`gwctl` command ships inside the gateway image and reads the database settings the pod already has. Substitute the workspace ID that the first command prints.

```bash
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl workspace create --name demo
```

```shellscript
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl key create --workspace <ID> --name demo
```

```shellscript
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl account add --workspace <ID> --provider anthropic --key <YOUR PROVIDER KEY>
```

```shellscript
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl route add --workspace <ID> --alias '*' --provider anthropic
```

{% hint style="info" %}
Note: `key create` prints the `gw_sk_` key once.
{% endhint %}

{% hint style="info" %}
Every pod can be `Ready`, `/healthz` can return `200`, and every request can still return `401`. That is an empty database rather than a failure. Create a workspace and a gateway key, and the `401` stops.
{% endhint %}

#### Use a database-backed admin instead of ADMIN\_TOKEN

`ADMIN_TOKEN` exists as a bootstrap credential for the case where the database has no rows yet. To avoid storing an admin credential in a Kubernetes Secret, leave it out of the Secret and mint an admin against the database instead.

```bash
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin create --role global
```

The command prints the token once. Governor stores only a SHA-256 hash of it, so the raw value never reaches disk or cluster state.

|                    | ADMIN\_TOKEN in a Secret    | gwctl admin create                 |
| ------------------ | --------------------------- | ---------------------------------- |
| Credential at rest | In your Secret              | A hash in the database             |
| Takes effect       | After a pod restart         | Immediately                        |
| Revoking           | Edit the Secret and restart | `gwctl admin revoke <id>`          |
| Audit trail        | One shared identity         | One row per admin                  |
| Scope              | Always global               | Global, or scoped to one workspace |

Leaving `ADMIN_TOKEN` unset is a supported configuration. The gateway boots normally and serves traffic, and only the bootstrap admin is disabled.

## Step 6: Add a provider account

A provider account stores one LLM API key. Add an account for every LLM provider you use, such as Anthropic, OpenAI, Groq, Fireworks, OpenRouter, Together, Google, etc. Add more than one account for the same provider when you hold several keys, for example one per team or environment.

1. In the left sidebar, click **Accounts**.
2. In the **Add account** form, complete the following fields:

| Field    | Description                                                                                                                                     |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| provider | The provider you are connecting.                                                                                                                |
| name     | A name for this account, for example `prod` or `my-vllm`. The name appears in routes, reports, and prices.                                      |
| key      | Your provider API key. Governor stores it envelope encrypted under the key encryption key in your cluster.                                      |
| base url | The provider endpoint. The default is filled in for each provider. Override it for a proxy, a regional endpoint, or a self-hosted model server. |

3. Click **Add**.

The account appears in the **Accounts** table with the actions **edit**, **test**, **reveal**, and **remove**, and a toggle to enable or disable it.

4. Click **test** on the new account.

**test** checks the connection to the provider to verify the key and endpoint.

{% hint style="info" %}
To forward the credential supplied by the caller, leave the **key** field blank. This is passthrough mode.

Azure accounts can authenticate with an Entra ID service principal instead of an API key.
{% endhint %}

{% hint style="info" %}
**reveal** displays a stored provider key. Every use is recorded in the audit log.
{% endhint %}

#### Examples

<details>

<summary><strong>Expand to view examples</strong></summary>

Each example states a goal, then the values to enter in the **Add account** form.

#### Connect a provider

Add your organization's Anthropic key.

| provider  | name             | key                    | base url                  |
| --------- | ---------------- | ---------------------- | ------------------------- |
| anthropic | `prod-anthropic` | your Anthropic API key | leave the prefilled value |

Governor fills in **base url** when you select a provider. Change it only for a proxy, a regional endpoint, or a server you host yourself.

#### Separate production and staging spend

Bill staging traffic to a different key from production.

| provider  | name                | key                 | base url                  |
| --------- | ------------------- | ------------------- | ------------------------- |
| anthropic | `prod-anthropic`    | your production key | leave the prefilled value |
| anthropic | `staging-anthropic` | your staging key    | leave the prefilled value |

Add the provider twice under different names. Routes select an account by name, and reports show which account served each request, so spend separates cleanly.

#### Connect a model you host yourself

Send requests to a model running on your own inference server.

| provider | name      | key                                                | base url                      |
| -------- | --------- | -------------------------------------------------- | ----------------------------- |
| openai   | `my-vllm` | your server's key, or leave empty if it needs none | your inference server address |

Any server that implements the OpenAI API works here.

#### Forward the caller's own key

Apply routing and reporting to traffic without storing provider keys centrally.

| provider | name                 | key         | base url                  |
| -------- | -------------------- | ----------- | ------------------------- |
| openai   | `passthrough-openai` | leave empty | leave the prefilled value |

An account with no key runs in passthrough mode, where Governor forwards the credential the caller supplied.

</details>

## Step 7: Add a route

A route maps a model alias your coding tool requests to a provider account and an upstream model.

1. In the left sidebar, click **Routes**.
2. In the **Add route** form, complete the following fields:

<table data-search="false"><thead><tr><th align="center">Field</th><th>Description</th></tr></thead><tbody><tr><td align="center">alias</td><td>The model name your coding tool requests, for example <code>claude-opus-4-8</code> or <code>claude-*</code>. Enter <code>*</code> to match any model.</td></tr><tr><td align="center">provider</td><td>The provider that serves the request.</td></tr><tr><td align="center">account</td><td>The provider account used.</td></tr><tr><td align="center">model (or *)</td><td>The upstream model sent to the provider. Enter <code>*</code> to forward the model name the tool requested.</td></tr><tr><td align="center">api</td><td>The API dialect. Leave it on <strong>auto</strong> to follow the caller.</td></tr><tr><td align="center">priority</td><td>The failover tier. Lower numbers are used first. Default <code>0</code>.</td></tr><tr><td align="center">weight</td><td>The share of traffic within a tier. Default <code>1</code>.</td></tr><tr><td align="center">retries</td><td>Retry attempts for this target. Leave blank to use the gateway default.</td></tr><tr><td align="center">auto-route this alias</td><td>Adds the route, then opens auto-routing so you can say which models answer which kind of request. It starts as a dry run: every request is classified and recorded, and this route keeps answering until you turn routing on.<br><br>See <a href="/governor/auto-ai-model-routing">Auto AI model routing</a> for more details.</td></tr><tr><td align="center">backing group (internal)</td><td>Hides this route from your apps. They cannot ask for it by name and it does not appear in the model list, so only auto-routing can send traffic here. Use it for the models a router picks between, so nobody skips the router by asking for one directly.</td></tr></tbody></table>

3. Click **Add route**.

Routes are grouped by alias in the table below the form. Each group lists its targets with provider, model, account, priority, weight, retries, an enable toggle, and a health state. Priority, weight, and retries are editable inline.

Each group also carries a **Direct** and an **Auto** control. **Direct** sends every request for that alias to the targets you configured. **Auto** hands the alias to the auto-router, which picks a model for each request.

A target marked **cooling** is in a cooldown period after repeated failures. Governor sends its traffic to the next available target until it recovers.

#### Wildcard and exact aliases

An alias can be an exact model name such as `claude-opus-4-8`, or a wildcard such as `claude-sonnet-*` or `*`.

A route with `*` as both the alias and the upstream model passes every request through to the selected account unchanged.

Exact aliases take precedence over wildcards. A route for `claude-opus-4-8` is used instead of a `claude-*` route, and a `claude-*` route is used instead of `*`. This lets you run one catch-all route so that every model reaches a provider, then override selectively for the models you care about.

#### Failover and load balancing

Add the same alias again with a different provider account.

* Governor uses the lowest priority tier first.
* Within a tier, traffic is distributed by weight.
* Targets with the same priority receive requests in turn.
* If a provider returns errors, Governor sends the request to the next available target.

#### Auto-routing

An alias can answer from the targets you configured, or you can hand it to the auto-router, which classifies each request and picks a model for it. Select **auto-route this alias** when you add the route, or click **Auto** on the group in the routes table.

See [Auto AI model routing](/governor/auto-ai-model-routing) for more details.

#### Examples

<details>

<summary><strong>Expand to view examples</strong></summary>

Each example states a goal, then the values to enter in the **Add route** form.

#### Route every model to one provider

Send all traffic to a single account, without naming each model.

| alias | provider  | account          | model | priority |
| ----- | --------- | ---------------- | ----- | -------- |
| `*`   | anthropic | `prod-anthropic` | `*`   | 0        |

Type the asterisk in both fields. `*` in the alias matches any model, and `*` in the model field forwards the model name your tool sent. Add this route first, so that every request reaches a provider while you configure the rest.

#### Route a model family to one account

Send every version of Sonnet to an Azure account.

| alias             | provider | account      | model | priority |
| ----------------- | -------- | ------------ | ----- | -------- |
| `claude-sonnet-*` | azure    | `azure-prod` | `*`   | 0        |

The wildcard matches `claude-sonnet-5`, `claude-sonnet-4-5`, and later versions, so new releases need no new route. This alias is more specific than `*`, so it overrides the catch-all.

#### Fail over to a second provider

Serve Opus 5 from Anthropic, and switch to Azure while Anthropic is unavailable.

| alias           | provider  | account          | model           | priority |
| --------------- | --------- | ---------------- | --------------- | -------- |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-opus-5` | 0        |
| `claude-opus-5` | azure     | `azure-prod`     | `claude-opus-5` | 1        |

Add the alias once per account. Priority `0` takes all traffic. When those requests fail, Governor moves them to priority `1` until the primary account recovers.

#### Split traffic across two accounts

Spread Opus 5 traffic so that neither account reaches its rate limit.

| alias           | provider  | account          | model           | priority | weight |
| --------------- | --------- | ---------------- | --------------- | -------- | ------ |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-opus-5` | 0        | 3      |
| `claude-opus-5` | azure     | `azure-prod`     | `claude-opus-5` | 0        | 1      |

Equal priorities put both targets in the same tier, and the weights send three requests to Anthropic for every one to Azure. Set both weights to `1` for an even split.

#### Serve a request with a different model

Serve Opus 5 requests with a lower-cost model, with no change on any developer machine.

| alias           | provider  | account          | model             | priority |
| --------------- | --------- | ---------------- | ----------------- | -------- |
| `claude-opus-5` | anthropic | `prod-anthropic` | `claude-sonnet-5` | 0        |

The alias is the model your tool requests. The model is what serves the request. Your tools continue to request Opus 5, and Governor serves those requests with Sonnet 5. Edit the route to reverse it.

</details>

{% hint style="info" %}
Before applying a model substitution across your workspace, run it against a representative set of your own tasks and compare results as well as cost.
{% endhint %}

## Step 8: Create a gateway key

A gateway key authenticates a coding tool to Governor. Provider keys stay in the Bito UI.

1. In the left sidebar, click **Keys**.
2. In the **Create key** form, enter a **name** that identifies the team or tool that will use the key.
3. Click **Create**.
4. Copy the key.

The key starts with `gw_sk_` and is displayed once. Governor stores keys hashed and cannot display them again.

The **Keys** table lists each key by ID, prefix, and name, with an enable toggle and a **revoke** action. Create one key per team or tool so that you can revoke one without affecting the others.

## Step 9: Enable features

Features are server-side capabilities that Governor runs inside a request. Two features are available, and both are optional.

The **Features** table lists each enabled feature with its alias, state, whether a token is stored, and its MCP URL, with **edit**, **test connection**, and **disable** actions. Enabled features also appear as badges against each alias on the **Routes** page.

#### AI Architect

AI Architect serves system context from a live knowledge graph of your engineering system, covering code, business context, and tribal knowledge. Governor applies it inside each request, so your coding tools receive that context as they work.

1. In the left sidebar, click **Features**.
2. In the **Configure feature** form, select `ai_architect` from the **feature** list.
3. Complete the following fields:

<table data-search="false"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>alias</td><td>Leave blank to enable the feature across the workspace, or enter a route alias such as <code>claude-*</code> to scope it to that alias.</td></tr><tr><td>MCP URL</td><td>Your AI Architect MCP endpoint. If left empty, Governor falls back to a built-in stub.</td></tr><tr><td>Steering text</td><td>Overrides the default instructions Governor sends with AI Architect. Leave blank to use the default.</td></tr><tr><td>Tool allowlist</td><td>Restricts which AI Architect tools the model may call, one tool name per line. Leave empty to allow all.</td></tr><tr><td>Max hops</td><td>The hop budget for a single AI Architect lookup. Default <code>16</code>. See <a href="#max-hops">Max hops</a> below.</td></tr><tr><td>Max hops per request</td><td>The combined hop budget across every AI Architect lookup in one request. Leave blank to use the gateway default.</td></tr><tr><td>Prompt-cache injection</td><td>Caches what Governor sends with AI Architect on Anthropic, so repeat hops bill at the cache-read rate. Leave on <strong>Use default</strong> to follow the gateway-wide setting.</td></tr><tr><td>Architect model (sub-agent)</td><td>Runs the AI Architect lookups on a cost-efficient sub-agent while the route model writes the answer, for example GPT-5.6 Luna or Gemini Flash Lite 3.5. Leave blank to run them on the request's own route model.<br><br>You must configure a sub-agent to capture most of the cost savings.</td></tr><tr><td>Run Architect in-loop (legacy)</td><td>Runs the AI Architect tools inline on the route model instead of the default sub-agent mode. Ignored when an Architect model is set.</td></tr><tr><td>Delegation pressure</td><td><p>How hard the assistant is pushed to consult AI Architect.</p><ul><li><strong>Balanced</strong> consults it when the assistant judges research worthwhile, which suits coding tools whose own file search competes for the same job.</li><li><strong>Aggressive</strong> tells the assistant to consult AI Architect first, before searching files itself, which suits chat-style products.</li></ul><p>Left unset it follows the <strong>Architect model</strong> setting above — Balanced with none pinned, Aggressive with one, because a pinned model makes research cheap enough to lean on; the unset option names whichever applies right now. Choosing a value explicitly overrides that link and holds even if the Architect model changes later.</p></td></tr><tr><td>Evidence format</td><td><p>What a finished research call hands back.</p><ul><li><strong>Prose</strong> returns a written answer with citations.</li><li><strong>Structured</strong> returns the same research as separate findings, each carrying a verbatim code excerpt with its file and line.</li></ul><p>Prose is recommended, and matched or beat Structured on accuracy in five test setups out of six while costing less in five out of six, because excerpts add to the size of every request. Choose Structured when you parse the findings yourself.</p><p></p><p>Default: Prose</p></td></tr><tr><td>Quality mode</td><td><p>Sets how deeply AI Architect researches a question.<br></p><p>Choose one of the following:</p><ul><li><strong>Use default:</strong> follows the gateway-wide setting.</li><li><strong>Normal:</strong> uses the standard prompts and hop budget. This is the default.</li><li><strong>High quality:</strong> researches deeper and more thoroughly, at roughly twice the AI Architect cost.</li></ul></td></tr><tr><td>Codebase context</td><td><p>Codebase context tells the assistant about your own codebase before it starts work.</p><p></p><p>This is the highest-impact setting on this form, and it is off by default.</p><p></p><ul><li><strong>Conventions</strong> sends a short summary of the repository the person is working in, covering how you handle errors and logging, how you name things, how you test, and your security and module boundaries. The summary is the same for every request, so it is inexpensive to send repeatedly, and in testing it roughly halved the cost of a coding session.</li><li><strong>Conventions + task research</strong> also reads the request, works out what kind of work it is, and looks that up before answering, covering where the change belongs, what it would break, which pattern to follow, and what is already underway.</li></ul><p></p><p>Default: Off</p></td></tr><tr><td>Include risk areas and in-flight work</td><td><p>Also tells the assistant about known risk areas, technical debt, and work currently underway in the part of the codebase the caller is working in. Carries no contributor names.</p><p></p><p>Available only when <strong>Codebase context</strong> is on.</p></td></tr><tr><td>MCP token</td><td>Your AI Architect access token. Leave blank to keep the token already stored.</td></tr></tbody></table>

**Task guidance**

Task guidance adds what only your indexed codebase can supply to three kinds of request. Each setting is off by default and applies only to the request type named.

| Field                    | What it adds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Guide what plans cover   | <p>When someone asks the assistant to plan or scope a change, it also covers what else the change would affect across your repositories, the patterns your code already follows, the business rules that constrain it, and the parts of the code that are risky to touch.</p><p></p><p>This makes plans more complete rather than more accurate, so it ensures the important ground is covered without making individual details more likely to be right.</p><p></p><p>In testing, plans that addressed those areas rose from about half to roughly four in five, with no slowdown.</p><p></p><p>Applies to planning, design, and implementation requests. Questions and troubleshooting are unaffected.</p> |
| Guide what reviews cover | <p>When someone asks what the codebase requires of a change they are about to make, the assistant also establishes which other repositories and services call the code being changed and would have to move with it, the convention the affected code is meant to follow, and the invariants the change could break.</p><p></p><p>The cross-repository part is the point, because call sites and conventions inside one repository are already searchable while a consumer in another service is not.</p><p></p><p>Applies to review requests only.</p>                                                                                                                                                      |
| Guide what triage covers | <p>When someone brings a bug or an outage, the assistant first checks what its local view cannot show, including whether an incident or alert is already firing for the services involved, what recently deployed in that area, and any issue already recorded against it.</p><p></p><p>Tracing the code is something the assistant can already do from the repository, while knowing that an alert has been firing since this morning is not.</p><p></p><p>Applies to bug reports and troubleshooting only.</p>                                                                                                                                                                                             |

4. Click **Enable**.

Changes apply to the next request. Users take no action.

{% hint style="info" %}
Setting **Architect model (sub-agent)** to a cost-efficient alias moves the AI Architect lookups off your main model while the route model still writes the answer. This reduces the cost of a request that takes several hops.
{% endhint %}

#### Max hops

Some questions require several passes to answer. A question about how your repositories connect requires Governor to retrieve the repository list, then look up the dependencies of each repository. Each pass is a hop.

Two settings cap this work, and both apply at the same time.

| Setting              | Scope                                               |
| -------------------- | --------------------------------------------------- |
| Max hops             | One AI Architect lookup.                            |
| Max hops per request | Every AI Architect lookup in one request, combined. |

A single request can trigger more than one lookup, so **Max hops per request** is what stops a complex request from running up cost through repeated lookups that each stay within their own limit.

Governor stops as soon as it has an answer, so both values are ceilings rather than fixed costs.

| Max hops     | Use                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------- |
| 16           | Default. Suitable for most workspaces.                                                            |
| 30 or higher | Workspaces with several hundred repositories, or teams that ask broad cross-repository questions. |

Raise **Max hops** if answers come back incomplete. Leave **Max hops per request** blank to use the gateway default, and set it when you want a firm ceiling on how much AI Architect work a single request can do. Each hop consumes tokens.

#### Reasoning downgrade

`reasoning_downgrade` lowers the reasoning effort of a request by exactly one level. Reasoning tokens bill at the output rate, so a lower level reduces the cost of the request.

1. In the left sidebar, click **Features**.
2. In the **Configure feature** form, select `reasoning_downgrade` from the **feature** list.
3. Leave **alias** blank to apply the feature across the workspace, or enter a route alias such as `claude-*` to scope it to that alias.
4. Click **Enable**.

Apart from **alias**, the feature has no settings.

Governor leaves a request unchanged when it already uses the lowest or second-lowest reasoning level, or when it sends no reasoning at all.

## Step 10: Connect a coding tool

In the left sidebar, click **Documentation**. Your own base URL is displayed at the top of the page, and the links below it jump to the four sections on the page.

| Section        | Contents                                                                                     |
| -------------- | -------------------------------------------------------------------------------------------- |
| Get started    | Your base URL, a field for your gateway key, and how to authenticate.                        |
| Use it         | Ready-made curl, Python, and JavaScript requests, and **Try it** for sending a live request. |
| Connect a tool | Copy-paste setup for each supported coding tool.                                             |
| Reference      | Endpoints, your route aliases, and how usage and cost are reported.                          |

To connect a coding tool:

1. In the **Get started** section, paste a gateway key into the key field. Every example on the page fills in with your base URL and key. To generate a key here, click **+ Create test key**.
2. In the **Connect a tool** section, select your tool.

Setup is provided for Claude Code, Claude Desktop, Cursor, Cline (VS Code), Continue (VS Code / JetBrains), Aider, Codex CLI, GitHub Copilot CLI, Windsurf, Zed, and any OpenAI-compatible or Anthropic-compatible tool.

To print the same setup from a terminal, run `gwctl connect` inside the gateway pod. The command outputs configuration values and changes no state.

```bash
kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl connect claude
# Supported values: claude | cursor | codex | copilot | cline | continue | aider
```

The output contains your data-plane URL and the required environment variables, with a `<YOUR_GATEWAY_KEY>` placeholder. Replace it with the key you created in Step 8.

For Claude Code, set two environment variables and start the tool:

```bash
export ANTHROPIC_BASE_URL="https://GATEWAY_HOST"
export ANTHROPIC_AUTH_TOKEN="gw_sk_..."
claude
```

Replace `GATEWAY_HOST` with your Ingress hostname, or use `http://localhost:8788` while port forwarding. To configure a team, distribute these two variables using your existing developer environment tooling. If your traffic already passes through a central gateway, set them there instead.

Governor accepts requests on three endpoints:

| Path                   | Dialect                 | Used by                             |
| ---------------------- | ----------------------- | ----------------------------------- |
| `/v1/messages`         | Anthropic Messages      | Claude Code, Anthropic SDKs         |
| `/v1/chat/completions` | OpenAI Chat Completions | Codex, most OpenAI-compatible tools |
| `/v1/responses`        | OpenAI Responses        | OpenAI Responses API clients        |

Authenticate with `Authorization: Bearer <GATEWAY_KEY>` or `X-Api-Key: <GATEWAY_KEY>`. The same gateway key works for all three dialects.

Every response carries an `x-bito-routed-model` header naming the model that answered. Read that header rather than the `model` field inside the response body, because some providers return the model that was requested and others return the model that answered. The difference matters once auto-routing is on, since the model that answers may not be the one your tool asked for.

{% hint style="info" %}
Claude Code reports that its connectors are disabled when it runs through Governor, because the session authenticates against Governor rather than a Claude account. This message is expected. AI Architect continues to work, because Governor serves it from the server side.
{% endhint %}

#### Connect Claude Desktop

Once you configure Bito Governor as Claude Desktop's third-party inference gateway, every model request the app makes goes through Governor. That covers Chat, Cowork, and Code sessions. Your routes, auto-routing, limits, cost tracking, and AI Architect settings apply to all of them. Claude Desktop uses a settings window instead of environment variables, so the setup differs from Claude Code.

**Before you begin**

* Update Claude Desktop to the latest version. [Download Claude Desktop](https://claude.com/download).
* Create a gateway key for Claude Desktop, as described in Step 8. A separate key per tool lets you track usage and set limits for Claude Desktop on its own.
* Expose Governor through an Ingress, as described in Step 4. Your gateway base URL is `https://GATEWAY_HOST`, your Ingress hostname.

{% hint style="warning" %}
**Each user's machine must reach Governor.** Claude Desktop calls the gateway URL directly from the user's computer, so your Ingress hostname has to resolve and respond from there. It can sit on the public internet or inside your private network or VPN. A `kubectl port-forward` session only works on the machine that runs it, so use the Ingress for your team. Raise your ingress controller's response timeout as well, or long streamed responses can stop partway.
{% endhint %}

{% hint style="info" %}
**What changes in Claude Desktop.** With Governor connected, Claude Desktop runs in third-party inference mode and stops using your claude.ai account for inference. Your existing chats and tasks don't appear in the sidebar, and connectors, skills, and plugins from your Claude account don't appear under **Settings**. The account label in the bottom-left corner changes to **\<your name> with Gateway connected**. This is expected.
{% endhint %}

**1. Turn on Developer Mode**

You only do this once on each machine. If you already see a **Developer** menu, skip to the next step.

1. Open Claude Desktop.
2. Open **Help** > **Troubleshooting** > **Enable Developer Mode**. On macOS, Help is in the menu bar. On Windows, it's in the application menu in the top-left corner.
3. Confirm the prompt. Claude Desktop restarts and a **Developer** menu appears.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIVfHCEL2iqGfQp8hYWN3%2Fscrnli_6NdzSz33G02ncF.png?alt=media&amp;token=8f5f5722-d5ca-4dac-bf5a-ccbbe8537527" alt=""><figcaption></figcaption></figure>

**2. Configure Governor as the gateway**

1. Open **Developer** > **Configure Third-Party Inference**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fpw9YkWTF2ICUjtucpgOh%2Fscrnli_66d2qLF5M06Q7z.png?alt=media&amp;token=032544c4-403c-4ae9-a564-95796685a2f2" alt=""><figcaption></figcaption></figure>

2. In the **Connection** section, enter these values:

| Field               | Value                     |
| ------------------- | ------------------------- |
| Inference provider  | **Gateway**               |
| Credential kind     | **Static API key**        |
| Gateway base URL    | `https://GATEWAY_HOST`    |
| Gateway API key     | Your `gw_sk_` gateway key |
| Gateway auth scheme | **Bearer** (the default)  |

3. Leave the remaining fields as they are. Governor doesn't need custom headers.
4. Click **Test Connection**. Continue when the result shows green. If it fails, open `https://GATEWAY_HOST` in a browser on the same machine to confirm the Ingress is reachable.
5. Click **Save Changes**, then **Apply Changes**, and confirm the relaunch.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fe1x9HFLlecUDEYaSyqsZ%2Fscrnli_jnsi2NLQz2h7IM.png?alt=media&amp;token=d157867c-5f3c-4db4-ad59-dcb7536bd9a1" alt=""><figcaption></figcaption></figure>

**3. Verify the connection**

1. Check that the bottom-left corner reads **\<your name> with Gateway connected**.
2. Open **Code** and click the model picker. It lists the route aliases you created in Step 7.
3. Send a short prompt and confirm the request appears on the Governor **Dashboard**.
4. If AI Architect is enabled on the selected route, ask `List my indexed repositories`. Claude Desktop returns the repositories from your knowledge graph without running local `grep` or file searches.

{% hint style="info" %}
AI Architect applies per route, as you set it in Step 9. On a route without it, Claude falls back to searching files on the local machine. After you change a route or feature, wait about 30 seconds and start a new session before you test.
{% endhint %}

**Roll out to your team**

The steps above configure one machine. To apply the same configuration across your team, configure and test one machine, click **Export** in the **Configure Third-Party Inference** window, and deploy the resulting `.mobileconfig` (macOS) or `.reg` (Windows) file through your MDM tool. See Anthropic's guide to [deploying Claude Desktop with MDM](https://claude.com/docs/third-party/claude-desktop/mdm).

## Operate the Bito Governor

### Verify the configuration

1. **Check route selection.** In the left sidebar, click **Test**. Enter a model alias and click **Test**. Governor returns the route, provider, account, and lane it would use. No request is sent, so this costs nothing.
2. **Check auto-routing, if you set it up.** In the left sidebar, click **Routes**. On a routed alias, click **Classify a prompt**, enter a sample request, and confirm it lands in the tier you expect. No request is sent, so this costs nothing.
3. **Send a request.** In the left sidebar, click **Documentation**. In the **Use it** section, go to **Try it**. Paste a gateway key, select a model, type a prompt in the message box, and click **Run**. This sends a real, billable request to your provider.
4. **Query your own system.** From your coding tool, ask a question that requires knowledge of your repositories. A response naming your own services confirms AI Architect is active.
5. **Check the report.** In the left sidebar, click **Reports** and confirm the requests appear.

{% hint style="info" %}
For a wildcard alias such as `claude-*`, enter a concrete model that matches it, for example `claude-opus-4-8`.
{% endhint %}

### Set prices

Token prices produce the cost figures on the **Dashboard** and in **Reports**. Prices are expressed in `$/Mtok`, meaning US dollars per million tokens.

Global defaults are maintained by your gateway operator. Set a price here to override the default for your workspace, or to record a negotiated rate for one account. Governor resolves prices in this order: account, then workspace, then global.

1. In the left sidebar, click **Prices**.
2. In the **Set price** form, select the **vendor**.
3. Select an **account** to apply the price to that account only, or leave it on **all accounts** to apply the vendor rate across your workspace.
4. Enter the **model** name.
5. Enter **in**, **out**, and optionally **cache-read** and **cache-write** prices, all in `$/Mtok`.
6. Click **Set**.

The **Prices** table lists each price with its scope, vendor, model, rates, and source.

A model with no price reports token counts and a cost of zero. The **Dashboard** shows the number of unpriced requests per model in the **UNPRICED** column. Auto-routing also depends on these prices. A model with no price cannot be selected by a router, and both the routing direction and the price ceiling are evaluated against them.

### Set limits

Limits are applied per gateway key.

1. In the left sidebar, click **Limits**.
2. In the **Set limits** form, select a **key**.
3. Complete any of the following fields:

| Field            | Description                                   |
| ---------------- | --------------------------------------------- |
| rpm              | Maximum requests per minute.                  |
| tpm              | Maximum tokens per minute.                    |
| budget ($/month) | Monthly spend cap. Requires prices to be set. |
| max\_concurrency | Maximum concurrent requests.                  |

4. Click **Set**.

Leave a field blank to leave it unchanged. Enter `0` to remove a cap, which makes that limit unlimited.

{% hint style="info" %}
Setting a limit to `0` removes the cap rather than blocking the key. To stop a key entirely, disable it on the **Keys** page.
{% endhint %}

### Monitor usage and cost

#### Dashboard

The **Dashboard** shows spend and request volume for the last 30 days, with totals for requests, input tokens, output tokens, and cost. Use **Group by** to break the numbers down by model, alias, key, provider, account, detail, or feature.

The table below the chart lists requests, token counts, cost, and unpriced request count per model.

#### Reports

**Reports** is the raw event log, with one row per request, updated in near real time. Filter the log and export it with **Download CSV**.

Token counts are split into four buckets:

| Bucket   | Description                                                             |
| -------- | ----------------------------------------------------------------------- |
| in       | Fresh prompt tokens, excluding anything served from cache.              |
| cached   | Prompt tokens read from cache, billed at a lower rate.                  |
| cache\_w | Tokens written to the cache. On Anthropic this carries a small premium. |
| out      | All generated tokens, including reasoning tokens.                       |

The full prompt your tool sent is `in + cached + cache_w`. The buckets do not overlap, so nothing is counted twice.

Features make hidden calls inside a request and are reported separately. The base columns show the answer the caller received, and the feature columns show the feature's own usage. A request's total is base plus feature. Expand a row to see the split.

#### Measure the effect of AI Architect

Governor does not currently report savings against a baseline. To measure the effect:

1. Select a set of tasks your team runs regularly.
2. Disable AI Architect, run the tasks, and record cost per task from **Reports**.
3. Enable AI Architect and run the same tasks with the same tool and model.
4. Compare cost per task and confirm the tasks still complete correctly.

### Add members

1. In the left sidebar, click **Members**.
2. In the **Add team member** form, enter a **name** and select a **role**.
3. Click **Create**.

Each member signs in to the admin UI with the token generated for them.

| Role            | Permissions                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| Member          | Manages their own gateway keys and views their own usage.                                     |
| Workspace admin | Full configuration access to the workspace, including routes, accounts, features, and limits. |

You can disable a member from the **Team** table.

### View the audit log

**Audit** records every configuration change and every secret reveal in your workspace, with the admin who performed it and a timestamp. The log is read only.

Give each person their own member token, so that the log identifies who made each change.

### Use your own MySQL or Redis

The chart brings up both by default. Turn off either one independently and point the gateway at your own.

| You already run | Set                    | Point the gateway at yours with                                                             |
| --------------- | ---------------------- | ------------------------------------------------------------------------------------------- |
| MySQL           | `mysql.enabled: false` | `config.DB_HOST`, `config.DB_PORT`, `config.DB_NAME`, `config.DB_USER`, and `config.DB_TLS` |
| Redis or valkey | `redis.enabled: false` | `config.REDIS_ADDR`, plus `REDIS_TLS` and `REDIS_PASSWORD`                                  |
| Both            | Both `false`           | Use `values-external-db.yaml`                                                               |

For an external database, create the database and a user that may run DDL on the first install. The gateway creates its own tables.

Deliver `REDIS_PASSWORD` through your Secret rather than through `config`, in the same way as every other credential.

### Run more than one replica

Governor holds one piece of shared mutable state, the counter store behind your rate limits, budgets, and route health. In-memory counters are per-pod, so running several replicas without a shared store multiplies every limit by the number of pods.

Before raising `replicaCount` above 1 or enabling autoscaling, set `config.STORE_BACKEND` to `redis`, `valkey`, or `aerospike`, and set `config.REDIS_ADDR` to a single `host:port` for the Redis and valkey backends. The chart refuses to install a multi-replica release without one.

{% hint style="info" %}
Give the counter store a dedicated Redis database or instance, configured with `maxmemory 0` or `maxmemory-policy noeviction`. Every counter carries a TTL, so an eviction policy removes them, and an evicted budget counter reads back as zero spend with no error.

Two separate installs must never share a Redis database and key prefix. Their counters are shaped identically and would sum silently, so limits bind early and spend over-counts.
{% endhint %}

Sentinel and Cluster are unsupported. Use a single endpoint.

### Upgrade Governor

```bash
helm upgrade gw oci://registry-1.docker.io/bitoai/bito-gateway-helm \
  --namespace bito-gateway -f my-values.yaml --timeout 1800s
```

Pass no new secret values on upgrade. The Secret is yours rather than the chart's, and both `DB_PASSWORD` and `CRYPTO_ENV_KEK_KEY` are fixed after the first install.

A change to the chart's configuration rolls the pods for you. A change to a Secret you own does not, because the chart cannot read it, so roll the pods yourself after rotating one:

```bash
kubectl -n bito-gateway rollout restart deploy/gw-bito-gateway
```

### Roll back

```bash
helm rollback gw <revision> -n bito-gateway
```

A rollback returns the pods to the previous image while the database keeps the newer schema. Bito keeps migrations backward compatible with the previous release for this reason. A schema rollback is a separate, deliberate operation.

### Uninstall

```bash
helm uninstall gw -n bito-gateway
```

Your data survives. The PersistentVolumeClaims are annotated to be kept, so `helm uninstall` leaves them behind and a reinstall under the same release name adopts them.

Remove them deliberately when you want the data gone:

```bash
kubectl -n bito-gateway delete pvc gw-bito-gateway-mysql
kubectl -n bito-gateway delete pvc gw-bito-gateway-redis
```

Helm also leaves the migration objects behind:

```bash
kubectl -n bito-gateway delete job,configmap,serviceaccount,secret \
  gw-bito-gateway-migrate --ignore-not-found
```

## Troubleshooting

Start with the pod status, which names most problems on its own:

```bash
kubectl -n bito-gateway get pods
kubectl -n bito-gateway logs deploy/gw-bito-gateway
```

<table data-search="false"><thead><tr><th>Symptom</th><th>Cause</th><th>Resolution</th></tr></thead><tbody><tr><td><code>ImagePullBackOff</code> on any pod</td><td>Docker Hub is rate limiting anonymous pulls, or your registry needs credentials.</td><td>Set <code>imagePullSecrets</code>, which every pod in the chart renders.</td></tr><tr><td>The gateway pod crash loops with an access-denied error</td><td><code>config.DB_USER</code> does not match the database user.</td><td>Set <code>config.DB_USER</code>. The binary defaults to <code>root</code>, and the in-chart MySQL root password is random.</td></tr><tr><td>The database pod exits during startup</td><td>An init step failed.</td><td>Read its logs with <code>kubectl -n bito-gateway logs deploy/gw-bito-gateway-mysql</code>.</td></tr><tr><td><code>CreateContainerConfigError</code> on the database pod</td><td>The Secret named by <code>secrets.existingSecret</code> is missing, or has no <code>DB_PASSWORD</code> key.</td><td>Create the Secret in the release namespace, then roll the pods.</td></tr><tr><td>Every pod is <code>Ready</code>, <code>/healthz</code> returns 200, every call returns <code>401</code></td><td>The database has no workspace or gateway key yet.</td><td>Create them, as in Step 5.</td></tr><tr><td><code>/admin/api</code> returns <code>401</code> with the token you read back</td><td><code>ADMIN_TOKEN</code> was absent from the Secret when the pod started.</td><td>Add it, then run <code>kubectl -n bito-gateway rollout restart deploy/gw-bito-gateway</code>. An existing Secret carries no checksum, so nothing rolls the pods for you.</td></tr><tr><td>The gateway is <code>Ready</code> but every request fails</td><td>The database pod restarted and re-ran its init, so the schema is fresh and holds no tenants.</td><td>Recreate your workspace and keys, and check that persistence is enabled.</td></tr><tr><td>Answers are truncated mid-sentence</td><td>Your ingress controller timed the response out.</td><td>Raise the response timeout, as in Step 4.</td></tr><tr><td><code>401</code> from Governor with a gateway key</td><td>The gateway key is invalid or revoked.</td><td>Create a new key on the <strong>Keys</strong> page and update the tool configuration.</td></tr><tr><td><code>404</code> for a model</td><td>No route matches the requested alias.</td><td>Add a route for the exact model name, or add a <code>*</code> route.</td></tr><tr><td>Requests reach an unexpected model</td><td>An exact alias takes precedence over the <code>*</code> route.</td><td>Check the <strong>Routes</strong> page. Exact aliases override wildcards.</td></tr><tr><td>A route shows <strong>cooling</strong></td><td>The target failed repeatedly and is in a cooldown.</td><td>Check the provider account with <strong>test</strong> on the <strong>Accounts</strong> page. Traffic uses the next target until it recovers.</td></tr><tr><td>Cost column shows zero, or UNPRICED is high</td><td>The model has no price set.</td><td>Add prices for that model on the <strong>Prices</strong> page.</td></tr><tr><td>Budget limit has no effect</td><td>The model has no price set, or the limit is <code>0</code>.</td><td>Set prices, then set a positive budget. <code>0</code> means unlimited.</td></tr><tr><td>A key still works after setting limits to <code>0</code></td><td><code>0</code> removes the cap rather than blocking the key.</td><td>Disable the key on the <strong>Keys</strong> page.</td></tr><tr><td>AI Architect responses lack system context</td><td>The feature is disabled, scoped to a different alias, or the MCP URL is empty.</td><td>Open the <strong>Features</strong> page and check the alias, MCP URL, and token. An empty MCP URL falls back to a built-in stub.</td></tr><tr><td>Broad questions return incomplete answers</td><td>Governor reached the max hops budget.</td><td>Increase <strong>Max hops</strong>, and check <strong>Max hops per request</strong> if the request makes several AI Architect lookups.</td></tr><tr><td>Repeated <code>429</code> or <code>5xx</code></td><td>One provider account is rate limited or unavailable.</td><td>Add a second target on the same alias to enable failover.</td></tr><tr><td>Requests reach a model you did not configure for that alias</td><td>Auto-routing is on for the alias.</td><td>Open <strong>Routes</strong> and check the tier assignments, or click <strong>Direct</strong> to stop routing that alias.</td></tr><tr><td>A check that compares the requested model to the returned model fails</td><td>The <code>model</code> field in the response names the model that answered on some providers.</td><td>Read the <code>x-bito-routed-model</code> response header instead, which always names the model that answered.</td></tr><tr><td>Auto-routing is on but nothing is routed</td><td>The router is in shadow, or every tier is unusable.</td><td>Check the mode on <strong>Routes</strong>. A tier marked <strong>will not route</strong> has a model with no price, no deployment on the account, or one blocked by your routing direction.</td></tr><tr><td>Every request is classified simple</td><td>The LLM classifier is timing out, so the built-in scorer is deciding instead.</td><td>Raise the classifier <strong>timeout</strong>, or point <strong>classifier model</strong> at a faster route alias.</td></tr></tbody></table>

## What's next

* [Governor overview](/governor/overview)
* [Set up Bito Governor (self-hosted with Docker)](/governor/set-up-bito-governor-self-hosted-with-docker) to run Governor on a single host with Docker
* [Set up Bito Governor (Bito-hosted)](/governor/set-up-bito-governor-bito-hosted)
* Contact <support@bito.ai> for deployment assistance


# Auto AI model routing

Send simple requests to cost-efficient models and complex work to capable ones, using an Auto-router.

Auto-routing sends each request to the model that fits the work. Simple requests go to a cost-efficient, faster model, and complex requests go to a more capable one.

Without it, every request reaches the same model. Renaming a variable costs the same as planning a migration across four services, because both go to whichever model the coding tool asked for.

[Bito Governor](/governor/overview) sorts each request into one of four tiers, Simple, Medium, Complex, and Reasoning, then sends it to the model you assigned to that tier. You write the description that defines each tier, so requests are sorted by your own words rather than by a fixed rule.

Your engineers change nothing. Their tools keep asking for the same model name, and Governor answers from whichever model it selected.

You turn auto-routing on one model name at a time. That name is the alias your coding tools ask for, such as `claude-opus-5` or `claude-*`. Each alias appears as a group on the **Routes** page, with a **Direct** and an **Auto** control. **Direct** answers from the targets you configured. **Auto** hands the alias to the router.

## Before you start

Set prices on the **Prices** page for every model a tier will point at. Routing direction, the price ceiling, and the shadow cost comparison all read from those prices, and a model with no price cannot be selected.

Add a route for the model you want the classifier to run on. The **classifier model** field takes a route alias in this workspace rather than a raw vendor model ID.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fa4dfQ7Rnm4510GOKoixb%2Fscrnli_6M6GwYiZIk1hhH.png?alt=media&amp;token=a93dba23-1739-4a21-8c57-42da5d892472" alt=""><figcaption></figcaption></figure>

## Open the router

In the Bito Governor, open the **Routes** tab.

Either select **auto-route this alias** in the **Add route** form, which adds the route and then opens the router settings, or click **Auto** on an existing group in the routes table.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FHsLxoYRkeotWrQCQxGF9%2Fscrnli_983nTuERo1as7E.png?alt=media&amp;token=c9b08159-cf52-44b3-abd2-024ad508076e" alt=""><figcaption></figcaption></figure>

The router step is optional. Nothing about auto-routing is saved until you click **Save**, and the route itself stays either way. **Skip for now** closes the router and keeps the route.

## Acknowledge the response header

The form opens on a notice you have to accept before it will save.

Clients asking for the alias will receive answers from other models. The `x-bito-routed-model` response header always names the model that answered. Do not read the `model` field inside the response instead, because some providers return the model that was asked for and others return the model that answered. Anything you run that compares the two will see a different name.

Tick **I understand.** to enable **Save**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F2qY8vFHYXkZJY01aDkbp%2Fscrnli_28lO02jhoJU0x9.png?alt=media&amp;token=8edbe0b9-5222-449b-8a58-7df38cac4634" alt=""><figcaption></figcaption></figure>

## Settings

<table data-search="false"><thead><tr><th align="center">Setting</th><th>Description</th></tr></thead><tbody><tr><td align="center">fallback</td><td>Read only. Names the route that answers while the router is <strong>Off</strong> or in <strong>Shadow</strong>, and whenever a tier cannot be used.</td></tr><tr><td align="center">mode</td><td><strong>Off</strong> disables the router. <strong>Shadow</strong> is a dry run that writes down what it would have done while requests still go to the alias's own route, exactly as they do on <strong>Off</strong>. <strong>On</strong> routes traffic. A new router starts in <strong>Shadow</strong>.</td></tr><tr><td align="center">routing direction</td><td><strong>Down only</strong> never sends a request to a model that costs more than the one your agent asked for. It needs a price for both models, and leaves the request alone and records why when either is missing. <strong>Both ways</strong> also allows an upgrade, for example sending a planning request from a small model to a larger one. <strong>Down only</strong> is the default.</td></tr><tr><td align="center">price ceiling</td><td>A cap in dollars per million output tokens. Governor never sends a request to a model above it, whatever the classifier decides. Leave it blank for no ceiling.</td></tr><tr><td align="center">rubric preset</td><td>Fills in the four tier descriptions below, and retunes the built-in scorer under <strong>Advanced</strong> to match that kind of traffic. Pick the one closest to your traffic and edit from there. Once you change the wording, the field reads <strong>User-defined</strong>.</td></tr><tr><td align="center">classifier</td><td><p><strong>LLM</strong> is the default and the most accurate.</p><p></p><p><strong>Heuristic</strong> uses the built-in scorer, which is free and instant, and on coding-tool traffic calls almost everything simple, so it is kept as the backup for when the LLM is too slow to answer.</p><p></p><p><strong>Keywords only</strong> matches on raw keywords.</p><p></p><p>See <a href="#how-requests-are-classified">How requests are classified</a>.</p></td></tr><tr><td align="center">classifier model</td><td>The route alias the classifier runs on. Pick a cheap, fast model, because it runs on every request that no rule has already decided.</td></tr><tr><td align="center">timeout (ms)</td><td>How long the classifier may take before Governor falls back to the built-in scorer. Default <code>2000</code>.</td></tr><tr><td align="center">context turns</td><td>How many recent user prompts the classifier reads, rather than the current one alone. Default <code>3</code>. Reading the last few turns catches a request that continues earlier work, so a short follow-up inside a planning session is still classified as planning.</td></tr></tbody></table>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FEoDBxOKkrYspp0bmYWK2%2Fscrnli_xj87etK7ZJSR7x.png?alt=media&amp;token=f9bbdf96-20a5-49ea-aec2-64f54e79582a" alt=""><figcaption></figcaption></figure>

#### Tier mapping

The four tier descriptions are the rule. They are the text the classifier reads to decide which tier a request belongs in, so write them the way you would explain the distinction to a colleague. A preset seeds them, and you can edit any of them.

Each tier takes:

|             Column             | What to enter                                                                                                                                                                                               |
| :----------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| When should this tier be used? | The description the classifier reads.                                                                                                                                                                       |
|            Routes to           | A route alias in this workspace, named exactly, and the model. Listing a route here does not make it reachable by your apps, and it keeps that route's own account, load balancing, failover, and cooldown. |
|            Thinking            | The reasoning effort for that tier. **as asked** passes through whatever the caller requested.                                                                                                              |

**+ model** gives a tier a second choice. Use it only for models you would be equally happy to receive, because the tier is the whole of what the classifier decided.

**+ new target** adds a provider, account, and model without leaving the router. **Suggest from my routes** proposes tier assignments from the routes you already have.

Governor seeds the preset descriptions from its own model research, which scored around 30 models across roughly 2,000 engineering tasks. The four tiers sort by risk and clarity rather than by how many files a request touches:

|    Tier   | What reaches it                                                                                                                                                                                                                                                            |
| :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   Simple  | A stated change with a clear target: build the described feature, fix the described bug, refactor, rename, add a test. Work spanning many files still counts as simple when the request says what done looks like.                                                         |
|   Medium  | Explaining and checking: how a piece of code works, why a job failed, whether a plan is missing anything, and requests from non-engineers that name what they want.                                                                                                        |
|  Complex  | Judgment and risk: writing an implementation plan, a design, or a migration plan, choosing between approaches, reviewing a diff, deciding whether something is safe to ship, and anything touching production, data, secrets, protected branches, or destructive commands. |
| Reasoning | Requests that do not say what done looks like: a symptom with no named cause, a request that could mean several different jobs, and open architecture questions. Working out what is actually being asked is the first task, so these reach the most capable model.        |

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FCghnhXwaLjMslnGnxByo%2Fscrnli_0Yr7X0BvBjm3hw.png?alt=media&amp;token=57277e89-ab64-4200-9662-b28c17dda26a" alt=""><figcaption></figcaption></figure>

#### How requests are classified

The LLM classifier reads the request and returns a tier. When it cannot answer inside the timeout, the built-in scorer decides instead, so every router has a scorer behind it whether you tune one or not.

The scorer turns each request into a score from signals such as context size, code markers, and reasoning markers, then places it in a tier using three boundaries. Defaults are shown in grey on the form, and leaving a box empty keeps the default.

<table data-search="false"><thead><tr><th align="center">Advanced setting</th><th align="center">Default</th></tr></thead><tbody><tr><td align="center">simple / medium boundary</td><td align="center">0.15</td></tr><tr><td align="center">medium / complex boundary</td><td align="center">0.35</td></tr><tr><td align="center">complex / reasoning boundary</td><td align="center">0.6</td></tr><tr><td align="center">weight: context size</td><td align="center">0.35</td></tr><tr><td align="center">weight: code markers</td><td align="center">0.15</td></tr><tr><td align="center">weight: reasoning markers</td><td align="center">0.15</td></tr><tr><td align="center">weight: technical vocabulary</td><td align="center">0.12</td></tr><tr><td align="center">weight: tool count</td><td align="center">0.05</td></tr><tr><td align="center">weight: declared effort</td><td align="center">0.05</td></tr><tr><td align="center">weight: conversation depth</td><td align="center">0.03</td></tr><tr><td align="center">weight: multi-step phrasing</td><td align="center">0.02</td></tr><tr><td align="center">context ramp starts at (tokens)</td><td align="center">20000</td></tr><tr><td align="center">context ramp saturates at (tokens)</td><td align="center">150000</td></tr><tr><td align="center">tool count saturates at</td><td align="center">8</td></tr><tr><td align="center">turn depth saturates at</td><td align="center">8</td></tr></tbody></table>

The three boundaries have to ascend. If the simple to medium line sat above the medium to complex line, nothing could ever be medium, and Governor refuses to save a set that does not ascend.

Most workspaces never open **Advanced**. Picking the rubric preset closest to your traffic retunes the scorer for you.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F0fPWKX8IFXxP59hPbbGT%2Fscrnli_N17IB6LcNjUrb0.png?alt=media&amp;token=c4ce06f2-963d-4653-bbdc-9219420bdb9f" alt=""><figcaption></figcaption></figure>

## Backing groups

Select **backing group (internal)** on the routes holding the models a router picks between. A backing group is hidden from your apps, so it cannot be requested by name and does not appear in the model list, and only the router can send traffic to it. This stops anyone reaching an internal model directly and bypassing the router.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FmB4k2cqIfP3uy2YRhR4I%2Fscrnli_L6vTok69GcM51g.png?alt=media&amp;token=fc60c3c1-23af-4955-a5f1-079ac18b5385" alt=""><figcaption></figcaption></figure>

## When the router does not route

The alias's own route answers whenever the router is off or in shadow, and whenever a tier cannot be used. A tier is unusable when its model has no price, has no deployment on the account, or would break your routing direction, and the tier shows **will not route** in that case. The routes table also carries a **when not routing** row naming the route that answers.

If the router selects a model that turns out to be unavailable, Governor falls back to the model your tool originally requested, so the request is still answered.

Governor also protects prompt caching. Moving an ongoing conversation to a different model discards its cache and makes the next turn slower and more expensive, so Governor keeps that conversation where it is when staying put costs less. One-off requests carry no cache and are routed freely.

## Test before you turn it on

| Action                | What it does                                                                                                          |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Classify a prompt     | Enter a sample prompt and see which tier it lands in and which model would answer. Nothing is sent.                   |
| Test, on a tier row   | Sends a real request to that tier's model to confirm it works on that account.                                        |
| Review shadow results | Reports what the router would have done across recorded traffic, with an estimated cost comparison. Export it as CSV. |

Leave a new router in **Shadow** across a day of real traffic, then review the results before switching to **On**. Shadow results state plainly when traffic was not moved, so a report never reads as a saving that did not happen.

The routes table reports what the router actually did, splitting recent traffic into requests routed, requests that needed a fallback, requests that failed, and requests deliberately not routed with the reason.

{% hint style="info" %}
A request routed to a model on a different API is marked **converted** in the routes table. Your messages, tools, images, and reasoning effort carry over where the target model supports them. Earlier thinking, attached documents, images returned by tools, and tools the provider runs itself, such as web search, do not carry over.
{% endhint %}

{% hint style="info" %}
Router changes reach live traffic within 30 seconds.
{% endhint %}


# Available commands

Quick reference for every Bito Governor command, for both the Docker and the Kubernetes self-hosted deployments.

This page is a quick reference for the commands that run and operate a self-hosted Bito Governor, whether you run it with Docker on a single machine or with Kubernetes in a cluster.

Each deployment uses a different set of commands, so go to the section that matches yours:

1. [**Commands for self-hosted Bito Governor with Docker**](#commands-for-self-hosted-bito-governor-with-docker), for an install on a single machine, using `bito-gateway-ctl`.
2. [**Commands for self-hosted Bito Governor with Kubernetes**](#commands-for-self-hosted-bito-governor-with-kubernetes), for an install in a cluster, using `helm` and `kubectl`.

{% hint style="info" %}
**Note:** The [Bito-hosted deployment](/governor/set-up-bito-governor-bito-hosted) needs no commands. Bito operates the infrastructure, and you configure everything in the admin UI.
{% endhint %}

Both self-hosted deployments run the same `gwctl` command inside the gateway, so each section repeats it with the prefix that deployment needs.

The examples use `bito-gateway` as the namespace and `gw` as the Helm release name, matching the setup guides. Substitute your own where they differ.

For the full setup procedures, see [Set up Bito Governor (self-hosted with Docker)](/governor/set-up-bito-governor-self-hosted-with-docker) and [Set up Bito Governor (self-hosted with Kubernetes)](/governor/set-up-bito-governor-self-hosted-with-kubernetes).

***

## Commands for self-hosted Bito Governor with Docker

#### Install

| Command                                                                     | What it does                                 |
| --------------------------------------------------------------------------- | -------------------------------------------- |
| `curl -fsSL https://gwinstall.bito.ai/latest/install-standalone.sh \| bash` | Installs Governor on Linux or macOS.         |
| `irm https://gwinstall.bito.ai/latest/install-standalone.ps1 \| iex`        | Installs Governor on Windows, in PowerShell. |

Everything installs under `~/.bito-gateway`, or `%USERPROFILE%\.bito-gateway` on Windows. Set `BITO_GW_HOME` to install elsewhere, and `PORT` to serve on a port other than 8788.

#### Manage the service

`bito-gateway-ctl` is installed on your PATH, including on Windows through a `.cmd` shim, and runs from any directory.

<table data-search="false"><thead><tr><th>Command</th><th>What it does</th></tr></thead><tbody><tr><td><code>bito-gateway-ctl status</code></td><td>Reports whether Governor is running.</td></tr><tr><td><code>bito-gateway-ctl health</code></td><td>Runs the <code>/healthz</code> check and a deep self-check.</td></tr><tr><td><code>bito-gateway-ctl logs</code></td><td>Follows the gateway logs. Press Ctrl+C to stop.</td></tr><tr><td><code>bito-gateway-ctl start</code></td><td>Starts Governor, and applies any changes to the <code>.env</code> file.</td></tr><tr><td><code>bito-gateway-ctl stop</code></td><td>Stops Governor and keeps your data.</td></tr><tr><td><code>bito-gateway-ctl restart</code></td><td>Restarts Governor.</td></tr><tr><td><code>bito-gateway-ctl update</code></td><td>Pulls a newer image and restarts.</td></tr></tbody></table>

#### Configure from the command line

`gwctl` lives inside the gateway container, and `bito-gateway-ctl` forwards to it.

| Command                                 | What it does                                                                                                          |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `bito-gateway-ctl gwctl quickstart`     | Walks through creating a workspace, key, provider account, and route.                                                 |
| `bito-gateway-ctl gwctl connect <tool>` | Prints the setup for a coding tool. Accepts `claude`, `cursor`, `codex`, `copilot`, `cline`, `continue`, and `aider`. |
| `bito-gateway-ctl gwctl doctor`         | Validates the database, schema, and key encryption key.                                                               |
| `bito-gateway-ctl gwctl <command> -h`   | Shows help for any command.                                                                                           |

#### Manage admins

| Command                                                                 | What it does                                              |
| ----------------------------------------------------------------------- | --------------------------------------------------------- |
| `bito-gateway-ctl gwctl admin create --role global`                     | Creates an admin with full access. Prints the token once. |
| `bito-gateway-ctl gwctl admin create --role workspace --workspace <id>` | Creates an admin scoped to one workspace.                 |
| `bito-gateway-ctl gwctl admin list`                                     | Lists existing admins.                                    |
| `bito-gateway-ctl gwctl admin revoke <id>`                              | Revokes an admin.                                         |

#### Back up

| Command                               | What it does                                                                            |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `mysqldump bito_gateway > backup.sql` | Backs up every workspace, key, account, route, and your encrypted provider credentials. |

Back up `CRYPTO_ENV_KEK_KEY` from `~/.bito-gateway/.env` alongside the dump. Without it, the credentials in the dump cannot be decrypted.

#### Uninstall

| Command                              | What it does                                                                       |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| `bito-gateway-ctl uninstall`         | Removes the containers and keeps your database volume and secrets.                 |
| `bito-gateway-ctl uninstall --purge` | Also deletes the database volume and the key encryption key. This is irreversible. |

#### Native systemd installs

On a native systemd install rather than Docker, manage the service directly. `gwctl` is on your PATH, so call it without the wrapper.

| Command                             | What it does                                                   |
| ----------------------------------- | -------------------------------------------------------------- |
| `sudo systemctl start bito-gateway` | Starts Governor. Also accepts `stop`, `restart`, and `status`. |
| `journalctl -u bito-gateway -f`     | Follows the logs.                                              |

***

## Commands for self-hosted Bito Governor with Kubernetes

#### Check your cluster first

| Command                          | What it does                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------ |
| `kubectl config current-context` | Shows which cluster your commands will apply to. Check this before installing. |
| `kubectl config get-contexts`    | Lists every cluster you can reach.                                             |

#### Install

```bash
kubectl create namespace bito-gateway
```

```bash
kubectl create secret generic bito-gateway-secrets \
  --namespace bito-gateway \
  --from-literal=DB_PASSWORD="$(openssl rand -base64 24 | tr -d '/+=')" \
  --from-literal=CRYPTO_ENV_KEK_KEY="$(openssl rand -base64 32)" \
  --from-literal=MYSQL_ROOT_PASSWORD="$(openssl rand -base64 24 | tr -d '/+=')" \
  --from-literal=ADMIN_TOKEN="$(openssl rand -base64 32 | tr -d '/+=')"
```

```bash
helm install gw oci://registry-1.docker.io/bitoai/bito-gateway-helm \
  --namespace bito-gateway \
  --set secrets.existingSecret=bito-gateway-secrets
```

| Command                                                                                                          | What it does                                                         |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `helm install gw oci://registry-1.docker.io/bitoai/bito-gateway-helm --namespace bito-gateway -f my-values.yaml` | Installs with your own values file.                                  |
| `helm show chart oci://registry-1.docker.io/bitoai/bito-gateway-helm`                                            | Shows what a chart version contains, without installing it.          |
| `helm pull oci://registry-1.docker.io/bitoai/bito-gateway-helm --untar`                                          | Downloads and unpacks the chart, including the example values files. |
| `ls bito-gateway-helm/values-*.yaml`                                                                             | Lists the example values files after unpacking.                      |

Add `--version X.Y.Z` to any of these to pin a chart version.

#### Check the deployment

| Command                                                                      | What it does                                                                   |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `kubectl -n bito-gateway rollout status deploy/gw-bito-gateway --timeout=5m` | Waits for the gateway to finish rolling out.                                   |
| `kubectl -n bito-gateway get pods`                                           | Lists every pod and its status.                                                |
| `kubectl -n bito-gateway get svc`                                            | Lists the services and their cluster IPs.                                      |
| `kubectl -n bito-gateway logs deploy/gw-bito-gateway`                        | Shows the gateway logs.                                                        |
| `kubectl -n bito-gateway logs deploy/gw-bito-gateway-mysql`                  | Shows the database logs.                                                       |
| `helm list -n bito-gateway`                                                  | Lists the Helm releases in the namespace, with their status and chart version. |

#### Reach the gateway

| Command                                                                                                  | What it does                                                                                        |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `kubectl -n bito-gateway port-forward svc/gw-bito-gateway 8788:8788`                                     | Makes Governor available on your own machine at `http://localhost:8788`, while the command runs.    |
| `kubectl -n bito-gateway get secret bito-gateway-secrets -o jsonpath='{.data.ADMIN_TOKEN}' \| base64 -d` | Prints your admin token. Kubernetes stores Secret values base64 encoded, so `base64 -d` decodes it. |

#### Configure from the command line

`gwctl` ships inside the gateway image and reads the database settings the pod already has. Substitute the workspace ID that `workspace create` prints.

| Command                                                                                                                                    | What it does                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl workspace create --name demo`                                                | Creates a workspace and prints its ID.                  |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl key create --workspace <ID> --name demo`                                     | Creates a gateway key. Prints the `gw_sk_` key once.    |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl account add --workspace <ID> --provider anthropic --key <YOUR PROVIDER KEY>` | Adds a provider account.                                |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl route add --workspace <ID> --alias '*' --provider anthropic`                 | Adds a route.                                           |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl connect <tool>`                                                              | Prints the setup for a coding tool.                     |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl doctor`                                                                      | Validates the database, schema, and key encryption key. |

#### Manage admins

| Command                                                                                                       | What it does                                              |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin create --role global`                     | Creates an admin with full access. Prints the token once. |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin create --role workspace --workspace <id>` | Creates an admin scoped to one workspace.                 |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin list`                                     | Lists existing admins.                                    |
| `kubectl -n bito-gateway exec deploy/gw-bito-gateway -- gwctl admin revoke <id>`                              | Revokes an admin.                                         |

#### Upgrade and roll back

```bash
helm upgrade gw oci://registry-1.docker.io/bitoai/bito-gateway-helm \
  --namespace bito-gateway -f my-values.yaml --timeout 1800s
```

| Command                                                          | What it does                                                                                                   |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `kubectl -n bito-gateway rollout restart deploy/gw-bito-gateway` | Rolls the pods. Run this after rotating a value in a Secret you own, because the chart cannot see that change. |
| `helm rollback gw <revision> -n bito-gateway`                    | Returns the pods to a previous revision. The database keeps the newer schema.                                  |
| `helm history gw -n bito-gateway`                                | Lists the revisions you can roll back to.                                                                      |

{% hint style="info" %}
Pass no new secret values on upgrade. Both `DB_PASSWORD` and `CRYPTO_ENV_KEK_KEY` are fixed after the first install.
{% endhint %}

#### Uninstall

| Command                                                                                                         | What it does                                                                                  |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `helm uninstall gw -n bito-gateway`                                                                             | Removes the release and keeps your data. The PersistentVolumeClaims are annotated to be kept. |
| `kubectl -n bito-gateway delete pvc gw-bito-gateway-mysql`                                                      | Deletes the database volume. This is irreversible.                                            |
| `kubectl -n bito-gateway delete pvc gw-bito-gateway-redis`                                                      | Deletes the counter store volume.                                                             |
| `kubectl -n bito-gateway delete job,configmap,serviceaccount,secret gw-bito-gateway-migrate --ignore-not-found` | Removes the migration objects, which Helm leaves behind.                                      |

***

## What's next

* [Governor overview](/governor/overview)
* [Set up Bito Governor (Bito-hosted)](/governor/set-up-bito-governor-bito-hosted)
* [Set up Bito Governor (self-hosted with Docker)](/governor/set-up-bito-governor-self-hosted-with-docker)
* [Set up Bito Governor (self-hosted with Kubernetes)](/governor/set-up-bito-governor-self-hosted-with-kubernetes)
* Contact <support@bito.ai> for deployment assistance


# Overview

The context layer for your entire software development lifecycle, from planning in Jira to generating code in your IDE to codebase-aware reviews in Git.

Bito's **AI Architect** builds a knowledge graph of your codebase (from repos to modules to APIs) and operational history (context from issue trackers such as Jira). This gives your team a shared, always-current understanding of the system, and makes that understanding available wherever engineering decisions are made:

* [**In issue trackers (Jira)**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira) for feasibility analysis, technical design, and cross-repo impact assessment.
* [**In coding agents**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) (Claude Code, Cursor, Windsurf, GitHub Copilot, and more) for grounded code generation, accelerated onboarding, and production issue triage.
* [**In pull requests**](/ai-code-reviews-in-git/overview) (GitHub, GitLab, Bitbucket) for codebase-aware AI code reviews

This fundamentally changes the game for enterprises with many microservices or large, complex codebases.

{% hint style="info" %}
Bito provides the AI Architect in a completely secure fashion, with the AI Architect available on-prem if you desire with no code ever being sent to Bito. No AI is trained on your code and your code is not stored.
{% endhint %}

{% embed url="<https://youtu.be/qAMtZ41-xJY>" %}

## Key capabilities of the AI Architect include:

* **Technical design and planning** — AI Architect analyzes your Jira tickets and posts a complete implementation plan directly in comments section: feasibility assessment, story breakdown, effort estimates, risk flags, and dependency mapping.
  * [**Watch demo video**](https://www.youtube.com/watch?v=FLik7gCd2iI)
* **Grounded 1-shot production-ready code** — The AI Architect learns all your services, endpoints, code usage examples, and architectural patterns. The agent automatically feeds those to your coding agent (Claude Code, Cursor, Codex, any MCP client) to provide it the necessary information to quickly and efficiently create production ready code.
  * [**Watch demo video**](https://www.youtube.com/watch?v=2yx_FfDsYco)
* **Consistent design adherence** — Code generated aligns with your architecture patterns and coding conventions.
* **Spec-driven development** — Automatically generate highly detailed, implementation-ready technical requirement documents (TRDs) and low-level designs (LLDs) with a deep, context-aware understanding of your codebase, services, and design patterns, ensuring architectural integrity and consistency at a granular level.
  * [**Watch demo video**](https://www.youtube.com/watch?v=xMmZbbZUcq0)
* **Triaging production issues** — Easily and quickly find root causes to production issues based on errors/logs/etc.
  * [**Watch demo video**](https://www.youtube.com/watch?v=05-2hKcaZKk)
* **Faster onboarding** — New engineers or AI agents can quickly understand how a system or component system structure.
* **Enhanced documentation and diagramming** — Through its internal understanding of interconnections between modules and APIs.
* **Smarter code reviews** — Reviews with system-wide awareness of dependencies and impacts.

The AI Architect builds the knowledge graph by analyzing all your repositories (whether you have 50 or 5,000 repos) to learn about your codebase architecture, microservices, modules, API endpoints, design patterns, and more.

## How you can use AI Architect

AI Architect is designed to be flexible and can power multiple use cases across different AI coding tools and workflows.

{% stepper %}
{% step %}

### Installation

* [Bito-hosted](/ai-architect/installation/install-ai-architect-bito-hosted) (Fully managed by Bito — no infrastructure setup required)
* [Self-hosted](/ai-architect/installation/install-ai-architect-self-hosted) (Run AI Architect on your own infrastructure for maximum control)
  {% endstep %}

{% step %}

### Integrate with your tools

* [Jira](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira)
* [Coding agents via MCP](/ai-architect/quick-mcp-integration-with-ai-coding-agents)
* [AI Code Review Agent](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-bitos-ai-code-review-agent)
  {% endstep %}
  {% endstepper %}

## Why use the AI Architect?

Most AI coding tools struggle with accuracy in real-world codebases because they

1. Don’t fully understand the breadth and depth of your codebase. They read some of the code in your existing repository, but they don’t have a complete graph of your internal APIs, endpoints, libraries, etc. On top of that, if you are accessing a monorepo or many services not available on your machine locally, they have no context or get confused trying to access them. Bito’s AI Architect has built a knowledge graph to provide this information in a cheap and efficient way to your coding agent so it can accomplish the task with grounded and complete information.
2. They don’t fully understand how all of your services and modules interact with each other when you are trying to understand your overall system versus just one component. The AI Architect’s graph contains a mapping of all the dependencies, allowing to provide sophisticated analysis – how you would expect an Architect too.

## How AI Architect differs from Embeddings?

Traditional embeddings work like a search engine — they retrieve code snippets or documents similar to a given query.&#x20;

They can find related content but can’t understand how different parts of your system work together.&#x20;

The AI Architect, on the other hand:&#x20;

* Builds a knowledge graph that captures relationships between repositories, modules, APIs, and libraries.
* Provides precise answers and implementations, not just search results.
* Understands context and intent — how and why something is implemented in your codebase.
* Enables system-aware reasoning, allowing AI agents to generate or review code with full architectural understanding.

## Getting started

1. [**Try Bito's AI Architect**](https://alpha.bito.ai/home/welcome/ai-architect)
2. [**Get a demo**](https://calendly.com/d/csk7-8yg-pwf) with our team.
3. Lastly, email [**support@bito.ai**](mailto:support@bito.ai) if you have any additional questions.

## Demos of different ways to use AI Architect

{% embed url="<https://www.youtube.com/watch?v=2yx_FfDsYco>" %}

{% embed url="<https://www.youtube.com/watch?v=xMmZbbZUcq0>" %}

{% embed url="<https://www.youtube.com/watch?v=05-2hKcaZKk>" %}


# Key features

AI Architect is a full engineering workflow platform built around a knowledge graph of your codebase, business context, tribal knowledge, docs, tickets, and observability data. It operates across three solution areas — **technical design & scoping**, **grounded coding**, and **code review** — surfacing system-level intelligence at every stage of development.

This page covers the core features that power those workflows.

## Knowledge graph

The knowledge graph is the context engine at the core of AI Architect. It ingests your codebase, Git history, issue tracker data (Jira, Linear), documentation (Confluence), observability signals, and Slack conversations into a unified, continuously updated graph.

Rather than treating your codebase as searchable text, the knowledge graph models the relationships between services, APIs, dependencies, past decisions, and recurring incident patterns — capturing how your system actually fits together.

This shared context powers every capability in AI Architect. When an agent runs a feasibility analysis, generates a technical design, or reviews a pull request, it draws from the same knowledge graph — so output is grounded in your real architecture, not generic patterns.

The knowledge graph also enables cross-repo reasoning: it understands blast radius, tracks instability histories, and connects a Jira incident from six months ago to the service a developer is about to change today.

<a href="/ai-architect/knowledge-graph" class="button primary">Learn more</a>

## Supported integrations

AI Architect connects to the tools your team already uses across planning, coding, review, and communication.

* [**Jira**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira) is the primary surface for technical design and scoping. AI Architect listens for new or updated Epics and Stories, posts implementation plans as ticket comments, and can be triggered on demand via `@bito` in any comment. Plans include feasibility assessments, story breakdowns, effort estimates, and risk flags — all grounded in your knowledge graph.
* [**Slack**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack) brings AI Architect into team discussions. Mention `@Bito` in any channel thread and the assistant reads the full conversation context, resolves referenced Jira tickets and Confluence pages, and responds with context-aware answers, task breakdowns, or implementation plans — directly in the thread.
* [**Coding agents**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) connect to AI Architect via MCP (Model Context Protocol). A one-command installer automatically configures all supported tools detected on your system. Supported agents include Claude Code, Cursor, Windsurf, GitHub Copilot (VS Code), Junie, and JetBrains AI Assistant. Once connected, Agent Skills are available inside each tool, giving developers access to the full knowledge graph while they build.
* [**Chat agents**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents) — including Claude.ai (Web & Desktop) and ChatGPT (Web & Desktop) — can also be connected to AI Architect via MCP for codebase-aware conversational assistance outside of a dedicated coding environment.
* [**Bito's AI Code Review Agent**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-bitos-ai-code-review-agent) integrates with AI Architect to bring knowledge graph context into every pull request review across GitHub, GitLab, and Bitbucket. Reviews go beyond the diff — they include cross-repo impact analysis, architectural consistency checks, and blast radius detection, catching issues before they reach production.

## Auto triage

When auto-analysis is enabled for Jira, AI Architect evaluates every new or updated Epic and Story before generating an implementation plan. It reads the full ticket — title, description, comments, attachments, and any linked Confluence pages — and assigns a complexity score from 1 to 10. Implementation plans are only generated for tickets that meet or exceed the complexity threshold (default: 7). Tickets below the threshold receive a short note explaining why a plan was skipped, along with a prompt to request one manually if needed.

This keeps your ticket history clean and ensures that AI Architect's output is directed at the work that actually benefits from it — complex, ambiguous, or cross-cutting changes — rather than straightforward tasks that engineers can act on immediately.

<a href="/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira#auto-triage" class="button primary">Learn more</a>

## Flexible trigger

AI Architect can be invoked in two ways: automatically when a ticket is created or updated, or on demand by any team member. On-demand triggering is done by commenting `@bito`, `/bito`, or `#bito` directly on the Jira ticket, or by adding a `bito`, `bito-analyse`, or `bito-analyze` label.

The same comment syntax also works for follow-up requests — you can ask AI Architect to revise its analysis, focus on a specific aspect, or regenerate the plan after requirements change.

This gives teams full control over when AI Architect runs. You can start with on-demand mode to evaluate output quality on specific tickets, then graduate to automatic analysis once you're confident in the results.

<a href="/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira#how-to-trigger-ai-architect-in-jira" class="button primary">Learn more</a>

## Iterative refinement

Requirements rarely stay fixed. AI Architect supports iterative refinement by generating new versions of any artifact — technical designs, scope breakdowns, feasibility assessments — as the ticket evolves. As engineers update descriptions, add comments, or link new context, they can re-trigger AI Architect to produce a revised plan that reflects the current state of the work.

This means technical planning stays in sync with changing requirements without manual rework. Each iteration builds on the ticket's full history, so AI Architect understands what has changed and why.

<a href="/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira#how-to-trigger-ai-architect-in-jira" class="button primary">Learn more</a>

## Custom templates

By default, AI Architect formats its output using Bito's standard structure. Custom templates let you override that with your team's own format — whether that's a specific TDD layout, an internal RFC structure, or a planning format tied to your sprint process. Output then matches what your engineers expect to see and what your workflow tooling can consume.

Custom templates are configured per workspace. To get started, contact the Bito team at <support@bito.ai>.

## Custom prompts

AI Architect supports free-form prompting directly inside the Jira ticket, coding agents, or Slack. Engineers can mention Bito followed by a question/instruction in natural-language, such as:

#### In Jira:

* `@bito analyze technical feasibility`
* `@bito focus on database migration risk`
* `@bito write this as a spike document`
* `@bito break this into frontend and backend workstreams`

#### In Slack:

* `@Bito PROJ-456 is causing errors in production — here are the logs. Identify the root cause?`
* `@Bito help us break this feature into smaller tasks`
* `@Bito explain the difference between these two approaches`
* `@Bito what are the action items from this thread?`
* `@Bito review the code changes in this thread and suggest improvements`&#x20;

#### In coding agents:

Open a chat or conversation in your AI tool and try a test query to confirm AI Architect is working:

* `"What repositories are available in my organization?"`
* `"Show me all Python repositories"`
* `"List the available tools"`
* `"What are the dependencies of [repo-name]?"`
* `"Find all microservices using Redis"`
* `"Show me repository clusters in our organization"`
* `"Plan a new feature for [component]"`
  * *(uses **bito-feature-plan** skill)*
* `"Write a PRD for [feature]"`
  * *(uses **bito-prd** skill)*
* `"Help me triage this production issue"`
  * *(uses **bito-production-triage** skill)*

Custom prompts work alongside the knowledge graph context AI Architect already has. You're directing the output, not replacing the grounding.

## Web research

AI Architect can pull external technical context alongside your internal knowledge graph when generating plans. When web research is enabled, it incorporates relevant industry patterns, library documentation, and external best practices into its analysis — useful for greenfield work, third-party integrations, or areas where your codebase doesn't yet have established patterns.

Web research is applied selectively. It supplements internal context rather than replacing it, so the output remains grounded in your actual system.

## Slack agent

The Bito AI Assistant brings AI Architect directly into Slack. You can ask system-level questions, trigger implementation plans, iterate on technical designs, and triage production issues — all without leaving the channel where the discussion is already happening. Mention `@Bito` in any thread, and the assistant reads the full conversation context, including any referenced Jira tickets or Confluence pages, before responding.

Common use cases include summarizing long planning threads, generating task breakdowns from a discussion, and pulling context from a specific ticket mid-conversation. The Slack agent is available in both public and private channels and supports file attachments including code files, configs, and logs.

<a href="/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack" class="button primary">Learn more</a>

## Agent skills

Agent Skills are structured instruction files that define how AI Architect approaches specific engineering tasks. Each skill is purpose-built for a different type of work: feasibility analysis, epic planning, spike investigations, production triage, PRD or TRD generation, pre-commit reviews, and more. Skills can be triggered in Jira and Slack by commenting with natural language (`@bito is this feasible?`, `@bito turn this epic into tasks`), or invoked directly inside your coding agent via MCP.

Skills have full access to your knowledge graph — codebase, Jira history, Confluence docs, and observability data — so their output is always grounded in how your system actually works, not a generic template. In coding agents, skills are installed automatically and discoverable via `/` in the chat interface.

<a href="/ai-architect/agent-skills" class="button primary">Learn more</a>

## Detailed agent specs

After a technical plan is approved, AI Architect can transform it into self-contained workstream agent specs — structured documents that give a coding agent everything it needs to implement a single workstream without further clarification. Each spec includes file paths, relevant patterns from your codebase, verification gates, and a dependency contract describing what other workstreams it relies on or produces.

Agent specs are designed to be passed directly into Cursor, Claude Code, Codex, or any MCP-compatible coding agent. They eliminate the back-and-forth between planning and implementation by encoding architectural decisions into the spec itself.

<a href="/ai-architect/agent-skills" class="button primary">Learn more</a>

## Automated implementation

Once a workstream plan is approved, AI Architect can execute it directly. It creates a new branch from your default branch, implements the code changes across the relevant repositories, and follows the patterns and conventions already present in your codebase. Implementation is guided by the agent spec, with verification gates checked at each step.

This capability is available via the `bito-agent-spec-executor` skill in your connected coding agent. It is designed for well-scoped workstreams with clear acceptance criteria and works best when paired with the detailed agent spec output.

<a href="/ai-architect/agent-skills" class="button primary">Learn more</a>

## Automated pull request creation

After implementation is complete, AI Architect opens a pull request per workstream, linked back to the originating Jira ticket. PRs include a summary of the changes made, the workstream spec they were generated from, and any verification results from the implementation run. This closes the loop between planning and review, giving engineers and reviewers immediate context on what was built and why.

Automated PRs work across GitHub, GitLab, and Bitbucket. They follow your existing branch naming and PR conventions.

<a href="/ai-architect/agent-skills" class="button primary">Learn more</a>

## Single Sign-On (SSO)

SSO integration lets your team authenticate with AI Architect through your organization's existing identity provider instead of managing shared access tokens. When someone joins or leaves, access is granted or revoked through the same system that controls their email, Slack, and other business tools — no separate credential rotation required.

AI Architect's SSO implementation supports a broad range of identity providers including Google Workspace, Okta, Azure Entra ID, Microsoft AD FS, Auth0, Keycloak, and others, as well as any custom SAML 2.0 or OIDC configuration.

For self-hosted deployments, SSO runs entirely on-premises — no authentication traffic leaves your environment except for identity provider federation (if Enterprise IdP is configured) and Bito API calls for SSO configurations.

Session duration, refresh token TTL, and concurrent session limits are all configurable per workspace.

<a href="/ai-architect/single-sign-on-sso-integration" class="button primary">Learn more</a><a href="/ai-architect/installation/install-ai-architect-self-hosted#sso-authentication" class="button primary">SSO for self-hosted deployments</a>


# Installation


# Install AI Architect (Bito-hosted)

Deploy AI Architect on Bito's managed infrastructure for instant setup and effortless maintenance.

Bito-hosted [**AI Architect**](/ai-architect/overview) runs on managed infrastructure and unifies your codebase, tickets, design docs, and team conversations into a single [knowledge graph](/ai-architect/knowledge-graph).

Your coding agents, issue trackers, and chat tools query that graph so planning, design, coding, review, and incident discussions all share the same system context.

Follow this guide to connect a Git provider, pick repositories for indexing, and wire AI Architect into Claude Code, Cursor, Jira, Linear, Slack, Confluence, and the other tools your team already uses.

## Prerequisites

Bito-hosted AI Architect is currently invitation-only. You can [**start a 14-day free trial**](https://alpha.bito.ai/home/welcome) to get instant access, no credit card required. If you're on a free or paid plan and would like access for your workspace, please contact [**support@bito.ai**](mailto:support@bito.ai).

## Installation steps

{% stepper %}
{% step %}

### Connect your Git provider

1. [Sign up for Bito Cloud](https://alpha.bito.ai/home/welcome) and create a workspace to get started.
2. You'll land on the Git integration screen, where you can connect your Git provider.
3. Choose between **SaaS** (your Git provider's cloud-hosted version) or **Self-managed** (an instance running behind your network), then select your Git provider: **GitHub**, **GitLab**, **Bitbucket**, or **Azure DevOps**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FVINeW4SSluuGhWfuu4Gg%2Fscrnli_29h9t2u3D371G4.png?alt=media&amp;token=1ebbd01c-4d85-408e-bda1-4e29508231e0" alt=""><figcaption></figcaption></figure>

4. Follow the on-screen instructions to authorize Bito on your Git organization. Grant access to all repositories or a subset.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIWTGWq3tTsQVJoDN1Gyu%2Fscrnli_k9e5LtSea6eeE1.png?alt=media&amp;token=4c3a86a0-139a-4ee1-ae4c-d91daebd0ffa" alt=""><figcaption></figcaption></figure>

4. Once your Git account is successfully connected, you'll be redirected back to Bito, where two product paths show up:

   * **AI Architect** — the system context layer for coding agents, Jira, Linear, Slack, and more.
   * **Code Review Agent** — for pull request reviews

   They share the same knowledge graph.
5. Click **Set up AI Architect** and it'll take you to the AI Architect setup page.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FHoddQIiccgI8W1DiYvfz%2Fscrnli_S470B11AT3qE7Y.png?alt=media&amp;token=a8488df7-9bcb-4efd-a26b-142986e8de01" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FwvNDg5mL3zR0OE3lNcyg%2Fscrnli_dZMBL1re94l7T4.png?alt=media&amp;token=643075f6-0180-4ab9-ada4-93dbc3a26cf9" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Set up AI Architect

1. **IMPORTANT:** Before you set up AI Architect, start your 14-day free trial by clicking **Start 14-Day Free Trial** in the left sidebar. No credit card required.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZqJW4PNmQ1AXUiKRgRJe%2Fscrnli_Mxt9yVzP84vJMh.png?alt=media&amp;token=0b34fa18-3746-45d5-969f-f470366ebba5" alt=""><figcaption></figcaption></figure>

2. Then click **Set up AI Architect** on the page.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FgeaUZFPYJyLR4Ov4W6m0%2Fscrnli_OP5e5D8aI4XG6I.png?alt=media&amp;token=32a43b02-2e9a-4b63-98c4-7e1011b210ff" alt=""><figcaption></figcaption></figure>

3. The repository selection screen loads. Select the repositories you want indexed and click **Index selected repositories**. Bito's indexing pipeline scans each repository and builds the underlying knowledge graph.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIKiXjgAGyiQyvA8sxaAu%2Fscrnli_bGN9RxZb951f76.png?alt=media&amp;token=f1cd240e-9420-4857-a408-4847e816359f" alt=""><figcaption></figcaption></figure>

3. You'll land on the [AI Architect repositories](https://alpha.bito.ai/home/ai-architect/repositories) screen, where you can track indexing progress. Each repository's **Index status** column updates to **Indexed** once it's ready.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FaPgUv4HEocYxnTfBU3Sw%2Fscrnli_QJgEe0Riw70Rez.png?alt=media&amp;token=dba4b4eb-f05f-4b86-8666-4c4f76291045" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FnHaUMN39Im2aOAeBxTMF%2Fscrnli_JKG2PoyjK7o3CG.png?alt=media&amp;token=88271e2e-90f4-4d29-934d-b5191bffce7f" alt=""><figcaption></figcaption></figure>

4. You can use the toggle next to each repository to enable or disable indexing. To update multiple repositories at once, select them using the checkboxes and use the bulk enable or disable action. Changes take effect during the next scheduled indexing run.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FGeVH1HcKKBOVYigtCLLN%2Fscrnli_Ey0rZ1sA77OdIy.png?alt=media&amp;token=6f6dffe6-f33f-46bf-9d05-fd735fb2a7a4" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Connect AI Architect with your tools

Once your repositories are indexed, you can connect AI Architect to the tools your engineering team already works in, so the same knowledge graph informs coding, planning, design, review, and incident discussions.

Each integration is configured from the [Home screen](https://alpha.bito.ai/home).

#### Coding agents

Connect AI Architect to Cursor, Claude Code, Windsurf, GitHub Copilot, and other coding agents over MCP. Bito provides a quick installer that sets up the connection in a few steps. Once connected, your coding agent grounds its responses in system context from the knowledge graph and produces more accurate results on changes that span multiple files, services, or repositories.

See the [Quick MCP integration guide](/ai-architect/quick-mcp-integration-with-ai-coding-agents).

#### Jira and Linear

Tag Bito on a ticket to get feasibility analysis, impact assessment, technical design, or an epic breakdown that reflects the services and repos the change touches, not just the ticket description.

See the setup guides for [Jira](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira) and [Linear](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-linear).

#### Slack

Capture tribal knowledge from incident discussions, architecture debates, and undocumented context. Tag Bito inside a channel to query the knowledge graph directly from team conversations.

See the [Slack integration guide](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack).

#### Confluence

Index design documents, architecture decisions, and wiki pages into the knowledge graph so AI Architect reasons about new work with the business intent and prior decisions already captured by your team.

See the [Confluence integration guide](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-confluence).

#### Chat agents

Bring AI Architect into Claude.ai, Claude Desktop, and ChatGPT so your engineering system context follows you into general-purpose chat.

See the [chat agents integration guide](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents).
{% endstep %}
{% endstepper %}

## Code retrieval at runtime

Bito-hosted AI Architect includes smart code retrieval ([getCode MCP tool](/ai-architect/integrating-ai-architect-with-your-tools/available-mcp-tools)) that works behind the scenes. When you ask questions about specific code — like "show me the authenticate method in the Auth class" — AI Architect automatically fetches the relevant code at runtime using your Git credentials.

This means you get detailed, accurate code references without storing any code on Bito's servers. Code is fetched on-demand and never persisted.

## Bito-hosted vs. Self-hosted AI Architect

Bito offers two deployment options for AI Architect:

1. **Bito-hosted** (Fully managed by Bito — no infrastructure setup required)
2. **Self-hosted** (Run AI Architect on your own infrastructure for maximum control)

|                    | Bito-hosted                                                                                                           | Self-hosted                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| **Infrastructure** | Bito manages indexes and infrastructure on our secure servers                                                         | You host AI Architect in your own environment |
| **Code storage**   | We don't store your code after indexing — only repository metadata is retained. Code is fetched at runtime as needed. | Full control over your data and indexes       |
| **Maintenance**    | Fully managed by Bito                                                                                                 | Requires infrastructure setup and maintenance |

For information on self-hosted deployment, visit the [self-hosted installation guide](/ai-architect/installation/install-ai-architect-self-hosted).

## Need help?

If you have questions about the setup process or need to modify your indexed repositories, reach out to the Bito team at [**support@bito.ai**](mailto:support@bito.ai). We're here to help you get the most out of AI Architect.


# 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**](/ai-architect/overview) 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.

{% hint style="info" %}
**Note:** All deployment options are self-hosted on your infrastructure — your code and knowledge graph remain under your control.
{% endhint %}

## Prerequisites

### a. Required accounts and tokens

{% stepper %}
{% step %}

### 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**](https://alpha.bito.ai/), and create an access key from [**Settings -> Advanced Settings**](https://alpha.bito.ai/home/advanced)

* [**View Guide**](/help/account-and-settings/access-key)
  {% endstep %}

{% step %}

### Git provider

We support the following Git providers:

* GitHub
* GitLab
* Bitbucket
* Azure DevOps
* [Local Git Provider (Pre-Cloned Repositories)](/ai-architect/installation/install-ai-architect-self-hosted/local-git-provider-pre-cloned-repositories-setup-guide)

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

{% step %}

### 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:** To connect your GitHub repositories to AI Architect, choose one of the following authentication methods:
   1. **GitHub App:** Install and authorize the Bito GitHub App, then select the repositories you want AI Architect to index.
      * [**View setup guide**](/ai-architect/installation/install-ai-architect-self-hosted/connect-bito-ai-architect-to-github-create-a-github-app)
   2. **Personal Access Token (Classic):** Create a classic personal access token with repo access and provide it during setup. Fine-grained personal access tokens are not currently supported.
      * [**View setup guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
2. **GitLab Personal Access Token:** To use GitLab repositories with AI Architect, a token with API access is required.
   * [**View setup guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)
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**.
      * [**View setup guide**](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)
   2. **Bitbucket Self-Hosted (`HTTP Access Token`):** You must provide both your **token** and **username**.
      * [**View setup guide**](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html)
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 setup guide**](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops\&tabs=Windows)
      {% endstep %}

{% step %}

### 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)

{% hint style="info" %}
**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)**](#copilot-bridge-vs-code) below.
{% endhint %}

{% hint style="info" %}
AI Architect supports [**Portkey**](https://portkey.ai) integration for custom proxy configurations.
{% endhint %}

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**](https://bito.ai/pricing/), 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.

{% hint style="info" %}
To use Bito-hosted LLM instead (no LLM keys required from you), contact [**support@bito.ai**](mailto:support@bito.ai) about the [Bito Enterprise Plan](https://bito.ai/pricing/).
{% endhint %}

#### How to test against the GitHub Copilot Bridge (VS Code) <a href="#copilot-bridge-vs-code" id="copilot-bridge-vs-code"></a>

**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](https://github.com/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:**

```
curl http://127.0.0.1:8000/health
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/v1/models
```

Note an exact model id from `/v1/models` (e.g. `claude-sonnet-4.6`, `gpt-5.4`).
{% endstep %}
{% endstepper %}

### 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

{% stepper %}
{% step %}

### 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+ |

{% hint style="info" %}
**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.
  {% endhint %}

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:

```shellscript
grep -E '_(MEMORY|CPU)_LIMIT=' .env-bitoarch
```

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

```shellscript
bitoarch restart --force
```

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

{% step %}

### **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:

```shellscript
wsl --install
```

3. Set up your Ubuntu username and password when prompted.
   {% endstep %}

{% step %}

### 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](https://docs.docker.com/compose/install) — 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](https://github.com/gitbito/ai-architect/blob/main/docs/KUBERNETES_DEPLOYMENT.md). |
| {% endstep %}         |                                                                           |                                                                                                                                                                                                                                                                                                 |

{% step %}

### 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**](https://docs.docker.com/compose/install)

**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**
   {% endstep %}

{% step %}

### Kubernetes cluster (required for Kubernetes based deployment method)

### For production environments:

During the setup process given below, if you choose [**Kubernetes**](https://kubernetes.io/docs/home/) 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:**

```shellscript
brew install kind kubectl helm
```

* **Linux:**

```shellscript
# KIND
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
```

{% hint style="info" %}
**Note:** Before creating a KIND cluster, verify Docker has sufficient resources:

```shellscript
docker info --format 'CPUs={{.NCPU}} Mem={{.MemTotal}}'
```

\
**Required:** Minimum 4 CPUs and 8GB RAM

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

#### Setting up a test cluster with KIND

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

```shellscript
kind create cluster --name bito-ai-architect --config - <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
  - containerPort: 443
    hostPort: 443
EOF
```

{% hint style="info" %}
**Note:** Services use ClusterIP for secure, internal-only access. External access is configured via Ingress Controller on ports 80/443.
{% endhint %}

#### Verify cluster

```shellscript
kubectl cluster-info --context kind-bito-ai-architect
kubectl get nodes
```

{% endstep %}
{% endstepper %}

## Installation guide

{% stepper %}
{% step %}

### 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:

```bash
curl -fsSL https://aiarchitect.bito.ai/install.sh | bash
```

The installation script will:

* Download the latest Bito AI Architect package
* Extract it to your system
* Initialize the setup process

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}

{% step %}

### Configuration

[**Download the `install.default.yaml` file**](https://raw.githubusercontent.com/gitbito/ai-architect/refs/heads/main/install.default.yaml), 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.

{% hint style="info" %}
**Note:** Refer to the [**Prerequisites section**](#prerequisites) for details on how to obtain these.
{% endhint %}

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.

{% hint style="info" %}
**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)
   {% endhint %}

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

{% hint style="info" %}
**Note:** Refer to the [**Prerequisites section**](#prerequisites) for details on how to obtain these.
{% endhint %}

* **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](#insights)

  * 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](#insights)

  * 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    &#x20;(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](#insights)

  * 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](https://github.com/gitbito/ai-architect#6-sso-authentication) for more details.
  {% endstep %}

{% step %}

### 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.

{% hint style="info" %}
For versions older than 1.4.0, configuration file can be found in installation directory.
{% endhint %}

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

```yaml
repository:
  configured_repos:
    - namespace: your-org/repo-name-1
    - namespace: your-org/repo-name-2
    - namespace: your-org/repo-name-3
```

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:

```shellscript
bitoarch add-repos
```

{% endstep %}

{% step %}

### 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:

```shellscript
bitoarch index-repos
```

{% hint style="info" %}
**Note:** Indexing process will take approximately 3-10 minutes per repository. Smaller repos take less time.
{% endhint %}

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

{% step %}

### Check indexing status

Run this command to check the status of your indexing:

```shellscript
bitoarch index-status
```

{% hint style="info" %}
**Example output:**

```
Configured Repositories:
  Total: 3

Repository Index Status:
State: ⏳ running
  Progress: 0 / 1 completed
  In Progress: 1

Workspace Index Progress:
State: ⏳ running
  Progress: 1 / 2 completed
  In Progress: 1

Overall Status: in-progress
```

**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.
  {% endhint %}
  {% endstep %}

{% step %}

### 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:

```shellscript
bitoarch mcp-info
```

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

```shellscript
bitoarch rotate-mcp-token <new-token>
```

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}
{% endstepper %}

## Update repository list and re-index

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

```shellscript
vim /usr/local/etc/bitoarch/.bitoarch-config.yaml
```

To apply the changes, run this command:

```shellscript
bitoarch update-repos
```

Start the re-indexing process using this command:

```shellscript
bitoarch index-repos --only-new-repos
```

## 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). |

{% hint style="info" %}
**Note:** If Enterprise IdP is selected but not yet configured, the system automatically falls back to Bito authentication until the IdP setup is complete.
{% endhint %}

#### 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](/ai-architect/single-sign-on-sso-integration#configure-your-identity-provider)
   * 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

{% hint style="info" %}
**Note:** You can also configure or reconfigure SSO at any time after installation using the `bitoarch sso setup` command.
{% endhint %}

#### 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:**

```shellscript
bitoarch sso setup
```

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

**Check SSO status:**

```shellscript
bitoarch sso status
```

Displays the current SSO configuration and IdP connection status.

#### Managing SSO

**Enable SSO**

Re-enable SSO after it has been temporarily disabled:

```shellscript
bitoarch sso enable
```

**Disable SSO**

You can disable SSO either temporarily or permanently:

```shellscript
bitoarch sso disable
```

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:

```shellscript
bitoarch sso rotate-key
```

{% hint style="info" %}
**Important:** After rotating the key, SSO services will restart automatically. Active sessions may need to re-authenticate.
{% endhint %}

#### 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 |

{% hint style="info" %}
**Note:** Session settings can be customized through environment variables in the `.env-bitoarch` configuration file.
{% endhint %}

## 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)

```shellscript
curl http://localhost:5001/health          # Provider
curl http://localhost:5002/health          # Manager
curl http://localhost:5003/health          # Config
```

#### Network access (from other machines on your network)

Get the host machine's IP address:

```shellscript
kubectl get nodes -o wide
# Or: hostname -I (Linux) / ifconfig (macOS)
```

From another machine on the network:

```shellscript
curl http://<host-ip>:5001/health          # Provider
curl http://<host-ip>:5002/health          # Manager
curl http://<host-ip>:5003/health          # Config
curl http://<host-ip>:5005/health          # Tracker
```

#### 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**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) 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:

* [**Guide for Claude Code**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-claude-code)
* [**Guide for Cursor**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-cursor)
* [**Guide for Windsurf**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-windsurf)
* [**Guide for GitHub Copilot (VS Code)**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-github-copilot-vs-code)
* [**Guide for Junie (JetBrains)**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-junie-jetbrains)
* [**Guide for JetBrains AI Assistant**](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-jetbrains-ai-assistant)

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:

```shellscript
# List available and installed plugins
bitoarch plugin list

# Install, configure, and check a plugin
bitoarch plugin install ai-assistant
bitoarch plugin config ai-assistant
bitoarch plugin status
```

Full setup, configuration, and troubleshooting steps for each plugin are in the [Plugins guide](/ai-architect/installation/install-ai-architect-self-hosted/plugins).

## 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**](https://bito.ai/product/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**](https://alpha.bito.ai/home/welcome)
2. Open the [**AI Architect Settings**](https://alpha.bito.ai/home/ai-architect/settings?mode=self-hosted) 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**](mailto: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

```shellscript
bitoarch insights enable git              # Enable commit-history insights (reuses git credentials)
bitoarch insights enable ticket-tracker   # Enable Jira insights (prompts for Jira base URL + email + API token)
bitoarch insights enable docs             # Enable Confluence insights (prompts for Confluence URL + email + API token)
bitoarch insights run                     # Trigger analysis
bitoarch insights status                  # Check what's enabled
```

#### Managing Jira project scope

```shellscript
bitoarch insights discover-tracker-projects   # Interactive selection from accessible projects
bitoarch insights tracker-projects list       # Show current project keys
bitoarch insights tracker-projects add PROJ   # Add a project key
bitoarch insights tracker-projects remove PROJ
```

#### Credential rotation

```shellscript
bitoarch update-ticket-tracker    # Re-enter Jira credentials (validates before saving)
bitoarch update-docs              # Re-enter Confluence credentials
```

{% hint style="info" %}
**Atlassian API tokens**

Generate API tokens at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). Provide the Confluence base URL without `/wiki` — the platform normalizes it automatically.
{% endhint %}

#### 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:

```shellscript
cd /path/to/bito-ai-architect
```

```shellscript
./scripts/upgrade.sh --version=latest
```

#### 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:

```shellscript
# Download the standalone upgrade script
curl -O https://github.com/gitbito/ai-architect/blob/main/upgrade.sh
chmod +x upgrade.sh

# Run upgrade with explicit path
./upgrade.sh --old-path=/path/to/bito-ai-architect --version=latest
```

#### Upgrade parameters

The upgrade script supports the following parameters:

```shellscript
# Description
--version=VERSION

# Upgrade to specific version
--version=latest

# Upgrade from custom URL or file
--url=file:///path/to/package.tar.gz

# Specify installation path (required if running outside installation directory)
--old-path=/opt/bito-ai-architect

# Show help message
--help
```

{% hint style="info" %}
**Your data is safe:** All repositories, indexes, API keys, and settings are automatically preserved during upgrade.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

## Uninstall

```shellscript
bitoarch reset       # wipe containers/volumes/config; keep install dir
bitoarch uninstall   # full removal (+ install dir + ~/.bitoarch/install.yaml)
```

{% hint style="info" %}
Docker images are kept — `docker image prune` to reclaim.
{% endhint %}

{% hint style="info" %}
Alternatively, you can also use the following curl command to uninstall AI Architect:

```shellscript
curl -fsSL https://aiarchitect.bito.ai/uninstall.sh | bash
```

{% endhint %}

## 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:

```shellscript
bitoarch diagnose
bitoarch diagnose --verbose          # show URLs, ports, and detail on failures
bitoarch diagnose --section services # run one section only
```

The `--section` flag accepts the following values:

<table><thead><tr><th width="201.199951171875" align="center">Value</th><th>What it checks</th></tr></thead><tbody><tr><td align="center"><code>prereqs</code></td><td>System prerequisites (Docker/Kubernetes, required tools)</td></tr><tr><td align="center"><code>install</code></td><td>Installation state and file integrity</td></tr><tr><td align="center"><code>filesystem</code></td><td>Disk space, volume mounts, log directories</td></tr><tr><td align="center"><code>config</code></td><td>Configuration files and environment variables</td></tr><tr><td align="center"><code>services</code></td><td>Container/pod status, health, and resource usage</td></tr><tr><td align="center"><code>connectivity</code></td><td>Service-to-service and network reachability</td></tr><tr><td align="center"><code>cert</code></td><td>TLS/SSL certificate validity</td></tr></tbody></table>

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

```shellscript
bitoarch diagnose --bundle
```

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

```
Share this file with Bito support: support@bito.ai
```

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:**

```shellscript
bitoarch diagnose --bundle --output <dir name>
```

#### Manual troubleshooting commands

```shellscript
# Check all services
bitoarch status
bitoarch health --verbose

# View full configuration
bitoarch show-config --raw

# Test MCP connection
bitoarch mcp-test

# Check indexing status with details
bitoarch index-status --raw

# Check setup log
tail -f setup.log

# Local log files
tail -f var/logs/cis-provider/provider.log
tail -f var/logs/cis-manager/manager.log

# Services stopped after reboot
bitoarch start

# Complete logs
bitoarch logs

# Reset installation (removes all data and configuration)
bitoarch reset

# To stop all the services
bitoarch stop

# Restart service (for env based config updates)
bitoarch restart --force

# Force pull latest images based on service-versions.json and restart services
bitoarch update
```

#### Commands specific to Kubernetes-based deployment

```shellscript
# Check Kubernetes pod status
# All pods should show "Running" status.
kubectl get pods -n bito-ai-architect

# Check detailed information about a specific Kubernetes pod
kubectl describe pod <pod-name> -n bito-ai-architect

# Access Kubernetes pod shell
kubectl exec -it -n bito-ai-architect \
  $(kubectl get pod -n bito-ai-architect -l app.kubernetes.io/component=provider -o jsonpath='{.items[0].metadata.name}') \
  -- /bin/sh

# Stop KIND cluster (preserves data)
docker stop bito-ai-architect-control-plane

# Start KIND cluster again
docker start bito-ai-architect-control-plane

# Delete KIND cluster completely
kind delete cluster --name bito-ai-architect

# View Provider service logs:
kubectl logs -n bito-ai-architect -l app.kubernetes.io/component=provider --tail=100 -f

# View Manager service logs:
kubectl logs -n bito-ai-architect -l app.kubernetes.io/component=manager --tail=100 -f
```

## Available commands

For complete reference of AI Architect CLI commands, refer to [Available commands](/ai-architect/installation/install-ai-architect-self-hosted/available-commands).


# Overview

Run AI Architect entirely inside your own infrastructure. Your source code, indexed knowledge graph, and credentials never leave your environment.

{% hint style="info" %}
**Prefer zero infrastructure?** [Bito-hosted AI Architect](/ai-architect/installation/install-ai-architect-bito-hosted) runs in Bito's cloud with a 3-step setup. Self-hosted is designed for teams that must keep code and data within their own network.
{% endhint %}

## Choose your deployment mode

Choose based on **who uses it** and **where it runs**.

<table data-search="false"><thead><tr><th></th><th>Standalone</th><th>Enterprise</th></tr></thead><tbody><tr><td><strong>Designed for</strong></td><td>One person, evaluation or personal use</td><td>A team sharing one deployment</td></tr><tr><td><strong>Runs on</strong></td><td>Your workstation</td><td>A shared server or cluster</td></tr><tr><td><strong>Infrastructure</strong></td><td>Docker only</td><td>Docker Compose <em>or</em> Kubernetes</td></tr><tr><td><strong>Knowledge graph</strong></td><td>Local to your machine</td><td>Shared across the team</td></tr><tr><td><strong>MCP access</strong></td><td><code>https://localhost:5001</code></td><td>Your host or domain, behind a proxy or ingress</td></tr><tr><td><strong>AI coding agent setup</strong></td><td>Registered automatically</td><td>Configured per user</td></tr><tr><td><strong>Authentication</strong></td><td>Bearer token</td><td>Bearer, Bito Auth, or Enterprise IdP</td></tr><tr><td><strong>Installation</strong></td><td>One command (<code>curl | bash</code>)</td><td>One command (<code>curl | bash</code>)</td></tr><tr><td><strong>Setup time</strong></td><td>5 to 10 minutes</td><td>15 to 30 minutes</td></tr></tbody></table>

{% hint style="info" %}
**Not sure?** Start with **Standalone** to evaluate on your workstation, then move to **Enterprise** when you are ready to share it with your team. Both modes run the same platform. Note that switching modes re-indexes your repositories from scratch, so keep the repository count small while evaluating.
{% endhint %}

{% hint style="info" %}
**Plans:** Teams of up to five members can use self-hosted AI Architect for free with their own LLM API keys. Larger teams require the Bito Enterprise Plan, which includes bundled LLM tokens. Powering the Bito AI Code Review Agent with AI Architect also requires the Enterprise Plan, regardless of team size. Contact [**support@bito.ai**](mailto:support@bito.ai) to get started.
{% endhint %}

## How it works

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FoxJIUdTzSDJSuY4SsAJR%2FScreenshot%202026-08-04%20170527.png?alt=media&amp;token=cfb0d373-4a49-4466-a3ad-f61834712b98" alt=""><figcaption></figcaption></figure>

Both modes index your repositories into a knowledge graph and serve it over an **MCP endpoint** that your AI coding agents (Claude Code, Cursor, Windsurf, VS Code, JetBrains) query for cross-repository context. AI Architect reaches out only to Bito for licensing and to your LLM provider for inference.

## Get started

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:$primary;"><strong>▶ Standalone deployment</strong></mark></td><td>One person, on your workstation, ready in minutes.</td><td><a href="/ai-architect/installation/install-ai-architect-self-hosted/standalone-mode-for-individuals">Standalone mode (for individuals)</a></td></tr><tr><td><mark style="color:$primary;"><strong>▶ Enterprise deployment</strong></mark></td><td>A shared deployment for your team, on Docker or Kubernetes.</td><td><a href="/ai-architect/installation/install-ai-architect-self-hosted/enterprise-deployment">Enterprise deployment</a></td></tr></tbody></table>

Before you begin, review [Prerequisites & requirements](/ai-architect/installation/install-ai-architect-self-hosted/prerequisites-and-requirements) for the accounts, tokens, hardware, and network access you will need.


# Prerequisites & requirements

Everything you need before installing self-hosted AI Architect, for both Standalone and Enterprise deployments.

## Accounts and keys

| Requirement            | Where to get it                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| **Bito API key**       | [alpha.bito.ai/home/advanced](https://alpha.bito.ai/home/advanced) (Settings → Advanced Settings) |
| **Git provider token** | Your Git provider (see Git provider access below)                                                 |
| **LLM key** (optional) | Only if you bring your own model (see LLM options below)                                          |

{% stepper %}
{% step %}

### Git provider access

A personal access token (PAT) lets AI Architect clone and index your repositories. Git authentication is **PAT-only**. SSH and OAuth helpers are not supported. Both cloud and enterprise (self-managed) editions are supported for every provider. Click a provider name to create the token before you install:

| Provider                                                                                                                         | Editions supported                    | Token type                                                       | Scope / permission | Also provide           |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------- | ------------------ | ---------------------- |
| [GitHub](https://github.com/settings/tokens)                                                                                     | GitHub.com · GitHub Enterprise Server | Classic PAT (**fine-grained not supported**)                     | `repo`             | -                      |
| [GitLab](https://gitlab.com/-/user_settings/personal_access_tokens)                                                              | GitLab.com · GitLab Self-Managed      | Personal access token                                            | `api`              | -                      |
| [Bitbucket Cloud](https://id.atlassian.com/manage-profile/security/api-tokens)                                                   | Cloud                                 | API token                                                        | Repository read    | Your account email     |
| Bitbucket Data Center / Server                                                                                                   | Self-managed                          | HTTP access token (your instance → Profile → HTTP access tokens) | Repository read    | Your username          |
| [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) | dev.azure.com · Azure DevOps Server   | Personal access token                                            | Full access        | Your organization name |

{% hint style="info" %}
**Enterprise or self-managed instance** (for example `github.company.com`)? During install, answer yes when asked whether this is an enterprise version of your provider, and enter your custom domain.
{% endhint %}
{% endstep %}

{% step %}

### LLM options

By default, AI Architect uses Bito's LLM, covered by your Bito API key. To bring your own key (BYOK), configure one provider during install, or later with `bitoarch update-llm-config`. Click a provider name to create the credentials:

<table data-search="false"><thead><tr><th>Provider</th><th>What you provide</th></tr></thead><tbody><tr><td><a href="https://console.anthropic.com/settings/keys">Anthropic</a></td><td>API key</td></tr><tr><td><a href="https://platform.openai.com/api-keys">OpenAI</a></td><td>API key</td></tr><tr><td><a href="https://aistudio.google.com/apikey">Google Gemini</a></td><td>API key. Model optional</td></tr><tr><td><a href="https://portal.azure.com">Azure AI</a></td><td>API key and endpoint URL (for example <code>https://&#x3C;resource>.openai.azure.com</code>)</td></tr><tr><td><a href="https://console.aws.amazon.com/iam/">AWS Bedrock</a></td><td>AWS access key ID, secret access key, and Bedrock region</td></tr><tr><td><a href="https://console.cloud.google.com/iam-admin/serviceaccounts">Google Vertex AI</a></td><td>Service-account key JSON (file path or inline), project ID, and region (for example <code>us-central1</code>). Model optional</td></tr><tr><td><a href="https://app.portkey.ai">Portkey</a></td><td>API token and model name (<code>@provider/model</code>). Gateway URL optional (defaults to <code>https://api.portkey.ai/v1</code>)</td></tr><tr><td><a href="https://novita.ai">Novita</a></td><td>API key</td></tr></tbody></table>

* **Portkey** is an exclusive gateway. When set, it handles all routing, and other providers are not used.
* With an Anthropic key, indexing costs approximately **$1 per MB** of indexable code.
* There is no basic-indexing-only mode. A Bito or custom LLM key is required.

For model selection and how to change providers later, see Custom LLM configuration.
{% endstep %}
{% endstepper %}

## Hardware requirements

Size the host by the number of repositories you plan to index:

| Tier       | Repositories | vCPU | Memory  | Storage |
| ---------- | ------------ | ---- | ------- | ------- |
| Minimum    | up to 25     | 12   | 24 GB   | 500 GB  |
| Ideal      | 25-100       | 16   | 48 GB   | 1.5 TB  |
| Enterprise | 100+         | 32+  | 128+ GB | 2-4 TB+ |

* For repositories larger than 5 GB, add roughly 50% more memory and storage.
* Keep total allocated memory under roughly 75% of host memory.
* Indexing produces CPU and memory peaks above steady state, so the tiers include headroom.

{% hint style="info" %}
**Right-sizing by scale:** run `bitoarch config edit env` and tune `CIS_REPO_LIMIT` (default 50, maximum 500) and `CIS_REPO_SIZE_LIMIT` (default 1 GB per repository) to match your workload.
{% endhint %}

## Network requirements

AI Architect keeps your code and knowledge graph inside your environment, but it must reach a small set of endpoints. If you run behind a corporate firewall or proxy, allow the following.

#### Outbound (egress) over HTTPS 443

| Destination                        | Purpose                                                                                  | When                |
| ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------- |
| `*.bito.ai`                        | License and entitlement validation (always), plus Bito LLM inference unless you use BYOK | Install and runtime |
| `docker.io` (`bitoai/*`) or mirror | Container image pulls                                                                    | Install and upgrade |
| Your Git host                      | Repository cloning                                                                       | Indexing            |
| Your LLM provider endpoint         | LLM inference, **only if BYOK**                                                          | Runtime             |
| Your Jira / Confluence host        | Insights, **only if enabled**                                                            | Runtime             |
| `*.descope.com` and your IdP       | SSO, **only if enabled**                                                                 | Runtime             |

#### Inbound (ingress)

Expose **only the MCP server**: `https://localhost:5001` (Standalone) or port `5001` behind TLS / your ingress (Enterprise). Keep all other services (5002-5006) **internal**.

{% hint style="info" %}
**Behind a proxy (Standalone)?** Export proxy variables before installing and exclude the internal service names:

```
export HTTP_PROXY=http://proxy:8080 HTTPS_PROXY=http://proxy:8080
export NO_PROXY=localhost,127.0.0.1,ai-architect-config,ai-architect-manager,ai-architect-provider
```

{% endhint %}

## Configuration file locations

| File                    | Contents                                    | Find it with                 |
| ----------------------- | ------------------------------------------- | ---------------------------- |
| `.env-bitoarch`         | Secrets and resource/port settings          | `bitoarch config path env`   |
| `.bitoarch-config.yaml` | Repository and ticket-tracker configuration | `bitoarch config path repos` |


# Standalone deployment

Run AI Architect privately on your own workstation. Setup takes about 5 to 10 minutes.

Your AI coding agent connects automatically during installation.

{% hint style="info" %}
Sharing with a team or installing on a server? Use the Enterprise deployment guide instead.
{% endhint %}

## Before you begin

Have the following ready. See [Prerequisites & requirements](/ai-architect/installation/install-ai-architect-self-hosted/prerequisites-and-requirements) for creation links and details.

| Requirement              | Notes                                                              |
| ------------------------ | ------------------------------------------------------------------ |
| Bito API key             | [alpha.bito.ai/home/advanced](https://alpha.bito.ai/home/advanced) |
| Git provider token (PAT) | GitHub, GitLab, Bitbucket, or Azure DevOps                         |
| Your email (optional)    | Associates the automatic coding-agent registration with you        |
| Docker Desktop 20.10+    | With Compose v2                                                    |
| Free ports               | 5001-5006 on localhost                                             |

{% stepper %}
{% step %}

### Pre-seed your configuration (optional)

To install **without prompts**, provide your configuration before running the installer. Skip this step to install interactively, and the installer asks for each value instead.

```shellscript
mkdir -p ~/.bitoarch
```

```shellscript
cat > ~/.bitoarch/install.yaml <<'EOF'
bito_api_key: "<your-bito-api-key>"
git:
  provider: github
  access_token: "<your-git-pat>"
user_email: "you@company.com"    # associates coding-agent registration with you
EOF
```

Start from the full template, [install.default.yaml](https://raw.githubusercontent.com/gitbito/ai-architect/refs/heads/main/install.default.yaml), to pre-seed any option: LLM provider keys, Insights, custom ports, and more.
{% endstep %}

{% step %}

### Install and index

```shellscript
curl -fsSL https://aiarchitect.bito.ai/standalone/install.sh | bash
```

If you pre-seeded your configuration, the installer runs without prompts. Otherwise, it asks for your Bito API key and Git provider token.

The installer validates prerequisites, deploys the services, then **fetches your repository list** from your Git provider and asks how to proceed:

* **Auto (recommended)**: saves the fetched repository list and starts indexing automatically (about 3-10 minutes per repository).
* **Manual**: follow the steps shown in the terminal to complete configuration. In summary:
  1. `bitoarch config edit repos` (review or trim the list, as each indexed repository consumes LLM tokens)
  2. `bitoarch add-repos` (apply the list)
  3. `bitoarch index-repos` (start indexing)

On success, the installer prints your **MCP URL and access token**.

**Your AI coding agent connects automatically.** Standalone serves MCP over HTTPS at `https://localhost:5001/mcp` with a locally trusted certificate, and the installer registers this endpoint in every detected AI coding agent (Claude Code, Cursor, Windsurf, VS Code, Junie, and JetBrains AI Assistant). During installation you are asked for an email to associate with this registration (or pre-seed `user_email`); press Enter to skip it. Restart each tool when prompted. No further setup is needed.

```shellscript
bitoarch mcp-info    # view the MCP URL, token, and authentication mode anytime
```

{% hint style="info" %}
Installed a new IDE after setup? Register it with `bitoarch mcp-install`. Re-running the install command is also safe: existing configuration is reused with no prompts.
{% endhint %}

<details>

<summary><strong>Manual agent configuration (if an IDE is not auto-detected)</strong></summary>

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "url": "https://localhost:5001/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>",
        "x-email-id": "you@company.com"
      }
    }
  }
}
```

Run `bitoarch mcp-info` for your URL and token. The `x-email-id` header is the email associated with your registration. For per-tool guidance, see:

* [Quick MCP integration with AI coding agents](/ai-architect/quick-mcp-integration-with-ai-coding-agents)
* [Integrating AI Architect with your tools](/ai-architect/integrating-ai-architect-with-your-tools)

</details>
{% endstep %}

{% step %}

### Verify the installation

```shellscript
bitoarch status        # all services healthy
bitoarch index-status  # reaches "completed"
bitoarch mcp-test      # end-to-end MCP check passes
```

Setup is complete. Ask your AI coding agent a cross-repository question to confirm it is using AI Architect context.
{% endstep %}
{% endstepper %}

## Next steps

* [Operations & troubleshooting](/ai-architect/installation/install-ai-architect-self-hosted/operations-and-troubleshooting)
* [CLI command reference](/ai-architect/installation/install-ai-architect-self-hosted/cli-command-reference)

Optional: connect the AI Code Review Agent for codebase-aware reviews, or enable Insights.

{% hint style="info" %}
The MCP certificate **renews automatically** every day through your OS scheduler. Check it anytime with `bitoarch mcp-cert status`.
{% endhint %}


# Enterprise deployment

Run AI Architect as a shared service for your team, on a server or cluster. Docker Compose suits a single shared host. Kubernetes suits production, high availability, and horizontal scaling.

{% hint style="info" %}
Evaluating on your workstation? The [Standalone deployment](/ai-architect/installation/install-ai-architect-self-hosted/standalone-deployment) is faster (one command, about 5 to 10 minutes).
{% endhint %}

## Before you begin

Have the following ready. See [Prerequisites & requirements](/ai-architect/installation/install-ai-architect-self-hosted/prerequisites-and-requirements) for creation links, hardware sizing, and, importantly, the network and firewall allowlist your deployment must reach.

| Requirement              | Notes                                                              |
| ------------------------ | ------------------------------------------------------------------ |
| Bito API key             | [alpha.bito.ai/home/advanced](https://alpha.bito.ai/home/advanced) |
| Git provider token (PAT) | GitHub, GitLab, Bitbucket, or Azure DevOps                         |
| Deployment tooling       | Docker Compose **or** Kubernetes (tabs below)                      |

{% tabs %}
{% tab title="Docker Compose" %}

* **Docker** Desktop 20.10+ with Compose v2
* Ports **5001-5006** free on the host (or customize)
  {% endtab %}

{% tab title="Kubernetes" %}

* `kubectl` and `helm` 3.x installed locally
* A reachable cluster (`kubectl cluster-info` succeeds)
* An Ingress Controller (nginx, traefik, or similar), or port-forward for testing
  {% endtab %}
  {% endtabs %}

<details>

<summary><strong>No cluster yet? Test on a local KIND cluster</strong></summary>

To evaluate the Kubernetes path locally, create a KIND cluster (requires 4 CPUs and 8 GB RAM):

```shellscript
# Install tools (macOS)
brew install kind kubectl helm

# Create a cluster with ingress port mappings
kind create cluster --name bito-ai-architect --config - <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
  - containerPort: 443
    hostPort: 443
EOF

kubectl cluster-info --context kind-bito-ai-architect
kubectl get nodes

# Tear down when done
kind delete cluster --name bito-ai-architect
```

</details>

{% stepper %}
{% step %}

### Pre-seed your configuration (optional)

To install **without prompts**, create `~/.bitoarch/install.yaml` from the full template, [install.default.yaml](https://raw.githubusercontent.com/gitbito/ai-architect/refs/heads/main/install.default.yaml), which covers every option: deployment method, Bito key, Git, LLM provider keys, Insights, ports, and SSO. Skip this step to install interactively, and the installer asks for each value instead.
{% endstep %}

{% step %}

### Install and index

```shellscript
curl -fsSL https://aiarchitect.bito.ai/install.sh | bash
```

If you pre-seeded your configuration, the installer runs without prompts. Otherwise, it asks for the **deployment method** (Docker Compose or Kubernetes), your **Bito API key**, and your **Git provider** and token.

The installer validates prerequisites, generates secure secrets (database passwords, JWT, MCP token), deploys the services, and installs the `bitoarch` CLI globally. It then **fetches your repository list** from your Git provider and asks how to proceed:

* **Auto (recommended)**: saves the fetched repository list, starts indexing automatically (about 3-10 minutes per repository), and prompts you to set up SSO before finishing.
* **Manual**: follow the steps shown in the terminal to complete configuration. In summary:
  1. `bitoarch config edit repos` (review or trim the list, as each indexed repository consumes LLM tokens)
  2. `bitoarch add-repos` (apply the list)
  3. `bitoarch index-repos` (start indexing)
  4. `bitoarch sso setup` (configure SSO, optional)

On success, the installer prints your **MCP URL and access token**.

{% hint style="info" %}
**Custom ports?** Services default to 5001-5006. To change them, run `bitoarch config edit env`, set the values below, then run `bitoarch restart --force`:

```
CIS_PROVIDER_EXTERNAL_PORT=5001   # MCP server
CIS_MANAGER_EXTERNAL_PORT=5002
CIS_CONFIG_EXTERNAL_PORT=5003
MYSQL_EXTERNAL_PORT=5004
CIS_TRACKER_EXTERNAL_PORT=5005
TEMPORAL_EXTERNAL_PORT=5006
```

{% endhint %}
{% endstep %}

{% step %}

### Expose the MCP endpoint

Your team connects through the MCP server. Expose only that service, and keep the rest internal.

{% tabs %}
{% tab title="Docker Compose" %}
Services expose ports **5001-5006** on the host. The MCP server is on **5001**. For team access, place a TLS reverse proxy in front of port 5001. Keep ports 5002-5006 internal.

```shellscript
bitoarch status
bitoarch mcp-info          # MCP URL + token
```

{% endtab %}

{% tab title="Kubernetes" %}
Services run in the `bito-ai-architect` namespace as ClusterIP (internal only). Expose the MCP server through an **Ingress Controller on ports 80/443** for production. Use port-forward only for testing.

```shellscript
# Via ingress (recommended): health of each service
curl http://your-domain.com/api/provider/health
curl http://your-domain.com/api/manager/health
curl http://your-domain.com/api/config/health
curl http://your-domain.com/api/tracker/health

# Via port-forward (testing only)
kubectl port-forward svc/ai-architect-provider 8080:8080 -n bito-ai-architect

# In-cluster (pod-to-pod)
kubectl run curl --image=curlimages/curl -it --rm --restart=Never -n bito-ai-architect -- \
  curl http://ai-architect-provider:8080/health

# Inspect pods
kubectl get pods -n bito-ai-architect
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Connect your team

Retrieve the MCP URL and token, then share the connection details with your team:

```shellscript
bitoarch mcp-info
```

Each user connects their tool with the [Quick MCP integration with AI coding agents](/ai-architect/quick-mcp-integration-with-ai-coding-agents) installer (Claude Code, Cursor, Windsurf, VS Code, JetBrains).

{% hint style="info" %}
**Using SSO?** When SSO is enabled, users authenticate through your identity provider instead of the shared access token. See Manage authentication below and the [SSO integration guide](/ai-architect/single-sign-on-sso-integration).
{% endhint %}
{% endstep %}

{% step %}

### Verify the installation

```shellscript
bitoarch status        # all services healthy
bitoarch index-status  # reaches "completed"
bitoarch mcp-test      # end-to-end MCP check passes
```

Setup is complete. Ask your AI coding agent a cross-repository question to confirm it is using AI Architect context.
{% endstep %}
{% endstepper %}

## Manage authentication (optional)

SSO setup is offered during installation (Step 2). By default, MCP uses a static bearer token. To enable or change user-level authentication later:

```shellscript
bitoarch sso setup     # Enterprise IdP (SAML/OIDC) or Bito Auth
bitoarch sso status
```

Full walkthrough: [Single Sign-On (SSO) integration](/ai-architect/single-sign-on-sso-integration).

## Next steps

* [Operations & troubleshooting](/ai-architect/installation/install-ai-architect-self-hosted/operations-and-troubleshooting)
* [CLI command reference](/ai-architect/installation/install-ai-architect-self-hosted/cli-command-reference)

Optional: connect the AI Code Review Agent for codebase-aware reviews, or enable Insights.

{% hint style="info" %}
Secrets live in `.env-bitoarch` (`bitoarch config path env`): your API key, Git token, MCP token, database passwords, and JWT secret. This file is preserved automatically across upgrades and removed on uninstall.
{% endhint %}


# Operations & troubleshooting

Common tasks for managing a running deployment (Standalone or Enterprise). For every command, see the CLI command reference.

## Quick reference

<table data-search="false"><thead><tr><th>Task</th><th>Command</th></tr></thead><tbody><tr><td>Check service health</td><td><code>bitoarch status</code> · <code>bitoarch health</code></td></tr><tr><td>Check indexing progress</td><td><code>bitoarch index-status</code></td></tr><tr><td>Add or remove a repository</td><td><code>bitoarch add-repo &#x3C;ns></code> · <code>bitoarch remove-repo &#x3C;ns></code></td></tr><tr><td>Rotate a credential</td><td><code>update-api-key</code> · <code>update-git-creds</code> · <code>rotate-mcp-token</code></td></tr><tr><td>View MCP connection details</td><td><code>bitoarch mcp-info</code></td></tr><tr><td>Upgrade the platform</td><td><code>bitoarch upgrade</code></td></tr><tr><td>Diagnose an issue</td><td><code>bitoarch diagnose</code></td></tr><tr><td>Create a support bundle</td><td><code>bitoarch diagnose --bundle</code></td></tr></tbody></table>

## Manage repositories

```shellscript
bitoarch add-repo myorg/repo        # add one repository
bitoarch remove-repo myorg/repo     # remove one repository
bitoarch config edit repos          # edit the repository list
bitoarch add-repos                  # apply the edited list
bitoarch index-repos --only-new-repos   # index newly added repositories only
bitoarch index-status               # in_progress | completed | failed
```

Indexing runs one job per workspace at a time. Schedule recurring re-indexing with `bitoarch create-index-scheduler`.

## Rotate credentials

```shellscript
bitoarch update-api-key      # rotate the Bito API key
bitoarch update-git-creds    # rotate the Git provider token
bitoarch update-llm-config   # change or rotate LLM provider configuration
bitoarch rotate-mcp-token    # rotate the MCP access token
```

After rotating the MCP token, update the token in each connected AI coding agent.

## Connect the AI Code Review Agent

Give Bito's AI Code Review Agent your AI Architect context for codebase-aware, cross-repository reviews:

1. Log in to [Bito Cloud](https://alpha.bito.ai/home/welcome).
2. Open the **AI Architect Settings** dashboard.
3. Enter your **MCP URL** in the Server URL field (`bitoarch mcp-info`).
4. Enter your **MCP access token** in the Auth token field.

{% hint style="info" %}
Requires the Bito Enterprise Plan. Full walkthrough: [Integrating with Bito's AI Code Review Agent](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-bitos-ai-code-review-agent).
{% endhint %}

## Upgrade

```shellscript
bitoarch upgrade                   # upgrade to the latest version
bitoarch upgrade --version=1.8.0   # upgrade to a specific version
```

{% hint style="info" %}
`upgrade` performs a blue/green swap, so **your indexed data, configuration, and `.env-bitoarch` are preserved automatically** with no manual backup needed. The previous install stays on disk until you remove it, and rollback is not supported once an upgrade succeeds. Upgrades must stay within the same deployment type (Docker Compose or Kubernetes).
{% endhint %}

## Stop, start, uninstall

```shellscript
bitoarch stop        # stop services, keep data
bitoarch start       # start stopped services
bitoarch restart     # restart services
bitoarch reset       # remove services, volumes, and configuration (keeps the install directory)
bitoarch uninstall   # full removal
```

{% hint style="info" %}
`reset` and `uninstall` **delete your indexed data**, and switching between Docker Compose and Kubernetes requires a `reset` followed by a full re-index. Docker images are kept: run `docker image prune` to reclaim disk space. On Kubernetes, `uninstall` removes the Helm release and namespace.
{% endhint %}

***

## Troubleshooting

#### Start with diagnose

```shellscript
bitoarch diagnose                      # pass/warn/fail sweep across all sections
bitoarch diagnose --section services   # limit to one section
bitoarch diagnose --bundle             # create a redacted support bundle (.tar.gz)
```

Sections: `prereqs`, `install`, `filesystem`, `config`, `services`, `connectivity`, `cert`.

#### Manual checks

```shellscript
bitoarch health                  # per-service health
bitoarch show-config             # current indexing configuration
bitoarch index-status            # indexing progress and state
bitoarch logs                    # tail logs from all services
bitoarch logs cis-manager        # tail logs from one service
```

#### Common issues

<table data-search="false"><thead><tr><th>Symptom</th><th>Likely cause</th><th>Resolution</th></tr></thead><tbody><tr><td><code>command not found: bitoarch</code></td><td>Shell PATH not reloaded</td><td><code>source ~/.zshrc</code></td></tr><tr><td>"Docker has only X GB RAM"</td><td>Docker under-allocated</td><td>Docker Desktop → Resources → Memory → 6 GB+ → Restart</td></tr><tr><td>"Port 5001 is in use"</td><td>Port conflict</td><td>Pre-seed custom ports in <code>install.yaml</code> before installing, or run <code>bitoarch config edit env</code> and <code>bitoarch restart --force</code> after</td></tr><tr><td>Services stopped after reboot</td><td>Not auto-started</td><td><code>bitoarch start</code></td></tr><tr><td>Indexing stuck</td><td>Stalled job</td><td><code>index-status</code> → <code>logs cis-manager</code> → <code>stop-indexing &#x26;&#x26; index-repos</code></td></tr><tr><td>MCP client cannot connect</td><td>Wrong URL/token or certificate</td><td><code>mcp-info</code>, then <code>mcp-test</code>. Standalone: <code>mcp-cert status</code></td></tr><tr><td>Pod <code>CrashLoopBackOff</code> (K8s)</td><td>Startup failure</td><td>Identify the restart reason and the crashed container's error output (see Kubernetes diagnostics below)</td></tr></tbody></table>

#### Kubernetes diagnostics

```shellscript
kubectl get pods -n bito-ai-architect                 # pod status at a glance
kubectl describe pod <pod> -n bito-ai-architect       # events and restart reason (for example OOM, image pull)
kubectl logs <pod> -n bito-ai-architect --previous    # error output from the crashed container
```

#### Escalate to Bito support

```shellscript
bitoarch diagnose --bundle                 # redacted .tar.gz (saved to ~/.bitoarch/diagnostics/)
bitoarch diagnose --bundle --output <dir>   # write it elsewhere
```

The bundle contains system information, logs, configuration, database health, indexing state, and local usage events. **Secrets and tokens are masked**, and triage fields such as email and IP are retained. Attach it to your ticket at [**support@bito.ai**](mailto:support@bito.ai).


# Custom LLM configuration

By default, AI Architect uses Bito's LLM, covered by your Bito API key. To bring your own key (BYOK), point AI Architect at a supported provider.

Configure a provider during installation, or at any time with:

```shellscript
bitoarch update-llm-config
```

## Supported providers

<table data-search="false"><thead><tr><th>Provider</th><th>Credentials required</th><th>Model</th></tr></thead><tbody><tr><td><a href="https://console.anthropic.com/settings/keys">Anthropic</a></td><td>API key</td><td>Provider default</td></tr><tr><td><a href="https://platform.openai.com/api-keys">OpenAI</a></td><td>API key</td><td>Provider default</td></tr><tr><td><a href="https://aistudio.google.com/apikey">Google Gemini</a></td><td>API key</td><td>Optional (workspace default if omitted)</td></tr><tr><td><a href="https://portal.azure.com">Azure AI</a></td><td>API key + endpoint URL</td><td>Deployment name</td></tr><tr><td><a href="https://console.aws.amazon.com/iam/">AWS Bedrock</a></td><td>Access key ID + secret + region</td><td>Provider default</td></tr><tr><td><a href="https://console.cloud.google.com/iam-admin/serviceaccounts">Google Vertex AI</a></td><td>Service-account JSON + project ID + region</td><td>Optional (workspace default if omitted)</td></tr><tr><td><a href="https://app.portkey.ai">Portkey</a></td><td>API token (+ optional gateway URL)</td><td>Required, as <code>@provider/model</code></td></tr></tbody></table>

* **Portkey is an exclusive gateway.** When configured, it routes all requests, and other providers are not used.
* Where the model is optional, leaving it blank uses the current workspace default managed by AI Architect.
* With an Anthropic key, indexing costs approximately **$1 per MB** of indexable code.

{% hint style="info" %}
**Model format notes.** Portkey requires the `@provider/model-name` format (for example `@openai/gpt-4o`). Azure AI uses your **deployment name** rather than a base model name. Vertex AI and Gemini accept an optional model; leave it blank to use the workspace default.
{% endhint %}

## Change the provider later

```shellscript
bitoarch update-llm-config   # reconfigure the provider or model
bitoarch show-config         # confirm the active configuration
```

Changing the provider or model does not re-index automatically. Run `bitoarch index-repos` if you want existing repositories re-indexed with the new model.


# CLI command reference

CLI commands for installing, operating, and maintaining Bito's AI Architect.

Complete reference for the `bitoarch` command-line interface used to manage a self-hosted deployment. Run `bitoarch <command> --help` for command-specific options.

{% hint style="info" %}
Commands marked **Standalone-only** exist only on Standalone deployments. They are hidden and refuse to run on Enterprise.
{% endhint %}

## Status

| `status`                             | Show the status of all services                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| `health [--verbose]`                 | Check health of all services (per-service detail)                               |
| `info`                               | Show platform information (version, ports)                                      |
| `diagnose [--verbose]`               | Diagnostic sweep, pass/warn/fail per section                                    |
| `diagnose --section <name>`          | One section: prereqs, install, filesystem, config, services, connectivity, cert |
| `diagnose --bundle [--output <dir>]` | Redacted `.tar.gz` for support (→ `~/.bitoarch/diagnostics/`)                   |

## Lifecycle

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><code>start</code></td><td>Start stopped services (idempotent)</td></tr><tr><td><code>stop</code></td><td>Stop all services (keeps data)</td></tr><tr><td><code>restart [--force]</code></td><td>Restart services (<code>--force</code> reloads env and recreates containers)</td></tr><tr><td><code>logs [service]</code></td><td>Tail service logs (<code>-f</code> to follow, all services if omitted)</td></tr><tr><td><code>upgrade [--version=&#x3C;ver>]</code></td><td>Upgrade the platform, blue/green (latest by default, data preserved)</td></tr><tr><td><code>reset</code></td><td>Remove services, volumes, and configuration (keeps the install directory)</td></tr><tr><td><code>uninstall</code></td><td>Full removal (services + install directory)</td></tr></tbody></table>

## Repositories

| `add-repo <ns>` / `remove-repo <ns>` | Add / remove a repository by namespace                                |
| ------------------------------------ | --------------------------------------------------------------------- |
| `add-repos` / `update-repos`         | Apply / update the repository list (edit it with `config edit repos`) |
| `repo-info <name>`                   | Show repository details                                               |
| `fetch-repo-list [--force-load]`     | Sync the repository list from the Git provider                        |

## Indexing

| `show-config [--raw]`                               | Show current indexing configuration (`--raw` = full resolved config) |
| --------------------------------------------------- | -------------------------------------------------------------------- |
| `index-repos [--only-new-repos]`                    | Trigger workspace repository indexing                                |
| `index-status`                                      | Check indexing status (`--raw` for full payload)                     |
| `index-repo-list`                                   | List all indexed repositories                                        |
| `stop-indexing`                                     | Stop indexing completely                                             |
| `create-index-scheduler` / `update-index-scheduler` | Manage scheduled indexing                                            |

## Configuration

| `update-api-key`                 | Update the Bito API key                                 |
| -------------------------------- | ------------------------------------------------------- |
| `update-git-creds`               | Update Git provider credentials                         |
| `update-llm-config`              | Update custom LLM provider configuration                |
| `rotate-mcp-token [<new-token>]` | Rotate the MCP access token (auto-generates if omitted) |
| `config path [env\|repos\|llm]`  | Print a configuration file path                         |
| `config edit [env\|repos\|llm]`  | Open a configuration file in `$EDITOR`                  |

## MCP

| `mcp-info`                           | Show MCP configuration (URL, token, auth mode) |
| ------------------------------------ | ---------------------------------------------- |
| `mcp-test`                           | Test the MCP connection end-to-end             |
| `mcp-tools` / `mcp-tool-info <name>` | List tools / show a tool's details             |
| `mcp-capabilities`                   | Show MCP server capabilities                   |

## SSO (Enterprise only)

| `sso setup`                  | Configure SSO (Enterprise IdP or Bito)   |
| ---------------------------- | ---------------------------------------- |
| `sso status`                 | Check SSO configuration and verification |
| `sso enable` / `sso disable` | Re-enable / disable SSO                  |
| `sso rotate-key`             | Rotate SSO keys                          |

## Insights (optional)

| `insights config` / `insights status`                  | Show configuration / workflow status     |
| ------------------------------------------------------ | ---------------------------------------- |
| `insights run [--force]`                               | Run analysis (`--force` re-analyzes all) |
| `insights enable\|disable [git\|ticket-tracker\|docs]` | Toggle an insights feature               |
| `insights tracker-projects [action] [KEY …]`           | Manage project keys                      |
| `insights set-lookback [git\|ticket-tracker]`          | Set lookback days                        |

## Standalone-only

| `mcp-install [--email <addr>]` | Register the local MCP with detected AI coding agents                  |
| ------------------------------ | ---------------------------------------------------------------------- |
| `mcp-uninstall`                | Deregister MCP from AI coding agents                                   |
| `mcp-cert status`              | Certificate verdict, days remaining, scheduler state                   |
| `mcp-cert renew [--check]`     | Re-issue the certificate (`--check` = only if expiring within 60 days) |
| `mcp-cert schedule [HH:MM]`    | Show or set the daily auto-renew time                                  |


# Connect Bito AI Architect to GitHub — Create a GitHub App

This guide walks you through creating a **GitHub App** in your own GitHub account or organization. You will use three values from it while setting up AI Architect so it can securely read and index your repositories.

* ⏱️ **Time required:** about 10 minutes
* 🔐 **You stay in control:** the App and its private key belong to *you* and stay in your own AI Architect setup. You can revoke access at any time.
* 🌐 **Works on:** GitHub.com **and** GitHub Enterprise Server (self-hosted GitHub).

At the end you will have three values to use while setting up AI Architect:

<table><thead><tr><th width="121.79998779296875">#</th><th width="263.4000244140625">Value</th><th>Looks like</th></tr></thead><tbody><tr><td>1</td><td><strong>App ID</strong></td><td>A number, e.g. <code>123456</code></td></tr><tr><td>2</td><td><strong>Installation ID</strong></td><td>A number, e.g. <code>987654321</code></td></tr><tr><td>3</td><td><strong>Private key</strong></td><td>A file ending in <code>.pem</code></td></tr></tbody></table>

***

### ⚡ Quick start — jump straight to the creation page

Click the link that matches where your code lives:

* **Organization repos (recommended)** → `https://github.com/organizations/YOUR-ORG/settings/apps/new` *(replace `YOUR-ORG` with your organization name)*
* **Personal account repos** → [**https://github.com/settings/apps/new**](https://github.com/settings/apps/new)
* **GitHub Enterprise Server (self-hosted)** → `https://YOUR-GITHUB-HOST/settings/apps/new` *(replace `YOUR-GITHUB-HOST` with your internal GitHub address)*

> 💡 Not sure? Use the **organization** link if your repositories belong to a company or team. Use the **personal** link if they are under your own username.

Then follow Steps 2–7 below.

***

### Step 1 — Open the GitHub App creation page

1. Sign in to GitHub.
2. Open the correct **"New GitHub App"** page using a link from the Quick start above.

   *Manual path (if you prefer clicking through):*

   * **Organization:** Your org → **Settings** → left sidebar **Developer settings** → **GitHub Apps** → **New GitHub App**.
   * **Personal:** Profile photo (top-right) → **Settings** → **Developer settings** (bottom of left sidebar) → **GitHub Apps** → **New GitHub App**.

***

### Step 2 — Fill in the basic details

| Field                | What to enter                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub App name**  | Any unique name, e.g. `Bito AI Architect` (names are global on GitHub, so add your company if it's taken, e.g. `Bito AI Architect – Acme`). |
| **Homepage URL**     | Your company website, or `https://bito.ai`. Any valid URL works.                                                                            |
| **Webhook → Active** | **Uncheck this box.** Bito does not need webhooks — leaving it off means there is nothing to configure and no callback into your network.   |

> Leave every other field on this page at its default. You do **not** need a "Callback URL", "Setup URL", or "Webhook URL".

***

### Step 3 — Set permissions (least privilege)

Scroll down to **Permissions → Repository permissions** and set only these:

| Permission   | Access        | Why                                                           |
| ------------ | ------------- | ------------------------------------------------------------- |
| **Contents** | **Read-only** | Lets AI Architect read and index your source code.            |
| **Metadata** | **Read-only** | Basic repo info. *(Selected automatically — leave it as-is.)* |

**Leave everything else set to "No access."** That's all AI Architect needs.

***

### Step 4 — Choose where the App can be installed

Scroll to the bottom, under **"Where can this GitHub App be installed?"**:

* Select **"Only on this account"**.

***

### Step 5 — Create the App and copy the App ID

1. Click the green **Create GitHub App** button.
2. You'll land on the App's settings page. Near the top you'll see **App ID** — a number like `123456`.
3. **📋 Copy the App ID and save it.** *(This is value #1 of 3.)*

***

### Step 6 — Generate the private key

1. Still on the App's settings page, scroll to the **Private keys** section.
2. Click **Generate a private key**.
3. GitHub immediately downloads a file named something like `your-app-name.YYYY-MM-DD.private-key.pem`.
4. **💾 Keep this `.pem` file safe.** *(This is value #3 of 3.)*

> ⚠️ GitHub shows the key **only once, at download time.** If you lose it, just generate a new one and delete the old — it's not a problem.

***

### Step 7 — Install the App and copy the Installation ID

1. On the App's settings page, click **Install App** in the left sidebar.
2. Click **Install** next to your account or organization.
3. Choose which repositories AI Architect may access:
   * **All repositories**, or
   * **Only select repositories** → pick the repos you want indexed.
4. Click **Install**.
5. After installing, look at the page's web address (URL). It ends in a number:

   ```
   https://github.com/settings/installations/987654321
                                              ^^^^^^^^^
                                          Installation ID
   ```

   *(For organizations it looks like `https://github.com/organizations/YOUR-ORG/settings/installations/987654321`.)*
6. **📋 Copy that final number — the Installation ID.** *(This is value #2 of 3.)*

> To find it again later: **App settings → Install App → the gear/Configure** button next to your account. The number at the end of that URL is the Installation ID.

***

### ✅ Step 8 — Use these three values while setting up AI Architect

When you configure AI Architect, provide:

* [ ] **App ID** (from Step 5) — e.g. `123456`
* [ ] **Installation ID** (from Step 7) — e.g. `987654321`
* [ ] **Private key file** (from Step 6) — the `.pem` file


# Standalone mode (for individuals)

Set up AI Architect on your local machine (e.g. Laptop) for quick evaluation

[Bito's AI Architect](/ai-architect/overview) can be self-hosted in two ways depending on your use case.

* **Enterprise mode** — (for teams to share the same indexed codebase, or you require Kubernetes, SSO, or dedicated server infrastructure. See the [Enterprise mode setup guide](/ai-architect/installation/install-ai-architect-self-hosted).)
* **Standalone mode** — (for individuals to quickly try out AI Architect on your own machine)

This guide covers **Standalone mode** — a lightweight, single-machine install for individual developers who want to get up and running quickly, without provisioning shared infrastructure or coordinating with a DevOps team. It runs entirely in Docker on your local machine and automatically registers itself with your coding agents.

**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 local machine, connected to your Git repositories, and ready to integrate with AI coding tools like Claude Code, Cursor, Windsurf, GitHub Copilot, etc. through the Model Context Protocol (MCP).

## Prerequisites

### a. Required accounts and tokens

{% stepper %}
{% step %}

### 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**](https://alpha.bito.ai/), and create an access key from [**Settings -> Advanced Settings**](https://alpha.bito.ai/home/advanced)

* [**View Guide**](/help/account-and-settings/access-key)
  {% endstep %}

{% step %}

### Git provider

We support the following Git providers:

* GitHub
* GitLab
* Bitbucket
* Azure DevOps
* [Local Git Provider (Pre-Cloned Repositories)](/ai-architect/installation/install-ai-architect-self-hosted/local-git-provider-pre-cloned-repositories-setup-guide)

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

{% step %}

### 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:** To connect your GitHub repositories to AI Architect, choose one of the following authentication methods:
   1. **GitHub App:** Install and authorize the Bito GitHub App, then select the repositories you want AI Architect to index.
      * [**View setup guide**](/ai-architect/installation/install-ai-architect-self-hosted/connect-bito-ai-architect-to-github-create-a-github-app)
   2. **Personal Access Token (Classic):** Create a classic personal access token with repo access and provide it during setup. Fine-grained personal access tokens are not currently supported.
      * [**View setup guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
2. **GitLab Personal Access Token:** To use GitLab repositories with AI Architect, a token with API access is required.
   * [**View setup guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)
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**.
      * [**View setup guide**](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)
   2. **Bitbucket Self-Hosted (`HTTP Access Token`):** You must provide both your **token** and **username**.
      * [**View setup guide**](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html)
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 setup guide**](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops\&tabs=Windows)
      {% endstep %}

{% step %}

### 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)

{% hint style="info" %}
**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)**](#copilot-bridge-vs-code) below.
{% endhint %}

{% hint style="info" %}
AI Architect supports [**Portkey**](https://portkey.ai/) integration for custom proxy configurations.
{% endhint %}

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**](https://bito.ai/pricing/), 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.

{% hint style="info" %}
To use Bito's LLM instead (no LLM keys required from you), contact [**support@bito.ai**](mailto:support@bito.ai) about the [Bito Enterprise Plan](https://bito.ai/pricing/).
{% endhint %}

#### How to test against the GitHub Copilot Bridge (VS Code) <a href="#copilot-bridge-vs-code" id="copilot-bridge-vs-code"></a>

**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](https://github.com/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:**

```shellscript
curl http://127.0.0.1:8000/health
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/v1/models
```

Note an exact model id from `/v1/models` (e.g. `claude-sonnet-4.6`, `gpt-5.4`).
{% endstep %}
{% endstepper %}

### b. System requirements

The AI Architect standalone mode requires the following specs:

{% stepper %}
{% step %}

### Hardware specifications

|                  | Minimum                        | Recommended         |
| ---------------- | ------------------------------ | ------------------- |
| Operating System | macOS 12+, Ubuntu 20.04+       | Same                |
| Docker           | Desktop 20.10+ with Compose v2 | Docker Desktop 4.x+ |
| Docker RAM       | 6 GB                           | 8 GB+               |
| Docker CPUs      | 3                              | 4+                  |
| Disk             | 10 GB                          | 50 GB+              |
| Ports            | 5001–5005 free on localhost    | Same                |

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.

You can customize resource limits by editing the `.env-bitoarch` file and run the command `bitoarch restart --force` to update the allocation. The following environment variables can be manually configured to control resource allocation.

```dotenv
CIS_PROVIDER_MEMORY_LIMIT=1g
CIS_MANAGER_MEMORY_LIMIT=2g
CIS_CONFIG_MEMORY_LIMIT=512m
MYSQL_MEMORY_LIMIT=2g
CIS_TRACKER_MEMORY_LIMIT=512m


CIS_PROVIDER_CPU_LIMIT=1.0
CIS_MANAGER_CPU_LIMIT=2.0
CIS_CONFIG_CPU_LIMIT=0.5
MYSQL_CPU_LIMIT=1.0
CIS_TRACKER_CPU_LIMIT=0.5
```

{% endstep %}

{% step %}

### 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**](https://docs.docker.com/compose/install)
{% endstep %}
{% endstepper %}

## Installation guide

{% stepper %}
{% step %}

### Configuration

[**Download the `install.default.yaml` file**](https://raw.githubusercontent.com/gitbito/ai-architect/refs/heads/main/install.default.yaml), 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.

{% hint style="info" %}
**Note:** Refer to the [**Prerequisites section**](#prerequisites) for details on how to obtain the required items.
{% endhint %}
{% endstep %}

{% step %}

### Install AI Architect

Before proceeding with the installation, ensure **Docker Desktop / Docker Service** 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

Execute the installation command:

```bash
curl -fsSL https://aiarchitect.bito.ai/standalone/install.sh | bash
```

{% hint style="info" %}
**Note:** To install self-hosted AI Architect for your team, refer to [Enterprise mode setup guide](/ai-architect/installation/install-ai-architect-self-hosted).
{% endhint %}

The installation script will:

* Download the latest Bito AI Architect package
* Extract it to your system
* Initialize the setup process

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}

{% step %}

### 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.

{% hint style="info" %}
For versions older than 1.4.0, configuration file can be found in installation directory.
{% endhint %}

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

```yaml
repository:
  configured_repos:
    - namespace: your-org/repo-name-1
    - namespace: your-org/repo-name-2
    - namespace: your-org/repo-name-3
```

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:

```shellscript
bitoarch add-repos
```

{% endstep %}

{% step %}

### 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:

```shellscript
bitoarch index-repos
```

{% hint style="info" %}
**Note:** Indexing process will take approximately 3-10 minutes per repository. Smaller repos take less time.
{% endhint %}

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

{% step %}

### Check indexing status

Run this command to check the status of your indexing:

```shellscript
bitoarch index-status
```

{% hint style="info" %}
**Example output:**

```
Configured Repositories:
  Total: 3

Repository Index Status:
State: ⏳ running
  Progress: 0 / 1 completed
  In Progress: 1

Workspace Index Progress:
State: ⏳ running
  Progress: 1 / 2 completed
  In Progress: 1

Overall Status: in-progress
```

**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.
  {% endhint %}
  {% endstep %}

{% step %}

### 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:

```shellscript
bitoarch mcp-info
```

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

```shellscript
bitoarch rotate-mcp-token <new-token>
```

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

### Connect MCP client

Standalone mode runs MCP over **HTTPS** at `https://localhost:5001/mcp` with a local mkcert-signed leaf cert. The cert is per-host (issued at install time, never reused across machines); mkcert is auto-downloaded if not on PATH.

The install bootstrap auto-registers the local MCP into every detected coding agent (Claude Code, Cursor, Windsurf, VS Code, Junie, JetBrains AI Assistant) and prints a one-time IDE-restart prompt for each. After restart, your IDE connects without further config.

```shellscript
bitoarch mcp-info         # URL + token + auth mode
bitoarch mcp-install      # re-run agent registration (e.g., after installing a new IDE)
bitoarch mcp-cert status  # cert verdict, days remaining, scheduler state
```

{% hint style="info" %}
The cert auto-renews daily via an OS-native scheduler (launchd on macOS, systemd-user timer or crontab on Linux). Override the renew time via `bitoarch mcp-cert schedule HH:MM`. To opt out, set `BITOARCH_CERT_AUTO_RENEW=false` in `.env-bitoarch` and re-run `bitoarch install`.
{% endhint %}

**Manual config fallback** (if your IDE isn't auto-detected, or for the Claude Desktop main chat which doesn't read `~/.claude.json`):

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "url": "https://localhost:5001/mcp",
      "headers": { "Authorization": "Bearer <Your-Bito-MCP-Access-Token>" }
    }
  }
}
```

{% hint style="info" %}
**Note:** Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
{% endhint %}
{% endstep %}
{% endstepper %}

## Update repository list and re-index

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

```shellscript
vim /usr/local/etc/bitoarch/.bitoarch-config.yaml
```

To apply the changes, run this command:

```shellscript
bitoarch update-repos
```

Start the re-indexing process using this command:

```shellscript
bitoarch index-repos --only-new-repos
```

## 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**](https://bito.ai/product/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**](https://alpha.bito.ai/home/welcome)
2. Open the [**AI Architect Settings**](https://alpha.bito.ai/home/ai-architect/settings?mode=self-hosted) 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**](mailto:support@bito.ai) to request a trial. We'll help you configure the integration and get your team up and running quickly.

## 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:

```shellscript
cd /path/to/bito-ai-architect
```

```shellscript
./scripts/upgrade.sh --version=latest
```

#### 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:

```shellscript
# Download the standalone upgrade script
curl -O https://github.com/gitbito/ai-architect/blob/main/upgrade.sh
chmod +x upgrade.sh

# Run upgrade with explicit path
./upgrade.sh --old-path=/path/to/bito-ai-architect --version=latest
```

#### Upgrade parameters

The upgrade script supports the following parameters:

```shellscript
# Description
--version=VERSION

# Upgrade to specific version
--version=latest

# Upgrade from custom URL or file
--url=file:///path/to/package.tar.gz

# Specify installation path (required if running outside installation directory)
--old-path=/opt/bito-ai-architect

# Show help message
--help
```

{% hint style="info" %}
**Your data is safe:** All repositories, indexes, API keys, and settings are automatically preserved during upgrade.
{% endhint %}

## Uninstall

```shellscript
bitoarch reset       # wipe containers/volumes/config; keep install dir
bitoarch uninstall   # full removal (+ install dir + ~/.bitoarch/install.yaml)
```

{% hint style="info" %}
Docker images are kept — `docker image prune` to reclaim.
{% endhint %}

{% hint style="info" %}
Alternatively, you can also use the following curl command to uninstall AI Architect standalone mode:&#x20;

```shellscript
curl -fsSL https://aiarchitect.bito.ai/standalone/uninstall.sh | bash
```

{% endhint %}

## 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:

```shellscript
bitoarch diagnose
bitoarch diagnose --verbose          # show URLs, ports, and detail on failures
bitoarch diagnose --section services # run one section only
```

The `--section` flag accepts the following values:

<table><thead><tr><th width="201.199951171875" align="center">Value</th><th>What it checks</th></tr></thead><tbody><tr><td align="center"><code>prereqs</code></td><td>System prerequisites (Docker/Kubernetes, required tools)</td></tr><tr><td align="center"><code>install</code></td><td>Installation state and file integrity</td></tr><tr><td align="center"><code>filesystem</code></td><td>Disk space, volume mounts, log directories</td></tr><tr><td align="center"><code>config</code></td><td>Configuration files and environment variables</td></tr><tr><td align="center"><code>services</code></td><td>Container/pod status, health, and resource usage</td></tr><tr><td align="center"><code>connectivity</code></td><td>Service-to-service and network reachability</td></tr><tr><td align="center"><code>cert</code></td><td>TLS/SSL certificate validity</td></tr></tbody></table>

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

```shellscript
bitoarch diagnose --bundle
```

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

```
Share this file with Bito support: support@bito.ai
```

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:**

```shellscript
bitoarch diagnose --bundle --output <dir name>
```

#### Manual troubleshooting commands

```shellscript
# "Docker has only X GB RAM allocated (6 GB recommended)"
# → Docker Desktop → Settings → Resources → Memory → 6 GB+ → Apply & Restart

# "Port 5001 is in use" — edit ~/.bitoarch/install.yaml BEFORE install:
# ports: { cis_provider: 6001, cis_manager: 6002, cis_config: 6003, mysql: 6004, cis_tracker: 6005 }

# "bitoarch: command not found" right after install
source ~/.zshrc        # or ~/.bashrc

# AI Architect not responding after a system restart
# If AI Architect stops responding after your machine has been restarted or shut down, the underlying Docker containers may have stopped. To restore:
# 1. Start Docker :  Make sure Docker Desktop (or your Docker service) is running before doing anything else.
# 2. Start the AI Architect services.
bitoarch start

# Indexing stuck
bitoarch index-status
bitoarch logs cis-manager
bitoarch stop-indexing && bitoarch index-repos

# Corporate proxy — before install
export HTTP_PROXY=http://proxy:8080 HTTPS_PROXY=http://proxy:8080
export NO_PROXY=localhost,127.0.0.1,ai-architect-config,ai-architect-manager,ai-architect-provider
curl -fsSL https://aiarchitect.bito.ai/standalone/install.sh | bash

# Defensive uninstall (CLI broken)
curl -fsSL https://aiarchitect.bito.ai/standalone/uninstall.sh | bash
```

## Available commands

For complete reference of AI Architect CLI commands, refer to [Available commands](/ai-architect/installation/install-ai-architect-self-hosted/available-commands).

#### Standalone-only commands

These exist only when `MCP_AUTO_INSTALL=true` in `.env-bitoarch` (set automatically by the Standalone install bootstrap). On Enterprise installs they are hidden from `bitoarch --help` and refuse to run.

| Command                                 | Description                                                                                                                                                    |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bitoarch mcp-install [--email <addr>]` | Re-register the local MCP with detected coding agents (Claude Code, Cursor, Windsurf, VS Code, Junie, JetBrains AI Assistant). Run after installing a new IDE. |
| `bitoarch mcp-cert status`              | Cert verdict (✓/⚠/✗), days remaining, paths, scheduler state.                                                                                                  |
| `bitoarch mcp-cert renew`               | Force re-issue cert and restart cis-provider.                                                                                                                  |
| `bitoarch mcp-cert renew --check`       | Renew only if expiring within 60 days (this is the cron entry point — not normally run by hand).                                                               |
| `bitoarch mcp-cert paths`               | Print cert path.                                                                                                                                               |
| `bitoarch mcp-cert schedule`            | Show current renew time + scheduler state.                                                                                                                     |
| `bitoarch mcp-cert schedule HH:MM`      | Set the daily auto-renew time (24h). Persists to `.env-bitoarch` as `BITOARCH_CERT_RENEW_TIME`.                                                                |

The cert auto-renews daily via an OS-native scheduler (launchd on macOS, systemd-user timer on Linux/WSL, crontab fallback). To opt out, add `BITOARCH_CERT_AUTO_RENEW=false` to `.env-bitoarch` and re-run `bitoarch install`.

#### Common commands

```shellscript
bitoarch status            # service health
bitoarch logs              # tail logs (append a service name to filter)
bitoarch mcp-info          # URL + token + auth mode
bitoarch mcp-test          # end-to-end MCP check
bitoarch mcp-install       # re-register MCP with installed coding agents (Standalone-only)
bitoarch mcp-cert --help   # cert lifecycle: status / renew / schedule (Standalone-only)

bitoarch stop
bitoarch start
bitoarch restart
bitoarch restart --force   # reload env + recreate containers
bitoarch update            # refresh images per versions/service-versions.json

bitoarch config edit
bitoarch config edit repos
bitoarch config path

bitoarch reset             # wipe state; keep install dir
bitoarch uninstall         # full removal
```


# Standalone mode vs Enterprise mode

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

[Bito's AI Architect](/ai-architect/overview) can be self-hosted in **two ways** depending on your use case. Pick the one that matches how you plan to use it:

## 1. Standalone mode (for individuals)

A lightweight, single-machine install for individual developers who want to evaluate AI Architect or use it for personal development work. It runs entirely in Docker on your local machine (e.g., laptop) and automatically registers itself with your installed coding agents — no shared infrastructure, no DevOps coordination required.

👉 [**Go to Standalone mode setup guide**](/ai-architect/installation/install-ai-architect-self-hosted/standalone-mode-for-individuals)

## 2. Enterprise mode (for teams)

A full-featured, multi-user deployment of Bito's AI Architect designed for teams who want to share a centralized knowledge graph across the organization. It supports both **Docker Compose** and **Kubernetes**, can be hosted on any on-premise or cloud infrastructure you control, and includes SSO authentication.

👉 [**Go to Enterprise mode setup guide**](/ai-architect/installation/install-ai-architect-self-hosted)

{% hint style="info" %}
**Note:** Both modes are fully self-hosted on your infrastructure — your code and knowledge graph remain entirely under your control in either case.
{% endhint %}

## Quick comparison

|                            | **Standalone mode**                                               | **Enterprise mode**                                                                                     |
| -------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Best for**               | Individual developers                                             | Teams & organizations                                                                                   |
| **Deployment target**      | Single machine (laptop/desktop)                                   | Shared server (on-prem or cloud)                                                                        |
| **Deployment mode**        | Docker Compose                                                    | Docker Compose or Kubernetes                                                                            |
| **Operating systems**      | macOS 12+, Ubuntu 20.04+                                          | macOS, Linux (Ubuntu, Debian, RHEL, etc.), Windows via WSL2                                             |
| **Shared knowledge graph** | No — per-machine only                                             | Yes — shared across the team                                                                            |
| **Authentication**         | Bearer token (local cert auto-managed)                            | Bearer Token, Bito Auth, or Enterprise IdP (SAML/OIDC)                                                  |
| **Recommended hardware**   | 8 GB+ RAM, 4+ CPUs, 50 GB+ disk                                   | 8–12 GB RAM, 6–8 cores, SSD                                                                             |
| **IDE auto-registration**  | Yes — Claude Code, Cursor, Windsurf, VS Code, Junie, JetBrains AI | Via [quick-setup installer](/ai-architect/quick-mcp-integration-with-ai-coding-agents) or manual config |

## Common prerequisites

Regardless of which mode you choose, you'll need the following before you start. Each setup guide covers these in full detail:

* A **Bito account** and **Bito Access Key** — sign up at [https://alpha.bito.ai](https://alpha.bito.ai/) and generate a key from [**Settings → Advanced settings**](https://alpha.bito.ai/home/advanced).
* A **Git Access Token** for your provider — GitHub, GitLab, Bitbucket, or Azure DevOps.
* **LLM API keys** — Bito's AI Architect uses Large Language Models (LLMs) to build a knowledge graph of your codebase. 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)
* **Docker Desktop** (or Docker Service on Linux) running on the host machine.

## Not sure which mode to pick?

* If you're a single developer trying AI Architect for the first time on your own machine, start with **Standalone mode**. It's the fastest way to get up and running.
* If you're rolling out AI Architect to a team, need a single shared knowledge graph across developers, or have requirements like Kubernetes or SSO, go with **Enterprise mode**.

{% hint style="info" %}
You can always start with **Standalone mode** to evaluate AI Architect on your own machine, and move to **Enterprise mode** later when you're ready to roll it out to your team.
{% endhint %}

### Next steps

* [**Standalone mode setup guide**](/ai-architect/installation/install-ai-architect-self-hosted/standalone-mode-for-individuals)
* [**Enterprise mode setup guide**](/ai-architect/installation/install-ai-architect-self-hosted)
* [**Available CLI commands**](/ai-architect/installation/install-ai-architect-self-hosted/available-commands)


# Local Git Provider (Pre-Cloned Repositories) — Setup Guide

[Bito's AI Architect](/ai-architect/overview) can index repositories **without any git credentials**. Instead of connecting to GitHub, GitLab, Bitbucket, or Azure DevOps, you clone your repositories yourself onto the host that runs AI Architect, and copy them in with a single command:

```shellscript
bitoarch import-repos /srv/bito-sources
```

AI Architect stores **no token, no app key, no username, and no git domain** for this provider, and nothing inside the platform ever contacts your git server — every remote is stripped from the copy it keeps.

{% hint style="info" %}
**Use this when:** your git server is unreachable from the AI Architect host (air-gapped or segmented network), your policy does not allow issuing a read token, your git server is not one of the four supported providers, or you want to index a source tree that is not in git at all.
{% endhint %}

Supported on **Docker Compose**, **Standalone**, and **Kubernetes** (single- or multi-node — no extra volume mounts, no `hostPath`, no shared `ReadWriteMany` storage).

***

### Prerequisites

* You can place repository clones on the machine that runs `bitoarch`.
* The clones live under **one parent directory**, with each repository as an **immediate subdirectory** of it.
* Each repository directory name uses only `a-z A-Z 0-9 _ . -` (these become the repository namespace).
* Every file in every repository is **readable by the user running `bitoarch`**.
* Each repository is at or under `CIS_REPO_SIZE_LIMIT` (default **5 GB**).
* The platform is **running** when you import (`bitoarch status`).

**Expected layout:**

```
/srv/bito-sources/
├── backend-api/      ← a git clone
├── web-frontend/     ← a git clone
└── shared-lib/       ← a git clone
```

This imports as three repositories: `local/backend-api`, `local/web-frontend`, and `local/shared-lib`.

***

### 1. Install with the local provider

#### Interactive install

At the git provider prompt, choose **5**:

```
Select Git provider (1) GitLab  (2) GitHub  (3) Bitbucket  (4) Azure DevOps  (5) Local (pre-cloned repos)  [1-5]: 5
```

The installer then **skips** the enterprise-domain question, the PAT/GitHub App choice, and the access-token prompt, and confirms:

```
No git credentials needed. After installation, import your pre-cloned repositories with: bitoarch import-repos <path>
```

Installation finishes with an empty repository list. You add repositories in step 2.

#### Non-interactive install

Pre-seed `~/.bitoarch/install.yaml` — omit `access_token` entirely:

```yaml
bito_api_key: "<your-bito-api-key>"
git:
  provider: local
```

`local` is the only provider for which the installer does not require a git access token.

#### Switching an existing install to local

```shellscript
bitoarch update-git-creds     # choose (5) Local (pre-cloned repos)
```

Any previously stored PAT or GitHub App key is cleared.

{% hint style="warning" %}
Repositories you configured under the **previous** provider are not local imports. Their leftover clones will fail to index until you re-import them. Remove the stale namespaces first (`bitoarch remove-repo <namespace>`), then import as below.
{% endhint %}

***

### 2. Import your repositories

```shellscript
bitoarch import-repos /srv/bito-sources
bitoarch index-repos
```

`import-repos` scans the immediate subdirectories of the path and, for each repository:

1. Checks the directory name is namespace-safe and the tree is fully readable.
2. Checks the size against `CIS_REPO_SIZE_LIMIT` *before* copying anything.
3. Registers it as namespace **`local/<directory-name>`**.
4. Copies it onto the platform's shared clone volume.
5. **Removes every git remote** from the copy, so nothing in the platform can reach your git server.

The copy is atomic: a repository is only swapped into place once it has transferred completely. A failure leaves any previously imported copy untouched.

It finishes with a summary:

```
✓ Import complete: 3 imported, 0 skipped, 0 failed (3 registered)
ℹ Run bitoarch index-repos to index the imported repositories
```

Check progress with `bitoarch index-status`, and confirm the result with `bitoarch index-repo-list` or `bitoarch repo-info backend-api`.

***

### 3. Keep repositories up to date

There is no webhook and no polling — **you** decide when AI Architect sees new commits. Pull in your source clones, then re-run the same command:

```shellscript
cd /srv/bito-sources/backend-api && git pull
bitoarch import-repos /srv/bito-sources
bitoarch index-repos
```

Re-running is the update flow and is safe to repeat:

* A repository whose `HEAD` already matches the imported copy is **skipped** (no copy, no re-index).
* A repository with new commits is re-synced and indexed **incrementally** on the next run.
* A **new** subdirectory is imported and registered automatically.

To automate it, pull and import from cron (or any scheduler) on the AI Architect host:

```shellscript
# Every night at 02:00 — refresh sources, import, index.
0 2 * * * cd /srv/bito-sources && for r in */; do git -C "$r" pull -q; done && bitoarch import-repos /srv/bito-sources && bitoarch index-repos
```

***

### 4. Source trees that are not git repositories

By default a subdirectory without a `.git` directory is skipped:

```
⚠ Skipping 'legacy-app': not a git clone (use --allow-non-git to import plain source trees)
```

To include plain source trees:

```shellscript
bitoarch import-repos /srv/bito-sources --allow-non-git
```

AI Architect synthesizes a git history inside its own copy so the indexing pipeline works normally. Your source directory is never modified. Two caveats:

* Because there is no real commit history, these repositories are **always fully re-indexed** when their contents change (never incrementally).
* An unchanged tree still keeps its identity across re-imports, so re-running the command on unchanged sources does not trigger needless re-indexing.

***

### 5. Removing a repository

```shellscript
bitoarch remove-repo local/backend-api      # deregister; index data stays until purged
bitoarch remove-index local/backend-api     # deregister + purge index data
```

`remove-repo` deliberately **keeps the imported copy** on the platform's volume so a later re-add is fast. Reclaim that disk space yourself if you do not plan to re-add the repository.

***

### What differs from a token-based provider

<table data-search="false"><thead><tr><th>Area</th><th>With local</th></tr></thead><tbody><tr><td>Credentials</td><td>None. Nothing is stored; no token to rotate or expire</td></tr><tr><td>Adding repositories</td><td><code>bitoarch import-repos &#x3C;path></code> — <strong>not</strong> <code>add-repo</code> / <code>add-repos</code> / a repos YAML</td></tr><tr><td><code>bitoarch fetch-repo-list</code></td><td>Not available — there is no remote to enumerate</td></tr><tr><td>Git Insights</td><td>Not available — it analyzes remote history and PRs. Disabled automatically at setup</td></tr><tr><td>New commits</td><td>Picked up only when you re-run <code>import-repos</code>. No webhooks, no polling</td></tr><tr><td>Namespaces</td><td>Always <code>local/&#x3C;directory-name></code> (two segments)</td></tr><tr><td>Network access</td><td>The platform never contacts your git server. All remotes are stripped from the copy</td></tr></tbody></table>

***

### Troubleshooting

<table data-search="false"><thead><tr><th>Message / symptom</th><th>What to do</th></tr></thead><tbody><tr><td><code>import-repos requires the local git provider (current: github)</code></td><td>This install uses a token-based provider. Switch with <code>bitoarch update-git-creds</code> → option 5</td></tr><tr><td><code>No running ai-architect-manager pod found</code> / a <code>docker exec</code> failure</td><td>The platform is not running. Start it with <code>bitoarch start</code>, then re-import</td></tr><tr><td><code>Cannot import 'X': not readable by &#x3C;user></code> / <code>not fully readable</code></td><td>Fix the source permissions, or re-run as a user that can read every file in that repository. The repository is skipped, not partially copied</td></tr><tr><td><code>Skipping 'X': directory name has characters not allowed in a repo namespace</code></td><td>Rename the directory using only <code>a-z A-Z 0-9 _ . -</code></td></tr><tr><td><code>Skipping 'X': not a git clone</code></td><td>Add <code>--allow-non-git</code>, or make the directory a real clone</td></tr><tr><td><code>Skipping 'X': size ... exceeds CIS_REPO_SIZE_LIMIT</code></td><td>Trim the repository, or raise <code>CIS_REPO_SIZE_LIMIT</code> in <code>.env-bitoarch</code> and restart</td></tr><tr><td><code>Could not register local/X -- is cis-config reachable?</code></td><td>Check <code>bitoarch status</code>. Once services are healthy, re-run <code>import-repos</code> — it heals partial runs</td></tr><tr><td><code>'X' is already imported at &#x3C;sha> (skipped)</code></td><td>Expected. The imported copy already matches your source <code>HEAD</code>. Pull new commits first</td></tr><tr><td>Imported, but nothing appears in results</td><td>Indexing has not run yet. <code>bitoarch index-repos</code>, then watch <code>bitoarch index-status</code></td></tr><tr><td><code>fetch-repo-list is not available for the local git provider</code></td><td>Expected. Use <code>bitoarch import-repos</code> instead</td></tr></tbody></table>

Full diagnostics: `bitoarch diagnose` produces a support bundle for <support@bito.ai>.

***

### Related environment variables

| Variable              | Meaning                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `GIT_PROVIDER`        | Set to `local` for this mode                                                                     |
| `CIS_CLONE_DIR`       | Where imported copies live inside the platform (default `/opt/bito/ai-architect/data/clone-dir`) |
| `CIS_REPO_SIZE_LIMIT` | Max indexable size per repository, in bytes (default `5368709120` = 5 GB)                        |

***

### See also

* [CLI Reference](/ai-architect/installation/install-ai-architect-self-hosted/available-commands) — all `bitoarch` commands
* [Standalone Setup Guide](/ai-architect/installation/install-ai-architect-self-hosted/standalone-mode-for-individuals)
* [Enterprise Setup Guide](/ai-architect/installation/install-ai-architect-self-hosted)


# 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.

This guide covers installing and managing plugins on an existing self-hosted deployment. If AI Architect itself is not installed yet, set it up first — see [Install AI Architect (self-hosted)](/ai-architect/installation/install-ai-architect-self-hosted).

### 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`) | Automatically analyzes new and updated Jira tickets and posts its findings back as comments — either on every change or on `@bito` mention. | Jira            |

Both plugins run on the same platform your base install already provides. Any shared infrastructure a plugin needs (such as an event bus or cache) is provisioned automatically on first use and shared across plugins.

### Prerequisites

Before installing a plugin, make sure you have:

1. **A running self-hosted AI Architect deployment.** Check with `bitoarch status`.
2. **Plugin entitlement on your plan.** Plugins are part of the Bito Enterprise plan. If your workspace is not entitled, the installer stops and tells you.
3. **A public URL that Slack or Jira can reach.** Both plugins receive events from an external service, so the plugin's endpoint must be reachable from the internet over HTTPS with a valid certificate. You provide this during setup.
4. **Access to the integration you're connecting.** Admin rights to create a Slack app (for `ai-assistant`), or a Jira account and project (for `task-analyzer`).

### How installing works

Every plugin installs with a single command that runs a short guided setup:

```bash
bitoarch plugin install <name>
```

The installer resolves shared dependencies, provisions the plugin's database, deploys the service, and then **prompts you for exactly what that plugin needs**. You don't pass values as flags — you answer the prompts, and each answer applies immediately. Check health at any time with `bitoarch plugin status <name>`, and change anything later with `bitoarch plugin config <name>` (it re-runs the same prompts). If you skip a required value, the plugin is left **pending** and the output tells you how to finish — nothing is half-installed.

The two plugins and their setup steps follow.

### Set up the Slack AI Assistant

You need admin rights to create a Slack app, and a public HTTPS URL Slack can reach. Start the install:

```bash
bitoarch plugin install ai-assistant
```

The guided setup then walks you through:

1. **Public URL.** Enter the public HTTPS address where the bot is reachable.
2. **Create the Slack app.** The setup prints a ready-to-paste Slack app manifest — your URL and every event/request URL are already filled in — and the path to the file to copy it from. Open [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From an app manifest**, paste it, and create the app.
3. **Credentials.** From the new app's **Basic Information → App Credentials**, the setup collects the Client ID, Client Secret, and Signing Secret.
4. **Install to your workspace.** Open the install link the setup prints and click **Allow** to authorize the bot in your Slack workspace.

Once it reports healthy, add the bot to a channel with **/invite @Bito**, then mention **@Bito** with a question or send it a direct message — it reads the full thread (and supported text attachments) for context. To change any of these settings later, run `bitoarch plugin config ai-assistant`, which re-runs the same steps.

### Set up the Bito Task Analyzer

You need a public HTTPS URL Jira can reach, and access to your Jira project. Start the install:

```bash
bitoarch plugin install task-analyzer
```

The guided setup then walks you through:

1. **Public URL.** Enter the public HTTPS address where the webhook receiver is reachable.
2. **Connect Jira.** If you already connected Jira for Insights, the plugin reuses that connection. Otherwise it asks for your Jira site URL, account email, and an API token (Jira Cloud) or personal access token (Jira Server/Data Center).
3. **Register the webhook.**
   * **Jira Server / Data Center:** registered automatically — nothing to do.
   * **Jira Cloud:** the setup prints a callback URL and the exact steps to add it in Jira — **Settings → System → WebHooks → Create a WebHook**, name it "Bito AI Architect", paste the URL, tick **Issue** and **Comment: created, updated, deleted**, and Save. Jira starts sending events immediately.
4. **Respond mode.** Choose when tickets are analyzed: **on-demand** (the default) analyzes a ticket only when a comment mentions **@bito** or **/bito**; **auto** analyzes every new or updated ticket.
5. **Projects.** Choose whether the analyzer watches all Jira projects or only specific ones.

To change the respond mode, watched projects, or the Jira connection later, run `bitoarch plugin config task-analyzer`, which re-runs the same steps.

### View or change a plugin's settings

```bash
bitoarch plugin config <name>
```

This shows the plugin's current configuration and walks you through the same setup prompts, so you can update the public URL, credentials, connection, or any plugin-specific option. Changes apply immediately.

### Keep plugins up to date

```bash
bitoarch plugin upgrade <name>
```

Upgrades are atomic and preserve your configuration and data. If an upgrade needs a credential you haven't provided, it holds and tells you what to add rather than starting a broken version. Installed plugins are also checked for updates daily, while at least one plugin is installed.

### Manage plugins

```bash
bitoarch plugin list              # installed plugins and versions
bitoarch plugin status            # health of all plugins
bitoarch plugin stop <name>       # pause (keeps config + data)
bitoarch plugin start <name>      # resume
bitoarch plugin uninstall <name>  # remove the service, keep data + config
```

By default, uninstalling **keeps** the plugin's database and configuration, so reinstalling restores your setup. To also delete them, add `--purge` — on purge, Bito Task Analyzer additionally removes the webhook it registered in your self-hosted Jira.

The base lifecycle commands are plugin-aware: `bitoarch stop`, `start`, `restart`, and `update` include your installed plugins automatically.

### Troubleshooting

| Symptom                        | What to check                                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Plugin shows **pending**       | A required value was not provided. Run `bitoarch plugin config <name>` to add it, then `bitoarch plugin start <name>`.                      |
| **Not healthy** after install  | `bitoarch plugin status <name>` shows the live state. Confirm required credentials are set and the service can start.                       |
| Slack/Jira events not arriving | Confirm your public URL is reachable from the internet and matches the request/webhook URL configured in Slack or Jira.                     |
| Need a support bundle          | `bitoarch diagnose --bundle` collects a shareable diagnostics archive with per-plugin logs and masked configuration (secrets are redacted). |

### Command reference

<table data-search="false"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><code>bitoarch plugin install &#x3C;name></code></td><td>Install a plugin and run guided setup.</td></tr><tr><td><code>bitoarch plugin config &#x3C;name></code></td><td>View settings and reconfigure interactively.</td></tr><tr><td><code>bitoarch plugin status [&#x3C;name>]</code></td><td>Show plugin health and services.</td></tr><tr><td><code>bitoarch plugin list</code></td><td>List installed plugins and versions.</td></tr><tr><td><code>bitoarch plugin upgrade &#x3C;name></code></td><td>Upgrade a plugin to the latest version.</td></tr><tr><td><code>bitoarch plugin start &#x3C;name></code> / <code>stop &#x3C;name></code></td><td>Resume or pause a plugin.</td></tr><tr><td><code>bitoarch plugin uninstall &#x3C;name></code></td><td>Remove a plugin (keeps data; add <code>--purge</code> to delete it).</td></tr></tbody></table>

## FAQs

#### Can I install just one plugin?

Yes. Each plugin is independent. A customer can install either or both.

#### What if I remove a plugin?

Uninstalling keeps the plugin's data and configuration by default, so reinstalling restores everything. A full purge is available if you want a clean removal.

#### Does this require new servers or hardware?

No. Plugins run on the same infrastructure the user already deployed for AI Architect. However the minimum server requirements has slightly modified.

#### Are plugins updated separately from the base platform?

Yes. Plugins have their own version and can be upgraded independently via `bitoarch plugin upgrade`. A base platform upgrade also upgrades any installed plugins automatically.

#### Does this work with Jira Server / Data Center (not just Cloud)?

Yes. The Task Analyzer supports Jira Cloud, Jira Server, and Jira Data Center. Self-hosted Jira gets automatic webhook registration; Cloud requires one manual step due to technical constraint.


# Available commands

CLI commands for installing, operating, and maintaining Bito's AI Architect.

Quick reference for `bitoarch` CLI commands used to configure and manage [**Bito's AI Architect**](/ai-architect/overview).

{% hint style="info" %}
**Note:** After [installation of AI Architect (self-hosted)](/ai-architect/installation/install-ai-architect-self-hosted), the `bitoarch` command is available globally. All commands support `--help` for per-command usage.
{% endhint %}

## Lifecycle

Commands used to control the lifecycle of AI Architect.

| `bitoarch start`             | For recovery if AI Architect services stopped/killed due to system issues |
| ---------------------------- | ------------------------------------------------------------------------- |
| `bitoarch stop`              | Stop all services (keeps data)                                            |
| `bitoarch restart [--force]` | Restart services. `--force` reloads env and recreates containers          |
| `bitoarch logs [service]`    | Tail service logs (`-f`). All services if `service` omitted               |
| `bitoarch update`            | Refresh service images per `versions/service-versions.json`               |
| `bitoarch reset`             | Remove services, volumes, and config. Keeps install directory             |
| `bitoarch uninstall`         | Full removal (services + install directory)                               |

**Examples:**

```shellscript
bitoarch restart --force            # reload env + recreate containers
bitoarch logs cis-provider          # tail one service
```

## AI Architect management commands

Use these `bitoarch` commands to manage AI Architect.

### Core operations

| Command                                          | Description                                                                                             | Example                                 |                                            |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------ |
| `bitoarch index-repos [--only-new-repos]`        | Trigger workspace repository indexing. Use `--only-new-repos` to index only newly added repositories    | `bitoarch index-repos --only-new-repos` |                                            |
| `bitoarch index-status [--raw] [--output json]`  | Check indexing status. `--raw` dumps the full API response; `--output json` emits machine-readable JSON | View progress and state                 |                                            |
| `bitoarch pause-indexing`                        | Pause ongoing indexing process                                                                          | `bitoarch pause-indexing`               |                                            |
| `bitoarch resume-indexing`                       | Resume paused indexing process                                                                          | `bitoarch resume-indexing`              |                                            |
| `bitoarch stop-indexing`                         | Stop indexing completely                                                                                | `bitoarch stop-indexing`                |                                            |
| \`bitoarch index-repo-list \[--status \<active\\ | all>] \[--limit <N>]\`                                                                                  | List indexed repositories               | `bitoarch index-repo-list --status active` |
| `bitoarch show-config`                           | Show current indexing configuration                                                                     | `bitoarch show-config --raw`            |                                            |
| `bitoarch create-index-scheduler`                | Create scheduled indexing tasks                                                                         |                                         |                                            |
| `bitoarch update-index-scheduler`                | Update existing scheduled indexing tasks                                                                |                                         |                                            |

**Examples:**

```shellscript
# Trigger repository indexing
bitoarch index-repos

# Check indexing status (default summary)
bitoarch index-status

# Full API response for debugging
bitoarch index-status --raw

# Machine-readable filtered JSON
bitoarch index-status --output json

# List all repositories
bitoarch index-repo-list --status active --limit 50
```

{% hint style="info" %}
One indexing job runs per workspace at a time. If you add a repo mid-run, re-trigger `bitoarch index-repos` after the current job finishes.
{% endhint %}

***

### Repository management

| Command                                      | Description                                                                      | Example                                    |
| -------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------ |
| `bitoarch add-repo <namespace>`              | Add single repository                                                            | `bitoarch add-repo myorg/myrepo`           |
| `bitoarch remove-repo <namespace>`           | Remove repository                                                                | `bitoarch remove-repo myorg/myrepo`        |
| `bitoarch add-repos [file]`                  | Load repos from YAML. Uses `.bitoarch-config.yaml` if `file` omitted             | `bitoarch add-repos`                       |
| `bitoarch update-repos [file]`               | Update repos from YAML. Uses `.bitoarch-config.yaml` if `file` omitted           | `bitoarch update-repos`                    |
| `bitoarch repo-info <name> [--dependencies]` | Show repository details (add `--dependencies` to include incoming/outgoing deps) | `bitoarch repo-info myrepo --dependencies` |
| `bitoarch fetch-repo-list [--force-load]`    | Sync repo list from your git provider. `--force-load` ignores local cache        | `bitoarch fetch-repo-list`                 |

**Examples:**

```shellscript
# Add a single repository
bitoarch add-repo myorg/myrepo

# Remove a repository
bitoarch remove-repo myorg/myrepo

# Load multiple repositories from default config file
bitoarch add-repos

# Load multiple repositories from a custom config file
bitoarch add-repos ./custom-repos.yaml

# Update configuration
bitoarch update-repos

# Get repository details
bitoarch repo-info myrepo
```

***

### Service operations

| Command           | Description                  | Example                     |
| ----------------- | ---------------------------- | --------------------------- |
| `bitoarch status` | View all services status     | Docker ps-like output       |
| `bitoarch health` | Check health of all services | `bitoarch health --verbose` |
| `bitoarch info`   | Get platform information     | Version, ports, resources   |

**Examples:**

```shellscript
# Check service status (docker ps-like)
bitoarch status

# Health check
bitoarch health

# Detailed health information
bitoarch health --verbose

# Platform information
bitoarch info
```

***

### Configuration

| Command                                   | Description                                                  | Example                                                            |                                                           |   |
| ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------- | - |
| `bitoarch update-api-key`                 | Update Bito API key                                          | Interactive or with `--api-key [--restart]` flag                   |                                                           |   |
| `bitoarch update-git-creds`               | Update Git provider credentials                              | Interactive or with `--provider <p> --token <t> [--restart]` flags |                                                           |   |
| `bitoarch update-llm-keys`                | Update LLM API keys                                          | Interactive prompt                                                 |                                                           |   |
| `bitoarch rotate-mcp-token [<new-token>]` | Rotate MCP access token. Omit `<new-token>` to auto-generate | `bitoarch rotate-mcp-token <new-token>`                            |                                                           |   |
| \`bitoarch config path \[env\\            | repos\\                                                      | llm]\`                                                             | Print the absolute path of a config file (default: `env`) |   |
| \`bitoarch config edit \[env\\            | repos\\                                                      | llm]\`                                                             | Open a config file in `$EDITOR` (default: `env`)          |   |

**Config file types:**

| `env`   | `.env-bitoarch`         | Main environment config (ports, credentials, secrets) |
| ------- | ----------------------- | ----------------------------------------------------- |
| `repos` | `.bitoarch-config.yaml` | Repository list                                       |
| `llm`   | `.env-llm-bitoarch`     | Custom LLM provider configuration                     |

**Examples:**

```shellscript
# Update API key (interactive)
bitoarch update-api-key

# Update API key with flag
bitoarch update-api-key --api-key <key> --restart

# Update Git credentials (interactive)
bitoarch update-git-creds

# Update Git credentials with flags
bitoarch update-git-creds --provider github --token <token> --restart

# Update LLM API keys
bitoarch update-llm-keys

# Rotate MCP token - auto-generates a new MCP token
bitoarch rotate-mcp-token

# Rotate MCP token - set a specific MCP token manually
bitoarch rotate-mcp-token <new-token>

# prints path to .bitoarch-config.yaml
bitoarch config path repos

# edit .env-bitoarch
bitoarch config edit env
```

***

### MCP operations

| Command                                                        | Description                       | Example                                          |
| -------------------------------------------------------------- | --------------------------------- | ------------------------------------------------ |
| `bitoarch mcp-test`                                            | End-to-end MCP connectivity check | Verify server connectivity                       |
| `bitoarch mcp-tools [--details] [--summary] [--output <file>]` | List available MCP tools          | `bitoarch mcp-tools --details`                   |
| `bitoarch mcp-capabilities [--output <file>]`                  | Show MCP server capabilities      | `bitoarch mcp-capabilities --output caps.json`   |
| `bitoarch mcp-info`                                            | Show MCP configuration            | Show MCP URL, access token, and active auth mode |
| `bitoarch mcp-tool-info <name>`                                | Show details for one MCP tool     | `bitoarch mcp-tool-info search_code`             |

**Examples:**

```shellscript
# Test MCP connection
bitoarch mcp-test

# List MCP tools
bitoarch mcp-tools

# Show detailed tool information
bitoarch mcp-tools --details

# Get server capabilities
bitoarch mcp-capabilities

# Save capabilities to file
bitoarch mcp-capabilities --output capabilities.json

# Show MCP configuration
bitoarch mcp-info

# Show details for one MCP tool (e.g. search_code)
bitoarch mcp-tool-info search_code
```

***

### SSO authentication

SSO is optional and disabled by default (bearer-token auth). When enabled, `bitoarch mcp-info` reflects the active auth mode.

| Command                   | Description                                                                                                                                                                                                                                                                        |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bitoarch sso setup`      | This command will guide you through the SSO configuration process, including choosing between Enterprise IdP and Bito authentication                                                                                                                                               |
| `bitoarch sso status`     | Displays the current SSO configuration and IdP connection status                                                                                                                                                                                                                   |
| `bitoarch sso enable`     | Re-enable SSO after it has been temporarily disabled                                                                                                                                                                                                                               |
| `bitoarch sso disable`    | You can disable SSO either temporarily or permanently. Choose temporary to turn off SSO authentication but preserve IdP configuration (can re-enable with `bitoarch sso enable`), or permanent to remove IdP configuration entirely (requires `bitoarch sso setup` to reconfigure) |
| `bitoarch sso rotate-key` | Rotate SSO management key for security purposes. Important: After rotating the key, SSO services will restart automatically. Active sessions may need to re-authenticate                                                                                                           |

**Auth modes:**

| Bearer Token   | Default — static MCP access token (SSO disabled)       |
| -------------- | ------------------------------------------------------ |
| Bito           | SSO via Bito — no external IdP required                |
| Enterprise IdP | SSO via your SAML/OIDC provider (Okta, Azure AD, etc.) |

***

### Diagnostics

| Command                      | Description                                                              | Example                       |
| ---------------------------- | ------------------------------------------------------------------------ | ----------------------------- |
| `bitoarch diagnose`          | Run a live health sweep across all services                              | `bitoarch diagnose --verbose` |
| `bitoarch diagnose --bundle` | Collect a full diagnostics bundle into a `.tar.gz` to share with support | `bitoarch diagnose --bundle`  |

**Flags:**

| Flag               | Description                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `--verbose`, `-v`  | Show URLs, ports, and detail on failures (live sweep only)                                             |
| `--section <name>` | Run one section only: `prereqs`, `install`, `filesystem`, `config`, `services`, `connectivity`, `cert` |
| `--bundle`         | Produce a shareable `.tar.gz` support bundle                                                           |

**Examples:**

```shellscript
# Live health sweep
bitoarch diagnose

# Show additional detail (URLs, ports, failure info)
bitoarch diagnose --verbose

# Check one section only
bitoarch diagnose --section services

# Generate a support bundle
bitoarch diagnose --bundle
```

***

### Output options

Add these flags to any command:

| Flag            | Purpose                | Example                |
| --------------- | ---------------------- | ---------------------- |
| `--format json` | JSON output            | For automation/scripts |
| `--raw`         | Show full API response | For debugging          |
| `--output json` | Filtered JSON output   | For `index-status`     |
| `--help`        | Show command help      | Get usage information  |

***

### Common workflows

#### Initial setup

```shellscript
# 1. Check services are running
bitoarch status

# 2. Add repositories - load repos from .bitoarch-config.yaml file
bitoarch add-repos

# 3. Trigger indexing
bitoarch index-repos

# 4. Monitor progress
bitoarch index-status

# 5. Grab MCP URL + token for your client
bitoarch mcp-info
```

#### Daily operations

```shellscript
# Check health
bitoarch health

# View repositories
bitoarch index-repo-list

# Check index status
bitoarch index-status
```

#### Adding new repositories

```shellscript
# Single repository
bitoarch add-repo myorg/newrepo

# Multiple repositories from config file
bitoarch add-repos

# Trigger re-indexing
bitoarch index-repos --only-new-repos
```

#### Credential rotation

```shellscript
# Update Bito API key
bitoarch update-api-key

# Update Git provider credentials
bitoarch update-git-creds

# Rotate MCP access token
bitoarch rotate-mcp-token

# Rotate SSO management key for security purposes.
# only if SSO is enabled
bitoarch sso rotate-key
```

#### Tear-down

```shellscript
# pause services
bitoarch stop

# remove services + volumes + config (keeps install dir)
bitoarch reset

# full removal
bitoarch uninstall
```

#### Troubleshooting

```shellscript
# Check all services
bitoarch status
bitoarch health --verbose

# View full configuration
bitoarch show-config --raw

# Test MCP connection
bitoarch mcp-test

# Check indexing status with details
bitoarch index-status --raw

# Check logs of all services
bitoarch logs

# Check logs of one service
bitoarch logs cis-manager

# Generate a full diagnostics bundle to share with support
bitoarch diagnose --bundle
```

***

### Getting help

| Command                     | Shows                            |
| --------------------------- | -------------------------------- |
| `bitoarch --help` \| `-h`   | Top-level help with all commands |
| `bitoarch <command> --help` | Command-specific usage and flags |

**Examples:**

```shellscript
# Main help
bitoarch --help

# Command help
bitoarch index-repos --help
bitoarch add-repo --help
bitoarch mcp-tools --help
```

***

### Environment

Configuration is loaded from `.env-bitoarch` file. (path: `bitoarch config path env`)

**Key variables:**

| Variable                     | Purpose                                        |
| ---------------------------- | ---------------------------------------------- |
| `BITO_API_KEY`               | Bito authentication key                        |
| `GIT_PROVIDER`               | Git provider (`github`, `gitlab`, `bitbucket`) |
| `GIT_ACCESS_TOKEN`           | Git personal access token                      |
| `BITO_MCP_ACCESS_TOKEN`      | MCP server access token                        |
| `CIS_PROVIDER_EXTERNAL_PORT` | MCP server port (default 8080 for k8s)         |
| `CIS_MANAGER_EXTERNAL_PORT`  | Manager API port                               |
| `CIS_CONFIG_EXTERNAL_PORT`   | Config API port                                |
| `CIS_TRACKER_EXTERNAL_PORT`  | Tracker API port                               |
| `MYSQL_EXTERNAL_PORT`        | MySQL external port                            |

{% hint style="info" %}
**Note:** See `.env-bitoarch.default` in the install directory for the full list with defaults.
{% endhint %}

***

### Version

Check CLI version:

```shellscript
bitoarch --version
```


# Quick MCP integration with AI coding agents

Connect Bito's AI Architect to your AI coding tools (Cursor, Claude Code, Windsurf, etc.) in seconds with our automated installer

## Prerequisites

Before running the installer, have these ready:

1. **Set up AI Architect** — AI Architect can be set up using one of the following deployment options:
   1. [**Bito-hosted**](/ai-architect/installation/install-ai-architect-bito-hosted) (Fully managed by Bito — no infrastructure setup required)
   2. [**Self-hosted**](/ai-architect/installation/install-ai-architect-self-hosted) (Run AI Architect on your own infrastructure for maximum control)
2. Your **Bito Workspace ID** or full **Bito MCP URL**
   1. You can find your **Bito MCP URL** on the [**AI Architect settings > MCP settings**](https://alpha.bito.ai/home/ai-architect/settings) page.
   2. You can find your **Bito Workspace ID** on the [**Workspace settings**](https://alpha.bito.ai/home/advance-settings) page.
3. Your **Bito MCP Access Token** — **optional**. If omitted, the installer configures the MCP client to complete SSO/OAuth against the server on first use. Most modern IDE MCP clients (Claude Code, Cursor, Windsurf, VS Code, Junie, JetBrains via `mcp-remote`) support this. Bito MCP advertises OAuth 2.1 discovery (PKCE, Dynamic Client Registration) at `https://mcp.bito.ai/{workspace}/.well-known/oauth-authorization-server`.

{% hint style="info" %}
Note: For self-hosted instances, follow the [**self-hosted AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter.
{% endhint %}

3. Your **email ID** (for tracking/identification)
4. At least one supported tool installed:
   * Claude Code
   * Cursor
   * Windsurf
   * VS Code (GitHub Copilot)
   * GitHub Copilot CLI
   * Junie
   * Google Antigravity (IDE + agy CLI)
   * JetBrains AI Assistant
   * OpenAI Codex CLI

{% hint style="info" %}
**Note:** For [Claude.ai (Web)](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-claude.ai-web) , [Claude Desktop](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-claude-desktop), and [ChatGPT (Web & Desktop)](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-chatgpt-web-and-desktop) you'll need to follow the manual setup process as they require OAuth authentication through your web browser.
{% endhint %}

## Installation guide

Our automated installer will prompt you for credentials and automatically configure all supported AI tools available on your system.

### macOS / Linux

Open your terminal and run:

```bash
curl -fsSL https://mcp-setup.bito.ai/install.sh | bash
```

### Windows

Run in **PowerShell** (not Command Prompt).

**1. One-time PowerShell setup (first time only):**

By default, PowerShell blocks scripts from running. Run this once to allow signed scripts to execute:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Per-user, no admin required.

**2. Run the installer:**

```powershell
irm https://mcp-setup.bito.ai/install.ps1 | iex
```

The script will prompt you for credentials and automatically configure all detected IDEs.

{% hint style="info" %}
**Note:** When using a self-hosted AI Architect, ensure that the MCP server is up and running before proceeding with the setup. The setup will fail if MCP is not running.
{% endhint %}

## What happens next

1. **The installer downloads the necessary files** and checks for compatible tools
2. **You'll be prompted** to enter your credentials
   * Refer to the [Prerequisites](#prerequisites) section for more details.
3. **Automatic configuration** - All detected tools are configured
4. **Agent skills installed** - [Agent skills](/ai-architect/agent-skills) are downloaded and installed for your configured tools

{% hint style="info" %}
Learn more about [available Agent skills](/ai-architect/agent-skills).
{% endhint %}

{% hint style="info" %}
**Note:** [Agent skills](/ai-architect/agent-skills) auto-sync daily (and on every Claude Code session start)
{% endhint %}

4. **Guidelines configured** - Bito's AI Architect [guidelines file](https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md) is automatically configured globally on Claude Code and Windsurf. To apply guidelines at the project level, see the [Add guidelines](#add-guidelines-optional-but-highly-recommended) section below.
5. **Confirmation** - You'll see which tools were successfully set up

## After installation

{% stepper %}
{% step %}

### Restart your AI tool

After the installer completes, **completely close and reopen your IDE(s)** to ensure the configuration takes effect.
{% endstep %}

{% step %}

### Verify AI architect connection

Check that AI Architect appears in your tool's MCP server list:

* **Claude Code:** Run `claude mcp list`
* **GitHub Copilot CLI:** Run `copilot mcp list` (or `/mcp` in a copilot session)
* **OpenAI Codex CLI:** Run `codex mcp list` (or `/mcp` in a codex session)
* **Cursor:** Settings → MCP → Check server list
* **Windsurf:** Settings → Cascade → MCP Servers
* **VS Code:** Copilot Chat → Tools icon
* **Junie:** Settings → Tools → Junie → MCP Settings
* **Antigravity (IDE + agy CLI):** Click "..." menu > MCP Servers > View raw config, or run `/mcp` in agy
* **JetBrains AI Assistant:** Settings → Tools → AI Assistant → Model Context Protocol
  {% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md) contains best practices, usage instructions, and prompting guidelines for the Bito's AI Architect MCP server. Adding it to your project helps your AI coding agent interact with Bito's AI Architect more effectively and get better results out of every query.

**If you are on Claude Code or Windsurf**, the installer automatically adds the guidelines file globally, covering all your projects. If you'd also like to apply guidelines at the project level for a specific project, run the relevant command below inside that project directory.

**If you are on Cursor, VS Code (GitHub Copilot), Junie, or JetBrains AI Assistant**, guidelines are not configured automatically by the installer. Run the relevant command below manually inside each project directory where you want the guidelines to apply. This is a per-project step, so repeat it whenever you start working in a new project.

To add Bito's AI Architect guidelines to your project, run the following commands based on your coding agent:

**Claude Code:**

```shellscript
cd /path/to/your/project
curl -sSL "https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md" -o CLAUDE.md
```

**Cursor:**

```shellscript
cd /path/to/your/project
curl -sfL "https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md" -o .cursorrules
```

**Windsurf:**

```shellscript
cd /path/to/your/project
mkdir -p .windsurf/rules
curl -sfL "https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md" -o .windsurf/rules/bitoai-architect.md
```

**VS Code (GitHub Copilot):**

```shellscript
cd /path/to/your/project
mkdir -p .github
curl -sfL "https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md" -o .github/copilot-instructions.md
```

**Junie:**

```shellscript
cd /path/to/your/project
mkdir -p .junie
curl -sfL "https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md" -o .junie/guidelines.md
```

**JetBrains AI Assistant:**

```shellscript
cd /path/to/your/project
mkdir -p .aiassistant/rules
curl -sfL "https://mcp-setup.bito.ai/BitoAIArchitectGuidelines.md" -o .aiassistant/rules/bitoai-architect.md
```

{% hint style="info" %}
**Note:** guidelines file auto-sync daily (and on every Claude Code session start)
{% endhint %}
{% endstep %}

{% step %}

### Run a test query

Open a chat or conversation in your AI tool and try a test query to confirm AI Architect is working:

* `"What repositories are available in my organization?"`
* `"Show me all Python repositories"`
* `"List the available tools"`
* `"What are the dependencies of [repo-name]?"`
* `"Find all microservices using Redis"`
* `"Show me repository clusters in our organization"`
* `"Plan a new feature for [component]"`&#x20;
  * *(uses **bito-feature-plan** skill)*
* `"Write a PRD for [feature]"`&#x20;
  * *(uses **bito-prd** skill)*
* `"Help me triage this production issue"`&#x20;
  * *(uses **bito-production-triage** skill)*

If you receive accurate responses about your codebase, the setup is complete!

{% hint style="info" %}
Learn more about [available Agent skills](/ai-architect/agent-skills).
{% endhint %}

{% hint style="info" %}
**Note:** [Agent skills](/ai-architect/agent-skills) auto-sync daily (and on every Claude Code session start)
{% endhint %}
{% endstep %}
{% endstepper %}

## Uninstalling

To remove Bito AI Architect from all tools:

#### macOS / Linux

Open your terminal and run:

```bash
curl -fsSL https://mcp-setup.bito.ai/uninstall.sh | bash
```

#### Windows

Run in **PowerShell** (not Command Prompt).

If you haven't already done so during install, run this once to allow signed scripts:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

After that run the following command:

```powershell
irm https://mcp-setup.bito.ai/uninstall.ps1 | iex
```

## Need manual setup?

If you prefer to configure tools individually or need to set up web-based tools (Claude.ai, ChatGPT), refer to our detailed integration guides:

* [Claude Code](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-claude-code)
* [Claude Desktop](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-claude-desktop)
* [Claude.ai (Web)](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-claude.ai-web)
* [Cursor](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-cursor)
* [Windsurf](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-windsurf)
* [GitHub Copilot (VS Code)](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-github-copilot-vs-code)
* [Junie](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-junie-jetbrains)
* [JetBrains AI Assistant](/ai-architect/integrating-ai-architect-with-your-tools/manual-mcp-integration-with-ai-coding-agents/guide-for-jetbrains-ai-assistant)
* [ChatGPT (Web & Desktop)](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-chat-agents/guide-for-chatgpt-web-and-desktop)

## Troubleshooting

#### Installer issues

**"Command not found" or similar errors:**

* Verify you're using the correct shell (bash for macOS/Linux, PowerShell for Windows)
* Check your internet connection
* Try running the command again

**No tools detected:**

* Ensure your AI tools are installed before running the installer
* The installer only configures tools it can detect on your system
* You can run the installer again after installing new tools

#### Connection issues

* Verify **Bito MCP URL** and **Bito MCP Access Token** are correct.
* Test endpoint with MCP protocol:

```bash
curl -s -X POST \
  -H "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' \
  <Your-Bito-MCP-URL>

# Should return HTTP 200 with JSON response for valid credentials
# HTTP 401: Invalid Bito MCP Access Token
# HTTP 404: Invalid Bito MCP URL
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
  {% endhint %}

**Server not appearing after install:**

* Completely restart your AI tool (don't just reload)
* Verify your credentials were entered correctly
* Check that you have the minimum required versions (see below)

#### Minimum requirements

Some tools require specific versions:

* **Node.js 20.18.1+** for Claude Desktop, VS Code, and JetBrains
* **VS Code 1.99+** with Agent Mode enabled
* **JetBrains 2025.1+** with AI Assistant plugin 251.26094.80.5+

**Check Node.js version:**

```bash
node --version
```

If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/)

#### Skills not appearing

If skills are not visible in your IDE after installation:

1. Verify files exist: `ls ~/.claude/skills/bito-*/SKILL.md` (Claude) or `ls ~/.cursor/rules/bito-*.mdc` (Cursor)
2. Restart your IDE completely
3. Check that `jq` is installed (required for manifest parsing): `jq --version`
4. Re-run the install script — skills installation is idempotent

#### Hooks not working

If hooks are not triggering:

1. Verify your IDE version supports hooks (Cursor hooks are in beta, VS Code hooks are preview)
2. Check that the hook configuration wasn't overwritten by another tool
3. Re-run the install script to restore hook configuration


# Bito's AI Architect plugin for Claude Code

Bito's AI Architect plugin brings cross-repository intelligence to Claude Code. Search code, explore dependencies, analyze architecture, and discover patterns across all your organization's repositories. Use it to build implementation plans, write requirements documents, diagnose production issues, and understand complex codebases.

It enables users to explore and understand any codebase — from high-level architecture to line-level code traces — calibrated for multiple personas (Developer, EM, PM, VP, CTO).

**Key capabilities:**

* Deep codebase exploration across multiple repositories
* AI-powered architecture analysis and documentation
* Production incident triage with blast radius mapping
* Feature planning grounded in real system context

## Installation

#### Step 1: Add the marketplace

Run this command in Claude Code:

```bash
/plugin marketplace add gitbito/claude-plugins
```

#### Step 2: Install the plugin

```bash
/plugin install bito-ai-architect@bito-claude-plugins
```

#### Step 3: Configure your credentials

Run the interactive setup:

```bash
/bito-ai-architect:bito-setup
```

This command guides you through configuring your workspace ID, bearer token, and email.

**Alternative: manual configuration**

Set these environment variables manually:

```bash
export BITO_WORKSPACE_ID="your-workspace-id"
export BITO_MCP_TOKEN="your-bearer-token"
export BITO_EMAIL="your-email@company.com"
```

After configuration, restart Claude Code and run `/mcp` to verify the server is connected.

## Available commands

Once installed, access these slash commands in Claude Code:

| Command                                | Description                                                                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/bito-ai-architect:bito-setup`        | Configure credentials interactively                                                                                                                                                                                             |
| `/bito-ai-architect:codebase-explorer` | Explore and understand any codebase from high-level architecture to line-level code traces. Uses "The One Test" methodology with a 4-phase exploration workflow calibrated for different personas (Developer, EM, PM, VP, CTO). |
| `/bito-ai-architect:feature-plan`      | Build a detailed implementation plan for complex features with cross-repo context                                                                                                                                               |
| `/bito-ai-architect:prd`               | Write a Product Requirements Document grounded in real system context                                                                                                                                                           |
| `/bito-ai-architect:trd`               | Produce a Technical Requirements Document by analyzing existing architecture                                                                                                                                                    |
| `/bito-ai-architect:production-triage` | Diagnose production incidents with cross-repo context and blast radius mapping                                                                                                                                                  |
| `/bito-ai-architect:epic-to-plan`      | Convert an approved epic or PRD into a complete, sprint-ready implementation plan                                                                                                                                               |
| `/bito-ai-architect:feasibility`       | Produce a go/no-go feasibility and impact analysis before committing to implementation                                                                                                                                          |
| `/bito-ai-architect:scope-to-plan`     | Convert any approved work item into a complete, sprint-ready implementation plan                                                                                                                                                |
| `/bito-ai-architect:spike`             | Conduct a structured technical investigation when the team doesn't know enough to plan                                                                                                                                          |

## Getting started

#### Explore a codebase

Use the codebase explorer to understand any repository:

```bash
/bito-ai-architect:codebase-explorer
```

The explorer uses a 4-phase workflow to analyze architecture, dependencies, and code patterns. Choose your persona (Developer, EM, PM, VP, CTO) to get insights calibrated to your role.

#### Plan a feature

Create an implementation plan with cross-repo context:

```bash
/bito-ai-architect:feature-plan
```

The plugin analyzes your codebase to identify affected components, dependencies, and potential conflicts.

#### Triage production issues

Diagnose incidents across repositories:

```bash
/bito-ai-architect:production-triage
```

Get cross-repo context and blast radius mapping to understand the full impact of production issues.

## GitHub repository

* <https://github.com/gitbito/claude-plugins>


# Integrating AI Architect with your tools


# Integrating with Jira

Connect Bito's AI Architect with Jira for feasibility analysis, technical design, and cross-repo impact assessment.

Planning is where engineering teams lose the most time. This is where [**AI Architect**](/ai-architect/overview) starts.

Senior engineers and tech leads spend hours on work that should take minutes, reading through old tickets to understand what went wrong before, figuring out what a one-line Epic description actually requires, mapping out which services will be affected and which ones have been fragile in the past.

AI Architect automates this work inside Jira. When an Epic or Story is created, AI Architect posts a detailed implementation plan directly as a comment on the ticket. Feasibility analysis, story breakdown, risk warnings, historical patterns from your team's own tickets — all generated in minutes, right where your team plans.

{% embed url="<https://www.youtube.com/watch?v=FLik7gCd2iI>" %}

## What gets posted on your ticket

When AI Architect analyzes an Epic or Story, it produces a structured Markdown implementation plan that covers:

* **Feasibility assessment** — Is this viable given your current architecture? Which services are involved, and how stable are they? What's the blast radius if something goes wrong?
* **Story breakdown** — For Epics, a full decomposition into Stories with acceptance criteria, dependencies, and recommended execution order across sprints.
* **Effort estimates** — Both traditional and agentic estimates, with a breakdown of where AI tooling saves the most time and where it doesn't.
* **Proactive risk detection** — Race conditions in concurrent flows, memory leak patterns, regression-prone areas, API rate-limiting gaps, security concerns. Each risk comes with a suggested mitigation drawn from your team's actual history.
* **Historical pattern insights** — AI Architect references past tickets to flag issues your team has already encountered. For example: *"A similar concurrency issue took 3 sprints to resolve in PROJ-456 — consider redesigning the locking strategy before implementing this."*
* **Open questions** — Technical decisions that need to be made before implementation begins, so they don't surface mid-sprint.

The plan is in Markdown. Engineers can paste it directly into Cursor, Claude Code, or any other coding agent to start implementation with full architectural context already loaded.

{% hint style="info" %}
**Note:** Confluence pages linked to Jira tickets are now automatically pulled as context for plan generation.
{% endhint %}

## Setup

{% stepper %}
{% step %}

### Enable AI Architect for your workspace

AI Architect can be set up using one of the following deployment options:

#### Bito-hosted

AI Architect is managed and maintained by Bito.

* Follow the [Bito-hosted installation guide](/ai-architect/installation/install-ai-architect-bito-hosted) to get started.
* If AI Architect isn't already active for your workspace, contact the Bito team at <support@bito.ai> to enable it.

#### Self-hosted

AI Architect is deployed and managed within your own infrastructure.

* Follow the [self-hosted installation guide](/ai-architect/installation/install-ai-architect-self-hosted) to set up and configure AI Architect for your workspace.
  {% endstep %}

{% step %}

### Connect Jira

Bito supports two ways to connect with Jira, depending on where your Jira instance is hosted:

1. **Jira Cloud:** for Jira sites hosted by Atlassian (e.g., `https://mycompany.atlassian.net`).
2. **Jira Data Center:** for Jira instances hosted on your own company domain or servers (e.g., `https://jira.mycompany.com`).

#### Connect Bito with Jira Cloud (hosted by Atlassian)

1. Navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page in your Bito dashboard
2. In the **Available integrations** section, you will see **Jira**. Click **Connect** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F3CZMMaEyZPfUIVmXj9TR%2Fscrnli_g0VBZ5rxF23pB8.png?alt=media&amp;token=5e5698dd-21bf-4ea5-bc6d-97c8d91caa19" alt=""><figcaption></figcaption></figure>

3. Select the option **Jira Cloud**. You will be redirected to the official Jira website, where you need to grant Bito access to your Atlassian account.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FU7e2oetORqHLPSAursIe%2Fscrnli_7GyIUpccQ28JNw.png?alt=media&amp;token=241ab4ca-55fd-4d6e-8da0-2357392418e0" alt=""><figcaption></figcaption></figure>

4. Click **Accept** to continue. If the integration is successful, you will be redirected back to Bito.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fupzqg1J4kkj1ciUwpR5f%2Fscrnli_wwLM5Or9W2duxG.png?alt=media&amp;token=f1d47480-1efb-4373-b72d-d01bc6c6c005" alt=""><figcaption></figcaption></figure>

#### Connect Bito with Jira Data Center (hosted on your own server)

1. Navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page in your Bito dashboard
2. In the **Available integrations** section, you will see **Jira**. Click **Connect** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F3CZMMaEyZPfUIVmXj9TR%2Fscrnli_g0VBZ5rxF23pB8.png?alt=media&amp;token=5e5698dd-21bf-4ea5-bc6d-97c8d91caa19" alt=""><figcaption></figcaption></figure>

3. Select the option **Jira Data Center (self-managed)**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FH3YifYLrDSokai0orp9C%2Fscrnli_HoeVqiJj928Ri1.png?alt=media&amp;token=286e8ec0-6c28-4635-8847-0d99a9fbd4e2" alt=""><figcaption></figcaption></figure>

4. Provide connection details:
   1. **Domain URL**: Enter the base URL for your Jira instance (e.g. `https://jira.mycompany.com`).
   2. **Personal Access Token**: Enter a valid Personal Access Token with admin permissions. Read the [official Jira documentation](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) to learn how to create a Personal Access Token.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FOBJuYQOdVOUdNAKiq3x9%2Fscrnli_vWOh95kn72j5mG.png?alt=media&amp;token=d3fd4126-f94e-40a7-bf24-ac3614577a3b" alt=""><figcaption></figcaption></figure>

5. Click **Connect to Jira**. You will be redirected to your self-hosted Jira website, where you need to grant Bito access to your Jira account.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fd58dTZn9XLlIL1gR4JNl%2Fscrnli_Xk4Gu68hP2q87n.png?alt=media&amp;token=84528ba3-e160-46df-9d97-16f167935c5b" alt=""><figcaption></figcaption></figure>

6. Click **Allow** to continue. If the integration is successful, you will be redirected back to Bito.
   {% endstep %}

{% step %}

### Select your Jira projects

After connecting, Bito will display a list of projects from your Jira site that Bito has access to.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F43UT9NU9WWGPIEYT4zEY%2Fscrnli_0928jZ4Jf58N3P.png?alt=media&amp;token=e4f20456-e967-487c-99bc-8f980059589d" alt=""><figcaption></figcaption></figure>

To enable or disable projects, go to the [**AI Architect settings**](https://alpha.bito.ai/home/ai-architect/settings) page and open the **Jira** tab, where you can select the Jira projects you want Bito to listen to and enable them using the toggle switch.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FMOONs6kKuniDrQnejLtO%2Fscrnli_7kR45jNbN0MkOg.png?alt=media&amp;token=60e29765-3444-4a73-a6de-ff764fe4718a" alt=""><figcaption></figcaption></figure>

Only Epics, Stories, and comments from selected Jira projects will trigger AI Architect analysis — events from unselected projects are ignored.

* You can update your project selection at any time.
* Saving an empty selection effectively pauses Bito for that Jira site without fully disconnecting.

{% hint style="info" %}
Projects in Jira are the equivalent of teams in Linear — they are the persistent scoping unit that determines which events Bito will act on.
{% endhint %}
{% endstep %}

{% step %}

### Enable the feature flags

Two flags control how AI Architect behaves on your tickets. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to enable them — a self-serve UI toggle is coming soon.

| Flag                           | What it enables                                                                                                                                                                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Jira Analysis Enabled**      | <p>Trigger on-demand analysis using <code>@bito</code>, <code>/bito</code>, or <code>#bito</code> in comments.<br><br>Alternatively, add the labels <code>bito</code>, <code>bito-analyse</code>, or <code>bito-analyze</code> to the ticket.</p> |
| **Jira Auto Analysis Enabled** | Automatically triggers analysis when an Epic or Story is created or updated.                                                                                                                                                                      |

{% hint style="info" %}
Start with **Jira Analysis Enabled** if you want to try it manually first, then enable auto-analysis when you're ready to run it on all new tickets.
{% endhint %}
{% endstep %}
{% endstepper %}

## How to trigger AI Architect in Jira

#### Automatic analysis

When enabled, AI Architect listens for new or updated Epics and Stories and posts the implementation plan automatically, no action needed from the ticket creator.

{% hint style="info" %}
Requires the **Jira Auto Analysis Enabled** flag to be enabled for your workspace. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to enable it.
{% endhint %}

{% hint style="info" %}
You can download the plan (markdown file) and use it in your agentic tools (Cursor, Claude Code, etc.) to further update it or use the analysis.
{% endhint %}

#### On-demand analysis

Trigger analysis manually on any ticket by using any of the following in a Jira comment:

```
@bito
/bito
#bito
```

{% hint style="info" %}
You can use the `@bito`, `/bito`, or `#bito` in Jira comment to ask Bito to make changes to the analysis or update based on your needs, or add more details to update the plan based on any new information.

**Example:**

```
@bito analyze technical feasibility
```

{% endhint %}

Or by adding one of these labels to the ticket:

```
bito
bito-analyse
bito-analyze
```

{% hint style="info" %}
Requires the **Jira Analysis Enabled** flag to be enabled for your workspace. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to enable it.
{% endhint %}

## Auto triage

By default, when auto-analysis is enabled, AI Architect generates a plan for every new or updated Epic or Story. Auto triage adds a layer of intelligence before that happens: it evaluates whether a ticket actually needs a detailed implementation plan, and skips generating one if it doesn't.

This keeps your tickets clean and avoids generating plans for work that is already well-defined or straightforward enough to implement without one.

{% hint style="info" %}
**Note:** Only events from your selected Jira projects are processed. Events from unselected projects are ignored before reaching auto triage.
{% endhint %}

#### How auto triage works

When a Story or Epic is created or updated, AI Architect reads the full ticket — title, description, comments, attachments, linked issues, and any associated Confluence pages — and assigns a complexity score from **1 to 10**.

<table><thead><tr><th width="314" align="center">Score</th><th>What happens</th></tr></thead><tbody><tr><td align="center"><strong>Below threshold (default: <code>7</code>)</strong></td><td>Plan is skipped. An optional comment is posted on the ticket.</td></tr><tr><td align="center"><strong>At or above threshold</strong></td><td>Implementation plan is generated as usual.</td></tr></tbody></table>

When a ticket is below the threshold, AI Architect posts the following comment:

> **AI Architect** — This ticket doesn't appear to need a detailed implementation plan based on its scope and complexity. If you'd like one anyway, type @Bito with what you want (example: `@Bito technical plan`)

{% hint style="info" %}
Once a plan or skip notification has been posted on a ticket, auto triage will not re-trigger automatically on subsequent updates. To request a new plan, use `@bito`, `/bito`, or `#bito` directly on the ticket.
{% endhint %}

{% hint style="info" %}
**Note:** AI Architect can perform live web research to incorporate up-to-date technical context into its evaluation and plan generation.
{% endhint %}

#### Supported attachment formats

When evaluating a ticket, AI Architect can read attachments in the following formats:

* `.pdf`&#x20;
* `.docx`&#x20;
* `.xlsx`&#x20;
* `.csv`&#x20;
* `.json`&#x20;
* `.yaml`&#x20;
* `.zip`

{% hint style="warning" %}
SVG files are supported as images only. Binary image attachments (`.png`, `.jpg`, `.gif`, `.webp`) are not yet supported, full image support is coming soon.
{% endhint %}

#### Configuration

The following settings control how auto triage behaves for your workspace. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to configure these.

|          Setting         | Options                                                            | Description                                                                                     |
| :----------------------: | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| **Complexity threshold** | Default: `7`                                                       | Minimum score required for a plan to be generated.                                              |
|  **Auto analysis type**  | <ul><li><code>plan</code> </li><li><code>comment</code> </li></ul> | Whether to generate a full plan or post a guidance comment when a ticket is created or updated. |

## Teaching Bito through feedback

When Bito's plan misses something, or you want to correct an assumption, you can teach it directly in a Jira ticket comment. That feedback is added to your team's [knowledge graph](/ai-architect/knowledge-graph), so future plans — on this ticket or any other — reflect what you taught it.

**Examples:**

```
@bito remember that "Cerberus" refers to our internal auth service, not the open-source library

@bito FYI — staging deploys go through the deploy-staging job, not deploy-stg

@bito that's not right, our retry budget is 3 attempts, not 5
```

## What AI Architect knows about your team

AI Architect draws on multiple sources when it analyzes a ticket:

**Your codebase** — All your repositories, services, API endpoints, modules, and design patterns are indexed into a knowledge graph. AI Architect understands how your system fits together, not just what individual files contain.

**Your Jira history** — AI Architect analyzes your team's Jira tickets and categorizes recurring patterns: race conditions across subsystems, services with instability histories, security and credential issues, error handling gaps, API rate-limiting problems. This context is applied to every new ticket so your team doesn't repeat what's already been learned.

**Other context sources** — AI Architect also incorporates insights from Confluence documents, Linear, observability data, Slack messages, and any custom instructions you provide.

[**Learn how Bito builds the knowledge graph**](/ai-architect/knowledge-graph)

## Agent skills power the Jira integration

AI Architect works through purpose-built agentic skills. The important agent skill that run in Jira is:

**bito-build-plan** — Convert any unit of work (story, ticket, feature brief, epic, PRD) into a sprint-ready implementation plan with effort estimates

[**See all available skills**](/ai-architect/agent-skills)

#### Skill selection by issue type

AI Architect uses different skill selection logic depending on the Jira issue type.

| Issue type                                      | Skill used                                 |
| ----------------------------------------------- | ------------------------------------------ |
| **Story**                                       | Always uses `bito-build-plan`              |
| **Epic**                                        | Always uses `bito-build-plan`              |
| **All other types** (Bug, Task, Sub-task, etc.) | Dynamically selected based on your comment |

For Bugs, Tasks, and other issue types, AI Architect reads the intent of your latest comment and automatically picks the most appropriate skill from its full library. For example, a comment like *"is this feasible?"* triggers `bito-feasibility`, while *"spike on this approach"* triggers `bito-spike`. If the intent is ambiguous, AI Architect falls back to `bito-build-plan`.


# Integrating with Linear

Connect Bito's AI Architect with Linear for feasibility analysis, technical design, and cross-repo impact assessment.

Planning is where engineering teams lose the most time. This is where [**AI Architect**](/ai-architect/overview) starts.

Senior engineers and tech leads spend hours on work that should take minutes — reading through old issues to understand what went wrong before, figuring out what a one-line ticket actually requires, mapping out which services will be affected and which ones have been fragile in the past.

AI Architect automates this work inside Linear. When an issue is created, AI Architect posts a detailed implementation plan directly as a comment on the ticket. Feasibility analysis, story breakdown, risk warnings, historical patterns from your team's own issues — all generated in minutes, right where your team plans.

## What gets posted on your issue

When AI Architect analyzes a Linear issue, it produces a structured Markdown implementation plan that covers:

* **Feasibility assessment** — Is this viable given your current architecture? Which services are involved, and how stable are they? What's the blast radius if something goes wrong?
* **Story breakdown** — A full decomposition into actionable tasks with acceptance criteria, dependencies, and recommended execution order.
* **Effort estimates** — Both traditional and agentic estimates, with a breakdown of where AI tooling saves the most time and where it doesn't.
* **Proactive risk detection** — Race conditions in concurrent flows, memory leak patterns, regression-prone areas, API rate-limiting gaps, security concerns. Each risk comes with a suggested mitigation drawn from your team's actual history.
* **Historical pattern insights** — AI Architect references past issues to flag problems your team has already encountered.
* **Open questions** — Technical decisions that need to be made before implementation begins, so they don't surface mid-sprint.

The plan is in Markdown. Engineers can paste it directly into Cursor, Claude Code, or any other coding agent to start implementation with full architectural context already loaded.

## Prerequisites

Before setting up the Linear integration, make sure the following are in place for your workspace:

* The **AI Architect** feature is enabled.
* **Linear analysis** is enabled.

If either of these isn't active yet, contact the Bito team at <support@bito.ai> to enable them.

## Setup

{% stepper %}
{% step %}

### Enable AI Architect for your workspace

AI Architect can be set up using one of the following deployment options:

#### Bito-hosted

AI Architect is managed and maintained by Bito.

* Follow the [Bito-hosted installation guide](/ai-architect/installation/install-ai-architect-bito-hosted) to get started.
* If AI Architect isn't already active for your workspace, contact the Bito team at <support@bito.ai> to enable it.

#### Self-hosted

AI Architect is deployed and managed within your own infrastructure.

* Follow the [self-hosted installation guide](/ai-architect/installation/install-ai-architect-self-hosted) to set up and configure AI Architect for your workspace.
  {% endstep %}

{% step %}

### Connect Linear

1. Navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page in your Bito dashboard.
2. In the **Available integrations** section, locate **Linear** and click **Connect**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F9p7MsvE56XHIkmXecsjT%2Fscrnli_bgURGQkxi9D32e.png?alt=media&amp;token=cf99bbb6-4151-4c49-b472-b4846cf9e294" alt=""><figcaption></figcaption></figure>

3. From next screen, click **Authorize with your Linear account**. This allows you to securely connect Bito to your Linear workspace using OAuth.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FnZE7OPMdjl36nwHNgqHx%2Fscrnli_HX7ZbvSGG9enEd.png?alt=media&amp;token=0a05974c-8ad1-46cc-ab5b-df767e38da6f" alt=""><figcaption></figcaption></figure>

3. You will be redirected to Linear's authorization page. Sign in to Linear if prompted, then grant Bito access to your Linear workspace. Click **Authorize** to continue. Once authorized, Bito completes the connection automatically and redirects you back to the Bito dashboard.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FI4ihoe9fy94oXXllnyCR%2Fscrnli_MNI1YoCpY9JHo2.png?alt=media&amp;token=51107952-764e-495d-a7dc-b4549d53e9cd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**The user who completes this step must be a Linear workspace admin.** Linear's OAuth requires admin permissions to allow Bito to register the necessary webhooks on your behalf.

If a non-admin connects, the setup will fail and you will see the following error:

*"Insufficient permissions. Creating webhooks in Linear requires the 'admin' OAuth scope, which is granted only when a Linear workspace admin completes the connection. Ensure the connecting user is a workspace admin and try again."*
{% endhint %}
{% endstep %}

{% step %}

### Select your Linear teams

After connecting, Bito will display a list of teams from your Linear site that Bito has access to.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Ffu8OuQkr39I6w6I1JKMZ%2Fscrnli_SvM0nNSAj9pS47.png?alt=media&amp;token=b7316fc2-7d86-48e0-afd7-df7acf8b645b" alt=""><figcaption></figcaption></figure>

To enable or disable teams, go to [**Set up AI Architect**](https://alpha.bito.ai/home/ai-architect) page and select your deployment type.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FdD58l5JA6c60TBghvjbr%2Fscrnli_k5ber0PK3a2g00.png?alt=media&amp;token=44411b85-3cfc-4a88-a31a-279780a025a7" alt=""><figcaption></figcaption></figure>

For example, if you have selected **Self-hosted AI Architect**, then on the next screen click **Configure AI Architect**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FHQGVBXWO2BxirXZZI8Na%2Fscrnli_694QrrBLkA40Av.png?alt=media&amp;token=4d60d418-9e33-4256-9bc0-2a701f0db1b5" alt=""><figcaption></figcaption></figure>

A settings screen will appear. From there, open the **Linear** tab, where you can select the Linear teams you want Bito to listen to and enable them using the toggle switch.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fr02NmoLwMOzCxdg8dYNR%2Fscrnli_L1hZmDetW9ZsvV.png?alt=media&amp;token=bc24faa6-c532-48ac-b2a7-88901f9ea5e2" alt=""><figcaption></figcaption></figure>

Only issues and comments from selected Linear teams will trigger AI Architect analysis, events from unselected teams are ignored.

* You can update your team selection at any time.
* Saving an empty selection effectively pauses Bito for that workspace without fully disconnecting.

{% hint style="info" %}
Teams in Linear are the equivalent of projects in Jira, they are the persistent scoping unit for which events Bito will act on.
{% endhint %}
{% endstep %}

{% step %}

### Enable the feature flags

Two flags control how AI Architect behaves on your Linear issues. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to enable them.

| Flag                             | What it enables                                                                                                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Linear Analysis Enabled**      | Trigger on-demand analysis using `@bito`, `/bito`, or `#bito` in comments. Alternatively, add the labels `bito`, `bito-analyse`, or `bito-analyze` to the issue. |
| **Linear Auto Analysis Enabled** | Automatically triggers analysis when a Linear issue is created or updated.                                                                                       |

{% hint style="info" %}
Start with **Linear Analysis Enabled** if you want to try it manually first, then enable auto-analysis when you're ready to run it on all new issues.
{% endhint %}
{% endstep %}
{% endstepper %}

## How to trigger AI Architect in Linear

#### Automatic analysis

When enabled, AI Architect listens for new or updated issues in your selected teams and posts an implementation plan automatically — no action needed from the issue creator.

{% hint style="info" %}
Requires the **Linear Auto Analysis Enabled** flag to be enabled for your workspace. Contact the Bito team at <support@bito.ai> to enable it.
{% endhint %}

{% hint style="info" %}
You can download the plan (as a Markdown file) and use it in your agentic tools (Cursor, Claude Code, etc.) to further refine it or begin implementation.
{% endhint %}

#### On-demand analysis

Trigger analysis manually on any issue by adding one of the following in a Linear comment:

```
@bito
/bito
#bito
```

{% hint style="info" %}
You can use `@bito`, `/bito`, or `#bito` to ask Bito to update the analysis, refine the plan based on new information, or focus on a specific concern.

**Example:**

```
@bito analyze technical feasibility
```

{% endhint %}

Or by adding one of these labels to the issue:

```
bito
bito-analyse
bito-analyze
```

{% hint style="info" %}
Requires the **Linear Analysis Enabled** flag to be enabled for your workspace. Contact the Bito team at <support@bito.ai> to enable it.
{% endhint %}

{% hint style="info" %}
**Explicit triggers always win.** Even if auto-analysis is turned off, using `@bito` in a comment or applying a trigger label will force an analysis to run.
{% endhint %}

### Auto triage

By default, when auto-analysis is enabled, AI Architect generates a plan for every new or updated issue in your selected Linear teams. Auto triage adds a layer of intelligence before that happens: it evaluates whether an issue actually needs a detailed implementation plan, and skips generating one if it doesn't.

This keeps your issues clean and avoids generating plans for work that is already well-defined or straightforward enough to implement without one.

{% hint style="info" %}
**Note:** Only events from your selected Linear teams are processed. Events from unselected teams are filtered out before reaching auto triage.
{% endhint %}

#### How auto triage works

When an issue is created or updated, AI Architect reads the full ticket — title, description, and comments — and assigns a complexity score from **1 to 10**.

|                Score               | What happens                                                 |
| :--------------------------------: | ------------------------------------------------------------ |
| **Below threshold (default: `7`)** | Plan is skipped. An optional comment is posted on the issue. |
|      **At or above threshold**     | Implementation plan is generated as usual.                   |

When an issue is below the threshold, AI Architect posts the following comment:

> **AI Architect** — This issue doesn't appear to need a detailed implementation plan based on its scope and complexity. If you'd like one anyway, type @Bito with what you want (example: `@Bito technical plan`)

{% hint style="info" %}
Once a plan or skip notification has been posted on an issue, auto triage will not re-trigger automatically on subsequent updates. To request a new plan, use `@bito`, `/bito`, or `#bito` directly on the issue.
{% endhint %}

{% hint style="info" %}
**Note:** AI Architect can perform live web research to incorporate up-to-date technical context into its evaluation and plan generation.
{% endhint %}

#### Supported attachment formats

When evaluating a ticket, AI Architect can read attachments in the following formats:

* `.pdf`
* `.docx`
* `.xlsx`
* `.csv`
* `.json`
* `.yaml`
* `.zip`

{% hint style="warning" %}
SVG files are supported as images only. Binary image attachments (`.png`, `.jpg`, `.gif`, `.webp`) are not yet supported, full image support is coming soon.
{% endhint %}

#### Configuration

The following settings control how auto triage behaves for your workspace. Contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai) to configure these.

|          Setting         | Options            | Description                                                                                     |
| :----------------------: | ------------------ | ----------------------------------------------------------------------------------------------- |
| **Complexity threshold** | Default: `7`       | Minimum score required for a plan to be generated.                                              |
|  **Auto analysis type**  | `plan` / `comment` | Whether to generate a full plan or post a guidance comment when an issue is created or updated. |

## What AI Architect knows about your team

AI Architect draws on multiple sources when it analyzes an issue:

**Your codebase** — All your repositories, services, API endpoints, modules, and design patterns are indexed into a knowledge graph. AI Architect understands how your system fits together, not just what individual files contain.

**Your Linear history** — AI Architect analyzes your team's past issues and categorizes recurring patterns: race conditions across subsystems, services with instability histories, security and credential issues, error handling gaps, API rate-limiting problems. This context is applied to every new issue so your team doesn't repeat what's already been learned.

**Other context sources** — AI Architect also incorporates insights from Jira tickets, Confluence documents, observability data, and any custom instructions you provide.

[**Learn how Bito builds the knowledge graph**](/ai-architect/knowledge-graph)

## Agent skills power the Linear integration

AI Architect works through purpose-built agentic skills. The same skills that run on Jira issues are used for Linear, delivering full feature parity. The important agent skill that run in Linear is:

**bito-build-plan** — Convert any unit of work (story, ticket, feature brief, epic, PRD) into a sprint-ready implementation plan with effort estimates

[**See all available skills**](/ai-architect/agent-skills)

## Disconnecting Linear

To disconnect, navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page and disconnect Linear from there. Bito will automatically clean up the integration — removing the webhook from your Linear workspace, clearing your team selection, and revoking stored credentials.

## Error messages

The following messages may appear if something goes wrong with your Linear integration.

| Situation                                                 | Message                                                                                                                                                                                                                                |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integration is no longer valid (token revoked or expired) | "Your Linear integration is no longer valid. To continue, please disconnect and reconnect your Linear workspace."                                                                                                                      |
| Bito's access in Linear was revoked by an admin           | "Access for the Bito Linear app was revoked. Please disconnect and reconnect the integration to avoid disruptions."                                                                                                                    |
| Connecting user wasn't a Linear workspace admin           | "Insufficient permissions. Creating webhooks in Linear requires the 'admin' OAuth scope, which is granted only when a Linear workspace admin completes the connection. Ensure the connecting user is a workspace admin and try again." |
| Generic / unknown failure                                 | "Something went wrong. Please try again later. If the issue persists, check your Linear settings or contact support."                                                                                                                  |


# Integrating with Slack

Get context-aware AI assistance in your team's Slack conversations

Bito AI Assistant brings powerful AI capabilities directly into your Slack workspace. Instead of switching between apps or losing context, you get instant AI assistance right where your team collaborates.

Ask Bito to help with planning, provide technical guidance, analyze code snippets, summarize lengthy threads, run a full code review on a PR or branch, or open merge requests. Bito reads the full thread context, understands shared files, and automatically pulls in information from Jira tickets and Confluence pages when you reference them.

With Bito in your Slack channels, you save time catching up on discussions, make faster technical decisions, and keep your team's knowledge accessible.

Click the button to add the Bito AI Assistant to your Slack. [<img src="https://platform.slack-edge.com/img/add_to_slack.png" alt="Add to Slack" data-size="original">](https://slack.com/oauth/v2/authorize?client_id=2061955158613.10908115946784\&scope=app_mentions:read,assistant:write,channels:history,channels:read,chat:write,commands,emoji:read,files:read,files:write,groups:history,groups:read,im:history,im:read,links:read,links:write,mpim:history,mpim:read,reactions:read,reactions:write,users:read,users:read.email\&user_scope=)

{% hint style="info" %}
**⚠️ AI Disclaimer**

The Bito Slack app is powered by large language models (LLMs). AI-generated responses may be **inaccurate, incomplete, biased, or outdated**. Outputs are informational suggestions, not professional, legal, financial, medical, or compliance advice. Always verify critical information independently.

For full details on which LLMs are used, what data is sent, and training policies, see [**Slack App – Data Handling**](/privacy-and-security/slack-app-data-handling).

Report inaccurate responses to [**support@bito.ai**](mailto:support@bito.ai).
{% endhint %}

## Prerequisites

Before you install Bito AI Assistant, ensure you have:

* A [**Bito account**](https://alpha.bito.ai/home/welcome) with an active paid plan that includes Bito AI Assistant for Slack
* **AI Architect** set up for your Bito account:
  * [Bito-hosted](/ai-architect/installation/install-ai-architect-bito-hosted) (Fully managed by Bito — no infrastructure setup required)
  * [Self-hosted](/ai-architect/installation/install-ai-architect-self-hosted) (Run AI Architect on your own infrastructure for maximum control)
* **Slack admin permissions** to install apps in your workspace

## Installation steps

Installation takes less than 2 minutes. Once complete, every team member in invited channels can interact with Bito.

{% stepper %}
{% step %}

### **Add the app to Slack**

1. Go to [bitoaiassistant.bito.ai/slack/install](https://bitoaiassistant.bito.ai/slack/install)
2. Select your Slack workspace, review the requested permissions, and click **Allow**
3. Connect your Bito account when prompted

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FqkRzsRjdaxQ4sbrsMcOc%2Fscrnli_NQOaqE462O4866.png?alt=media&amp;token=772eb614-36a4-4413-8cfd-f6d121e9d46b" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### **Invite Bito to channels**

1. Open any Slack channel where you want AI assistance
2. Invite Bito's AI Assistant to a channel by typing `@Bito` followed by your query. Slack will automatically prompt you to add Bito to the channel if it isn't already there, click **Add Them** to add it and get your answer, or dismiss the prompt to skip.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FFCliJu9mdB0MPlM6l3I0%2Fscrnli_6a1x1qTyPohd0u.png?alt=media&amp;token=0a157f31-ea4d-44b0-b857-805f01009701" alt=""><figcaption></figcaption></figure>

3. Repeat for each channel (both public and private channels work)
   {% endstep %}

{% step %}

### **Start using Bito**

1. In any channel where you invited Bito, type `@Bito` followed by your question
2. Bito reads the thread and responds with context-aware answers
   {% endstep %}
   {% endstepper %}

## How to use Bito AI Assistant

#### Basic usage

Mention `@Bito` in any message to get AI assistance. Bito reads the entire conversation thread, not just your message, so it understands the full context.

**Example:**

```
@Bito Based on the above discussion create a plan
```

Bito analyzes the thread and generates a structured, actionable plan based on the discussion.

{% hint style="info" %}
When you ask about "this thread" — for example "summarize this thread" or "what was discussed above" — Bito scopes its context to thread messages only and won't mix in unrelated channel history. Each message also carries a permalink, so Bito can point back to specific messages when it references them.
{% endhint %}

#### Asking questions

You can ask Bito questions in natural language. Be specific about what you need:

**Good questions:**

* `@Bito PROJ-456 is causing errors in production — here are the logs. Identify the root cause?`
* `@Bito help us break this feature into smaller tasks`
* `@Bito explain the difference between these two approaches`
* `@Bito what are the action items from this thread?`
* `@Bito review the code changes in this thread and suggest improvements`

**Tips for better responses:**

* Ask specific questions rather than general ones
* Reference what you're asking about if the thread contains multiple topics
* Use follow-up questions to dive deeper into a response

#### Working with files

When you share files in a Slack thread, Bito automatically processes them and incorporates their content into its responses.

**Supported file types:**

* Code files (`.py`, `.js`, `.java`, etc.)
* Configuration files (`.yaml`, `.json`, `.xml`)
* Documents (`.txt`, `.md`, `.pdf`)
* Log files

**Unsupported file types:**

Bito skips the following file types during processing. If any of these are attached to a Slack conversation, Bito will ignore them and continue processing the rest of the thread.

* **Executables & binaries:** `.exe`, `.dll`, `.so`, `.dylib`, `.a`, `.lib`, `.bin`, `.o`, `.obj`, `.sys`, `.app`, `.deb`, `.rpm`, `.apk`, `.msi`, `.elf`, `.mach`
* **Images & graphics:** `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.ico`, `.tiff`, `.webp`, `.heic`, `.psd`, `.eps`
* **Media files:** `.mp4`, `.avi`, `.mov`, `.mkv`, `.flv`, `.wmv`, `.mp3`, `.wav`, `.flac`, `.aac`, `.m4a`, `.ogg`, `.m3u`, `.m3u8`, `.pls`

{% hint style="info" %}
If your thread contains a mix of supported and unsupported files, Bito will process the supported ones and silently skip the rest.
{% endhint %}

**Example workflow:**

1. Upload a config file to the channel
2. Ask: `@Bito review this configuration and suggest improvements`
3. Bito reads the file and provides specific recommendations

#### Understanding integrations

Bito automatically detects and incorporates information from:

**Jira tickets**

* Mention a ticket ID like `PROJ-123` in your conversation
* Bito recognizes the reference and pulls in context from that ticket

**Confluence pages**

* Paste a Confluence link in your discussion
* Bito reads the linked page and factors it into its response

You don't need to do anything special — just mention or paste the link as you normally would.

## 1:1 direct message with Bito

You can chat with Bito AI Assistant privately, just like you would with any teammate. In a 1:1 DM, you do not need to mention `@Bito` — every message you send is automatically processed by the bot.

#### How to start a 1:1 chat

1. In Slack, click Apps in the left sidebar
2. Select Bito AI Assistant
3. Start typing your message and press Enter

#### What you can do

* Ask questions directly: `what does this function do?`
* Share files for analysis: attach a file and ask `can you review this code?`
* Have a conversation: follow-up messages maintain context from the thread

**Example:**

```
You:   Can you help me understand what this code does?
       [uploaded: authentication.py]

Bito:  This file implements JWT-based authentication with three key functions...
```

{% hint style="info" %}
**Notes:**

* Every message you type in the 1:1 DM with Bito is processed — there is no need to prefix with `@Bito`
* Message edits: if you edit a message to add a new `@Bito` mention, Bito will respond to the new request
  {% endhint %}

## Group direct message with Bito

You can also include Bito AI Assistant in a group chat with other teammates. This is useful when collaborating on a discussion where you want Bito's input along side human participants.

#### How to create a group DM with Bito

1. In Slack, click the "New Message" or pencil icon at the top of the left sidebar
2. In the **"To:"** field, add the teammates you want to include
3. In the same **"To:"** field, add Bito AI Assistant (start typing "Bito" and select it from the dropdown)
4. Send your first message to create the group

{% hint style="info" %}
**Important:** Bito must be added to the group at the time of creation. Slack does not allow adding bots to an existing group DM. If you want to add Bito to an ongoing conversation, create a new group DM or use a private channel instead.
{% endhint %}

#### Talking to Bito in a group DM

Unlike 1:1 DMs, in a group DM you must explicitly mention `@Bito` when you want Bito to respond. Messages without a mention are treated as normal conversation between humans and Bito will not respond.

**Example:**

```
You:   Hey team, quick question about the new API design?
       [Bito does not respond — no mention]

Alice: I think we should use REST for consistency.

You:   @Bito AI Assistant what are the tradeoffs between REST and GraphQL
       for our use case?

Bito:  Great question. Here's a breakdown of the tradeoffs...
```

{% hint style="info" %}
**Notes:**

* Only messages containing `@Bito` trigger a response in group DMs
* Message edits trigger Bito only if a new mention is added during the edit (Bito will not respond to unrelated text edits on messages it has already replied to)
  {% endhint %}

## Teaching Bito through feedback

Bito learns from your team. Anyone in the workspace can teach Bito a fact, a piece of internal terminology, or a correction — and Bito applies that knowledge automatically in future answers, across channels, threads, and DMs.

**How it works**

When you correct Bito or share a workspace-specific fact, Bito captures that input and feeds it into the [knowledge graph](/ai-architect/knowledge-graph). The next time anyone on the team asks a related question or Bito generates a plan, it applies what it learned.

**Examples:**

```
@Bito remember that "Cerberus" refers to our internal auth service, not the open-source library

@Bito FYI — staging deploys go through the deploy-staging job, not deploy-stg

@Bito that's not right, our retry budget is 3 attempts, not 5
```

{% hint style="info" %}
Workspace learnings are shared across your entire Slack workspace, so a single teaching moment in one channel benefits the whole team.
{% endhint %}

{% embed url="<https://youtu.be/jWRobI68g2I>" %}

## Common use cases

#### Break down complex work

Your team needs to implement a new feature but isn't sure where to start.

**What to do:**

```
@Bito help us break down this feature into implementable tasks
```

**What you get:**

* Suggested task breakdown
* Logical sequencing
* Considerations from your team's discussion

#### Turn plans into code

Your team has discussed and finalized an implementation plan in a thread and wants to move straight to coding.

**What to do:**

```
@Bito based on the implementation plan above, create a new branch and make the code changes
```

**What you get:**

1. A new branch created from your default branch
2. Code changes implemented following the agreed plan
3. Changes aligned with your existing codebase patterns and conventions

#### Review technical decisions

Your team discusses two different architectural approaches.

**What to do:**

1. Share code snippets for both approaches
2. Ask: `@Bito compare these two approaches and explain the trade-offs`

**What you get:**

* Analysis of each approach
* Pros and cons
* Recommendations based on the discussion context

#### Pull context from tickets

You're discussing a bug that relates to an existing Jira ticket.

**What to do:**

1. Mention the ticket: "This might be related to PROJ-456"
2. Ask: `@Bito what's the background on PROJ-456 and how does it relate to this issue?`

**What you get:**

* Summary of the referenced ticket
* Connection to current discussion
* Relevant history or context

#### Extract action items

After a long planning discussion, you need to know what comes next.

**What to do:**

```
@Bito list all action items from this thread with who's responsible
```

**What you get:**

* Organized list of tasks
* Assignments (when mentioned in the thread)
* Priorities or deadlines discussed

#### Catch up on long threads

You return from vacation to find 100+ messages in a project channel.

**What to do:**

```
@Bito summarize the last 3 days of discussion and highlight any decisions that need my input
```

**What you get:**

* Key points from the conversation
* Decisions already made
* Open questions requiring your attention

#### Review code from Slack

You want a real code review on a pull request, branch, commit, or local changes — without leaving Slack.

**What to do:**

Paste a link of pull request or describe what to review:

```
@Bito review https://github.com/your-org/repo/pull/1234
@Bito review the auth-refactor branch
@Bito review commit a1b2c3d
@Bito review my staged changes
```

You can narrow the review with flags:

```
@Bito review pull/1234 --focus security --depth deep
```

**What you get:**

* Severity-rated findings covering correctness, security, and performance
* Evidence quoted from the code with exact `file:line` references
* Cross-repo impact analysis when AI Architect is set up for your repo
* Actionable suggestions, not generic advice

{% hint style="info" %}
This is powered by the `bito-code-review` skill. See the [**Agent skills**](/ai-architect/agent-skills) page for the full list of supported review targets and flags.
{% endhint %}

#### Create a merge / pull request from Slack

After Bito makes code changes — or on any existing branch — you can open a merge request or pull request without switching tools.

**What to do:**

```
@Bito create an MR for the auth-refactor branch
@Bito open a draft PR with these changes
```

**What you get:**

1. A new MR or PR opened on GitHub, GitLab, or Bitbucket (cloud or self-hosted)
2. Title, description, and ticket references filled in automatically
3. Smart template detection — your repo's PR/MR template is used when present
4. Duplicate-MR guards so you don't accidentally open the same MR twice
5. Draft MR/PR support when you want to share work-in-progress

## Best practices

#### Get the most from Bito

**Do:**

* ✅ Ask specific, focused questions
* ✅ Use Bito in threads where team discussions happen
* ✅ Reference files and tickets to give Bito more context
* ✅ Ask follow-up questions to clarify responses
* ✅ Use Bito to document decisions by asking for summaries

**Don't:**

* ❌ Ask multiple unrelated questions in one message
* ❌ Expect Bito to make decisions for you — use it to inform your decisions
* ❌ Share sensitive credentials or secrets in threads (Bito reads all messages)

## Privacy and context

**What Bito can see:**

* All messages in the current thread
* Files shared in the thread
* Content from referenced Jira/Confluence links (if connected)

**What Bito cannot see:**

* Messages in channels where it hasn't been invited
* Direct messages between users
* Private channels where it's not a member

Always invite Bito only to channels where AI assistance is appropriate for your team's privacy requirements.

## Troubleshooting

#### Bito doesn't respond

**Check:**

1. Did you invite Bito to this channel? If not, invite Bito's AI Assistant to a channel by typing `@Bito` followed by your query. Slack will automatically prompt you to add Bito to the channel if it isn't already there, click **Yes** to add it and get your answer, or dismiss the prompt to skip.
2. Did you mention `@Bito` at the start of your message?
3. Is your Bito subscription active and does it include Bito AI Assistant for Slack?

**Solution:** Verify Bito is in the channel members list. If not, invite it again.

#### Bito's response seems incomplete

**Possible reasons:**

* The thread context is very long
* Multiple topics are discussed simultaneously

**Solution:**

* Ask more specific questions that focus on one aspect
* Reference the specific part of the conversation you're asking about
* Break complex questions into smaller parts

#### Bito doesn't see my Jira ticket

**Check:**

1. Is your Bito account connected to Jira?
2. Did you mention the exact ticket ID (e.g., `PROJ-123`)?
3. Do you have access to that ticket in Jira?

**Solution:** Verify integrations are configured in your Bito account settings.

#### I need to remove Bito from a channel

**Steps:**

1. Open the channel
2. Click the channel name to view details
3. Go to the **Integrations** tab
4. Find Bito and click **Remove**

Bito will no longer see messages or respond in that channel.

## Frequently Asked Questions

#### Does Bito read all messages in a channel?

Bito only reads messages in threads where someone mentions `@Bito`. It doesn't process or store messages from conversations where it's not mentioned.

#### Can I use Bito in private channels?

Yes. Invite Bito to private channels the same way you would invite any team member. Only people in that private channel can interact with Bito there.

#### How much does Bito AI Assistant cost?

Bito AI Assistant is included in Bito's paid plans. Check [bito.ai/pricing](https://bito.ai/pricing) for current plan details and features.

#### Does Bito learn from our conversations?

Bito uses conversation context to provide better responses during that discussion. Your team's specific conversations are used to improve responses within your Bito account but are not used to train public AI models.

#### What happens if I exceed my plan limits?

Bito will notify you when you approach plan limits. Responses may be rate-limited if you exceed usage caps. Upgrade your plan to increase limits.

#### Can I use Bito for customer support channels?

Yes, but consider privacy implications. Bito reads all messages in threads where it's mentioned. Only use it in channels where AI assistance is appropriate.

## Next steps

Now that you understand how Bito AI Assistant works:

1. **Invite Bito** to your most active project channels
2. **Try common use cases** like summarizing threads or extracting action items
3. **Share with your team** so everyone knows how to use `@Bito`
4. **Experiment** with different types of questions to discover what works best for your workflow

Welcome to faster, smarter team collaboration with AI assistance right in Slack.

## Related Resources

* 🔒 [Slack App – Data Handling](/privacy-and-security/slack-app-data-handling) — retention, deletion, LLM info, security
* :shield: [Bito Privacy and Security](/privacy-and-security) — overall security posture, SOC 2, sub-processors
* 💬 [Get Support](/help/support-and-questions/getting-support) — contact our team
* 📜 [Bito Privacy Policy](https://bito.ai/privacy-policy/) — full legal privacy policy


# Integrating with Confluence

Use Confluence as context for AI Architect's analysis, and create, update, and manage pages from Jira or Slack — without leaving your workflow.

Your team's documentation lives in Confluence — design decisions, RFCs, runbooks, acceptance criteria, architecture notes. [**Bito's AI Architect**](/ai-architect/overview) reads that documentation and uses it as context whenever it analyzes Jira tickets, answers questions in Slack, or generates implementation plans. And it can write back to Confluence too — creating pages, updating content, adding labels, leaving comments, and managing attachments — all from inside Jira or Slack, without ever switching tabs.

Once you connect Confluence, AI Architect treats it as a first-class context source alongside your code, Jira tickets, and team conversations in Slack.

## What AI Architect does with Confluence

### Pulls Confluence into analysis as context

* **Automatic context on Jira plans** — When AI Architect generates an implementation plan for a Jira Epic or Story, any Confluence pages linked to that ticket are pulled in automatically. Recommendations, risk assessments, and effort estimates reflect what's already documented.
* **Reads page attachments** — Attachments on Confluence pages are read along with the page content, so design specs, requirement docs, and reference data attached to a page all factor into the plan.
* **Surfaces information in Slack** — When you paste a Confluence link into a Slack thread, the [Bito AI Assistant for Slack](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack) reads the linked page and uses it to answer questions, summarize, or compare against the discussion.

### Lets you manage Confluence from Jira and Slack

You can ask AI Architect — through Jira comments or Slack — to create and maintain Confluence content for you.

**Supported operations:**

| Operation             | What you can ask                                        |
| --------------------- | ------------------------------------------------------- |
| **Create page**       | Create a new Confluence page in a given space           |
| **Update page**       | Edit the body or title of an existing page              |
| **Add labels**        | Add labels to a page for findability and categorization |
| **Read comments**     | Read both footer and inline comments on a page          |
| **Add comment**       | Add a footer comment to any page                        |
| **Upload attachment** | Attach a file (design mock, spec, CSV, etc.) to a page  |
| **Delete page**       | Delete a page programmatically                          |

No browser tab required — the same Jira ticket or Slack thread where you're already working can drive your wiki.

#### Supported attachment formats

When AI Architect reads attachments from Confluence pages (whether for context or when you ask about a specific file), the following formats are supported:

* `.pdf`
* `.docx`
* `.xlsx`
* `.csv`
* `.json`
* `.yaml`
* `.zip`

…and other common document formats.

## Setup

{% stepper %}
{% step %}

### Enable AI Architect for your workspace

AI Architect can be set up using one of the following deployment options:

#### Bito-hosted

AI Architect is managed and maintained by Bito.

* Follow the [Bito-hosted installation guide](/ai-architect/installation/install-ai-architect-bito-hosted) to get started.
* If AI Architect isn't already active for your workspace, contact the Bito team at <support@bito.ai> to enable it.

#### Self-hosted

AI Architect is deployed and managed within your own infrastructure.

* Follow the [self-hosted installation guide](/ai-architect/installation/install-ai-architect-self-hosted) to set up and configure AI Architect for your workspace.&#x20;
  {% endstep %}

{% step %}

### Connect Bito with Confluence

1. In your Bito dashboard, go to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page.
2. Under **Available integrations**, find **Confluence** and click **Connect**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FDUjfwVLdl7gwG34Db0TQ%2Fscrnli_lG7XCHKOS1azh4.png?alt=media&amp;token=cdd56083-c41c-4c72-aa7d-ee9be1829984" alt=""><figcaption></figcaption></figure>

3. Click **Authorize with your Confluence account**. You will be redirected to Atlassian's site to grant Bito access to your Confluence workspace. This uses OAuth to securely link your Confluence content.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FXxIXGUW1Q79u3ph8961i%2Fscrnli_1BV41mj941C68g.png?alt=media&amp;token=3ae37270-2684-4681-bdbb-c6948e71b99e" alt=""><figcaption></figcaption></figure>

4. Review the requested permissions and click **Accept**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FaCYPbL2Pr1yG6P9i9Vot%2Fscrnli_JEi9waknG1g73m.png?alt=media&amp;token=294fa509-3b39-40cd-877b-f5b76bac6485" alt=""><figcaption></figcaption></figure>

5. After successful authorization, Bito will display a list of spaces from your Confluence site that Bito has access to.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7ctz9cS2s1MFAgRVHJUA%2Fscrnli_lMNiZlLXP1wZ7j_1.png?alt=media&amp;token=df19f105-a313-41e2-a5a0-35b9f1f806d5" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**One Confluence connection covers all workflows.** Once Confluence is connected to your Bito workspace, AI Architect will use it everywhere — in Jira ticket analysis, in Slack threads, and when you ask it to write back to Confluence.
{% endhint %}

## How to use AI Architect with Confluence

#### Get richer Jira plans automatically

If you've already linked a Confluence page to a Jira ticket — for example, an RFC, design doc, or product brief — there's nothing more to do. When AI Architect generates a plan for that ticket, it reads the linked Confluence pages (and their attachments) and folds them into the analysis.

**Example:** A Story links to a Confluence page that documents the team's preferred retry strategy. AI Architect's plan will reference that strategy directly, instead of suggesting a generic approach.

[**Learn more about Jira integration**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira)

#### Reference Confluence pages in Slack

Paste a Confluence URL into a Slack thread and ask AI Architect about it.

**Examples:**

```
@Bito summarize this Confluence page and tell me what's missing
[Confluence link]

@Bito does the approach in this design doc conflict with PROJ-456?
[Confluence link]
```

The Bito AI Assistant reads the page, factors it into the thread context, and responds with answers grounded in your documentation.

[**Learn more about Slack integration**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack)

#### Create and update Confluence pages from Jira

Ask AI Architect to write to Confluence directly from a Jira ticket comment.

**Examples:**

```
@bito create a Confluence page in the "Engineering" space summarizing the implementation plan above

@bito update the linked Confluence page with the decisions made on this ticket

@bito add the label "post-mortem" to the linked Confluence page
```

#### Create, update, and manage Confluence pages from Slack

The same operations work from Slack threads.

**Examples:**

```
@Bito create a Confluence page in the "Platform" space documenting the conclusions from this thread

@Bito leave a comment on this Confluence page noting that the API contract changed: [Confluence link]

@Bito attach this file to the linked Confluence page

@Bito delete the stale Confluence page at [Confluence link]
```

## What AI Architect knows about your team

Once Confluence is connected, it becomes one of several context sources AI Architect uses:

* **Your codebase** — All your repositories, services, API endpoints, modules, and design patterns are indexed into a knowledge graph.
* **Your Jira/Linear history** — Recurring patterns from past tickets: race conditions, fragile services, security gaps, error-handling issues.
* **Your Confluence documentation** — RFCs, design docs, runbooks, acceptance criteria, and any attached specifications.
* **Other context sources** — Slack threads, observability data, and custom instructions you provide.

[**Learn how Bito builds the knowledge graph**](/ai-architect/knowledge-graph)

## Permissions required for Confluence integration

When you connect Confluence, Bito requests access to your Atlassian account via OAuth. The integration requests **read**, **write**, and **delete** permissions across Confluence content so AI Architect can both pull pages into analysis and act on them when you ask it to.

#### Summary of access:

| Capability | Scope                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Delete** | Comments, Custom content, Page, Content attachments, Blogposts, Database, Smart Link, Folder, Whiteboard                                                                                                                                                                                                                                                                                     |
| **View**   | Comments, Custom content, Page, App Properties, Content attachments, Blogpost, Content metadata, Content Property, email-address, Smart Link, Groups, Contents, Inline tasks, Labels, Task, Space permissions, Space properties, Space settings, Space details, Task, Content templates, User properties, User details, Content watchers, Whiteboard, Database, Folder, Content restrictions |
| **Update** | Comments, Custom content, Page, App Properties, Content attachments, Labels, Space details, Content templates, Content watchers, Blogpost, Content Property, Content restrictions, Database, Smart Link, Folder, Inline tasks, Whiteboard                                                                                                                                                    |

#### Full list of permissions requested:

**Delete**

* Delete comments on content.
* Delete custom content.
* Delete pages.
* Delete attachments.
* Delete blogposts.
* Delete databases.
* Delete Smart Links.
* Delete folders.
* Delete whiteboards.

**View**

* View comments on pages or blogposts.
* View custom content.
* View page content.
* Read connect app properties data
* View and download attachments of a page or blogpost that you have access to.
* View blogpost content.
* View information about the content. Note that this does not provide access to the content itself.
* View properties associated with a content.
* View email addresses of all users regardless of the user's profile visibility settings.
* View Smart Link data, such as its content id and title
* View details about groups including its members.
* View children or descendants for hierarchical content, including pages, whiteboards, databases, folders and smart links
* Search and view inline tasks.
* View labels associated with the content or space.
* View content restrictions and space permissions. Note that is only used for V2 APIs
* View space permissions.
* View properties associated with the space.
* View space settings and themes.
* View space details
* View Confluence tasks. Note that is only used for V2 APIs
* View content templates.
* View properties associated with the user.
* View user details.
* View the watchers associated with the contents, spaces or labels.
* View whiteboard data, such as its content id and title
* View database data, such as its content id and title
* View folder data, such as its content id and title
* View the restrictions on the content.

**Update**

* Create and update comments on content.
* Create and update custom content.
* Create and update pages.
* create, modify and delete app properties data
* Create and update attachments.
* Add and remove labels associated with the content or space.
* Create and update spaces.
* Create, update and delete content templates.
* Add and remove the watchers associated with content, spaces, or labels.
* Create and update blogposts.
* Create, update and delete properties associated with a content.
* Update the restrictions on the content.
* Create and update databases.
* Create and update Smart Links.
* Create and update folders.
* Mark inline tasks as complete or incomplete.
* Create and update whiteboards.

{% hint style="info" %}
AI Architect only acts on Confluence content when you ask it to (via Jira or Slack) or when a page is linked to a ticket it's analyzing. It doesn't make changes on its own.
{% endhint %}

## Troubleshooting

#### AI Architect's Jira plan doesn't reflect my Confluence docs

**Check:**

1. Is Confluence connected in [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations)?
2. Is the Confluence page actually linked to the Jira ticket — either via a link in the ticket description/comments, or via the *Jira Issue* macro on the Confluence page?
3. Does the OAuth user used to connect Confluence have access to the page in question? Bito sees only what that user can see.

#### AI Architect can't read an attachment

**Check:**

1. Is the attachment in a supported format (`.pdf`, `.docx`, `.xlsx`, `.csv`, `.json`, `.yaml`, `.zip`, or similar)?
2. Is the attachment under your Confluence instance's size limits?

#### Authorization errors

If Bito reports that it can't access Confluence:

1. Go to [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) and reconnect Confluence.
2. Confirm the Atlassian account used has access to the spaces and pages you expect AI Architect to read or write to.

#### My Confluence instance is self-hosted (Data Center)

Confluence Data Center is **not yet supported**. Support for self-hosted Confluence is coming soon for both Bito-hosted and Self-hosted AI Architect. In the meantime, contact <support@bito.ai> to be notified when it's available.

## Frequently Asked Questions

#### Does AI Architect read every page in our Confluence?

No. AI Architect reads Confluence pages on demand:

* Pages **linked to a Jira ticket** it's analyzing
* Pages **referenced by URL** in a Slack thread where it's mentioned
* Pages you explicitly ask it to read, create, update, or delete

It does not crawl or index your full Confluence instance.

#### Can I limit which spaces AI Architect can access?

Yes — at the Atlassian/Confluence level. The OAuth user used to connect Confluence to Bito determines what AI Architect can see. Restrict that user's space access in Confluence to control what's reachable.

#### Does AI Architect modify Confluence pages without asking?

No. Write and delete operations happen only when you explicitly request them through a Jira comment or Slack message.

## Next steps

1. **Connect Confluence** to your Bito workspace via [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations).
2. **Link your design docs and RFCs** to the Jira tickets that reference them — AI Architect will pick them up automatically when you ask it to generate implementation plan.
3. **Try writing back from Slack or Jira** — ask AI Architect to create a Confluence page summarizing a thread or ticket, and see how it reads.
4. **Combine with** [**Jira**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira) **and** [**Slack**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack) **integrations** for the full workflow: plan in Jira, discuss in Slack, document in Confluence — all driven by AI Architect.


# Integrating with Google Docs

Use Google documents (Docs, Sheets, Slides, and Drive) as context for AI Architect's analysis

Your team's documented intent lives in Google Docs, Sheets, and Slides — design decisions, edge cases, test scenarios, requirement docs, and specs. [**Bito's AI Architect**](/ai-architect/overview) reads that documentation and uses it as context whenever it analyzes Jira tickets, answers questions in Slack, or generates implementation plans. It can also create and update Google Docs for you — writing back plans, summaries, and decisions directly from Jira or Slack, without ever switching tabs.

Once you connect Google Docs, AI Architect treats your Google documents as a first-class context source alongside your code, Jira/Linear tickets, Confluence docs, and team conversations in Slack.

{% hint style="info" %}
**Read across Docs, Sheets, Slides, and Drive; write to Docs.**

AI Architect can browse Google Drive folders and search Docs, Sheets, and Slides by name or content. It reads Google Docs, Sheets, and Slides, and it can create and update Google Docs.

Write support applies to Google Docs only — Sheets and Slides are read-only.
{% endhint %}

## What AI Architect does with Google Docs

#### Pulls Google Docs into analysis as context

* **Automatic context on Jira plans** — When AI Architect generates an implementation plan for a Jira Epic or Story, any Google Docs referenced in that ticket are pulled in automatically. It fetches the relevant details — edge cases, design decisions, and test scenarios — so recommendations, risk assessments, and effort estimates reflect what your team has already documented.
* **Grounds your coding agents** — Because the plan carries your documented intent, the code your agents generate is grounded in your team's decisions, not just the code that already exists.
* **Reads across Docs, Sheets, Slides, and Drive** — AI Architect can browse Drive folders and search for files by name or content, then read the Google Docs, Sheets, and Slides it finds. Supporting material spread across your documents factors into the plan.
* **Surfaces information in Slack** — When you paste a Google Docs link into a Slack thread, the [Bito AI Assistant for Slack](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack) reads the linked document and uses it to answer questions, summarize, or compare against the discussion.

#### Lets you manage Google Docs from Jira and Slack

You can ask AI Architect — through Jira comments or Slack — to create and update Google Docs for you.

**Supported operations:**

| Operation           | What you can ask                                         | Scope                |
| ------------------- | -------------------------------------------------------- | -------------------- |
| **Browse Drive**    | Browse folders in Google Drive to locate documents       | Drive                |
| **Search files**    | Search Docs, Sheets, and Slides by name or content       | Docs, Sheets, Slides |
| **Read a document** | Read the contents of a Doc, Sheet, or Slide deck         | Docs, Sheets, Slides |
| **Create a Doc**    | Create a new Google Doc (for example, a plan or summary) | Docs only            |
| **Update a Doc**    | Edit the contents of an existing Google Doc              | Docs only            |

{% hint style="info" %}
Write access applies to Google Docs only. AI Architect can read Google Sheets and Google Slides, but it cannot modify them.
{% endhint %}

### Setup

{% stepper %}
{% step %}

### Enable AI Architect for your workspace

AI Architect can be set up using one of the following deployment options:

#### 1. Bito-hosted

AI Architect is managed and maintained by Bito.

* Follow the [Bito-hosted AI Architect installation guide](/ai-architect/installation/install-ai-architect-bito-hosted) to get started.
* If AI Architect isn't already active for your workspace, contact the Bito team at <support@bito.ai> to enable it.

#### 2. Self-hosted

AI Architect is deployed and managed within your own infrastructure.

* Follow the [self-hosted AI Architect installation guide](/ai-architect/installation/install-ai-architect-self-hosted) to set up and configure AI Architect for your workspace.
  {% endstep %}

{% step %}

### Connect Bito with Google Docs

1. In your Bito dashboard, go to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page.
2. Under **Available integrations**, find **Google Docs** and click **Connect**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FYJ3qoOOd8YOYyXVAbnQe%2Fscrnli_749IMcq0XfqGJ9.png?alt=media&amp;token=53abc0a8-3bc5-4fdf-bd62-25b79533659f" alt=""><figcaption></figcaption></figure>

3. Click **Authorize with your Google account**. You will be redirected to Google's site to grant Bito access to your documents (Google Docs, Sheets, Slides, and Drive). This uses OAuth to securely link your documents.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FI7t2x9pYxh7hAL6ZypUR%2Fscrnli_70iG29PiofS8Ax.png?alt=media&amp;token=1c4e2325-e1b7-4247-be6b-ede80b730b22" alt=""><figcaption></figcaption></figure>

4. Review the requested permissions, click the **Select all** checkbox to grant all permissions, and then click **Continue**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FbBbZfl5evhOm6TCZERpe%2Fscrnli_xCw6JH3lQ2KT5E.png?alt=media&amp;token=d1b66134-d9f5-436b-8fcb-2a558bcab736" alt=""><figcaption></figcaption></figure>

5. After successful authorization, you will be redirected to Bito, where a success message confirms the connection.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FemNgySetPc0yXGGgwK3q%2Fscrnli_OrXAG2K3pgjv28.png?alt=media&amp;token=292d7e71-692a-42a7-8c30-3d6c15f9aa3f" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## How to use AI Architect with Google Docs

#### Get richer Jira plans automatically

If you've already referenced a Google Doc in a Jira ticket — for example, a design doc, test plan, or requirements brief — there's nothing more to do. When AI Architect generates a plan for that ticket, it reads the referenced documents and folds them into the analysis.

**Example:** A Story references a Google Doc that documents the edge cases for a payments flow. AI Architect's plan will account for those edge cases directly, instead of assuming a generic happy path.

[**Learn more about Jira integration**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira)

#### Reference Google Docs in Slack

Paste a Google Docs link into a Slack thread and ask AI Architect about it.

**Examples:**

```
@Bito summarize this design doc and tell me what's missing
[Google Docs link]
```

```
@Bito do the test scenarios in this doc cover PROJ-456?
[Google Docs link]
```

The Bito AI Assistant reads the document, factors it into the thread context, and responds with answers grounded in your documentation.

[**Learn more about Slack integration**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack)

#### Create and update Google Docs from Jira

Ask AI Architect to write to Google Docs directly from a Jira ticket comment.

**Examples:**

```
@bito create a Google Doc summarizing the implementation plan above
```

```
@bito update the linked Google Doc with the decisions made on this ticket
```

#### Create and update Google Docs from Slack

The same operations work from Slack threads.

**Examples:**

```
@Bito create a Google Doc documenting the conclusions from this thread
```

```
@Bito update this Google Doc with the API contract we just agreed on: [Google Docs link]
```

{% hint style="info" %}
AI Architect can search your Drive to find the right document. If you're unsure of the exact link, ask it by name — for example, `@Bito find the "Checkout redesign" doc and summarize the open questions`.
{% endhint %}

## What AI Architect knows about your team

Once Google Docs is connected, it becomes one of several context sources AI Architect uses:

* **Your codebase** — All your repositories, services, API endpoints, modules, and design patterns are indexed into a knowledge graph.
* **Your Jira/Linear history** — Recurring patterns from past tickets: race conditions, fragile services, security gaps, error-handling issues.
* **Your Google documentation** — Design docs, requirement briefs, test plans, and specs stored in Google Docs, Sheets, and Slides.
* **Other context sources** — Confluence pages, Slack threads, observability data, and custom instructions you provide.

[**Learn how Bito builds the knowledge graph**](/ai-architect/knowledge-graph)

## Permissions required for Google Docs integration

When you connect Google Docs, Bito requests access to your Google account via OAuth. AI Architect needs to read your Google Docs, Sheets, and Slides, browse Drive, and write to Google Docs, so it requests the following access.

**Summary of access**

| Google product    | Access level      | What AI Architect can do                           |
| ----------------- | ----------------- | -------------------------------------------------- |
| **Google Docs**   | Read and write    | Read document content; create and update documents |
| **Google Sheets** | Read-only         | Read spreadsheet content                           |
| **Google Slides** | Read-only         | Read presentation content                          |
| **Google Drive**  | Browse and search | Browse folders and search files by name or content |

{% hint style="info" %}
AI Architect only acts on your documents when you ask it to (via Jira or Slack) or when a document is referenced in a ticket it's analyzing. It does not make changes on its own.
{% endhint %}

## Troubleshooting

#### AI Architect's Jira plan doesn't reflect my Google Doc

**Check:**

1. Is Google Docs connected in [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations)?
2. Is the Google Doc actually referenced in the Jira ticket — via a link in the ticket description or comments?
3. Does the Google account used to connect the integration have access to the document? Bito sees only what that account can see.

#### AI Architect can't read a document

**Check:**

1. Is the file a Google Doc, Sheet, or Slide deck? These are the supported Google file types.
2. Is the document shared with the Google account used to connect the integration?

#### AI Architect can't update a document

**Check:**

1. Is the file a Google Doc? Write access applies to Google Docs only — Sheets and Slides are read-only.
2. Does the connected Google account have edit permission on that document?

#### Authorization errors

If Bito reports that it can't access Google Docs:

1. Go to [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) and reconnect Google Docs.
2. Confirm the Google account used has access to the documents you expect AI Architect to read or write to.

## Frequently Asked Questions

#### Does AI Architect read every document in our Google Drive?

No. AI Architect reads documents on demand:

* Documents **referenced in a Jira ticket** it's analyzing
* Documents **referenced by URL** in a Slack thread where it's mentioned
* Documents you explicitly ask it to browse, search, read, create, or update

It does not crawl or index your entire Google Drive.

#### Can AI Architect edit my Google Sheets or Slides?

No. AI Architect has read-only access to Google Sheets and Google Slides. It can read their content for context, but it can only create and update Google Docs.

#### Can I limit which documents AI Architect can access?

Yes — at the Google account level. The Google account used to connect the integration determines what AI Architect can see. Share only the documents and folders you want AI Architect to reach with that account.

#### Does AI Architect modify my documents without asking?

No. Create and update operations happen only when you explicitly request them through a Jira comment or Slack message.

## Next steps

1. **Connect Google Docs** to your Bito workspace via [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations).
2. **Reference your design docs and test plans** in the Jira tickets that relate to them — AI Architect will pick them up automatically when you ask it to generate an implementation plan.
3. **Try writing back from Slack or Jira** — ask AI Architect to create a Google Doc summarizing a thread or ticket, and see how it reads.
4. **Combine with** [**Jira**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira) **and** [**Slack**](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack) **integrations** for the full workflow: plan in Jira, discuss in Slack, document in Google Docs — all driven by AI Architect.


# Integrating with chat agents


# Guide for Claude.ai (Web)

Integrate Claude.ai with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **Claude.ai (Web)** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), Claude.ai can leverage AI Architect's deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
   * **Note:** The **Bito MCP URL** must be publicly accessible. Localhost or private network URLs (for example, `http://localhost` or internal IP addresses) are not supported and will not work.
2. [Download **BitoAIArchitectGuidelines.md file**](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.
3. **A paid Claude.ai subscription** - MCP integrations require one of the following:
   * Claude Pro
   * Claude Max
   * Claude Team
   * Claude Enterprise

{% hint style="info" %}
**Note:** Free tier accounts do not have access to MCP Integrations.
{% endhint %}

## OAuth authentication

Claude.ai uses **OAuth 2.1 with PKCE** for secure authentication, so you don't need to manually manage access tokens. Your email will be collected during the OAuth consent flow for tracking purposes.

**How OAuth authentication works:**

1. You add the MCP server URL in Claude.ai Integrations settings
2. Claude.ai initiates an OAuth flow
3. Your browser opens a consent page hosted by Bito
4. You enter your email and approve the connection
5. Claude.ai receives secure tokens automatically
6. Your email is tracked for usage analytics (collected during OAuth consent)

**Benefits:**

* No manual token management
* Secure browser-based authentication
* Automatic token refresh
* Email collected during consent (no separate header needed)

**OAuth Callback URL:** `https://claude.ai/api/mcp/auth_callback`

## Set up AI Architect

{% stepper %}
{% step %}

### Open Claude.ai integrations

1. Go to [claude.ai](https://claude.ai) and sign in with your paid account
2. Click on your **profile icon** (bottom-left corner)
3. Select **Settings**
4. Navigate to **Integrations** section
   {% endstep %}

{% step %}

### Add Bito AI Architect MCP server

1. Click **"+ Add Custom Integration"**
2. Enter the integration details:
   * **Name:** BitoAIArchitect
   * **URL:** `<Your-Bito-MCP-URL>`

{% hint style="info" %}

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
    {% endhint %}

3. Click **"Connect"** or **"Add"**
   {% endstep %}

{% step %}

### Complete OAuth authorization

1. A new browser window/tab will open showing the **Bito Authorization** page
2. Review the requested permissions
3. **Enter your email address** (required for tracking/identification)
4. Click **"Authorize"** or **"Allow"**
5. The window will close and you'll be returned to Claude.ai
   {% endstep %}

{% step %}

### Verify connection

1. Return to Claude.ai Settings → Integrations
2. BitoAIArchitect should show as **"Connected"** with a green indicator
3. Start a new conversation and try:

   ```
   What repositories are available in my organization?
   ```

{% endstep %}
{% endstepper %}

## Troubleshooting Claude.ai

#### **"Integrations" option not visible:**

* Verify you have a paid Claude subscription (Pro, Max, Team, or Enterprise)
* Free tier accounts do not have MCP access
* Contact Anthropic support if you have a paid plan but don't see the option

#### **OAuth authorization fails:**

* Ensure pop-ups are allowed for claude.ai
* Check that your Workspace ID is correct
* Verify your organization has OAuth enabled for the MCP server
* Try clearing browser cache and cookies, then retry

#### **Connection shows "Disconnected":**

* Click the server entry and select "Reconnect"
* OAuth tokens may have expired - re-authorize when prompted
* Check if your Bito workspace is still active

#### **Tools not appearing in conversation:**

* Ensure the MCP server shows "Connected" status
* Try starting a fresh conversation
* Some tools may require specific prompts to activate


# Guide for Claude Desktop

Integrate Claude Desktop with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **Claude Desktop** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), Claude Desktop can leverage AI Architect's deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md file**](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.
3. **Claude Desktop installed** - Download and install Claude Desktop from [claude.ai/download](https://claude.ai/download) if you haven't already.
4. **Node.js 20.18.1 or higher** - Required for the `mcp-remote` proxy
   * **macOS:**

     ```shellscript
     brew install node@20
     # Or use nvm: nvm install 20 && nvm use 20
     ```
   * **Windows:** Download from <https://nodejs.org/> (download 20.x LTS)
   * **Linux (Ubuntu/Debian):**

     ```shellscript
     curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
     sudo apt-get install -y nodejs
     ```
   * **Verify installation:**

     ```shellscript
     node --version  # Should show v20.x.x or higher
     npx --version
     ```

{% hint style="info" %}
**Note:** Claude Desktop uses OAuth 2.1 authentication via the `mcp-remote` proxy, so you don't need to manually manage access tokens. Your email will be collected during the OAuth consent flow.
{% endhint %}

## Set up AI Architect

Claude Desktop uses `claude_desktop_config.json` with the `mcp-remote` proxy for OAuth-enabled remote servers.

Claude Desktop supports both local MCP servers and remote HTTP servers. For Bito AI Architect (a remote OAuth server), we use the `mcp-remote` proxy which handles the OAuth flow automatically.

{% stepper %}
{% step %}

### Open configuration file

#### **macOS:**

1. Open Claude Desktop
2. Click **Claude** menu → **Settings** → **Developer** tab
3. Click **Edit Config** to open `claude_desktop_config.json`

Or manually open: `~/Library/Application Support/Claude/claude_desktop_config.json`

#### **Windows:**

1. Open Claude Desktop
2. Click **File** → **Settings** → **Developer** tab
3. Click **Edit Config** to open `claude_desktop_config.json`

Or manually open: `%APPDATA%\Claude\claude_desktop_config.json`
{% endstep %}

{% step %}

### Add AI Architect configuration

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>"
      ]
    }
  }
}
```

{% hint style="info" %}

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
    {% endhint %}

If you already have other MCP servers configured, add BitoAIArchitect to the existing `mcpServers` object:

```json
{
  "mcpServers": {
    "existing-server": {
      ...
    },
    "BitoAIArchitect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>"
      ]
    }
  }
}
```

{% hint style="info" %}

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
    {% endhint %}

**Windows-specific configuration:**

On Windows, you may need to use the `cmd` wrapper:

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>"
      ]
    }
  }
}
```

{% hint style="info" %}

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
    {% endhint %}
    {% endstep %}

{% step %}

### Restart Claude Desktop

1. **Completely quit** Claude Desktop (not just close the window)
   * macOS: Claude menu → Quit Claude
   * Windows: Right-click system tray icon → Exit
2. Reopen Claude Desktop
3. The MCP server will start automatically
   {% endstep %}

{% step %}

### Complete OAuth authorization

On first use, `mcp-remote` will open your browser to complete OAuth:

1. A browser window opens showing the **Bito Authorization** page
2. Review the requested permissions
3. **Enter your email address** (required for tracking)
4. Click **"Authorize"** or **"Allow"**
5. Return to Claude Desktop - the connection is now active
   {% endstep %}

{% step %}

### Verify connection

1. In Claude Desktop, click the **"+"** button at the bottom of the chat
2. Select **"Connectors"** or look for the hammer/wrench icon
3. BitoAIArchitect should appear in the list
4. Try asking: "What repositories are available?"
   {% endstep %}
   {% endstepper %}

## Troubleshooting Claude Desktop

#### **Server not appearing:**

1. Verify JSON syntax in config file
2. Ensure Node.js 20+ is installed: `node --version`
3. Check that `npx` is available: `npx --version`
4. Fully quit and restart Claude Desktop

#### **OAuth flow not starting:**

1. Ensure your browser is set as default
2. Allow pop-ups for the OAuth flow
3. Check firewall settings

#### **"mcp-remote not found" error:**

* Ensure Node.js is in your PATH
* Try running `npx -y mcp-remote --help` in terminal to verify it works

#### **Connection shows "Disconnected":**

* OAuth tokens may have expired - restart Claude Desktop to re-authorize
* Check your internet connection
* Verify the Workspace ID is correct


# Guide for ChatGPT (Web & Desktop)

Integrate ChatGPT with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **ChatGPT (Web & Desktop)** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), ChatGPT can leverage AI Architect's deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

{% hint style="info" %}
**Note:** This guide covers setup for both the web interface (chat.openai.com) and the ChatGPT desktop app. The configuration is identical for both platforms.
{% endhint %}

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
   * **Note:** When using Bito AI Architect MCP with ChatGPT (Web), the **Bito MCP URL** must be publicly accessible. Localhost or private network URLs (for example, `http://localhost` or internal IP addresses) are not supported and will not work.
2. [Download **BitoAIArchitectGuidelines.md file**](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.
3. **A paid ChatGPT subscription** - MCP connectors require one of the following:
   * ChatGPT Plus
   * ChatGPT Pro
   * ChatGPT Team
   * ChatGPT Enterprise
   * ChatGPT Edu

{% hint style="info" %}
**Note:** Free tier accounts do not have access to MCP connectors.
{% endhint %}

{% hint style="info" %}
**Note:** Full MCP support (including write/modify actions) is available for Team, Enterprise, and Edu plans. Plus and Pro users have read/fetch permissions via Developer Mode.
{% endhint %}

## OAuth authentication

ChatGPT uses **OAuth 2.1 with PKCE** for secure MCP server authentication via the Connectors feature in Developer Mode.

**How OAuth authentication works:**

1. You enable Developer Mode and add the MCP server URL in Connectors settings
2. ChatGPT initiates an OAuth flow
3. Your browser opens a consent page hosted by Bito
4. You enter your email and approve the connection
5. ChatGPT receives secure tokens automatically
6. Your email is tracked for usage analytics (collected during OAuth consent)

**Benefits:**

* No manual token management
* Secure browser-based authentication
* Automatic token refresh
* Email collected during consent (no separate header needed)

## Set up AI Architect

{% stepper %}
{% step %}

### Enable Developer mode

1. Go to [chatgpt.com](https://chatgpt.com) (or open the ChatGPT desktop app) and sign in
2. Click on your **profile icon** (bottom-left corner)
3. Select **Settings**
4. Go to **Apps and Connectors** (or just **Connectors**)
5. Scroll down and click **"Advanced Settings"**
6. Toggle **"Developer Mode"** to ON
   {% endstep %}

{% step %}

### Create Bito AI Architect Connector

1. In the **Connectors** section, click **"Create"** or **"+ Add Connector"**
2. Fill in the connector details:
   * **Connector Name:** BitoAIArchitect
   * **Description:** Repository intelligence and architecture analysis for your organization
   * **MCP Server URL:** `<Your-Bito-MCP-URL>`
   * **Authentication:** Select **"OAuth"**

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
    {% endhint %}

3. Click **"Create"** or **"Save"**
   {% endstep %}

{% step %}

### Complete OAuth authorization

1. Click on the newly created BitoAIArchitect connector
2. Click **"Connect"** to initiate the OAuth flow
3. A browser window opens showing the **Bito Authorization** page
4. Review the requested permissions
5. **Enter your email address** (required for tracking)
6. Click **"Authorize"** or **"Allow"**
7. Return to ChatGPT - the connection is now active
   {% endstep %}

{% step %}

### Verify connection

1. Return to ChatGPT Settings → Connectors
2. BitoAIArchitect should show as **"Connected"**
3. Start a new conversation
4. In the composer, click **"Use Connectors"** or look for the connector tools
5. Try asking:

   ```
   What repositories are available in my organization?
   ```

{% endstep %}

{% step %}

### Using Bito AI Architect in ChatGPT

Once connected, you can use **BitoAIArchitect** in several ways:

* **Direct prompts:** Ask questions about your repositories
* **Deep Research:** BitoAIArchitect tools appear in "Deep Research" mode
* **Connectors menu:** Select BitoAIArchitect from the "Use Connectors" option
  {% endstep %}
  {% endstepper %}

## Troubleshooting ChatGPT

#### **"Connectors" or Developer Mode option not visible:**

* Verify you have a paid ChatGPT subscription (Plus, Pro, Team, Enterprise, or Edu)
* Free tier accounts do not have connector access
* The feature may be rolling out gradually - check back later if recently subscribed

#### **OAuth authorization fails:**

* Ensure pop-ups are allowed for chatgpt.com
* Check that your Workspace ID is correct
* Verify your organization has OAuth enabled for the MCP server
* Try using an incognito/private browser window

#### **"Error fetching OAuth configuration":**

* Verify the MCP server URL is correct and accessible
* Ensure the server supports OAuth 2.1 with dynamic client registration
* Check that `code_challenge_methods_supported` includes `S256` in the authorization server metadata

#### **Connection shows "Error" or "Disconnected":**

* Click the connection and select "Reconnect"
* OAuth tokens may have expired - re-authorize when prompted
* Check if your Bito workspace is still active

#### **Tools not working in conversation:**

* Ensure the MCP connection shows "Connected" status
* Try starting a fresh conversation
* Explicitly mention "use BitoAIArchitect" in your prompt if tools don't activate automatically
* Check that you're using the connector in a mode that supports tools (not all chat modes do)


# Integrating with Bito's AI Code Review Agent

Leverage AI Architect's knowledge graph to power more intelligent code reviews

Enhance your code reviews with deeper codebase intelligence by connecting Bito's [AI Code Review Agent](/ai-code-reviews-in-git/overview) to [AI Architect](/ai-architect/overview). This integration enables significantly more accurate and context-aware reviews by leveraging the comprehensive knowledge graph that AI Architect builds from your codebase.

### What this integration provides

When AI Code Review Agent accesses AI Architect's knowledge graph, it gains a complete understanding of your codebase architecture — including microservices, modules, APIs, dependencies, and design patterns.

This enhanced context allows 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

### Setup instructions

Follow these steps to connect AI Architect with AI Code Review Agent:

1. Log in to [**Bito Cloud**](https://alpha.bito.ai/home/welcome)
2. Open the [**AI Architect Settings**](https://alpha.bito.ai/home/ai-architect/settings?mode=self-hosted) 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?

Contact our team at [**support@bito.ai**](mailto:support@bito.ai) to request a trial. We'll help you configure the integration and get your team up and running quickly.


# Manual MCP integration with AI coding agents


# Guide for Claude Code

Integrate Claude Code with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **Claude Code** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), Claude Code can leverage AI Architect’s deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Quick setup (recommended)

**Want to get started faster?** We offer an automated installer that can configure AI Architect for all your AI coding tools in just a few seconds.

The automated setup will:

* Detect all compatible AI tools installed on your system
* Configure them automatically with your credentials
* Save you time by eliminating manual configuration steps

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) for automated setup.

## Manual setup

If you prefer manual configuration, follow the step-by-step instructions below.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md** file](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

## Set up AI Architect

Claude Code has the same setup process across all platforms (Windows, macOS, Linux, WSL) using the command line.

Claude Code uses CLI-based configuration, NOT manual JSON editing.

{% stepper %}
{% step %}

### Install Claude Code

If you haven't already:

```shellscript
npm install -g @anthropic-ai/claude-code
```

Verify installation:

```shellscript
claude --version
```

{% endstep %}

{% step %}

### Add Bito AI Architect MCP server

Use the `claude mcp add` command with the correct parameter order:

```shellscript
claude mcp add \
  --transport http \
  --scope user \
  BitoAIArchitect \
  <Your-Bito-MCP-URL> \
  --header "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  --header "x-email-id: <Your-Email>"
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

{% hint style="info" %}
**Important:** The server name and URL must come BEFORE the `--header` option.
{% endhint %}

{% hint style="info" %}
**Scope options:**

* `--scope user`: Available in all your projects (recommended)
* `--scope project`: Only in current project (stored in `.mcp.json`)
* `--scope local`: Only in current directory (default)
  {% endhint %}
  {% endstep %}

{% step %}

### Verify installation

List your MCP servers:

```shellscript
claude mcp list
```

You should see "BitoAIArchitect" in the list.

Test the server:

```shellscript
claude mcp get BitoAIArchitect
```

{% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

**You can either create:**

1. **Global guidelines** - Apply across all your projects. Best for teams or developers who want consistent standards everywhere.
2. **Project-specific guidelines** - Apply to a single project only.

Choose one of the following based on your preference:

### Option A: Global guidelines

Create `.claude` directory if it doesn't exist:

```shellscript
mkdir -p ~/.claude
```

Create or edit `CLAUDE.md`:

```shellscript
nano ~/.claude/CLAUDE.md
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into this file, then save.

### Option B: Project-specific guidelines

Run this command in your project directory:

```shellscript
nano CLAUDE.md
```

Or run these commands:

```shellscript
mkdir -p .claude
```

```shellscript
nano .claude/CLAUDE.md
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into this file, then save.
{% endstep %}

{% step %}

### Start using Claude Code

In your project directory, run:

```shellscript
claude
```

Now, in the chat you can ask questions about your indexed repositories. The AI Architect will help Claude Code provide accurate answers based on your codebase.

**Try asking something like:**

```
What repositories are available in my organization?
```

{% endstep %}
{% endstepper %}

## Windows-specific notes

#### Windows (Native - Command Prompt/PowerShell):

* MCP servers using `npx` require the `cmd /c` wrapper:

```shellscript
# For stdio servers on Windows
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
```

#### Windows (WSL):

* Configuration is stored in Linux file system
* No need for `cmd /c` wrapper
* Use standard Linux paths (`~/.claude/`)

## Configuration file locations

<table><thead><tr><th width="104.60003662109375">Platform</th><th>Main config</th><th>Settings</th><th>Global guidelines</th></tr></thead><tbody><tr><td><strong>Windows</strong></td><td><code>%USERPROFILE%\.claude\claude.json</code></td><td><code>%USERPROFILE%\.claude\settings.json</code></td><td><code>%USERPROFILE%\.claude\CLAUDE.md</code></td></tr><tr><td><strong>macOS</strong></td><td><code>~/.claude/claude.json</code></td><td><code>~/.claude/settings.json</code></td><td><code>~/.claude/CLAUDE.md</code></td></tr><tr><td><strong>Linux</strong></td><td><code>~/.claude/claude.json</code></td><td><code>~/.claude/settings.json</code></td><td><code>~/.claude/CLAUDE.md</code></td></tr><tr><td><strong>WSL</strong></td><td><code>~/.claude/claude.json</code></td><td><code>~/.claude/settings.json</code></td><td><code>~/.claude/CLAUDE.md</code></td></tr></tbody></table>

{% hint style="info" %}
**IMPORTANT:**

* ✅ These files are managed automatically by `claude mcp` commands
* ❌ Do NOT manually create `~/.claude/mcp.json` (this file doesn't exist)
* ❌ Do NOT manually edit `~/.claude/claude.json` (use CLI commands instead)
  {% endhint %}

## Common Claude Code MCP commands

```shellscript
# Add HTTP server with Bearer token (correct parameter order)
claude mcp add --transport http --scope user \
  <name> <url> \
  --header "Authorization: Bearer <token>" \
  --header "x-email-id: <your-email>"

# Add server with environment variables
claude mcp add <name> -e API_KEY="value" -- npx @server/package

# Add server with JSON config (for complex setups)
claude mcp add-json <name> '{"type":"http","url":"...","headers":{...}}'

# List all MCP servers
claude mcp list

# Get server details
claude mcp get <name>

# Remove MCP server
claude mcp remove <name>

# View server status (inside Claude Code session)
/mcp

# Reset project-scoped server approval choices
claude mcp reset-project-choices

```

## Troubleshooting Claude Code

#### Server not appearing:

```shellscript
# Verify it was added
claude mcp list

# Check for errors
claude --verbose

# Try removing and re-adding
claude mcp remove BitoAIArchitect
claude mcp add --transport http --scope user \
  BitoAIArchitect <Your-Bito-MCP-URL> \
  --header "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  --header "x-email-id: <Your-Email>"
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

#### Connection issues:

```shellscript
# Test the endpoint with proper MCP protocol
curl -s -X POST \
  -H "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' \
  <Your-Bito-MCP-URL>

# Should return HTTP 200 with JSON response for valid credentials
# HTTP 401: Invalid Bito MCP Access Token
# HTTP 404: Invalid Bito MCP URL
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
  {% endhint %}

#### Permission issues (macOS/Linux):

```shellscript
chmod 755 ~/.claude
chmod 644 ~/.claude/claude.json
chmod 644 ~/.claude/settings.json
```


# Guide for Cursor

Integrate Cursor with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **Cursor** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), Cursor can leverage AI Architect’s deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Quick setup (recommended)

**Want to get started faster?** We offer an automated installer that can configure AI Architect for all your AI coding tools in just a few seconds.

The automated setup will:

* Detect all compatible AI tools installed on your system
* Configure them automatically with your credentials
* Save you time by eliminating manual configuration steps

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) for automated setup.

## Manual setup

If you prefer manual configuration, follow the step-by-step instructions below.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md** file](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

## Set up AI Architect

Follow the setup instructions for your operating system:

* [**Windows**](#windows)
* [**macOS/Linux**](#macos-linux)

## Windows

{% stepper %}
{% step %}

### Create Cursor config directory

1. Press `Win + R`
2. Type: `%USERPROFILE%\.cursor`
3. Press Enter

If the folder doesn't exist, create it:

1. Open File Explorer
2. Navigate to `%USERPROFILE%`
3. Create new folder: `.cursor`
   {% endstep %}

{% step %}

### Create or edit mcp.json

1. Open `%USERPROFILE%\.cursor\mcp.json` in a text editor.
2. If the file doesn't exist, create it with this content:

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "url": "<Your-Bito-MCP-URL>",
      "headers": {
        "Authorization": "Bearer <Your-Bito-MCP-Access-Token>",
        "x-email-id": "<Your-Email>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

3. If the file exists with other servers, add `BitoAIArchitect` to the `mcpServers` object:

```json
{
  "mcpServers": {
    "existing-server": {
      ...
    },
    "BitoAIArchitect": {
      "url": "<Your-Bito-MCP-URL>",
      "headers": {
        "Authorization": "Bearer <Your-Bito-MCP-Access-Token>",
        "x-email-id": "<Your-Email>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}
  {% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

1. In your project root, create `.cursorrules` file.
2. Open this file with a text editor.
3. Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `.cursorules` file.
4. Save.
   {% endstep %}

{% step %}

### Restart Cursor

1. Close Cursor completely
2. Reopen Cursor
3. Open **Settings → Tools & MCP**
4. Verify `BitoAIArchitect` appears in the MCP servers list
   {% endstep %}
   {% endstepper %}

## macOS/Linux

{% stepper %}
{% step %}

### Create Cursor config directory

```shellscript
mkdir -p ~/.cursor
```

{% endstep %}

{% step %}

### Create or edit mcp.json

```
nano ~/.cursor/mcp.json
```

Add this content:

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "url": "<Your-Bito-MCP-URL>",
      "headers": {
        "Authorization": "Bearer <Your-Bito-MCP-Access-Token>",
        "x-email-id": "<Your-Email>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

Save and exit (Ctrl+O, Enter, Ctrl+X)
{% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

1. In your project root, create `.cursorrules` file.
2. Open this file with a text editor.
3. Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `.cursorules` file.
4. Save.
   {% endstep %}

{% step %}

### Restart Cursor

1. Close Cursor completely
2. Reopen Cursor
3. Open **Settings → Tools & MCP**
4. Verify `BitoAIArchitect` appears in the MCP servers list
   {% endstep %}
   {% endstepper %}

## Troubleshooting Cursor

#### Server not showing:

```shellscript
# Verify file location
ls -la ~/.cursor/mcp.json

# Check file permissions
chmod 644 ~/.cursor/mcp.json

# Verify JSON syntax
cat ~/.cursor/mcp.json | python -m json.tool
```

#### Connection errors:

* Verify **Bito MCP URL** and **Bito MCP Access Token** are correct.
* Test endpoint with MCP protocol:

```shellscript
curl -s -X POST \
  -H "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' \
  <Your-Bito-MCP-URL>

# Should return HTTP 200 with JSON response for valid credentials
# HTTP 401: Invalid Bito MCP Access Token
# HTTP 404: Invalid Bito MCP URL
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)

* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
  {% endhint %}

* Check **Settings → Tools & MCP** for error messages


# Guide for Windsurf

Integrate Windsurf with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **Windsurf** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), Windsurf can leverage AI Architect’s deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Quick setup (recommended)

**Want to get started faster?** We offer an automated installer that can configure AI Architect for all your AI coding tools in just a few seconds.

The automated setup will:

* Detect all compatible AI tools installed on your system
* Configure them automatically with your credentials
* Save you time by eliminating manual configuration steps

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) for automated setup.

## Manual setup

If you prefer manual configuration, follow the step-by-step instructions below.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md** file](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

## Set up AI Architect

Follow the setup instructions for your operating system:

* [**Windows**](#windows)
* [**macOS/Linux**](#macos-linux)

## Windows

{% stepper %}
{% step %}

### Create Windsurf config directory

1. Press **Win + R**
2. Type: `%USERPROFILE%\.codeium\windsurf`
3. Press **Enter**

If the folders don't exist, create them:

1. Open File Explorer
2. Navigate to `%USERPROFILE%`
3. Create folders: `.codeium\windsurf`
   {% endstep %}

{% step %}

### Create or edit mcp\_config.json

1. Open `%USERPROFILE%\.codeium\windsurf\mcp_config.json` in a text editor.
2. If the file doesn't exist, create it with this content:

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "serverUrl": "<Your-Bito-MCP-URL>",
      "headers": {
        "Authorization": "Bearer <Your-Bito-MCP-Access-Token>",
        "x-email-id": "<Your-Email>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

3. If the file exists with other servers, add `BitoAIArchitect` to the `mcpServers` object:

```json
{
  "mcpServers": {
    "existing-server": {
      ...
    },
    "BitoAIArchitect": {
      "serverUrl": "<Your-Bito-MCP-URL>",
      "headers": {
        "Authorization": "Bearer <Your-Bito-MCP-Access-Token>",
        "x-email-id": "<Your-Email>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

4. Save
   {% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

#### Option A: Global guidelines (applies to all projects):

Create directory:

```shellscript
mkdir %USERPROFILE%\.codeium\windsurf\memories
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `global_rules.md` file:

```shellscript
copy BitoAIArchitectGuidelines.md %USERPROFILE%\.codeium\windsurf\memories\global_rules.md
```

#### Option B: Project-level guidelines (applies to specific project):

In your project directory, create `.windsurf\rules` directory:

```shellscript
mkdir .windsurf\rules
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `bitoai-architect.md` file:

```shellscript
copy BitoAIArchitectGuidelines.md .windsurf\rules\bitoai-architect.md
```

{% hint style="info" %}
**Note:** Windsurf Wave 8+ uses `.windsurf\rules\*.md` format for project-level rules. Global guidelines in `~/.codeium/windsurf/memories/global_rules.md` are supported in all versions.
{% endhint %}
{% endstep %}

{% step %}

### Restart Windsurf

1. Close Windsurf completely
2. Reopen Windsurf
3. Open **Settings → Cascade → MCP Servers**
4. Click "Refresh"
5. Verify `BitoAIArchitect` appears with green status
   {% endstep %}
   {% endstepper %}

## macOS/Linux

{% stepper %}
{% step %}

### Create Windsurf config directory

```shellscript
mkdir -p ~/.codeium/windsurf
```

{% endstep %}

{% step %}

### Create or edit mcp\_config.json

```shellscript
nano ~/.codeium/windsurf/mcp_config.json
```

Add this content:

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "serverUrl": "<Your-Bito-MCP-URL>",
      "headers": {
        "Authorization": "Bearer <Your-Bito-MCP-Access-Token>",
        "x-email-id": "<Your-Email>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

Save and exit (Ctrl+O, Enter, Ctrl+X)
{% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

#### Option A: Global guidelines (applies to all projects):

Create directory:

```shellscript
mkdir -p ~/.codeium/windsurf/memories
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `global_rules.md` file:

```shellscript
cp BitoAIArchitectGuidelines.md ~/.codeium/windsurf/memories/global_rules.md
```

#### Option B: Project-level guidelines (applies to specific project):

In your project directory, create `.windsurf/rules` directory:

```shellscript
mkdir -p .windsurf/rules
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `bitoai-architect.md` file:

```shellscript
cp BitoAIArchitectGuidelines.md .windsurf/rules/bitoai-architect.md
```

{% hint style="info" %}
**Note:** Windsurf Wave 8+ uses `.windsurf/rules/*.md` format for project-level rules. Global guidelines in `~/.codeium/windsurf/memories/global_rules.md` are supported in all versions.
{% endhint %}
{% endstep %}

{% step %}

### Restart Windsurf

1. Close Windsurf completely
2. Reopen Windsurf
3. Open **Settings → Cascade → MCP Servers**
4. Click "Refresh"
5. Verify `BitoAIArchitect` appears with green status
   {% endstep %}
   {% endstepper %}

## Troubleshooting Windsurf

#### Server not showing:

```shellscript
# Verify file location
ls -la ~/.codeium/windsurf/mcp_config.json

# Check permissions
chmod 755 ~/.codeium/windsurf
chmod 644 ~/.codeium/windsurf/mcp_config.json

# Verify JSON syntax
cat ~/.codeium/windsurf/mcp_config.json | python -m json.tool
```

#### Connection errors:

* Verify **Bito MCP URL** and **Bito MCP Access Token** are correct.
* Test endpoint with MCP protocol:

```shellscript
curl -s -X POST \
  -H "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' \
  <Your-Bito-MCP-URL>

# Should return HTTP 200 with JSON response for valid credentials
# HTTP 401: Invalid Bito MCP Access Token
# HTTP 404: Invalid Bito MCP URL
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)

* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
  {% endhint %}

* Check **Settings → Cascade → MCP Servers** for error messages.


# Guide for GitHub Copilot (VS Code)

Integrate GitHub Copilot in VS Code with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **GitHub Copilot in VS Code** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), GitHub Copilot can leverage AI Architect’s deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Quick setup (recommended)

**Want to get started faster?** We offer an automated installer that can configure AI Architect for all your AI coding tools in just a few seconds.

The automated setup will:

* Detect all compatible AI tools installed on your system
* Configure them automatically with your credentials
* Save you time by eliminating manual configuration steps

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) for automated setup.

## Manual setup

If you prefer manual configuration, follow the step-by-step instructions below.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md** file](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.
3. **Requires Visual Studio Code version 1.99 or later**
   1. **Check VS Code version:** `code --version`
   2. **Update VS Code if needed:** Help → Check for Updates
4. **Enable Agent Mode**
   1. Open VS Code Settings (Ctrl/Cmd + ,)
   2. Search: `chat.agent.enabled`
   3. Check the box to enable Agent Mode
5. **Ensure Node.js 20.18.1+ is Installed:**

   VS Code's MCP implementation automatically tries to use OAuth for HTTP servers. For static Bearer token authentication (which Bito AI Architect uses), you need to use the `mcp-remote` proxy tool.

   The `mcp-remote` proxy requires **Node.js 20.18.1 or higher**.

   **Why Node.js 20+?** The mcp-remote proxy depends on undici v7, which requires Node.js 20+ (needs the `File` global API added in Node 20.0.0). Node.js 18 and earlier will fail with `ReferenceError: File is not defined`.

   **Windows:** Download from <https://nodejs.org/> (download 20.x LTS)

   **macOS:**

   ```shellscript
   brew install node@20
   # Or use nvm: nvm install 20 && nvm use 20
   ```

   **Linux (Ubuntu/Debian):**

   ```shellscript
   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt-get install -y nodejs
   ```

   **Verify:**

   ```shellscript
   node --version  # Should show v20.x.x or higher
   npx --version
   ```
6. GitHub Copilot extension installed and enabled
7. GitHub account with Copilot access

## Set up AI Architect

VS Code has the same setup process across all platforms (Windows, macOS, Linux, WSL).

### Workspace configuration (recommended)

{% stepper %}
{% step %}

### Create .vscode directory

In your project root:

```shellscript
mkdir .vscode
```

{% endstep %}

{% step %}

### Create mcp.json

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "BitoAIArchitect": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>",
        "--header",
        "Authorization: Bearer <Your-Bito-MCP-Access-Token>",
        "--header",
        "x-email-id: <Your-Email>"
      ]
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

**Important:**

* Include `"type": "stdio"` in the configuration
* VS Code requires `mcp-remote` proxy for static Bearer token authentication
* The `"servers"` object is at the root level in workspace configs
* Direct HTTP transport with static Bearer tokens triggers OAuth flows in VS Code

**Why mcp-remote?** VS Code's MCP implementation automatically initiates OAuth discovery when connecting to HTTP MCP servers. Since `BitoAIArchitect` uses static Bearer token authentication (not OAuth), we use the `mcp-remote` proxy to handle the authentication properly.
{% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

Create `.github` directory:

```shellscript
mkdir -p .github
```

Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `.github/copilot-instructions.md` file:

```shellscript
cp BitoAIArchitectGuidelines.md .github/copilot-instructions.md
```

{% endstep %}

{% step %}

### Start the MCP server

**Important:** VS Code requires manually starting MCP servers. Follow these steps:

1. Open **Copilot Chat** (Ctrl/Cmd + I)
2. Click the **gear icon** in the Copilot Chat panel
3. Select **"MCP Servers"**
4. Find **BitoAIArchitect** in the list
5. Click the **gear icon** next to BitoAIArchitect
6. Select **"Start Server"**

**Alternative method:**

1. Open `.vscode/mcp.json` in VS Code
2. Look for a **Start** button above the configuration
3. Click **Start** to initialize the server
   {% endstep %}

{% step %}

### Verify in Copilot Chat

1. Open Copilot Chat (Ctrl/Cmd + I)
2. Switch to Agent mode (toggle in chat interface)
3. Click the Tools icon (wrench)
4. Verify `BitoAIArchitect` appears in the tools list
5. Try asking: "What repositories are available?"
   {% endstep %}
   {% endstepper %}

### User configuration (global)

To make `BitoAIArchitect` available in ALL projects, create a user-level `mcp.json` file:

#### Windows

* **Create/edit:** `%APPDATA%\Code\User\mcp.json`

#### macOS

* **Create/edit:** `~/Library/Application Support/Code/User/mcp.json`

#### Linux

* **Create/edit:** `~/.config/Code/User/mcp.json`

#### Configuration

Add this to your `mcp.json`:

```json
{
  "servers": {
    "BitoAIArchitect": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>",
        "--header",
        "Authorization: Bearer <Your-Bito-MCP-Access-Token>",
        "--header",
        "x-email-id: <Your-Email>"
      ]
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

#### Enable MCP discovery

Also ensure MCP discovery is enabled in your `settings.json`:

```
{
  "chat.mcp.discovery.enabled": true
}
```

**Important:**

* User-level config uses `mcp.json` (separate from `settings.json`)
* Include `"type": "stdio"` in the configuration
* After saving, manually start the server via Copilot Chat (see Step 4 above)

## Troubleshooting VS Code (GitHub Copilot)

#### Server not appearing in MCP Servers list:

1. Verify `mcp.json` is in the correct location (see paths above)
2. Ensure `"type": "stdio"` is included in the configuration
3. Check JSON syntax is valid
4. Restart VS Code completely (Cmd+Q / Alt+F4)

#### Server not starting:

1. Manually start the server:
   * Open Copilot Chat → gear icon → MCP Servers
   * Click gear icon next to BitoAIArchitect → Start Server
2. Check Node.js version: `node --version` (must be 20.18.1+)
3. View → Output → select "MCP" for error messages

#### Tools not showing in Copilot Chat:

1. Ensure server is started (see above)
2. Open Copilot Chat
3. Switch to Agent mode
4. Click Tools (wrench icon)
5. Verify BitoAIArchitect appears

#### Agent Mode not available:

1. Update VS Code to 1.99+
2. Settings → Search: `chat.agent.enabled`
3. Enable the checkbox

#### MCP discovery issues:

Ensure `settings.json` has:

```
"chat.mcp.discovery.enabled": true
```

**Note:** This must be a boolean `true`, NOT an object like `{"claude-desktop": true}`.

#### Node.js version too old:

Error: `ReferenceError: File is not defined` or similar

* Upgrade Node.js to 20.18.1 or later
* If using nvm: `nvm install 20 && nvm use 20 && nvm alias default 20`

#### Reset if needed:

* Ctrl/Cmd + Shift + P
* Run: `MCP: Reset Cached Tools`
* Restart VS Code

#### OAuth prompts appearing:

If VS Code is prompting for OAuth instead of using your Bearer token:

1. Ensure you're using the `mcp-remote` proxy configuration (not direct HTTP)
2. Verify `"type": "stdio"` is in your config
3. Cancel the OAuth prompt - the server should still work
4. Check that Node.js and npx are installed: `npx --version`


# Guide for Junie (JetBrains)

Integrate Junie (JetBrains) with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **Junie (JetBrains)** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), Junie can leverage AI Architect’s deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Quick setup (recommended)

**Want to get started faster?** We offer an automated installer that can configure AI Architect for all your AI coding tools in just a few seconds.

The automated setup will:

* Detect all compatible AI tools installed on your system
* Configure them automatically with your credentials
* Save you time by eliminating manual configuration steps

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) for automated setup.

## Manual setup

If you prefer manual configuration, follow the step-by-step instructions below.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md** file](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.
3. **Junie installed in a JetBrains IDE** (IntelliJ IDEA, PyCharm, WebStorm, etc.)
4. **Node.js 20.18.1+** installed (for `mcp-remote` proxy)
   1. **Why Node.js 20+?** The mcp-remote proxy depends on undici v7, which requires Node.js 20+ (needs the `File` global API added in Node 20.0.0). Node.js 18 and earlier will fail with `ReferenceError: File is not defined`.
   2. **Verify:**

      ```shellscript
      node --version  # Should show v20.x.x or higher
      npx --version
      ```
   3. If Node.js is not installed or the version < 20 then [download Node.js 20.x LTS](https://nodejs.org/)

## Set up AI Architect <a href="#set-up-ai-architect" id="set-up-ai-architect"></a>

Junie has the same setup process across all platforms (Windows, macOS, Linux, WSL).

{% stepper %}
{% step %}

### Access Junie MCP settings

1. Open your JetBrains IDE (IntelliJ, PyCharm, etc.)
2. Go to: **Settings** (Ctrl/Cmd + Alt + S)
3. Navigate to: **Tools** → **Junie** → **MCP Settings**
4. Click the **+** (Add) button to open the global `mcp.json` configuration file in the editor, or manually edit the file as shown below
   {% endstep %}

{% step %}

### Configure `BitoAIArchitect`

The global configuration file is located at:

* **macOS/Linux**: `~/.junie/mcp/mcp.json`
* **Windows**: `%USERPROFILE%\.junie\mcp\mcp.json`

**macOS/Linux configuration:**

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "x-email-id: <Your-Email>"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <Your-Bito-MCP-Access-Token>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

**Windows configuration (IMPORTANT - uses cmd /c):**

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "x-email-id: <Your-Email>"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <Your-Bito-MCP-Access-Token>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}
  {% endstep %}

{% step %}

### Save and restart

1. Save the `mcp.json` file
2. Close all JetBrains IDE windows
3. Reopen your IDE
   {% endstep %}

{% step %}

### Verify connection

1. Go to: **Settings** → **Tools** → **Junie** → **MCP Settings**
2. Check that `BitoAIArchitect` appears in the server list
3. Status should show as **Connected** or **Running**
   {% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

To add Bito AI Architect usage guidelines to a specific project:

1. Navigate to your project root
2. Create `.junie` directory:

   ```shellscript
   mkdir -p .junie
   ```

   Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `.junie/guidelines.md` file:

   ```shellscript
   cp /path/to/BitoAIArchitectGuidelines.md .junie/guidelines.md
   ```
3. Junie will automatically use these guidelines for the project

**What Junie guidelines should contain:**

* `BitoAIArchitect` MCP usage best practices
* When to query repository information
* How to search for dependencies and tech stacks
  {% endstep %}
  {% endstepper %}

## Troubleshooting

#### Junie not showing `BitoAIArchitect`:

1. Verify Node.js is installed: `node --version`
2. Check `mcp.json` syntax (must be valid JSON)
3. On Windows, ensure you're using `cmd` with `/c` argument
4. Restart the IDE completely

#### Connection errors:

1. **Test the endpoint manually:**

```shellscript
# Use proper MCP protocol to test authentication
curl -s -X POST \
  -H "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' \
  <Your-Bito-MCP-URL>
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
  {% endhint %}

2. Verify your **Bito MCP URL** and **Bito MCP Access Token** are correct
3. Check firewall settings


# Guide for JetBrains AI Assistant

Integrate JetBrains AI Assistant with AI Architect for more accurate, codebase-aware AI assistance.

Use Bito's [**AI Architect**](/ai-architect/overview) with **JetBrains AI Assistant** to enhance your AI-powered coding experience.

Once connected via MCP (Model Context Protocol), JetBrains AI Assistant can leverage AI Architect’s deep contextual understanding of your project, enabling more accurate code suggestions, explanations, and code insights.

## Quick setup (recommended)

**Want to get started faster?** We offer an automated installer that can configure AI Architect for all your AI coding tools in just a few seconds.

The automated setup will:

* Detect all compatible AI tools installed on your system
* Configure them automatically with your credentials
* Save you time by eliminating manual configuration steps

👉 [**Try our Quick MCP Integration Guide**](/ai-architect/quick-mcp-integration-with-ai-coding-agents) for automated setup.

## Manual setup

If you prefer manual configuration, follow the step-by-step instructions below.

## Prerequisites

1. Follow the [**AI Architect installation instructions**](/ai-architect/installation/install-ai-architect-self-hosted). Upon successful setup, you will receive a **Bito MCP URL** and **Bito MCP Access Token** that you need to enter in your coding agent.
2. [Download **BitoAIArchitectGuidelines.md** file](https://github.com/gitbito/ai-architect/blob/main/BitoAIArchitectGuidelines.md). You will need to copy/paste the content from this file later when configuring AI Architect.
   * **Note:** This file contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server. The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.
3. **JetBrains IDE**: IntelliJ IDEA 2025.1+ (or PyCharm, WebStorm, PhpStorm, etc. 2025.1+)
4. **AI Assistant Plugin (version 251.26094.80.5 or higher)**
   1. Open your JetBrains IDE
   2. Go to: **Settings** (Ctrl/Cmd + Alt + S)
   3. Navigate to: **Plugins**
   4. Search for "AI Assistant"
   5. Verify version is 251.26094.80.5 or higher
5. **Node.js**: **20.18.1+** installed (for mcp-remote proxy)
   1. **Why Node.js 20+?** The mcp-remote proxy depends on undici v7, which requires Node.js 20+ (needs the `File` global API added in Node 20.0.0). Node.js 18 and earlier will fail with `ReferenceError: File is not defined`.
   2. Verify:

      ```shellscript
      node --version  # Should show v20.x.x or higher
      npx --version
      ```
   3. If Node.js is not installed or the version < 20 then [download Node.js 20.x LTS](https://nodejs.org/)

## Set up AI Architect <a href="#set-up-ai-architect" id="set-up-ai-architect"></a>

JetBrains AI Assistant has the same setup process across all platforms (Windows, macOS, Linux, WSL).

{% stepper %}
{% step %}

### Access MCP settings

1. Open your JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm, etc.)
2. Go to: **Settings** (Ctrl/Cmd + Alt + S)
3. Navigate to: **Tools** → **AI Assistant** → **Model Context Protocol (MCP)**
4. Click **Add** to add a new MCP server
   {% endstep %}

{% step %}

### Configure `BitoAIArchitect`

The configuration dialog accepts JSON input. Paste the appropriate JSON configuration for your platform:

#### **macOS/Linux configuration:**

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "x-email-id: <Your-Email>"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <Your-Bito-MCP-Access-Token>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}

#### **Windows configuration (IMPORTANT - uses cmd):**

```json
{
  "mcpServers": {
    "BitoAIArchitect": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "<Your-Bito-MCP-URL>",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "x-email-id: <Your-Email>"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <Your-Bito-MCP-Access-Token>"
      }
    }
  }
}
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
* Replace `<Your-Email>` with your actual email address.
  {% endhint %}
  {% endstep %}

{% step %}

### Save and restart

1. Click **OK** to save the MCP server configuration
2. Click **OK** to close Settings
3. Restart your IDE completely
   {% endstep %}

{% step %}

### Verify connection

1. Go to: **Settings** → **Tools** → **AI Assistant** → **Model Context Protocol (MCP)**
2. Find `BitoAIArchitect` in the list
3. Check the **Status** column - should show **Running** or **Connected**
   {% endstep %}

{% step %}

### Enable Codebase Mode

**IMPORTANT**: MCP tools only work in "Codebase" mode or Edit mode.

To use `BitoAIArchitect`:

1. Open JetBrains AI Assistant chat
2. Toggle on the **"Codebase"** mode switch at the top of the chat window
3. OR use Edit mode (Ctrl/Cmd + Shift + Enter), which implicitly enables codebase context
   {% endstep %}

{% step %}

### Add guidelines (optional but highly recommended)

The [**BitoAIArchitectGuidelines.md** file](#prerequisites) contains best practices, usage instructions, and prompting guidelines for the Bito AI Architect MCP server.

The setup will work without this file, but including it helps AI tools interact more effectively with the Bito AI Architect MCP server.

To add Bito AI Architect usage rules to a specific project:

1. Navigate to your project root
2. Create `.aiassistant/rules/` directory:

   ```shellscript
   mkdir -p .aiassistant/rules
   ```
3. Create a rule file (e.g., `bitoai-architect.md`):

   Copy the contents of your [**BitoAIArchitectGuidelines.md** file](#prerequisites) into `.aiassistant/rules/bitoai-architect.md` file:

   ```shellscript
   cp /path/to/BitoAIArchitectGuidelines.md .aiassistant/rules/bitoai-architect.md
   ```
4. In your IDE: **Settings** → **Tools** → **AI Assistant** → **Rules**
5. The rule file should appear automatically
6. Configure how it should be applied:
   * **Always**: Applied to all chats automatically
   * **Manually**: Invoked using `@rule:bitoai-architect`
   * **By Model Decision**: AI decides when to apply
   * **By File Patterns**: Applied when specific files are open

**What AI Assistant rules should contain:**

* `BitoAIArchitect` MCP usage instructions
* When to query organizational repositories
* How to search for dependencies and tech stacks
  {% endstep %}
  {% endstepper %}

## Troubleshooting

#### JetBrains AI Assistant not showing MCP settings:

1. Verify IDE version is 2025.1 or later
2. Verify AI Assistant plugin is version 251.26094.80.5+
3. Update both if needed

#### `BitoAIArchitect` not appearing or showing "Not started":

1. Verify Node.js is installed: `node --version`
2. Check that you've toggled "Codebase" mode ON in the chat
3. On Windows, ensure you're using `cmd` command (not `npx` directly)
4. Restart the IDE completely
5. Check IDE logs for errors: **Help** → **Show Log in Explorer/Finder**
   * Look for files in the `mcp` folder

#### Connection errors:

1. **Test the endpoint manually:**

```shellscript
# Use proper MCP protocol to test authentication
curl -s -X POST \
  -H "Authorization: Bearer <Your-Bito-MCP-Access-Token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' \
  <Your-Bito-MCP-URL>
```

{% hint style="info" %}
**Note:**

* Replace `<Your-Bito-MCP-URL>` with the **Bito MCP URL** you received after completing the AI Architect setup.
  * For the Bito-hosted AI Architect, use the following URL format: `https://mcp.bito.ai/<Your-Bito-Workspace-ID>/mcp`

    Replace `<Your-Bito-Workspace-ID>` with your actual Bito workspace ID, which you can find after logging into your Bito account at [**alpha.bito.ai**](https://alpha.bito.ai/)
* Replace `<Your-Bito-MCP-Access-Token>` with the **Bito MCP Access Token** you received after completing the AI Architect setup.
  {% endhint %}

2. Verify your **Bito MCP URL** and **Bito MCP Access Token** are correct
3. Check firewall settings
4. Verify the `--header` argument format: `Authorization:${AUTH_HEADER}` (colon, no space)

#### Windows-specific issues:

1. Verify the JSON uses `"command": "cmd"` (not `npx`)
2. Ensure `"/c"` is the first element in the `args` array
3. Node.js must be in system PATH


# AI Code Review Agent (with AI Architect vs without AI Architect)

From single-repo reviews to system-wide insights

The [AI Code Review Agent](/ai-code-reviews-in-git/overview) becomes significantly more powerful when paired with [**AI Architect**](/ai-architect/overview).

Below is a clear explanation of how the agent behaves in each setup and why AI Architect unlocks much deeper, system-level insights.

## AI Code Review Agent without AI Architect

The standard AI Code Review Agent analyzes code at the **repository level**.

It creates a ***within-repo knowledge graph*** by building:

* Abstract Syntax Trees (ASTs)
* Symbol indexes
* Local dependency relationships

This allows it to perform strong, context-aware code reviews **within a single repository**, including:

* Identifying issues in the diff
* Understanding dependencies inside the repo
* Checking for consistency and correctness within that project
* Suggesting improvements based on local patterns

However, the agent’s visibility stops at the repository boundary. It cannot detect effects on other services or codebases.

## AI Code Review Agent powered by AI Architect

When **AI Architect** is enabled, the **AI Code Review Agent** gains a **complete view of your entire engineering ecosystem**.

AI Architect builds a **cross-repository knowledge graph** that maps:

* All services
* Shared libraries
* Modules and components
* Inter-service dependencies
* Upstream and downstream call chains

With this system-level understanding, the agent can perform much deeper analysis.

#### **Key capabilities unlocked by AI Architect**

**1. Cross-repository awareness**

The agent understands how code in one repo interacts with code in others — crucial for microservices and distributed systems.

**2. Cross-repo impact analysis**

During a pull request review, the agent can identify:

* What breaks downstream if you change an interface
* Which services call the function you updated
* Which teams or repos depend on your changes
* Whether the update introduces architecture-wide risks

**3. Architecture-level checks**

The agent evaluates your changes not just for correctness, but for their alignment with the overall system design.

**4. Early problem detection across the entire codebase**

Ripple effects, breaking changes, or dependency violations that traditionally appear only in staging or after deployment can now be flagged directly during review.

***

### **Side-by-side comparison**

| Capability                  | Without AI Architect | With AI Architect                 |
| --------------------------- | -------------------- | --------------------------------- |
| Scope                       | Single repository    | Entire system (multi-repo)        |
| Knowledge graph             | Repo-only            | Cross-repository, system-wide     |
| AST + symbol analysis       | ✅                    | ✅ (plus cross-repo linking)       |
| Dependency visibility       | Local to repo        | Full call chains across repos     |
| Impact analysis             | Local only           | Upstream + downstream, multi-repo |
| Architecture checks         | Limited              | System-level validation           |
| Ripple-effect detection     | ❌                    | ✅                                 |
| Multi-service understanding | ❌                    | ✅                                 |


# Available MCP tools

Access deep repository intelligence and codebase insights through AI Architect's MCP server

[**AI Architect's**](/ai-architect/overview) MCP server provides a comprehensive suite of tools for exploring, analyzing, and understanding your organization's codebase. These tools enable AI coding assistants to access deep repository intelligence, architectural insights, and code-level information across all your Git repositories.

Below is the complete list of MCP tools provided by AI Architect:

|             Tool name            |                                                                                                                                                                                                                                                                                                                                                                                                          Description                                                                                                                                                                                                                                                                                                                                                                                                         |
| :------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|        **getCapabilities**       |                                                                                                                                                                                                    <p>Discover what repository intelligence and analysis capabilities this MCP server provides.</p><p></p><p>Returns comprehensive information about available repository data, dependency analysis features, architectural insights, and clustering patterns for your organization's Git repositories.</p><p></p><p>Use this to understand what repository information is available through this specialized service.</p>                                                                                                                                                                                                   |
|       **listRepositories**       |                                                                                                                                                         <p>Browse all Git repositories in your organization. Returns comprehensive repository catalog with names, descriptions, and resource URIs.</p><p></p><p>Use this to discover available repositories, understand the organization's project landscape, identify microservices and components, or get an overview of all systems.</p><p></p><p>Each entry includes a resource URI for accessing detailed repository information.</p><p></p><p>Instant access to pre-indexed organizational repository data.</p>                                                                                                                                                        |
|         **listClusters**         |                                                                                                                                                          <p>View automatically identified clusters of related repositories in your organization.</p><p></p><p>Clusters represent groups of repositories with strong dependencies or architectural relationships, often forming subsystems or microservice groups.</p><p></p><p>Use this to understand system architecture, identify bounded contexts, discover service groupings, or analyze component relationships.</p><p></p><p>Returns cluster information with member repositories and their resource URIs.</p>                                                                                                                                                         |
|       **getRepositoryInfo**      | <p>Get comprehensive repository information including metadata, structure, and dependencies.</p><p></p><p>To access incoming dependencies (services depending on this repo): set includeIncomingDependencies=true.</p><p></p><p>To access outgoing dependencies (services this repo depends on): set includeOutgoingDependencies=true.</p><p></p><p>Edge data includes various dependency types - filter by edge.type field to isolate specific categories.</p><p></p><p>Smart defaults: dependencies auto-limited by detailLevel (summary: 10, standard: 25, full: unlimited).</p><p></p><p>Essential for understanding repository relationships, analyzing dependencies, investigating integration points, and assessing impact of changes.</p><p></p><p>Returns pre-analyzed dependency graphs and relationship data.</p> |
|        **getClusterInfo**        |                                                                                                                                                                  <p>Examine a specific cluster of related repositories to understand subsystem architecture within your organization.</p><p></p><p>Returns all member repositories, their interdependencies, project summaries, and resource URIs.</p><p></p><p>Use this to analyze how repositories collaborate, understand service boundaries, explore microservice architectures, or investigate system decomposition patterns.</p><p></p><p>Valuable for architectural reviews and impact analysis.</p>                                                                                                                                                                  |
|      **searchRepositories**      |                                            <p>ONLY use when you DON'T know the repository name. If you know exact name, use getRepositoryInfo or getFieldPath directly.</p><p></p><p>Intelligent search across your organization's Git repositories using natural language queries.</p><p></p><p>Search by technology, functionality, frameworks, or project characteristics when repository name is unknown.</p><p></p><p>Uses TF-IDF algorithm on pre-indexed repository metadata for relevant results.</p><p></p><p>Examples: 'Python microservices', 'repositories using Redis', 'authentication services', 'React applications', 'payment processing systems', 'Kubernetes deployments'.</p><p></p><p>Returns repositories with relevance scores and direct access URIs.</p>                                            |
|    **searchWithinRepository**    |                                                                                  <p>Search for content within a single repository including metadata and dependency data.</p><p></p><p>Searches metadata fields and optionally incoming\_dependencies and outgoing\_dependencies.</p><p></p><p>By default searches ALL data for comprehensive results.</p><p></p><p>Use includeIncomingDependencies=false and includeOutgoingDependencies=false for faster metadata-only search.</p><p></p><p>Returns filtered results with matches from metadata and dependencies.</p><p></p><p>Use when: You know which repo but need to find specific information without knowing exact field paths.</p><p></p><p>Natural language queries work well.</p>                                                                                 |
|      **getRepositorySchema**     |                                                                                                                                                                                                                                                                                                       <p>Discover repository structure without fetching data.</p><p></p><p>Returns field names, types, array counts, and nested hierarchy.</p><p></p><p>Essential first step for exploring unfamiliar repositories.</p>                                                                                                                                                                                                                                                                                                      |
|         **getFieldPath**         |                                                                                                                                                           <p>Extract specific nested field using dot notation and array indexing.</p><p></p><p>MOST EFFICIENT for surgical data extraction - returns only requested field vs full repository.</p><p></p><p>For dependencies: use 'incoming\_dependencies' or 'outgoing\_dependencies' paths with arraySlice, then filter by edge.type field to isolate specific categories.</p><p></p><p>Supports deep nesting, array slicing, and optional parent context.</p><p></p><p>Returns only the requested field data.</p>                                                                                                                                                          |
| **queryFieldAcrossRepositories** |                                                                                                                                                                                                                                                                                                                              <p>Query same field path across multiple repositories in single call.</p><p></p><p>Comparative analysis, pattern discovery, and technology audits across repos.</p>                                                                                                                                                                                                                                                                                                                             |
|          **searchCode**          |                                                                                                                                                                                                                                                                                                                      <p>Search code using zoekt index with powerful query syntax.</p><p></p><p>Supports file filters, exclusions, case sensitivity.</p><p></p><p>Returns code matches with snippets.</p>                                                                                                                                                                                                                                                                                                                     |
|         **searchSymbols**        |                                                                                                                                                                                                                                                                                                                                                                     Search for symbol definitions (functions, classes, methods) across indexed codebase.                                                                                                                                                                                                                                                                                                                                                                     |
|            **getCode**           |                                                                                                                                                                                                                                                                                   <p>Retrieve actual source code content from repository files.</p><p></p><p>Use after searchCode/searchSymbols to view the full code around matches.</p><p></p><p>Returns file contents with line numbers. Only available when reposDir is configured.</p>                                                                                                                                                                                                                                                                                  |


# Knowledge graph

The context engine behind Bito's AI Architect

Bito's **Knowledge graph** is the context engine behind [Bito's AI Architect](/ai-architect/overview) that captures your entire engineering system. It ingests your codebase, business context, and tribal knowledge into a unified graph, giving AI and dev tools a shared understanding of the system.

This always-updated graph powers smarter planning, grounded code generation, and faster problem-solving across a variety of tools, including:

* Issue trackers (Jira, Linear)
* Coding agents (Claude Code, Cursor, etc.)
* Code reviews (GitHub, GitLab, Bitbucket)
* Team communication (Slack)

The knowledge graph is great at answering questions like "What will be affected if we change Service A?" or "Have we seen this issue before?" without manual research.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyOMf7vhqESsd4yIkKWXF%2FIllustration-Desktop-2.webp?alt=media&amp;token=6fd72965-70ad-48ea-8459-5758ccb38982" alt=""><figcaption><p><em>Bito's AI Architect knowledge graph indexes your codebase,</em> business context, and tribal knowledge<em>. AI and dev tools can query this graph to give context-aware answers.</em></p></figcaption></figure>

## Table of contents

1. [**How the knowledge graph is built**](#how-the-knowledge-graph-is-built)
2. [**Capabilities enabled by the knowledge graph**](#capabilities-enabled-by-the-knowledge-graph)
3. [**How the knowledge graph differs from other AI tools**](#how-the-knowledge-graph-differs-from-other-ai-tools)
4. [**Why the knowledge graph matters**](#why-the-knowledge-graph-matters)

## How the knowledge graph is built

The knowledge graph ingests data from multiple sources to form a complete context layer.

The following sources are fed into Bito's indexing pipeline, which scans and parses each type of data to populate the knowledge graph.

* **Code and commits history:** All source code (microservices, libraries, modules) and Git history (commits, branches). The graph records entities like classes, functions, and API endpoints, and notes code changes (e.g. refactor patterns) from commit metadata.
* **Issue trackers:** Jira or Linear tickets, epics, and bugs. Each ticket is connected to the code or service it involves, and recurring incident patterns (like frequent hotfixes) become part of the context.
* **Documentation:** Design documents, architecture decisions, wikis (e.g. Confluence). The graph links these to the relevant code components, capturing business intent and past decisions for reference.
* **Observability data:** Logs, errors, and performance metrics. For example, if a service has repeated errors or missing logs, the graph notes that instability. This means operational risk indicators (like outage-prone services) are surfaced in the graph.
  * **Note:** Observability data integration is available as a custom-built solution for your organization. We can integrate with your existing observability platform (such as DataDog, New Relic, or others) to enrich the knowledge graph with operational insights. Contact the Bito team at <support@bito.ai> to discuss your observability integration needs.
* **Team communication:** Slack messages that contain tribal knowledge like incident discussions, architecture debates, undocumented context.
* **Custom instructions:** Enrich the knowledge graph with additional context that's relevant to your engineering workflow. By providing supplementary documentation, you help AI Architect develop a more complete understanding of your project.
  * [Learn more](/ai-architect/custom-instructions)

## Capabilities enabled by the knowledge graph

#### Feasibility analysis

The knowledge graph evaluates proposed changes against your actual system state. It understands service boundaries, existing patterns, historical constraints, and known limitations. This allows it to determine what is realistically buildable, highlight risks early, and surface constraints that may not be obvious from specifications alone.

#### Impact assessment

Before any change is made, the knowledge graph maps its full system impact. It traces dependencies across services, APIs, and shared components, and combines this with historical usage and change patterns. This ensures that decisions are based on a complete view of downstream effects, not partial assumptions.

#### Technical design

The knowledge graph grounds design decisions in how your system actually works. It reflects existing architectural patterns, prior design decisions, and service-level responsibilities. This leads to designs that are consistent with your environment and easier to implement, operate, and maintain.

#### Epic breakdown

The knowledge graph connects high-level work to real system components. It uses past implementation patterns, system dependencies, and team workflows to break down epics into actionable units. This results in tasks that are aligned with how work is actually executed in your organization.

#### Context for AI coding agents

When generating code, the knowledge graph provides system-specific context such as API contracts, service interactions, error handling patterns, and operational constraints. This ensures that generated code aligns with your architecture and integrates correctly with existing systems.

#### Code review enhancement

The knowledge graph adds system-wide context to code reviews. It highlights relevant patterns, prior issues, and cross-service implications that may not be visible within a single pull request. This helps reviewers make more informed decisions with less manual investigation.

## How the knowledge graph differs from other AI tools

#### Beyond RAG and vector search

Most AI coding tools use retrieval-augmented generation: embedding code as vectors and retrieving relevant snippets. This treats your codebase as searchable text rather than an interconnected system.

When you ask about authentication, vector search finds files containing "auth" keywords. It doesn't understand that your authentication service depends on specific Redis configuration, that an Architecture Decision Record (ADR) documents why Redis was chosen, or that a recent incident involved rate limiting.

The difference is between finding information and understanding relationships. A vector database can retrieve your authentication service code and a Jira ticket separately, but can't connect that the ticket describes an incident that led to the code change, which implemented a pattern from an ADR, and monitoring shows the pattern's effectiveness.

#### More context isn't better context

Some tools add more context to prompts — feeding more code and documentation to the AI. But retrieving fifty potentially relevant files when only three matter creates noise, not clarity.

The knowledge graph solves a different problem: identifying which information matters for specific decisions and why it matters.

#### Understanding system evolution

Traditional AI tools treat codebases as relatively static, re-indexing periodically without modeling change over time. The knowledge graph understands that your current architecture results from decisions made in specific contexts.

When your team has been migrating from monolith to microservices for a year, that's not historical trivia — it's a pattern that should inform how new features are designed.

#### Operational context

Code analysis tools build dependency graphs and trace function calls, but they don't capture operational reality. Knowing Service A calls Service B is useful. Knowing that Service B has rate limits that caused a production incident eight months ago, that the response involved implementing circuit breakers, and that a shared library now exists for this pattern — that's the context difference between adequate code and production-ready code.

## Why the knowledge graph matters

#### Scaling engineering organizations

The constraint in scaling engineering isn't hiring developers — it's enabling them to make good decisions without complete context. When critical knowledge lives in senior engineers' heads, scaling means either accepting decisions with less context (leading to rework) or creating bottlenecks.

The knowledge graph distributes accumulated knowledge. Mid-level engineers access the same contextual understanding staff engineers bring, not through years of experience but through the graph making that context explicit and queryable.

#### Technical debt visibility

Technical debt is the gap between how your system is designed and how it needs to work. The graph makes this visible by connecting what was decided (ADRs, design docs), what was built (code), what happened (incidents, monitoring), and what's planned (Jira epics).

This visibility enables informed decisions about what technical debt costs and what remediation provides value.

#### Compliance and auditability

For organizations with regulatory requirements, the graph provides an auditable record of technical decisions. When you need to demonstrate why architectural choices were made, what alternatives were considered, and how security requirements were addressed, the graph traces these relationships explicitly.

#### AI for high-level decisions

Most AI tools excel at isolated tasks: writing functions, explaining code, suggesting refactors. The knowledge graph makes AI useful for decisions requiring system-wide understanding: feasibility analysis, architectural design, impact assessment, etc.

These are tasks senior engineers spend most time on, and where AI historically provided least value due to lacking context.

#### Organizational learning

Every decision captured in the graph becomes training data for better future decisions. Organizations accumulate knowledge over time, but it usually remains implicit until people leave and understanding walks out the door.

The knowledge graph makes accumulation explicit, preserving it in a form that informs decision-making as teams evolve.


# Custom instructions

{% hint style="info" %}
**Note:** Custom instructions feature is available exclusively on Bito's [Enterprise plan](https://bito.ai/pricing/). To use this feature, provide your custom instructions in markdown document (`.md` file) to the Bito team at <support@bito.ai>, and we'll integrate it into your knowledge graph.
{% endhint %}

Custom Instructions allows you to enrich [AI Architect's knowledge graph](/ai-architect/knowledge-graph) with additional context that's relevant to your engineering workflow. By providing supplementary documentation, you help AI Architect develop a more complete understanding of your project ecosystem.

By default, AI Architect builds a knowledge graph using multiple inputs such as your codebase, issue tracking systems, documentation tools, and observability data. While this provides strong coverage, there is often still important context that lives outside these systems or is not easily discoverable.

Custom instructions allow you to fill that gap by providing documents that describe your system in a more complete way.

{% hint style="info" %}
Refer to the [Knowledge graph documentation](/ai-architect/knowledge-graph) for details on how AI Architect builds and maintains its knowledge.
{% endhint %}

## Table of contents

1. [**Why use custom instructions?**](#why-use-custom-instructions)
2. [**What to include in custom instructions?**](#what-to-include-in-custom-instructions)
3. [**How it works?**](#how-it-works)
4. [**Impact on AI Architect's capabilities**](#impact-on-ai-architects-capabilities)
5. [**Best practices**](#best-practices)
6. [**Getting started**](#getting-started)

## Why use custom instructions?

Use Custom Instructions to add important context that enhances AI Architect's understanding of your projects and systems:

* **Fill knowledge gaps**: Add context that doesn't exist in your existing systems
* **Synthesize information**: Consolidate knowledge that spans multiple sources
* **Capture tribal knowledge**: Document institutional understanding that lives in people's heads
* **Provide domain expertise**: Include specialized knowledge, business rules, or industry-specific context

## What to include in custom instructions?

Custom Instructions can contain any context that helps AI Architect better understand and assist with your projects. Consider including:

#### Domain knowledge

* Industry-specific terminology and concepts
* Business rules and constraints
* Regulatory or compliance requirements
* User personas and use cases

#### Operational context

* Service ownership and team structures
* Communication channels and escalation paths
* Deployment processes and environments
* Access patterns and security considerations

#### Architecture decisions

* Design principles and patterns used
* Technology choices and rationale
* Cross-service dependencies not visible in code
* Integration points with external systems

#### Standards and guidelines

* Coding conventions specific to your team
* Testing strategies and requirements
* Review and approval processes
* Performance benchmarks and targets

#### Tribal knowledge

* Historical context for major decisions
* Common pitfalls and how to avoid them
* Undocumented workarounds or solutions
* Best practices learned from experience

## How it works?

When you provide a custom instructions document:

1. Bito processes your document and extracts relevant information
2. The extracted context is intelligently integrated into the knowledge graph
3. AI Architect uses this enriched knowledge to provide more accurate and contextual assistance

## Impact on AI Architect's capabilities

**With custom instructions, AI Architect can:**

* Avoid known issues and apply documented best practices
* Answer questions using your project-specific context
* Generate code that follows your team's conventions and standards
* Understand terminology, patterns, and concepts unique to your domain
* Provide recommendations that account for your constraints and requirements

## Best practices

#### Start with high-impact information

Focus on context that significantly affects how AI Architect should understand your systems and processes:

* Critical constraints or requirements
* Frequently misunderstood concepts
* Context that connects different parts of your architecture

#### Organize for clarity

Structure your document logically:

* Use clear headings and sections
* Group related information together
* Include examples where helpful
* Keep explanations concise but complete

#### Be specific and actionable

Provide concrete information rather than vague statements:

* ✅ "Use library X for date handling to ensure timezone consistency"
* ❌ "Be careful with dates"

#### Document the "Why"

Explain reasoning and context behind decisions:

* Why certain approaches are preferred
* Why specific constraints exist
* Why particular patterns are used

## Getting started

{% stepper %}
{% step %}

### Create your document

Prepare a markdown document (`.md` file) containing custom instructions:

* Start with your most important information
* Organize content with clear structure
* Use plain language and specific examples
  {% endstep %}

{% step %}

### Submit to Bito Team

Send your custom instructions document to [**support@bito.ai**](mailto:support@bito.ai):

* The Bito team will integrate the document into your workspace's knowledge graph
* You'll be notified once the integration is complete
  {% endstep %}
  {% endstepper %}


# Agent skills

AI Architect comes with a set of Agent Skills — each one built to handle a specific engineering task like feasibility analysis, epic planning, or production triage. You can trigger them in Jira before coding starts, inside your coding agent while you're building, or in Slack.

Agent skills are structured instruction files that enhance your AI coding assistant with specialized capabilities. In coding agents, skills are installed automatically by the [install scripts](/ai-architect/quick-mcp-integration-with-ai-coding-agents) and are discovered dynamically from a `skills/manifest.json` file. Whereas, in Jira, skills are available from Bito Cloud.

Every skill has full context of your codebase and your team's Jira history, so the output reflects how your system actually works.

## All available skills

| Skill                         | Trigger phrases                                                                                              | Description                                                                                                                                                                                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **bito-codebase-explorer**    | "explain this service", "how does X work", "what does Y depend on", "show me the architecture", "onboard me" | Explore and explain the codebase at any depth for any audience — executive summary to line-level traces                                                                                                                                                                        |
| **bito-build-plan**           | "plan this work", "break down this ticket", "create plan from story"                                         | Convert any unit of work (story, ticket, feature brief, epic, PRD) into a sprint-ready implementation plan with effort estimates                                                                                                                                               |
| **bito-feasibility**          | "is this feasible", "go/no-go on", "what's the blast radius", "trade-off analysis"                           | Go/no-go feasibility and impact analysis — viability, blast radius, effort, dependencies, risks, alternatives                                                                                                                                                                  |
| **bito-spike**                | "spike on", "investigate whether", "explore options for", "proof of concept for"                             | Time-boxed technical investigation — delivers findings and recommendations, not a plan                                                                                                                                                                                         |
| **bito-feature-plan**         | "plan a feature", "design implementation for"                                                                | Detailed org-specific implementation plan for a complex feature using cross-repo context                                                                                                                                                                                       |
| **bito-prd**                  | "write a PRD", "product requirements for"                                                                    | Comprehensive Product Requirements Document grounded in real system context                                                                                                                                                                                                    |
| **bito-trd**                  | "write a TRD", "technical requirements for"                                                                  | Technical Requirements Document analyzing existing architecture, dependencies, and patterns                                                                                                                                                                                    |
| **bito-production-triage**    | "production issue", "incident triage", "debug outage"                                                        | Diagnose production incidents — cross-repo context, blast radius mapping, structured remediation plan                                                                                                                                                                          |
| **bito-code-review**          | "review this PR", "review this MR", "review this branch", "review commit abc123", "review my staged changes" | Read-only code review on any target — PR/MR URL, branch, commit or commit range, local changes (staged / unstaged / all), specific files, or a diff/patch file. Returns severity-rated findings with `file:line` evidence and cross-repo impact. Never commits.                |
| **bito-commit-review**        | "review my changes", "pre-commit review", "check my changes"                                                 | <p>Pre-commit code review analyzing all changes (staged and unstaged) for issues and cross-repo impact.<br><br>It's like a pre-commit gate on your local changes — blocks the commit if there are blocking issues, asks before proceeding, and creates the commit on pass.</p> |
| **bito-plan-to-coding-tasks** | "turn this plan into coding tasks", "make this implementable by an agent"                                    | Transform an implementation plan into self-contained workstream coding tasks                                                                                                                                                                                                   |
| **bito-coding-task-executor** | "execute this coding task", "implement this workstream coding task"                                          | Execute a workstream coding task with verification gates + two-stage review                                                                                                                                                                                                    |

{% hint style="info" %}
**`bito-code-review` vs `bito-commit-review`**

* **`bito-code-review`** reviews any target (PR/MR, branch, commit, local changes, diff file) and produces a report. It's read-only and never commits.
* **`bito-commit-review`** is a pre-commit gate on your local changes. It blocks the commit if there are blocking issues, and creates the commit on pass.

In short: `bito-code-review` reviews anything, anywhere. `bito-commit-review` gates right before committing.
{% endhint %}

### Code review — supported targets

The `bito-code-review` skill is runtime-agnostic — it works in Slack, in your coding agent (Claude Code, Cursor, GitHub Copilot, Windsurf, Junie), and anywhere the Bito skill runtime has shell and `git` access. The same trigger phrases work everywhere.

**What it can review**

<table><thead><tr><th width="240">Target</th><th>How to invoke</th></tr></thead><tbody><tr><td>GitHub PR / GitLab MR / Bitbucket PR</td><td>Paste the URL</td></tr><tr><td>Branch</td><td><code>review the auth-refactor branch</code> — repo is auto-resolved from the thread, a linked ticket, or AI Architect. If none resolve, Bito will ask. You can always specify <code>repo + branch</code> explicitly.</td></tr><tr><td>Single commit</td><td><code>review commit abc123</code></td></tr><tr><td>Commit range</td><td><code>review commits abc123..def456</code></td></tr><tr><td>Local changes</td><td><code>review my staged changes</code> / <code>review unstaged changes</code> / <code>review all my local changes</code></td></tr><tr><td>Specific files</td><td><code>review src/auth/service.ts and src/auth/middleware.ts</code></td></tr><tr><td>Diff or patch file</td><td>Attach the file and ask Bito to review it</td></tr><tr><td>Re-review</td><td><code>verify again</code> after applying fixes</td></tr></tbody></table>

**Flags**

* `--focus security|performance|correctness` — narrow the review to a specific concern
* `--depth quick|standard|deep` — trade depth for latency, or vice versa

**Repository requirements**

Any repository the skill can get code for works:

* **Local targets** use your working directory — no indexing required.
* **Remote targets** work with any repo Bito can clone via your `git` auth.

{% hint style="info" %}
AI Architect indexing is **not required** for code review. When it's set up, Bito enriches the review with cross-repo impact analysis; without it, the review degrades gracefully and still runs.
{% endhint %}

## How to invoke skills

#### In Jira

Agent skills can be triggered on demand on Epic or Story by commenting:

```
@bito turn this epic into tasks
@bito technical plan for this PRD
```

<a href="/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-jira" class="button primary">Integrating with Jira</a>

#### In Slack

Agent skills are also available directly in Slack via the [**Bito AI Assistant** app](/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack). Mention `@Bito` in any channel and describe what you need. It will activate the right skill automatically.

```
@Bito is this feasible
@Bito turn this plan into agent specs
@Bito execute this agent spec
```

<a href="/ai-architect/integrating-ai-architect-with-your-tools/integrating-with-slack" class="button primary">Integrating with Slack</a>

#### In your coding agent

Once AI Architect is connected via MCP, skills are available in compatible coding agents. Describe what you need in natural language and the agent activates the right skill automatically — or invoke one directly by name. You can type `/` in the chatbox to see the list of available skills and select one interactively.

<a href="/ai-architect/quick-mcp-integration-with-ai-coding-agents" class="button primary">Integrating with coding agents</a>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fw8zixqidL20UuLvO2wxE%2FScreenshot%202026-03-02%20at%2010.59.58%E2%80%AFPM.png?alt=media&amp;token=1513dc31-4164-4d23-a307-1f21385638fd" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fr8FO4lgzkQV5HzEKVHFE%2FScreenshot%202026-03-02%20at%2011.00.16%E2%80%AFPM.png?alt=media&amp;token=8a4a20ef-cd76-46ae-a316-006dcd266628" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FaamsZyo5rb9tfujjjiT8%2FScreenshot%202026-03-02%20at%2011.32.07%E2%80%AFPM.png?alt=media&amp;token=a7aa3ff3-1e74-4fba-9fd0-8cb2114c1c3b" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FxCxV63wwOutfRz6HKkD9%2FScreenshot%202026-03-02%20at%2011.33.58%E2%80%AFPM.png?alt=media&amp;token=7a2fa5e4-a5ab-44d5-b102-cbd35e64574a" alt=""><figcaption></figcaption></figure>

## Skills installation locations:

<table><thead><tr><th width="188.20001220703125">IDE</th><th>Location</th><th>Format</th></tr></thead><tbody><tr><td>Claude Code</td><td><code>~/.claude/skills/bito-{name}/SKILL.md</code></td><td>Markdown with YAML frontmatter</td></tr><tr><td>Cursor</td><td><code>~/.cursor/rules/bito-{name}.mdc</code></td><td><code>.mdc</code> with <code>alwaysApply: false</code></td></tr><tr><td>Windsurf</td><td><code>~/.codeium/windsurf/memories/bito-{name}.md</code></td><td>Plain markdown</td></tr><tr><td>VS Code (GitHub Copilot)</td><td><code>{User}/prompts/bito-{name}.prompt.md</code></td><td><code>.prompt.md</code> with <code>applyTo</code></td></tr><tr><td>Junie</td><td><code>~/.junie/skills/bito-{name}/SKILL.md</code></td><td></td></tr></tbody></table>


# Single Sign-On (SSO) integration

{% hint style="info" %}
**Note:** If you are using a self-hosted deployment of AI Architect, please refer to the [SSO authentication guide for self-hosted installations](/ai-architect/installation/install-ai-architect-self-hosted#sso-authentication) instead, as the setup process differs from the cloud version.
{% endhint %}

Single Sign-On (SSO) enables your team to authenticate with Bito's [AI Architect](/ai-architect/overview) MCP through your organization's identity provider instead of sharing access tokens with team members.

## Why use SSO

SSO addresses a critical security challenge: when teams share access tokens, you lose visibility into who accessed what and when. If someone leaves the company or changes roles, you need to rotate tokens for everyone. SSO solves this by integrating authentication with your existing identity infrastructure.

Your organization likely already uses an identity provider like Google Workspace, Okta, Azure Entra ID, Auth0, or others to manage access to email, Slack, and other business tools. SSO extends this same authentication system to AI Architect, giving you centralized control over access without creating a separate credential management burden.

The practical benefits include automatic enforcement of your existing security policies (like multi-factor authentication requirements), immediate access revocation when someone leaves, and a complete audit trail of who accessed the system and when. This meets enterprise compliance requirements while making access simpler for your users.

## Supported identity providers

AI Architect's SSO implementation uses Descope as the authentication platform, which provides native integrations with enterprise identity providers.

Common identity providers include:

* Google Workspace
* Okta
* Azure Entra ID
* Microsoft AD FS
* PingFederate
* PingOne
* onelogin
* Keycloak
* JumpCloud
* Auth0
* ClassLink
* Cyberark
* Descope
* Duo
* LastPass
* miniOrange
* Salesforce

{% hint style="info" %}
If your organization uses a different provider, you can configure it as a custom SAML 2.0 or OpenID Connect (OIDC) integration.
{% endhint %}

The setup process varies by provider but follows the same general pattern: you'll configure an application in your identity provider, exchange metadata or configuration details, and test the connection.

## Prerequisites

To enable SSO, you need:

1. **Workspace admin access**: You must be an admin in your Bito workspace. You can check your role in Bito by going to [Manage Users](https://alpha.bito.ai/home/members) dashboard.
2. **Identity provider account**: Access to configure your organization's IdP (Google Workspace, Okta, etc.). This is typically an IT admin or someone in your identity and access management team. You'll need to add AI Architect as an authorized application and provide configuration details.
3. **AI Architect**: Your workspace must have AI Architect enabled. [Learn more](/ai-architect/overview)

## How to configure SSO

{% stepper %}
{% step %}

### Access SSO settings in Bito

1. Log in to [Bito Cloud](https://alpha.bito.ai/auth/login).
2. Navigate to the [Manage integrations](https://alpha.bito.ai/home/cra-integrations) dashboard.
3. In the **Available integrations** section, you will see **Single Sign-On (SSO)**. Click **Connect** to proceed.
4. Click **Connect via SSO**. You will be redirected to Descope.
   {% endstep %}

{% step %}

### Configure your identity provider

The SSO configuration uses Descope as the authentication platform, which [supports multiple identity providers](#supported-identity-providers).

1. In the Welcome page, click **SSO Configuration**.
2. Choose your identity provider from the [list](#supported-identity-providers). If you do not find the identity provider, use the generic configuration options such as SAML 2.0 or OpenID Connect (OIDC) at the bottom of the screen.
3. Follow the provider-specific setup wizard to configure SSO.

For the sake of this documentation, we'll provide setup guide for Keycloak. For other identity providers, simply follow the step-by-step instructions provided by Descope in the setup wizard.

#### Guide for Keycloak:

1. From the **Identity Provider (IdP) Selection** screen, click **Keycloak**.
2. Click **SAML**.
3. From the **Service Provider Information** screen, copy **`Client ID`**.
4. Log in to the Keycloak administration console and follow these steps:
   1. In the left menu, select **Clients**, and click on **Create client**.
   2. Select **SAML** as the **Client type**, name the client, and paste the **`Client ID`** you copied above in the **Client ID** field.
   3. Click **Next**.
   4. From the **Service Provider Information** screen of the Descope setup wizard, copy **`SP ACS URL`**.
   5. Now in Keycloak administration console, paste the **`SP ACS URL`** to the **`Valid redirect URIs`** and the **`Master SAML Processing URL`** fields.
   6. Click **Save**.
   7. Scroll down, enable the **`Sign assertions`** toggle and click **Save**.
   8. In the top menu, select **Keys** and disable the **`Client signature required`** toggle.
   9. In the top menu, select **Client scopes**, and click on the newly created client.
   10. Select **Add predefined mapper**.
   11. Select **`x500 email`**, **`x500 givenName`** and **`x500 surname`**, and click **Add**.
   12. In the left menu, select **Realm settings**.
   13. Copy the **`SAML 2.0 Identity Provider Metadata`** link address.
   14. Now in Descope setup wizard, open **Identity Provider Information** screen.
   15. Paste the **`SAML 2.0 Identity Provider Metadata`** link address you copied from Keycloak administration console in the **`SAML 2.0 Identity Provider Metadata`** field.
   16. Click **Continue**.
   17. In the **SSO Domains** screen, click **Continue**.
   18. In the **Testing** screen, click **Save & Test**.
   19. If the configuration is done correctly, you will see **SSO test completed successfully**.
   20. Click **Done**, and you will be redirected back to Bito.
   21. In Bito Cloud, [Manage integrations](https://alpha.bito.ai/home/cra-integrations) dashboard, you will see **Setup completed** for **Single Sign-On (SSO)** integration.
       {% endstep %}
       {% endstepper %}

## How users connect using SSO

Once SSO is enabled for your workspace, you can easily connect to AI Architect MCP in your coding agents (Cursor, Windsurf, VS Code, etc.) using the following steps:

1. Connect Bito's AI Architect to your AI coding tools (Cursor, Windsurf, VS Code, etc.) in seconds with our automated installer.
   1. [Follow quick MCP integration guide](/ai-architect/quick-mcp-integration-with-ai-coding-agents)
2. Open your IDE's MCP settings.
3. In `BitoAIArchitect` MCP, remove the **Bito MCP Access Token** line.

{% hint style="info" %}
**Note:** Sometime your changes in MCP settings will not take effect immediately. To fix this, you can try renaming the `BitoAIArchitect` MCP to something else. For example, `BitoAIArchitect_test`.
{% endhint %}

4. Enable the `BitoAIArchitect` MCP.
5. Click the **Connect** button next to Bito's AI Architect MCP. The secure authentication link of your organization's identity provider will open in browser.
6. Sign in using your credentials.
7. After successful authentication, return to your IDE.
8. Bito's AI Architect MCP is now connected and ready to use.

## How SSO authentication works

In your IDE, when you click "Connect" for Bito's AI Architect MCP, the MCP client generates a secure authorization request. Your browser opens and redirects to your identity provider (like Google or Okta). You authenticate with your credentials. Your identity provider verifies your identity and confirms you're authorized to access the application. It sends a secure token back to Bito, which verifies it and creates a session for you. Your IDE receives confirmation and establishes the MCP connection.

This entire process takes about 30 seconds the first time. The IDE stores your session securely, so you won't need to authenticate again unless your session expires (typically after 1 hour of inactivity) or you explicitly disconnect.

## Fallback authentication (when SSO isn't configured yet)

If a workspace admin has enabled SSO but hasn't completed the configuration with an identity provider, you will see a different authentication flow. Instead of being redirected to your organization's identity provider login page, you'll be directed to Bito's standard authentication page at [https://alpha.bito.ai/](https://alpha.bito.ai/auth/login?_gl=1*1cgl6kw*_gcl_au*MTcyMDg0Nzg1NC4xNzY2OTg5MDc3).

On this page, you need to enter your email address. Bito sends you a one-time code. You enter this code to verify your identity, then select which workspace you want to access. If you're a member of the workspace and have AI Architect enabled, you'll be authenticated successfully.

This fallback ensures your team can still work even if SSO configuration is in progress or experiencing issues. However, you lose the centralized access control benefits that SSO provides, so you should complete the full SSO configuration when possible.

## Managing team access

Once SSO is configured, you can control team member access to AI Architect by managing workspace membership and seat assignments.

#### 1. User already exists in the workspace with an assigned seat

If a user already exists in your Bito workspace and has a seat assigned, they can authenticate with AI Architect MCP through SSO immediately. No additional steps required, they simply connect using the SSO flow.

&#x20;[Learn more about seat management](/help/billing-and-plans/overview#seat-management)

#### 2. Manually add new team members

To manually add a new team member:

* [Log in to Bito Cloud](https://alpha.bito.ai/auth/login) and navigate to [Manage Users](https://alpha.bito.ai/home/members)
* Go to the **IDE Code Review** tab and click **Add members**
* Enter their email address and click **Add members**
* Assign them a seat

The team member can now authenticate with AI Architect MCP through SSO.

#### 3. Automatically add users to the workspace after successful SSO login

When the **`autoAddUser`** flag is enabled in XMCP configuration, team members are automatically added to your workspace (if they don't already exist) after their first successful SSO login. For this to work, your workspace settings must allow adding users with the same email domain.

{% hint style="info" %}
To enable the **`autoAddUser`** flag, contact the Bito team at <support@bito.ai>.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FUNfDXXvPliFFm9U2Ha4r%2Fscrnli_Xf6c302Bicmjdf.png?alt=media&amp;token=344bbc29-8631-46a0-b335-7ad7cf9d0237" alt=""><figcaption></figcaption></figure>

#### Removing access

You have two options for removing someone's access, and they work differently.

1. If you remove someone from your workspace in Bito, their access is revoked immediately for new authentication attempts. However, if they have an active session (they're already authenticated in their IDE), that session will continue to work until it expires. Sessions expire after 1 hour of inactivity by default.
2. If you need to revoke access immediately, including active sessions, you should remove or disable their account in your identity provider (Google Workspace, Okta, etc.). This prevents them from authenticating at all, and their existing sessions will fail the next time they try to use AI Architect.

For employees leaving the company, the standard practice is to disable their account in your identity provider as part of your offboarding process. This automatically revokes their access to AI Architect along with your other business applications. If you want to preserve their workspace membership for record-keeping but remove their AI Architect access, you can unassign their seat instead.


# MCP Analytics

The [**Architect MCP Analytics**](https://alpha.bito.ai/home/dashboard?view=Architect_Overview) dashboard in Bito Cloud provides visibility into how Bito's AI Architect is being used across your workspace through the Model Context Protocol (MCP). Use these metrics to track tool usage, monitor engagement, and understand what tasks the AI Architect is being applied to.

All charts update on a rolling basis and are accessible directly from the Bito UI.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZ7YYaZHStyuv4rhORpA2%2FScreenshot%202026-05-08%20at%2014.47.05.png?alt=media&amp;token=4b11f5bf-394e-42d7-a67f-d8e6f9e251ce" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FV3lD9kRDsKNn2UfvR7Wj%2FScreenshot%202026-05-08%20at%2014.47.13.png?alt=media&amp;token=6885d6aa-d021-4926-b8c3-66c57a3a1cb1" alt=""><figcaption></figcaption></figure>

## Overview

Each time the AI Architect invokes a structured capability — such as code search, file reading, or architecture analysis — it is recorded as a [**tool call**](/ai-architect/integrating-ai-architect-with-your-tools/available-mcp-tools). The analytics page aggregates these tool calls to help you answer questions like:

* How much is the AI Architect being used?
* Who is using it, and how many people are actively engaged?
* Which types of tasks is it being used for most?
* Is usage growing or declining over time?

## Available charts

#### Tool Call Volume — Last 4 Weeks

Displays the total number of MCP tool calls made by all users in the last 4 weeks.

Use this as a high-level indicator of overall AI Architect activity. A rising count suggests growing adoption or deeper integration into developer workflows. A sudden drop may point to access issues, a change in team workflow, or a degraded experience worth investigating.

#### Active Users — Last 4 Weeks

Shows the number of unique workspace members who triggered at least one MCP tool call within the last 4 weeks.

This metric reflects the **breadth** of adoption rather than total volume. Compare it alongside tool call volume to understand usage distribution:

* High volume + low active users → a few power users driving most activity
* Growing active users + stable volume → broader but lighter adoption across the team

#### Tool Call Volume — Last 8 Weeks

Breaks down tool call volume **week by week** over the last 8 weeks.

The longer time horizon makes it easier to identify growth trajectories, plateau periods, or regressions following a product change or team event. Use this chart to compare performance before and after AI Architect rollouts, onboarding pushes, or feature updates.

#### Tool Calls by Purpose — Last 4 Weeks

Segments tool calls by their functional category, showing **which types of tasks** the AI Architect is most frequently being used for. Volume is displayed over time so you can track how the purpose distribution shifts within the 4-week window.

Use this chart to identify which Architect capabilities are most valued by your team and where adoption of specific features may need support or enablement.

## Interpreting the data

| Signal                             | What it may indicate                                     |
| ---------------------------------- | -------------------------------------------------------- |
| Steady or growing tool call volume | Healthy adoption and continued use                       |
| Increasing active users            | Broader team engagement                                  |
| Flat volume after onboarding       | Adoption gap; consider enablement efforts                |
| High volume, few active users      | Power-user concentration; limited spread                 |
| Sharp weekly drop                  | Possible access issue or workflow disruption             |
| Single purpose dominating usage    | Narrow use case; other capabilities may be underexplored |

{% hint style="info" %}
**Tip:** Cross-reference Tool Call Volume and Active Users to calculate an average calls-per-user ratio. This helps distinguish between deep individual usage and broad team adoption.
{% endhint %}

## Glossary

| Term                      | Definition                                                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP**                   | Model Context Protocol — the structured interface used by AI Architect to invoke tools like code search, file access, and architectural analysis. |
| **Tool call**             | A single invocation of an MCP tool by the AI Architect on behalf of a user. One session may produce many tool calls.                              |
| **Tool call volume**      | The total count of tool calls recorded within a given time window, across all users.                                                              |
| **Active users**          | Unique workspace members who triggered at least one tool call within the specified window.                                                        |
| **Tool calls by purpose** | A categorization of tool calls by the intent or function they serve, such as code navigation or architecture review.                              |
| **Rolling window**        | A time range (e.g. 4 weeks or 8 weeks) that shifts forward each day relative to the current date, rather than being fixed to a calendar period.   |


# Privacy and security in AI Architect

Your code stays yours — understand how Bito protects your data

Security and privacy are fundamental to how [**Bito's AI Architect**](/ai-architect/overview) operates. Bito doesn't store your code and we don't use your code for AI model training.

This document explains how AI Architect handles your code and data across different deployment modes.

## Code storage: Bito-hosted vs. Self-hosted

The way AI Architect handles your code depends on your deployment choice:

### Bito-hosted AI Architect

**Your code is not stored on Bito's servers.**

When you use Bito-hosted AI Architect, Bito stores only summaries and indexes of your code — not the code itself. These indexes help AI Architect understand your repository structure, key functionalities, service calls, design patterns, variable naming conventions, and architectural relationships across microservices.

**How it works:**

* AI Architect analyzes your code to build a knowledge graph
* Only metadata and summaries are stored on Bito's servers (e.g., "this repo contains authentication services," "this module calls these other services")
* The actual code is never persisted in Bito's cloud

**When code access is needed:**

* If you ask a question that requires viewing actual code, AI Architect authenticates with your Git provider using your credentials
* It fetches the specific file on-demand
* Extracts the necessary information
* Passes it back to you through the MCP server
* The code is not retained after the request

#### Code caching

For performance optimization, Bito temporarily caches individual code files for up to 10 minutes during analysis. You have full control over this behavior — you can configure the cache duration or disable caching entirely through your settings.

### Self-hosted AI Architect

**Your code remains entirely in your data center.**

When you deploy AI Architect on-premises in your own infrastructure, all code and indexes are stored locally. Bito receives no code or code-related information. We only receive anonymous metadata about usage to confirm the product is working properly — no details about what your code does or contains.

## Performance considerations

Bito-hosted AI Architect adds a few seconds to requests that require actual code access because the code must be fetched on-demand from your Git provider. This slight latency is the trade-off for keeping your code off Bito's servers. In practice, this difference is not material to user experience.

## Code security and encryption

* All requests to and from AI Architect are transmitted over HTTPS and fully encrypted
* Your Git credentials are used only to authenticate and fetch code when needed
* Code accessed during analysis is handled securely and not logged or stored beyond the temporary cache window

## No AI model training

**Your code is never used for AI model training.** Bito doesn't train on, learn from, or retain any of your code snippets or queries for model improvement purposes.

## Privacy and third parties

Bito uses leading AI providers (such as Anthropic, OpenAI, etc.) via their APIs to power AI Architect features. None of your code or AI requests are stored by these partners. All AI providers we work with maintain commitments to not use API data for model training or retain user data beyond the immediate request processing.

## Metadata and usage analytics

To ensure AI Architect is working correctly and to improve the product, Bito collects:

* Anonymous usage metrics
* Feature usage statistics
* Error logs (without code content)

This information helps us understand how AI Architect is being used and identify areas for improvement.

## Compliance and certifications

Bito maintains SOC 2 Type II compliance and follows industry-leading security practices. For detailed information about our security posture and certifications, visit our [Trust Center](https://trust.bito.ai).

For our full privacy practices, see our [Privacy Policy](https://bito.ai/privacy-policy/).

## Questions?

If you have questions about how AI Architect handles your code or data, contact the Bito team at [**support@bito.ai**](mailto:support@bito.ai). We're committed to transparency about security and privacy practices.


# Local repository intelligence for AI assistants

A single-binary tool that indexes your Git repositories and serves them via the **Model Context Protocol (MCP)**, so AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) can search, navigate, and reason about your codebase.

* **Indexes** your repos — code search, symbol tables, dependency graphs, metadata, TF-IDF vectors
* **Serves** an MCP server exposing 13 tools your AI assistant calls automatically
* **Zero runtime dependencies** — everything is bundled into the binary

### Install

```bash
curl -fsSL https://bitoarch.bito.ai/install.sh | bash
```

Supported on macOS (Apple Silicon and Intel) and Linux (x64 and arm64).

That places the binary at `~/.bito/bitoarch/bin/bitoarch-local` and updates your PATH. **Open a new terminal** so the PATH update takes effect — or run `source ~/.zshrc` (or your shell's rc file) to pick it up in the current one.

### Quick start

Once installed, three steps to a working MCP server your AI assistant can talk to.

#### Step 1 — Index your repos

Point `-i` at any directory that contains git repositories. The indexer scans that directory's top-level entries and picks up anything with a `.git/` subdirectory. A single repo path also works — if the directory itself has a `.git/`, it's indexed as a single repo. **Replace `/path/to/your/repos` in the examples below with your actual path** — e.g. `~/code`, `~/projects`, `/opt/repos`, wherever your git clones live.

> **All your repos need to live under a single directory.** `-i` and `--repos` take one path everywhere (`index`, `serve`, `config mcp-config`); multi-root setups aren't supported. If your clones are split across, say, `~/code/work` and `~/code/personal`, gather them under one parent with a symlink farm and use that as your input:
>
> ```bash
> mkdir -p ~/repos-mcp
> ln -s ~/code/work/* ~/code/personal/* ~/repos-mcp/
> # then pass ~/repos-mcp wherever the docs say /path/to/your/repos
> ```
>
> Repo basenames must be unique across roots — `ln` will refuse to overwrite an existing entry, so any collision surfaces immediately.

```bash
# Index every git repo under a directory
bitoarch-local index -i /path/to/your/repos

# Or limit to specific ones (recommended if the directory has many repos)
bitoarch-local index -i /path/to/your/repos --repos "my-api,my-frontend,shared-lib"

# Check what got indexed
bitoarch-local status
```

Indexing is incremental — re-running `index` hashes each repo and skips unchanged ones. No `--force` needed for normal workflows.

#### Step 2 — Verify the server works

Start the MCP server in HTTP mode on port 3000 (easier to verify than stdio mode, which is meant for AI assistants to connect to directly):

```bash
# Leave this running in one terminal
bitoarch-local serve --mode http --port 3000 --repos /path/to/your/repos
```

In another terminal, hit the health endpoint and call the `listRepositories` tool:

```bash
curl http://127.0.0.1:3000/health
# → {"status":"ok","transport":"http-unified",...}

curl http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"listRepositories","arguments":{"purposeType":"codebase_understanding","purpose":"smoke test"}}}'
# → {"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"{\"items\":[...]}"}]}}
```

If you see your repos in the JSON response, the server works. Stop it with `Ctrl+C`.

<details>

<summary>Manual stdio smoke test (optional)</summary>

Stdio is the default transport — the AI assistant launches the binary and talks JSON-RPC over stdin/stdout, no ports involved. You rarely run this by hand; Step 3 wires it up automatically. To smoke-test it manually, send one request, read the reply, let stdin close — server exits:

```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | bitoarch-local serve --repos /path/to/your/repos
```

</details>

#### Step 3 — Wire it into your AI assistant

Use the auto-configure command to add the server to every supported MCP client installed on your machine in one shot:

```bash
# See which clients are detected
bitoarch-local config mcp-config --list-clients

# Preview the changes without writing
bitoarch-local config mcp-config --dry-run --all

# Apply to all detected clients (creates timestamped backups first)
bitoarch-local config mcp-config --all --repos /path/to/your/repos
# ↑ prompts "Configure bitoarch-local for N clients? (y/N)" — pass --yes to skip (scripts, CI)
```

**Supported clients (9 total):** `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `cline`, `vscode-copilot`, `zed`, `amazon-q`, `xcode`

Or configure one at a time:

```bash
bitoarch-local config mcp-config --client cursor --repos /path/to/your/repos
```

Restart your AI assistant and `bitoarch-local` appears in its MCP tool list.

### Common commands

| Command                   | What it does                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `index -i <dir>`          | Index git repos under `<dir>` (or a single repo path). Incremental by default.                               |
| `serve`                   | Start the MCP server. Stdio mode by default (what AI assistants use); `--mode http --port 3000` for testing. |
| `status`                  | Show which repos are indexed and when they were last updated.                                                |
| `clean --repo <name>`     | Remove one repo's index data. `clean --all --force` wipes everything.                                        |
| `config mcp-config --all` | Auto-configure every detected AI assistant to use this server.                                               |
| `info`                    | Print version, build info, and binary path (useful for bug reports).                                         |

For every flag and every command, see the full CLI reference.

### Uninstall

Standalone scripts mirror the installers and reverse only what they did. Safe by default — opt in to deeper cleanup with flags.

```bash
bash <(curl -fsSL https://bitoarch.bito.ai/uninstall.sh)                                 # binary + PATH entries only
bash <(curl -fsSL https://bitoarch.bito.ai/uninstall.sh) --revert-mcp                    # plus clean up AI-assistant MCP configs
bash <(curl -fsSL https://bitoarch.bito.ai/uninstall.sh) --revert-mcp --purge            # plus delete indexed data
bash <(curl -fsSL https://bitoarch.bito.ai/uninstall.sh) --dry-run --purge --revert-mcp  # preview the full removal
```

What the defaults touch:

* Removes `~/.bito/bitoarch/bin/` (the binary and its extracted native helpers).
* Strips the Bito `export PATH=...` line from `~/.bashrc`, `~/.zshrc`, and `~/.profile`. Timestamped `.bak` files are left next to each rcfile.

Flags:

* `--revert-mcp` — deletes the `bitoarch-local` entry from every supported MCP client config (Claude Desktop, Cursor, Windsurf, Cline, VS Code Copilot, Zed, Amazon Q, Xcode on macOS) and from Claude Code via `claude mcp remove`. Other MCP servers in those configs are preserved.
* `--purge` — also deletes `~/.bito/bitoarch/` (indexed repo data, config cache, version-check cache). **Irreversible — indexed data is lost.**
* `--dry-run` — prints every action, changes nothing.
* `--yes` — skips confirmation prompts.

> **⚠ Open a new terminal after uninstall** — the current shell still has the old PATH.

### Documentation

For full CLI reference, see the [Available commands](/ai-architect/local-repository-intelligence-for-ai-assistants/available-commands) documentation — every command, every flag, every env var.

### License

Proprietary and confidential — Bito Inc. All rights reserved.

### Support

For issues or questions, feel free to email us at [**support@bito.ai**](mailto:support@bito.ai)


# Available commands

Full reference for every `bitoarch-local` subcommand, flag, and environment variable. For install + quick start, see the [main documentation](/ai-architect/local-repository-intelligence-for-ai-assistants).

* [`index`](#index-index-git-repositories)
* [`serve`](#serve-start-mcp-server)
* [`status`](#status-check-indexing-status)
* [`resume`](#resume-resume-interrupted-indexing)
* [`clean`](#clean-remove-index-data)
* [`config mcp-config`](#config-mcp-config-configure-mcp-clients)
* [`update`](#update-self-update-the-binary)
* [`setup`](#setup-one-time-post-install-setup)
* [`info`](#info-show-binary-information)
* [Global options and env vars](#global-options-and-env-vars)

***

### `index` — Index Git Repositories

```shellscript
bitoarch-local index -i <repos-dir> [options]
```

Scans `<repos-dir>` one level deep and indexes every entry that looks like a git repo (has a `.git/` subdirectory). `<repos-dir>` can also be a single repo path — if the directory itself has a `.git/`, it's indexed as a single repo. For large `repos-dir` with many unrelated repos, use `--repos "name1, name2"` to narrow the scope.

Re-running `index` is cheap: it hashes each repo and skips unchanged ones. No `--force` needed for normal workflows.

| Flag                  | Description                                                                 | Default                  |
| --------------------- | --------------------------------------------------------------------------- | ------------------------ |
| `-i, --input <dir>`   | **Required.** Directory of git repos (one level deep) OR a single repo path | —                        |
| `-o, --output <dir>`  | Output directory for index data                                             | `~/.bito/bitoarch/index` |
| `--repos <names>`     | Comma-separated repo names to index (quote the value)                       | all repos in `<dir>`     |
| `--skip-metadata`     | Skip metadata extraction                                                    | false                    |
| `--skip-tfidf`        | Skip TF-IDF generation                                                      | false                    |
| `--skip-project-info` | Skip project-info extraction                                                | false                    |
| `--skip-edges`        | Skip dependency extraction                                                  | false                    |
| `--skip-clusters`     | Skip cluster generation                                                     | false                    |
| `--force`             | Re-index even if data exists (wipes state, re-runs every phase)             | false                    |
| `--yes`               | Skip `--force --repos` confirmation prompt                                  | false                    |
| `-v, --verbose`       | Verbose output                                                              | false                    |
| `-d, --debug`         | Debug mode                                                                  | false                    |

**Examples:**

```shellscript
# Index all repos under a directory
bitoarch-local index -i ~/code
​
# Index a single repo
bitoarch-local index -i ~/code/my-api
​
# Index specific repos only (use quotes!)
bitoarch-local index -i ~/code --repos "my-api, my-frontend, shared-lib"
​
# Index to a custom location
bitoarch-local index -i ~/code -o /data/bito-index
​
# Force complete re-index (rarely needed — incremental is the default)
bitoarch-local index -i ~/code --force
```

**Indexing phases** (run in order):

1. Code search index
2. Symbol index
3. Local metadata extraction
4. Local edges / dependency extraction
5. Project-info generation
6. Edges finalization
7. TF-IDF index generation
8. Repository clustering

**Incremental behavior.** On re-run, the tool compares each repo's current hash (git HEAD + file mtimes) against the stored hash from the last run. New or changed repos are reprocessed; unchanged repos are skipped. To force a full re-index of everything, add `--force`.

***

### `serve` — Start MCP Server

```shellscript
bitoarch-local serve [options]
```

Starts the MCP server that AI assistants connect to. Stdio mode (the default) is what AI assistants use; HTTP mode is for testing, scripting, or fronting with a reverse proxy.

| Flag                | Description                                                            | Default                  |
| ------------------- | ---------------------------------------------------------------------- | ------------------------ |
| `-m, --mode <mode>` | Transport: `stdio` or `http`                                           | `stdio`                  |
| `-p, --port <port>` | Port for HTTP mode                                                     | `3000`                   |
| `--data <dir>`      | Directory containing the pre-built index data                          | `~/.bito/bitoarch/index` |
| `--repos <dir>`     | Directory containing the original git source trees (enables `getCode`) | —                        |
| `-v, --verbose`     | Verbose logging                                                        | false                    |
| `-d, --debug`       | Debug logging                                                          | false                    |

**`--data` vs `--repos`.** `--data` points at the already-indexed data produced by `index`; you rarely need to change this unless you indexed to a custom `-o` location. `--repos` points at the original git source trees (where the `.git/` dirs live) so the `getCode` tool can read source files on demand. Without `--repos`, `getCode` returns errors. Without `--data`, the server has no indexed data to serve.

**Examples:**

```shellscript
# Typical usage: default index, point at original source trees
bitoarch-local serve --repos ~/code
​
# Custom index location (if you indexed with -o)
bitoarch-local serve --data /data/bito-index --repos ~/code
​
# HTTP mode for testing / non-stdio clients
bitoarch-local serve --mode http --port 3000 --repos ~/code
```

**HTTP mode health check:**

```shellscript
curl http://127.0.0.1:3000/health
# → {"status":"ok","server":"bitoarch-local","transport":"http-unified",...}
```

**Network-exposed deployments.** There is no built-in HTTPS mode (TLS on `127.0.0.1` adds nothing). If you need HTTPS, put a reverse proxy (Caddy, nginx) in front for TLS termination.

**MCP tools served (13 total):**

| Tool                           | Description                                |
| ------------------------------ | ------------------------------------------ |
| `getCapabilities`              | Discover available analysis capabilities   |
| `listRepositories`             | Browse all indexed repositories            |
| `searchRepositories`           | Natural language search across repos       |
| `getRepositoryInfo`            | Get repo metadata, structure, dependencies |
| `getRepositorySchema`          | Discover repo data structure               |
| `getFieldPath`                 | Extract specific nested fields             |
| `queryFieldAcrossRepositories` | Compare same field across repos            |
| `searchWithinRepository`       | Search within a single repo's data         |
| `searchCode`                   | Search code across indexed repos           |
| `searchSymbols`                | Symbol search (functions, classes, etc.)   |
| `getCode`                      | Read actual source code from files         |
| `listClusters`                 | View repository clusters                   |
| `getClusterInfo`               | Examine a specific cluster                 |

***

### `status` — Check Indexing Status

```shellscript
bitoarch-local status [options]
```

Reads `.indexer-state.json` and reports which repos are indexed, their last-updated timestamps, and the current indexing status. Does not probe the server — it's a pure state-file read.

| Flag                 | Description              | Default                  |
| -------------------- | ------------------------ | ------------------------ |
| `-o, --output <dir>` | Index directory to check | `~/.bito/bitoarch/index` |
| `--json`             | JSON output              | false                    |

***

### `resume` — Resume Interrupted Indexing

```shellscript
bitoarch-local resume [options]
```

If a previous `index` run was interrupted (Ctrl+C, crash, power loss), `resume` picks up where it left off. If the previous run completed successfully, `resume` prints a message showing the original input directory and exits.

| Flag                 | Description                                 | Default                  |
| -------------------- | ------------------------------------------- | ------------------------ |
| `-o, --output <dir>` | Output directory with the interrupted state | `~/.bito/bitoarch/index` |
| `--concurrency <n>`  | Number of parallel indexing operations      | `2`                      |
| `-v, --verbose`      | Verbose output                              | false                    |
| `-d, --debug`        | Debug mode                                  | false                    |

***

### `clean` — Remove Index Data

```shellscript
bitoarch-local clean [options]
```

| Flag                 | Description                                                                                                                         | Default                  |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `-o, --output <dir>` | Index directory to clean                                                                                                            | `~/.bito/bitoarch/index` |
| `--repo <name>`      | Remove a **single** repository from the index (not plural)                                                                          | —                        |
| `--all`              | Remove everything: state + per-repo data + TF-IDF + clusters (**requires `--force`**)                                               | false                    |
| `--force`            | Required only with `--all`. Accepted (but no-op) with `--repo` and default state-only clean, for back-compat with existing scripts. | false                    |

**Confirmation policy.** `--repo <name>` and the default state-only clean run without prompting — the user named a specific repo (intent is explicit), and the state-only clean is trivially reversible (just re-run `index`). `--all` is the only destructive path that needs a full re-index to recover, so it keeps the `--force` gate.

**Behavior by flag combination:**

| Command               | What it removes                                                                                                                                                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clean` (no flags)    | Only the state file (`.indexer-state.json` + `repos.json`). Next `index` starts fresh but reuses existing data on disk.                                                                                                                                              |
| `clean --repo <name>` | Just that one repo's data: `project-info/<name>.json`, `edges/<name>.json`, `ctags-indices/<name>.tags`, `zoekt-indices/<name>_v*.zoekt`, and the repo's state entry. TF-IDF and `clusters.json` are NOT regenerated automatically — re-run `index` to refresh them. |
| `clean --all`         | Refuses without `--force`. Prints a warning explaining recovery requires a full re-index.                                                                                                                                                                            |
| `clean --all --force` | Everything: state + all per-repo data + TF-IDF + clusters. Full wipe.                                                                                                                                                                                                |

**Examples:**

```shellscript
# Remove just one repo (e.g. after deleting it from disk)
bitoarch-local clean --repo my-api
​
# Reset state but keep existing indices
bitoarch-local clean
​
# Full wipe (only path that needs --force)
bitoarch-local clean --all --force
```

***

### `config mcp-config` — Configure MCP Clients

```shellscript
bitoarch-local config mcp-config [options]
```

Detects installed AI assistants on your machine and configures them to use `bitoarch-local` as an MCP server. Creates timestamped backups of existing configs before modifying.

| Flag              | Description                                                                | Default |
| ----------------- | -------------------------------------------------------------------------- | ------- |
| `--all`           | Configure every detected MCP client                                        | —       |
| `--client <name>` | Configure a specific client                                                | —       |
| `--dry-run`       | Preview changes without modifying files                                    | false   |
| `--list-clients`  | List supported clients and their detection status                          | —       |
| `--remove`        | Remove `bitoarch-local` from configs instead of adding                     | false   |
| `--repos <dir>`   | Repos directory for the `serve` command in the generated config            | —       |
| `--yes`           | Skip the "Configure for N clients?" confirmation prompt (for scripts / CI) | false   |

**Supported clients (9 total):**

`claude-desktop` · `claude-code` · `cursor` · `windsurf` · `cline` · `vscode-copilot` · `zed` · `amazon-q` · `xcode`

Most clients are file-based — the command writes/merges an entry into a JSON config file on disk. `claude-code` is CLI-based — the command invokes `claude mcp add-json bitoarch-local '<json>'` via the `claude` CLI rather than writing a config file directly.

**Examples:**

```shellscript
# List all supported clients and detection status
bitoarch-local config mcp-config --list-clients
​
# Preview changes without writing
bitoarch-local config mcp-config --dry-run --all
​
# Configure all detected clients
bitoarch-local config mcp-config --all
​
# Configure all clients non-interactively (CI / scripts)
bitoarch-local config mcp-config --all --yes
​
# Configure all clients with a repos directory
bitoarch-local config mcp-config --all --repos ~/code
​
# Configure a specific client
bitoarch-local config mcp-config --client cursor
​
# Remove bitoarch-local from all client configs
bitoarch-local config mcp-config --remove --all
```

**What this does:**

1. Detects installed MCP clients on your system
2. Creates a timestamped backup of existing configs
3. Adds/updates the `bitoarch-local` MCP server entry
4. Preserves all other existing MCP server configurations

***

### `update` — Self-update the binary

```shellscript
bitoarch-local update [options]
```

Fetches the release manifest from the CDN, downloads the latest binary for your platform, verifies its SHA256 against the manifest, re-applies the ad-hoc code signature (macOS), and atomically replaces the running binary.

| Flag      | Description                                                                | Default |
| --------- | -------------------------------------------------------------------------- | ------- |
| `--force` | Re-download even if the manifest says you're already at the latest version | false   |

**Examples:**

```shellscript
# Normal upgrade
bitoarch-local update
​
# Force re-download (useful during pre-release iteration where
# multiple builds share the same version string)
bitoarch-local update --force
```

**Env var override** — point `update` at a different CDN (mirrors, staging, internal hosts):

```shellscript
BITO_DOWNLOAD_URL=https://my-mirror.example.com bitoarch-local update
```

If your binary's version is below the published `minimum` in the manifest, `update` is exempt from the version-check block — so you can always upgrade out of a blocked state.

***

### `setup` — One-time post-install setup

```shellscript
bitoarch-local setup
```

On macOS and Linux there are no one-time setup tasks — the installer handles everything. This command exists so `setup` is discoverable; running it prints a "no setup needed" message and exits.

***

### `info` — Show Binary Information

```shellscript
bitoarch-local info [--json]
```

Prints version, build ID, build time, platform, and the binary path. Useful for bug reports and verifying which binary is on `$PATH`.

| Flag     | Description |
| -------- | ----------- |
| `--json` | JSON output |

**Example:**

```
=== Bito AI Architect ===
Version:      1.0.0
Build:        2vav654z (2026-04-17T10:35:12.661Z)
Platform:     darwin/arm64
Binary:       /Users/foo/.bito/bitoarch/bin/bitoarch-local
Standalone:   yes
```

***

### Global options and env vars

These apply to every command.

**Global flags:**

| Flag                  | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `-V, --version`       | Print version string and exit                                                     |
| `--skip-update-check` | Skip the remote version check (useful for offline / CI / air-gapped environments) |
| `-h, --help`          | Print help for the current command                                                |

**Environment variables:**

| Variable                 | Purpose                                                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BITO_DOWNLOAD_URL`      | Base URL for the release CDN. Overrides the baked-in default in `install.sh` / the `update` command. Use this for enterprise mirrors, staging tests, or internal hosts. |
| `BITO_SKIP_UPDATE_CHECK` | Set to `1` to skip the version check on every command (same effect as `--skip-update-check` but globally).                                                              |
| `BITO_INSTALL_DIR`       | Where `install.sh` places the binary. Defaults to `~/.bito/bitoarch/bin`.                                                                                               |
| `BITO_LOCAL_BINARY`      | Path to a local binary for `install.sh --local`. Alternative to passing the path as an argument.                                                                        |

**Exit codes:**

| Code | Meaning                                                   |
| ---- | --------------------------------------------------------- |
| 0    | Success                                                   |
| 1    | User error, validation failure, or version-check block    |
| 126  | Binary not executable (missing `chmod +x`)                |
| 127  | Binary not found on PATH                                  |
| 137  | SIGKILL — OS killed the process                           |
| 139  | SIGSEGV — arch mismatch, GLIBC mismatch, truncated binary |


# Overview

On-demand, context-aware AI code reviews for GitHub, GitLab, and Bitbucket.

{% hint style="info" %}
[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

{% embed url="<https://youtu.be/WukH9rA_5go>" %}

Bito’s [**AI Code Review Agent**](https://bito.ai/product/ai-code-review-agent/) is the first agent built with **Bito’s AI Agent framework and engine**. It is an automated AI assistant (powered by best-in-class AI models) that will review your team’s code; it spots bugs, issues, code smells, and security vulnerabilities in Pull/Merge Requests (PR/MR) and provides high-quality suggestions to fix them.

It seamlessly integrates with Git providers such as **GitHub, GitLab, and Bitbucket**, automatically posting recommendations directly as comments within the corresponding Pull Request. It includes real-time recommendations from Static Code Analysis and OSS vulnerability tools such as fbinfer, Dependency-Check, etc. and can include high severity suggestions from other 3rd party tools you use such as Snyk.

{% hint style="info" %}
We also support **GitHub (Self-Managed)** and **GitLab (Self-Managed)**.
{% endhint %}

The AI Code Review Agent acts as a **set of specialized engineers** each analyzing different aspects of your PR. They analyze aspects such as Performance, Code Structure, Security, Optimization, and Scalability. By combining and filtering the results, the Agent can provide you with much more detailed and insightful code reviews, bringing you a better quality code review and helping you save time.

The AI Code Review Agent helps engineering teams merge code faster while also keeping the code clean and up to standard, making sure it runs smoothly and follows best practices.

It ensures a secure and confidential experience without compromising on reliability. Bito neither reads nor stores your code, and none of your code is used for AI model training. Learn more about our [**Privacy & Security practices**](/privacy-and-security).

By accessing Bito's [**AI that Understands Your Code**](https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/) feature, the AI Code Review Agent can analyze relevant context from your entire repository, providing better context-aware analysis and suggestions. This tailored approach ensures a more personalized and contextually relevant code review experience.

To comprehend your code and its dependencies, we use Symbol Indexing, Abstract Syntax Trees (AST), and Embeddings. Each step feeds into the next, starting from locating specific code snippets with Symbol Indexing, getting their structural context with AST parsing, and then leveraging embedding vectors for broader semantic insights. This approach ensures a detailed understanding of the code's functionality and its dependencies. For more information, see [**How does Bito’s “AI that understands your code” work?**](https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/)

The AI Code Review Agent is built using **Bito Dev Agents**, an open framework and engine to **build custom AI Agents** for software developers that understands code, can connect to your organization’s data and tools, and can be discovered and shared via a global registry.

<p align="center"><a href="https://alpha.bito.ai/home/welcome" class="button primary">Start free trial</a><a href="https://bit.ly/bito-code-review-Demo" class="button secondary">Get a demo</a></p>

## Why use an AI Agent for code review?

In many organizations, senior developers spend approximately half of their time reviewing code changes in PRs to find potential issues. The AI Code Review Agent can help save this valuable time.

AI Code Review Agent **speeds up PR merges by 89%**, **reduces regressions by 34%**, and **delivers 87% human-grade feedback**.

However, it's important to remember that the AI Code Review Agent is designed to assist, not replace, senior software engineers. It takes care of many of the more mundane issues involved in code review, so senior engineers can focus on the business logic and how new development is aligned with your organization’s business goals.

## Pricing details

The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)

## Learn more

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:purple;"><strong>Getting Started</strong></mark></td><td></td><td><a href="/ai-code-reviews-in-git/getting-started">Getting started</a></td></tr><tr><td><mark style="color:purple;"><strong>Key Features</strong></mark></td><td></td><td><a href="/ai-code-reviews-in-git/key-features">Key features</a></td></tr><tr><td><mark style="color:purple;"><strong>Supported Programming Languages and Tools</strong></mark></td><td></td><td><a href="/ai-code-reviews-in-git/supported-programming-languages-and-tools">Supported programming languages and tools</a></td></tr><tr><td><mark style="color:purple;"><strong>Agent Configuration: bito-cra.properties File</strong></mark></td><td></td><td><a href="/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file">Agent Configuration: bito-cra.properties File</a></td></tr><tr><td><mark style="color:purple;"><strong>FAQs</strong></mark></td><td></td><td><a href="/ai-code-reviews-in-git/faqs">FAQs</a></td></tr></tbody></table>


# Key features

Explore the powerful capabilities of the AI Code Review Agent.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)

## Features overview

A quick look at powerful features of [**Bito's AI Code Review Agent**](https://bito.ai/product/ai-code-review-agent/)—click to jump to details.

1. [**AI that understands your code**](#ai-that-understands-your-code)
2. [**One-click setup for GitHub, GitLab, and Bitbucket**](#one-click-setup-for-github-gitlab-and-bitbucket)
3. [**Automated and manually-triggered AI code reviews**](#automated-and-manually-triggered-ai-code-reviews)
4. [**Pull request summary**](#pull-request-summary)
5. [**Changelist**](#changelist)
6. [**One-click to accept suggestions**](#one-click-to-accept-suggestions)
7. [**Chat with AI Code Review Agent**](#chat-with-ai-code-review-agent)
8. [**Incremental code reviews**](#incremental-code-reviews)
9. [**Code review analytics**](#code-review-analytics)
10. [**Custom code review rules and guidelines**](#custom-code-review-rules-and-guidelines)
11. [**Multiple specialized engineers for targeted code analysis**](#multiple-specialized-engineers-for-targeted-code-analysis)
12. [**Integrated feedback from dev tools you use**](#integrated-feedback-from-dev-tools-you-use)
13. [**Jira integration**](#jira-integration)
14. [**Supports all major programming languages**](#supports-all-major-programming-languages)
15. [**Enterprise-grade security**](#enterprise-grade-security)

<p align="center"><a href="https://alpha.bito.ai/home/welcome" class="button primary">Start free trial</a><a href="https://bit.ly/bito-code-review-Demo" class="button secondary">Get a demo</a></p>

***

## AI that understands your code

The [AI Code Review Agent](https://bito.ai/product/ai-code-review-agent/) understand code changes in pull requests. It analyzes relevant context from your entire repository, resulting in more accurate and helpful code reviews.

To comprehend your code and its dependencies, it uses Symbol Indexing, Abstract Syntax Trees (AST), and Embeddings.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/">https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/</a></td></tr></tbody></table>

## One-click setup for GitHub, GitLab, and Bitbucket

[Bito Cloud](https://alpha.bito.ai/) offers a one-click solution for using the [AI Code Review Agent](/ai-code-reviews-in-git/install-run-using-bito-cloud), eliminating the need for any downloads on your machine.

Bito supports integration with the following Git providers:

* [GitHub](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github)
* [GitHub (Self-Managed)](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github-self-managed)
* [GitLab](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab)
* [GitLab (Self-Managed)](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab-self-managed)
* [Bitbucket](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket)
* [Bitbucket (Self-Managed)](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket-self-managed)

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud">Install/run using Bito Cloud</a></td></tr></tbody></table>

## Automated and manually-triggered AI code reviews

By default, the AI Code Review Agent automatically reviews all new pull requests and provides detailed feedback.

To initiate a manual review, simply type **`/review`** in the comment box on the pull request and submit it. This action will start the code review process.

## Pull request summary

Get a concise overview of your pull request (PR) directly in the description section, making it easier to understand the code changes at a glance.

Each pull request includes an automatically generated summary that explains the intent and scope of the changes in a clear, easy-to-read format.

The summary highlights the main objective of the update, outlines the most important modifications, and provides a high-level view of their impact on the codebase. This allows reviewers to quickly understand what the pull request is about before diving into the detailed code changes.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FS2Zvc4lkM8KCpl6ql0Cj%2Ftuxpi.com.1772692380.jpg?alt=media&amp;token=6779b01e-8ea1-4cc5-9937-bd48bddcf015" alt=""><figcaption><p>Summary of pull request in the description section.</p></figcaption></figure>

## Changelist

A tabular view that displays key changes in a pull request, making it easy to spot important updates at a glance without reviewing every detail. Changelist categorizes modifications and highlights impacted files, giving you a quick, comprehensive summary of what has changed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FKvprpQl5Q6Q5cjQ0JDtI%2Fchangelist_by_bito.png?alt=media&amp;token=90deeb82-25a6-401a-b26c-43f24dfd7965" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

## One-click to accept suggestions

The AI-generated code review feedback is posted as comments directly within your pull request, making it seamless to view and address suggestions right where they matter most.

You can accept the suggestions with a single click, and the changes will be added as a new commit to the pull request.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FXeSZETfSx7uVpMdn6KD4%2Fscrnli_ypuJi4RX3JeL32_1.png?alt=media&amp;token=83d2a18c-94da-481c-abd0-2bb4e0be341e" alt="One-click to accept AI code review suggestions"><figcaption><p>One-click to accept AI code review suggestions</p></figcaption></figure>

## Chat with AI Code Review Agent

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

Real-time collaboration with the AI Code Review Agent accelerates your development cycle. By delivering immediate, actionable insights, it eliminates the delays typically experienced with human reviews. Developers can engage directly with the Agent to clarify recommendations on the spot, ensuring that any issues are addressed swiftly and accurately.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FDLSrDW0fZeh5flN0awRY%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=88d024d5-e9b9-48b0-a0eb-7b42b355c296" alt="" width="563"><figcaption></figcaption></figure>

## Incremental code reviews

AI Code Review Agent automatically reviews only the recent changes each time you push new commits to a pull request. This saves time and reduces costs by avoiding unnecessary re-reviews of all files.

You can enable or disable incremental reviews using the [Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance).

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="https://bito.ai/blog/how-to-perform-ai-powered-incremental-code-reviews-with-bito/">https://bito.ai/blog/how-to-perform-ai-powered-incremental-code-reviews-with-bito/</a></td></tr></tbody></table>

## Code review analytics

Get in-depth insights into your org’s code reviews with user-friendly [Code Review Analytics](https://alpha.bito.ai/home/dashboard?view=overview) dashboard. Track key metrics such as pull requests reviewed, issues found, lines of code reviewed, and understand individual contributions.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FlInn8tc18zASv8l9iU24%2Fscrnli_7_12_2024_9-49-52%20PM.png?alt=media&amp;token=ab7c9143-d65e-4fa3-8827-9eb0d634dc13" alt=""><figcaption><p>Code Review Analytics dashboard</p></figcaption></figure>

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/code-review-analytics">Code review analytics</a></td></tr></tbody></table>

## Custom code review rules and guidelines

The AI Code Review Agent offers a flexible solution for teams looking to enforce custom code review rules, standards, and guidelines tailored to their unique development practices. Whether your team follows specific coding conventions or industry best practices, you can customize the Agent to suite your needs.

We support two ways to customize AI Code Review Agent’s suggestions:

1. [**Provide feedback on Bito-reported issues in pull requests**](/ai-code-reviews-in-git/implementing-custom-code-review-rules#id-1-provide-feedback-on-bito-reported-issues), and the AI Code Review Agent automatically adapts by creating code review rules to prevent similar suggestions in the future.
2. [**Create custom code review guidelines via the dashboard**](/ai-code-reviews-in-git/implementing-custom-code-review-rules#id-2-create-custom-code-review-guidelines). Define rules through the [**Custom Guidelines**](https://alpha.bito.ai/home/ai-agents/custom-guidelines) dashboard in Bito Cloud and apply them to agent instances in your workspace.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/implementing-custom-code-review-rules">Implementing custom code review rules</a></td></tr></tbody></table>

## Multiple specialized engineers for targeted code analysis

The AI Code Review Agent acts as a team of specialized engineers, each analyzing different aspects of your pull request. You'll get specific advice for improving your code, right down to the exact line in each file.

The areas of analysis include:

* Security
* Performance
* Scalability
* Optimization
* Will this change break anything? Based on the diff can we include anything?
* Code structure and formatting (e.g., tab, spaces)
* Basic coding standards including variable names (e.g., ijk)

This multifaceted analysis results in more detailed and accurate code reviews, saving you time and improving code quality.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/available-commands#review-scope">Available commands</a></td></tr></tbody></table>

## Integrated feedback from dev tools you use

Elevate your code reviews by harnessing the power of the development tools you already trust. Bito's AI Code Review Agent seamlessly integrates feedback from essential tools including:

* **Static code analysis**
* **Open source security vulnerabilities check**
* **Linter integrations**
* **Secrets scanning** (e.g., passwords, API keys, sensitive information)

**Static code analysis**

Using tools like Facebook’s open-source fbinfer (available out of the box), the Agent dives deep into your code—tailored to each language—and suggests actionable fixes. You can also configure additional tools you use for a more customized analysis experience.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBbscfaNSN1GCmy4PSzkp%2Fscrnli_3_28_2024_5-33-27%20AM_1.png?alt=media&amp;token=767d2abc-3b4e-4141-b5b0-5f8f5bf4a01e" alt=""><figcaption><p>Static Code Analysis feedback highlighting suggestions and fixes.</p></figcaption></figure>

**Open source security vulnerabilities check**

The AI Code Review Agent checks real-time for the latest high severity security vulnerabilities in your code, using [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) (available out of the box). Additional tools such as [Snyk](https://snyk.io/), or [GitHub Dependabot](https://github.com/dependabot) can also be configured.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FiLlr9WhjlOLIWgk52G9w%2Fscrnli_3_28_2024_5-08-00%20AM_1.png?alt=media&amp;token=66382333-925d-4d9f-ada3-e14e6dd8c0a1" alt=""><figcaption><p>Showing high-severity security vulnerabilities report.</p></figcaption></figure>

**Linter integrations**

Our integrated linter support reviews your code for consistency and adherence to best practices. By catching common errors early, it ensures your code stays clean, maintainable, and aligned with modern development standards.

**Secrets scanning**

Safeguard your sensitive data effortlessly. With built-in scanning capabilities, the Agent checks your code for exposed passwords, API keys, and other confidential information—helping to secure your codebase throughout the development lifecycle.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/supported-programming-languages-and-tools">Supported programming languages and tools</a></td></tr></tbody></table>

## Jira integration

Seamlessly connect Bito with Jira to automatically validate pull request code changes against linked Jira tickets. This ensures your implementations meet specified requirements through real-time, structured validation feedback directly in your pull requests.

Support for Jira Cloud and Jira Data Center setups enables flexible integrations, while multiple ticket-linking methods ensure accurate requirement tracking.

Boost your team's code quality, collaboration, and traceability with automated Jira ticket validation.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/jira-integration">Jira integration</a></td></tr></tbody></table>

## Supports all major programming languages

No matter if you're coding in Python, JavaScript, Java, C++, or beyond, our AI Code Review Agent has you covered. It understands the unique syntax and best practices of every popular language, delivering tailored insights that help you write cleaner, more efficient code—every time.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/supported-programming-languages-and-tools">Supported programming languages and tools</a></td></tr></tbody></table>

## Enterprise-grade security

Bito and third-party LLM providers never store or use your code, prompts, or any other data for model training or any other purpose.

Bito is SOC 2 Type II compliant. This certification reinforces our commitment to safeguarding user data by adhering to strict security, availability, and confidentiality standards. SOC 2 Type II compliance is an independent, rigorous audit that evaluates how well an organization implements and follows these security practices over time.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/privacy-and-security">Privacy and security</a></td></tr></tbody></table>


# Supported programming languages and tools

Supports key languages & tools, including fbInfer, Dependency Check, and Snyk.

## Supported Programming Languages

### AI Code Review

The [AI Code Review Agent](/ai-code-reviews-in-git/overview) understands code changes in pull requests by analyzing relevant context from your entire repository, resulting in more accurate and helpful code reviews. The agent provides either **Basic Code Understanding** or **Advanced Code Understanding** based on the programming languages used in the code diff. Learn more about all the supported languages in the table below.

**Basic Code Understanding** is providing the surrounding code for the diff to help AI better understand the context of the diff.

**Advanced Code Understanding** is providing detailed information holistically to the LLM about the changes the diff is making—from things such as global variables, libraries, and frameworks (e.g., Lombok in Java, React for JS/TS, or Angular for TS) being used, the specific functions/methods and classes the diff is part of, to the upstream and downstream impact of a change being made. Using advanced code traversal and understanding techniques, such as symbol indexes, embeddings, and abstract syntax trees, Bito deeply tries to understand what your changes are about and the impact and relevance to the greater codebase, like a senior engineer does when doing code review. [**Read more here about our approach**](https://bito.ai/blog/how-does-bitos-ai-that-understands-your-code-work/).

{% hint style="info" %}
For requests to add support for specific programming languages, please reach out to us at <support@bito.ai>
{% endhint %}

|         Languages        | AI Code Review | Basic Code Understanding | Advanced Code Understanding |
| :----------------------: | :------------: | :----------------------: | :-------------------------: |
|       **Assembly**       |       YES      |            YES           |             YES             |
|      **Bash/Shell**      |       YES      |            YES           |             YES             |
|           **C**          |       YES      |            YES           |             YES             |
|          **C++**         |       YES      |            YES           |             YES             |
|          **C#**          |       YES      |            YES           |             YES             |
|         **Dart**         |       YES      |            YES           |             YES             |
|        **Delphi**        |       YES      |            YES           |             YES             |
|          **Go**          |       YES      |            YES           |             YES             |
|        **Groovy**        |       YES      |            YES           |             YES             |
|       **HTML/CSS**       |       YES      |            YES           |             YES             |
|         **Java**         |       YES      |            YES           |             YES             |
|      **JavaScript**      |       YES      |            YES           |             YES             |
| **JavaScript Framework** |       YES      |            YES           |             YES             |
|        **Kotlin**        |       YES      |            YES           |             YES             |
|          **Lua**         |       YES      |            YES           |             YES             |
|      **Objective-C**     |       YES      |            YES           |             YES             |
|          **PHP**         |       YES      |            YES           |             YES             |
|      **PowerShell**      |       YES      |            YES           |             YES             |
|        **Python**        |       YES      |            YES           |             YES             |
|           **R**          |       YES      |            YES           |             YES             |
|         **Ruby**         |       YES      |            YES           |             YES             |
|         **Rust**         |       YES      |            YES           |             YES             |
|         **Scala**        |       YES      |            YES           |             YES             |
|         **SCSS**         |       YES      |            YES           |             YES             |
|          **SQL**         |       YES      |            YES           |             YES             |
|         **Swift**        |       YES      |            YES           |             YES             |
|       **Terraform**      |       YES      |            YES           |             YES             |
|      **TypeScript**      |       YES      |            YES           |             YES             |
| **TypeScript Framework** |       YES      |            YES           |             YES             |
|        **Vue.js**        |       YES      |            YES           |             YES             |
|   **Visual Basic .NET**  |       YES      |            YES           |             YES             |
|        **Others**        |       YES      |            YES           |             YES             |

***

### Static Code Analysis and Open Source Vulnerabilities Check

For custom SAST tools configuration to support specific languages in the [AI Code Review Agent](/ai-code-reviews-in-git/overview), please reach out to us at <support@bito.ai>

|       Languages       |                        Static Code Analysis / Linters                        | Open Source Vulnerabilities Check |
| :-------------------: | :--------------------------------------------------------------------------: | :-------------------------------: |
|      **Assembly**     |                                      NO                                      |                 NO                |
|     **Bash/Shell**    |                                      NO                                      |                 NO                |
|         **C**         |             <p>YES<br>(using <strong>Facebook Infer</strong>)</p>            |                 NO                |
|        **C++**        |             <p>YES<br>(using <strong>Facebook Infer</strong>)</p>            |                 NO                |
|         **C#**        |                                      NO                                      |                 NO                |
|        **Dart**       |                                      NO                                      |                 NO                |
|       **Delphi**      |                                      NO                                      |                 NO                |
|         **Go**        |             <p>YES<br>(using <strong>golangci-lint</strong>)</p>             |                YES                |
|       **Groovy**      |                                      NO                                      |                 NO                |
|      **HTML/CSS**     |                                      NO                                      |                 NO                |
|        **Java**       |             <p>YES<br>(using <strong>Facebook Infer</strong>)</p>            |                 NO                |
|     **JavaScript**    |                 <p>YES<br>(using <strong>ESLint</strong>)</p>                |                YES                |
|       **Kotlin**      |                                      NO                                      |                 NO                |
|        **Lua**        |                                      NO                                      |                 NO                |
|    **Objective-C**    |             <p>YES<br>(using <strong>Facebook Infer</strong>)</p>            |                 NO                |
|        **PHP**        |                                      NO                                      |                 NO                |
|     **PowerShell**    |                                      NO                                      |                 NO                |
|       **Python**      | <p>YES<br>(using <strong>Astral Ruff</strong> and <strong>Mypy</strong>)</p> |                 NO                |
|         **R**         |                                      NO                                      |                 NO                |
|        **Ruby**       |                                      NO                                      |                 NO                |
|        **Rust**       |                                      NO                                      |                 NO                |
|       **Scala**       |                                      NO                                      |                 NO                |
|        **SCSS**       |                                      NO                                      |                 NO                |
|        **SQL**        |                                      NO                                      |                 NO                |
|       **Swift**       |                                      NO                                      |                 NO                |
|     **Terraform**     |                                      NO                                      |                 NO                |
|     **TypeScript**    |                 <p>YES<br>(using <strong>ESLint</strong>)</p>                |                YES                |
|       **Vue.js**      |                                      NO                                      |                 NO                |
| **Visual Basic .NET** |                                      NO                                      |                 NO                |
|       **Others**      |                                      NO                                      |                 NO                |

***

## Supported Tools and Platforms

|            Tool            |                                Type                                |          Supported/Integrated         |
| :------------------------: | :----------------------------------------------------------------: | :-----------------------------------: |
|       **Astral Ruff**      |                          Linter for Python                         |                  YES                  |
|      **Azure DevOps**      |                           Code Repository                          |              Coming soon              |
|        **Bitbucket**       |                           Code Repository                          |                  YES                  |
|     **detect-secrets**     | Secrets scanner (e.g., passwords, API keys, sensitive information) |                  YES                  |
|         **ESLint**         |                Linter for JavaScript and TypeScript                |                  YES                  |
|     **Facebook Infer**     |       Static Code Analysis for Java, C, C++, and Objective-C       |                  YES                  |
|      **GitHub cloud**      |                           Code Repository                          |                  YES                  |
|  **GitHub (Self-Managed)** |                           Code Repository                          |  YES, supports version 3.0 and above. |
|      **GitLab cloud**      |                           Code Repository                          |                  YES                  |
|  **GitLab (Self-Managed)** |                           Code Repository                          | YES, supports version 15.5 and above. |
|      **golangci-lint**     |                            Linter for Go                           |                  YES                  |
|          **Mypy**          |                   Static Type Checker for Python                   |                  YES                  |
| **OWASP dependency Check** |                              Security                              |                  YES                  |
|          **Snyk**          |                              Security                              |                  YES                  |
|        **Whispers**        | Secrets scanner (e.g., passwords, API keys, sensitive information) |                  YES                  |

***

## Supported output languages for code review feedback

Bito supports posting code review feedback in over 20 languages. You can choose your preferred language in the [agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance). Supported languages include the following:

1. Arabic (عربي)
2. Bulgarian (български)
3. Chinese (Simplified) (简体中文)
4. Chinese (Traditional) (繁體中文)
5. Czech (čeština)
6. Dutch (Nederlands)
7. English (English)
8. French (français)
9. German (Deutsch)
10. Hebrew (עִברִית)
11. Hindi (हिंदी)
12. Hungarian (magyar)
13. Italian (italiano)
14. Japanese (日本語)
15. Korean (한국어)
16. Malay (Melayu)
17. Polish (polski)
18. Portuguese (português)
19. Russian (русский)
20. Spanish (español)
21. Turkish (Türkçe)
22. Vietnamese (Tiếng Việt)


# Try AI code reviews using Test Mode

Experience AI-powered code analysis on any pull request — no admin access needed.

Bito offers **Test Mode** to help you quickly explore our [**AI Code Review Agent**](/ai-code-reviews-in-git/overview) without requiring administrator permissions for your Git repositories. Whether you're evaluating Bito for your team or simply want to see it in action before a full setup, Test Mode gives you immediate access using just a personal access token.

You can point Bito at any pull request you have access to and receive instant AI-generated feedback.

**What you get:**

* Instant access to AI-powered code reviews
* Support for GitHub, GitLab, and Bitbucket (cloud and self-hosted)
* 10 complimentary pull request analyses

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FqVlbGXqjnQt2E2qaVad5%2Fscrnli_GLgdASP4YVzfQ9.png?alt=media&amp;token=4e1ac44e-d684-45ab-9838-a6c9913990bf" alt=""><figcaption></figcaption></figure>

## Who can use Test Mode?

Test Mode is designed for first-time evaluators. You can access it when:

* Your Bito account is on a trial subscription (or eligible for a trial, meaning you haven't used any trials before)
* Your workspace has a clean slate (no previous Git repository connections)

{% hint style="info" %}
When you analyze your first pull request in Test Mode, Bito automatically activates your 14-day trial, giving you access to code review capabilities.
{% endhint %}

## Getting started

{% stepper %}
{% step %}

### Log in to Bito

[**Log in to Bito Cloud**](https://alpha.bito.ai/home/welcome) with a fresh user account and create a new workspace
{% endstep %}

{% step %}

### Access Test Mode

* Click **"Do a test code review"** option at the bottom of the Git setup wizard

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FPtd1tm0n4S8RCAOlJbsK%2Fscrnli_Y4T3koD33Vyr4v.png?alt=media&amp;token=6c8391cc-2725-4492-92e4-d2697705e701" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Enter pull request details

1. **Pull request URL**

   Enter the complete URL of the pull request you want Bito to review.

   * **Example:** `https://github.com/username/repository/pull/123`

2. **Personal Access Token**

   Generate a personal access token from your Git platform to authorize Bito to read the pull request:

   1. **For GitHub:**
      1. Create **GitHub classic Token with `repo` access**. Fine-grained tokens are not supported. [Learn more](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
   2. **For GitLab:**
      1. Create **GitLab token with `api` scope** [Learn more](https://docs.gitlab.com/user/profile/personal_access_tokens/#create-a-personal-access-token)
   3. **For Bitbucket:**
      1. Depending on your Bitbucket setup, you may need one of the following:
         * For **Bitbucket Cloud** use **API Token**. [Learn more](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)
         * For **Bitbucket Enterprise (Self-Hosted)** use **HTTP Access Token**. [Learn more](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html)
      2. Required scopes:
         * `read:pullrequest:bitbucket`
         * `write:pullrequest:bitbucket`
         * `read:workspace:bitbucket`
         * `read:repository:bitbucket`
         * `read:user:bitbucket`
      3. Enter both your Bitbucket **email address** and the **personal access token** in Bito
   4. **For Self-managed GitHub, GitLab, and Bitbucket:**

      If you're using self-managed Git instances (GitHub Enterprise, GitLab Self-Managed, or Bitbucket Server):

      1. Select your Git provider
      2. Enter your Git domain URL (e.g., `https://bitbucket.example.com`)
      3. Configure Network Access
         * If your network restricts external services from accessing your Git server, add these Bito IP addresses to your allowed IP list:

```
18.188.201.104
3.23.173.30
18.216.64.170
```

3. **Validate your token**

   Click **"Validate"** to verify that your personal access token is working correctly. This ensures Bito can access the pull request before proceeding.

4. **Choose your review depth**

   Select the level of analysis you want:

   * **Essential:** Focuses on the most critical issues (faster review)
   * **Comprehensive:** Provides deeper analysis with more detailed feedback (more thorough review)

{% hint style="info" %}
Feel free to experiment with both approaches on different pull requests to find what works best for your needs.
{% endhint %}
{% endstep %}

{% step %}

### Start code review

Click **Do a test code review** to start the AI code review.
{% endstep %}
{% endstepper %}

## Test Mode dashboard

After completing your first test review, you'll have access to a dashboard showing:

* Number of test reviews remaining (out of 10 total)
* History of analyzed pull requests
* Quick-start button for new reviews

#### Starting new test review

To analyze another pull request, click **"New code review"** button in the upper-right corner of your review history table.

## Upgrading to full Git integration

Once you've used all 10 test reviews, you'll need to complete full Git integration to continue using Bito's AI Code Review Agent.

#### Why upgrade?

Full Git integration unlocks powerful features not available in Test Mode:

**Advanced configuration:**

* **Default branch settings:** Customize which branch is used for code reviews
* **Custom guidelines:** Define your own review rules and coding standards
* **Filters:** Exclude draft PRs, files, or branches from review to focus on relevant code.
* **Tools:** Enable additional checks, such as secret scanning.
* **Automation:** Configure auto-reviews, batching, and summary settings
* **And much more.**

**Unlimited reviews:**

* No review limits — analyze every pull request
* Automatic reviews on new PRs
* Incremental reviews on PR updates
* Complete team analytics and insights

#### How to upgrade

From your Test Mode dashboard, click **"Complete Git integration"** and follow the setup wizard to connect your Git repositories.

For detailed setup instructions, see:

* [**Guide for GitHub**](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github)
* [**Guide for GitHub (Self-Managed)**](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github-self-managed)
* [**Guide for GitLab**](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab)
* [**Guide for GitLab (Self-Managed)**](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab-self-managed)
* [**Guide for Bitbucket**](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket)
* [**Guide for Bitbucket (Self-Managed)**](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket-self-managed)

### FAQs

**Q: Can I use Test Mode if I've previously used Bito?**\
A: Test Mode is only available to users who haven't previously used a trial and haven't set up Git integration in their workspace.

**Q: What happens after I use all 10 test reviews?**\
A: You'll need to complete full Git integration to continue reviewing pull requests.

**Q: Can I test on private repositories?**\
A: Yes, as long as your personal access token has the correct permissions to access the repository.

**Q: Does Test Mode work with self-hosted Git instances?**\
A: Yes, Test Mode supports GitHub Enterprise, GitLab Self-Managed, and Bitbucket Server. You'll need to provide your Git domain URL and configure network access (whitelist Bito IP addresses) if needed.

**Q: Will my code be stored or used for training?**\
A: No. Bito does not store your code, and your code is never used for AI model training. Learn more about our [privacy and security practices](/privacy-and-security).

**Q: What's the difference between Essential and Comprehensive review modes?**\
A: Essential mode focuses on critical issues and completes faster, while Comprehensive mode provides deeper analysis with more detailed feedback. You can try both to see which fits your needs.


# Getting started

Deploy the AI Code Review Agent in Bito Cloud or opt for self-hosted service.

**The** [**AI Code Review Agent**](/ai-code-reviews-in-git/overview) **supports two deployment options:**

* [**Bito Cloud (fully managed)**](/ai-code-reviews-in-git/install-run-using-bito-cloud)
* [**Self-hosted service (run on your own infrastructure)**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service)

Each option comes with its own set of benefits and considerations.

This guide walks you through both options to help you determine which deployment model best fits your team’s needs.

## Bito Cloud

[**Bito Cloud**](/ai-code-reviews-in-git/install-run-using-bito-cloud) provides a managed environment for running the AI Code Review Agent, offering a seamless, hassle-free experience. This option is ideal for teams looking for quick deployment and minimal operational overhead.

**Pros:**

* **Simplicity:** Enjoy a straightforward setup with a single-click installation process, making it easy to get started without technical hurdles.
* **Maintenance-Free:** Bito Cloud takes care of all necessary updates and maintenance, ensuring your Agent always operates on the latest software version without any effort on your part.
* **Scalability:** The platform is designed to easily scale, accommodating project growth effortlessly and ensuring reliable performance under varying loads.

**Cons:**

* **Handling of Pull Request Diffs:** For analysis purposes, diffs from pull requests are temporarily stored on our servers.

<p align="center"><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud" class="button primary">Install/run using Bito Cloud</a></p>

***

## Self-hosted service

[**Self-hosted**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service) AI Code Review Agent offers a higher degree of control and customization, suited for organizations with specific requirements or those who prefer to manage their own infrastructure.

**Pros:**

* **Full Control:** Self-hosting provides complete control over the deployment environment, allowing for extensive customization and the ability to integrate with existing systems as needed.
* **Privacy and Security:** Keeping the AI Code Review Agent within your own infrastructure can enhance data security and privacy, as all information remains under your direct control.

**Cons:**

* **Setup Complexity:** Establishing a self-hosted environment requires technical know-how and can be more complex than using a managed service, potentially leading to longer setup times.
* **Maintenance Responsibility:** The responsibility of maintaining and updating the software falls entirely on your team, which includes ensuring the system is scaled appropriately to handle demand.

<p align="center"><a href="/ai-code-reviews-in-git/install-run-as-a-self-hosted-service" class="button primary">Install/run as a self-hosted service</a></p>


# Install/run using Bito Cloud

Deploy the AI Code Review Agent in Bito Cloud.

[**Bito Cloud**](https://alpha.bito.ai/) offers a single-click solution for using the [**AI Code Review Agent**](/ai-code-reviews-in-git/overview), eliminating the need for any downloads on your machine. You can create multiple instances of the Agent, allowing each to be used with a different repository on a Git provider such as GitHub, GitLab, or Bitbucket.

We also support **GitHub (Self-Managed)**, **GitLab (Self-Managed)**, and **Bitbucket (Self-Managed)**.

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Connect Bito to your Git provider

Select your Git provider from the options below and follow the step-by-step installation guide to seamlessly set up your AI Code Review Agent.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Guide for GitHub</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github">Guide for GitHub</a></td></tr><tr><td><mark style="color:blue;"><strong>Guide for GitHub (Self-Managed)</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github-self-managed">Guide for GitHub (Self-Managed)</a></td></tr><tr><td><mark style="color:blue;"><strong>Guide for GitLab</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab">Guide for GitLab</a></td></tr><tr><td><mark style="color:blue;"><strong>Guide for GitLab (Self-Managed)</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab-self-managed">Guide for GitLab (Self-Managed)</a></td></tr><tr><td><mark style="color:blue;"><strong>Guide for Bitbucket</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket">Guide for Bitbucket</a></td></tr><tr><td><mark style="color:blue;"><strong>Guide for Bitbucket (Self-Managed)</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-bitbucket-self-managed">Guide for Bitbucket (Self-Managed)</a></td></tr></tbody></table>


# Guide for GitHub

Integrate the AI Code Review Agent into your GitHub workflow.

Speed up code reviews by configuring the [AI Code Review Agent](/ai-code-reviews-in-git/overview) with your GitHub repositories. In this guide, you'll learn how to set up the Agent to receive automated code reviews that trigger whenever you create a pull request, as well as how to manually initiate reviews using [available commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).&#x20;

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Video tutorial

{% embed url="<https://www.youtube.com/watch?v=cmkCwpoQer4>" %}

## Installation and configuration steps

Follow the step-by-step instructions below to install the **AI Code Review Agent** using **Bito Cloud**:

### **Step 1: Log in to Bito**

[Log in to Bito Cloud](https://alpha.bito.ai/) and select a workspace to get started.

### **Step 2: Open the Code Review Agents setup**

Click [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) under the **CODE REVIEW** section in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7jB4NvihTZqLpAX1nuaf%2Fscrnli_KuCSLAb2uwZqov.png?alt=media&amp;token=8c7fdbb7-2358-40ed-9a5f-db23cb11be40" alt=""><figcaption></figcaption></figure>

### **Step 3: Select your Git provider**

Bito supports integration with the following Git providers:&#x20;

* GitHub&#x20;
* GitHub (Self-Managed)&#x20;
* GitLab&#x20;
* GitLab (Self-Managed)&#x20;
* Bitbucket
* Bitbucket (Self-Managed)

Since we are setting up the Agent for GitHub, select **GitHub** to proceed.

This will redirect you to **GitHub**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FjYUnUM1FSNqL4FPlhIeb%2Fscrnli_eJySqPMukXXS5p.png?alt=media&amp;token=1c3f3d9c-a9a7-42c9-b923-0989aa2fbca6" alt="" width="563"><figcaption></figcaption></figure>

### **Step 4: Install the Bito app for GitHub** &#x20;

To enable pull request reviews, you need to install and authorize the **Bito’s AI Code Review Agent** app.

On GitHub, select where you want to install the app.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FQUYQHV8vf2jbjVPYibBi%2Fscrnli_M43vf65IMb8eev.png?alt=media&amp;token=7f1c2b04-ee16-45a9-90ce-33f589f9a4d7" alt=""><figcaption></figcaption></figure>

Grant Bito access to your repositories:

* Choose **All repositories** to enable Bito for every repository in your account.&#x20;
* Or, select **Only select repositories** and pick specific repositories using the dropdown menu.&#x20;

{% hint style="info" %}
Bito app uses these permissions:

* **Read** access to metadata
* **Read** and **write** access to code, issues, and pull requests
* **Read** access to organization members
  {% endhint %}

Click **Install & Authorize** to proceed. Once completed, you will be redirected to Bito.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FjaaPBoWE8y2AdTHEf1QM%2Fscrnli_T7rYz0M1AVfzWP.png?alt=media&amp;token=5f5d0b5c-7187-4a96-bd37-2b977e478647" alt="" width="527"><figcaption></figcaption></figure>

### **Step 5: Enable AI Code Review Agent on repositories**

After connecting Bito to your GitHub account, you'll see a list of repositories that Bito has access to.

Use the toggles in the **Code Review Status** column to **enable** or **disable** the Agent for each repository.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FeMOMn63PXgdez23nneKy%2Fscrnli_bYdbJiIK81y982_1.png?alt=media&amp;token=752fe5c7-710d-43f6-90fb-0c876d0fc0f3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To customize the Agent’s behavior, you can edit existing configurations or create new Agents as needed.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endhint %}

### **Step 6: Automated and manual pull request reviews**&#x20;

Once a repository is enabled, you can invoke the AI Code Review Agent in the following ways:

1. **Automated code review:** By default, the Agent automatically reviews all new pull requests and provides detailed feedback.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the pull request and submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and submit it to re-review the entire pull request from scratch, rather than only the latest changes.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed. To always re-review all changes, use `/review full`.
{% endhint %}

The AI-generated code review feedback will be posted as comments directly within your pull request, making it seamless to view and address suggestions right where they matter most.&#x20;

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FryhzTFegsxvL4eoZewT7%2Fscrnli_2_28_2024_8-57-29%20PM.png?alt=media&amp;token=af92cdfb-089b-4f95-8200-52adebe366dd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** To enhance efficiency, the automated code reviews are only triggered for pull requests merging into the repository’s default branch. This prevents unnecessary processing and Advanced AI requests usage.

To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review pull requests when the source or target branch matches the list.

The **Include Source/Target Branches** filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
{% endhint %}

{% hint style="info" %}
The AI Code Review Agent automatically reviews code changes up to 5000 lines when a pull request is created. For larger changes, you can use the **`/review full`** command.
{% endhint %}

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull request.
{% endhint %}

### **Step 7: Specialized commands for code reviews**

Bito also offers **specialized commands** that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.&#x20;

* **`/review security`**: Analyzes code to identify security vulnerabilities and ensure secure coding practices.&#x20;
* **`/review performance`**: Evaluates code for performance issues, identifying slow or resource-heavy areas.&#x20;
* **`/review scalability`**: Assesses the code's ability to handle increased usage and scale effectively.&#x20;
* **`/review codeorg`**: Scans for readability and maintainability, promoting clear and efficient code organization.&#x20;
* **`/review codeoptimize`**: Identifies optimization opportunities to enhance code efficiency and reduce resource usage.&#x20;

By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**&#x20;

For more details, refer to [Available Commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

### **Step 8: Chat with AI Code Review Agent**

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

To start the conversation, type your question in the comment box within the inline suggestions on your pull request, and then submit it. Typically, Bito AI responses are delivered in about 10 seconds. On GitHub and Bitbucket, you need to manually refresh the page to see the responses, while GitLab updates automatically.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FivCegqSzdY80hPdZIMGN%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=528ddcda-100d-49a8-b6b5-2b9767a23785" alt="" width="563"><figcaption></figcaption></figure>

### Step 9: Configure Agent settings

[Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) let you control how reviews are performed, ensuring feedback is tailored to your team’s needs. By adjusting the options, you can:

* Make reviews more focused and actionable.
* Apply your own coding standards.
* Reduce noise by excluding irrelevant files or branches.
* Add extra checks to improve code quality and security.

[**Learn more**](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated pull request (PR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fk5wsTj4siolCcaZqHRIX%2Fscrnli_9_13_2024_12-33-56%20PM.png?alt=media&amp;token=63cb7da9-21ca-41a1-83ba-9b107d07a6cf" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a pull request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the pull request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FP0sUIAZ3Lq0FqL9ytfPF%2Fscrnli_9_13_2024_12-49-29%20PM_cropped_3.png?alt=media&amp;token=d74d3b27-4831-4735-9559-6f9da191e910" alt=""><figcaption></figcaption></figure>


# Guide for GitHub (Self-Managed)

Integrate the AI Code Review Agent into your self-hosted GitHub Enterprise workflow.

Speed up code reviews by configuring the [AI Code Review Agent](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent) with your self-managed GitHub Enterprise server. In this guide, you'll learn how to set up the Agent to receive automated code reviews that trigger whenever you create a pull request, as well as how to manually initiate reviews using [available commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Video tutorial

coming soon...

## Prerequisites

Before proceeding, ensure you've completed all necessary prerequisites.

#### 1. Create a GitHub Personal Access Token (classic):

For GitHub pull request code reviews, ensure you have a **CLASSIC** personal access token with **`repo`** scope. We do not support fine-grained tokens currently.

[**View Guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBZH0vDwrPqYQPMIxIyNW%2Fimage.png?alt=media&amp;token=a4c42d8d-61a5-4cdb-87a1-622c0ba8f1ae" alt=""><figcaption><p><strong>GitHub Personal Access Token (classic)</strong></p></figcaption></figure>

#### 2. Authorizing a GitHub Personal Access Token for use with SAML single sign-on:

If your GitHub organization enforces [SAML Single Sign-On (SSO)](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization), you must authorize your Personal Access Token (classic) through your Identity Provider (IdP); otherwise, Bito's AI Code Review Agent won't function properly.

For detailed instructions, please refer to the [GitHub documentation](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).

## Installation and configuration steps

Follow the step-by-step instructions below to install the **AI Code Review Agent** using **Bito Cloud**:

### **Step 1: Log in to Bito**

[Log in to Bito Cloud](https://alpha.bito.ai/) and select a workspace to get started.

### **Step 2: Open the Code Review Agents setup**

Click [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) under the **CODE REVIEW** section in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7jB4NvihTZqLpAX1nuaf%2Fscrnli_KuCSLAb2uwZqov.png?alt=media&amp;token=8c7fdbb7-2358-40ed-9a5f-db23cb11be40" alt=""><figcaption></figcaption></figure>

### **Step 3: Select your Git provider**&#x20;

Bito supports integration with the following Git providers:&#x20;

* GitHub&#x20;
* GitHub (Self-Managed)&#x20;
* GitLab&#x20;
* GitLab (Self-Managed)&#x20;
* Bitbucket
* Bitbucket (Self-Managed)

Since we are setting up the Agent for self-managed GitHub Enterprise server, select **GitHub (Self-Managed)** to proceed.

{% hint style="info" %}
**Supported versions:**

* **GitHub Enterprise Server:** 3.0 and above
  {% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FhJOg0OlVYrzpFw1KP3yw%2Fscrnli_Jk7BcFXL0xXyja.png?alt=media&amp;token=3bfd22c4-99bc-494c-a426-c6ae7215d466" alt="" width="563"><figcaption></figcaption></figure>

### **Step 4: Register & install the Bito App for GitHub**&#x20;

To enable pull request reviews, you need to register and install the **Bito’s AI Code Review Agent** app on your self-managed GitHub Enterprise server.

{% hint style="info" %}
If your network blocks external services from interacting with the GitHub server, whitelist all of Bito's gateway IP addresses in your firewall to ensure Bito can access your self-hosted repositories. The Agent response can come from any of these IPs.&#x20;

* **List of IP addresses to whitelist:**&#x20;
  * **`18.188.201.104`**
  * **`3.23.173.30`**
  * **`18.216.64.170`**&#x20;
    {% endhint %}

You need to enter the details for the below mentioned input fields:&#x20;

* **Hosted GitHub URL:** This is the domain portion of the URL where you GitHub Enterprise Server is hosted (e.g., `https://yourcompany.github.com`). Please check with your GitHub administrator for the correct URL.&#x20;
* **Personal Access Token:** Generate a **Personal Access Token (classic)** with **“repo”** scope in your GitHub (Self-Managed) account and enter it into the **Personal Access Token** input field. We do not support fine-grained tokens currently. For guidance, refer to the instructions in the [Prerequisites](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-github-self-managed#prerequisites) section.&#x20;

Click **Validate** to ensure the login credentials are working correctly. If the credentials are successfully validated, click the **Install Bito App for GitHub** button. This will redirect you to your GitHub (Self-Managed) server.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FeiSAyQzwhsWkr9bPZrce%2Fscrnli_rCj22uk5HFb2t2_1.png?alt=media&amp;token=d17d9f8e-c8a3-472e-a13f-8fa4b13e8109" alt=""><figcaption></figcaption></figure>

Before proceeding, you’ll be asked to **enter your GitHub App name** — this is the name that will appear in your GitHub Apps list and during installations. Choose a clear, recognizable name (for example, “Bito Code Reviewer”).

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FXWiiC7FFRU0ZXKy9TZcL%2Fscrnli_98w41S7XJ9u6zO.png?alt=media&amp;token=20db7387-9ddd-4529-bdf8-6c20c358f9fa" alt=""><figcaption></figcaption></figure>

Now select where you want to install the app: &#x20;

* Choose **All repositories** to enable Bito for every repository in your account.&#x20;
* Or, select **Only select repositories** and pick specific repositories using the dropdown menu.&#x20;

{% hint style="info" %}
Bito app uses these permissions:&#x20;

* **Read** access to metadata&#x20;
* **Read** and **write** access to code, issues, and pull requests&#x20;
* **Read** access to organization members
  {% endhint %}

Click **Install & Authorize** to proceed. Once completed, you will be redirected to Bito.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FpkNPb32ypSep8KvCjxhE%2Fscrnli_53aedt4Zg9v0Rm.png?alt=media&amp;token=210bfd9b-ea7a-449d-8e07-1f080c0ddd82" alt=""><figcaption></figcaption></figure>

### **Step 5: Enable AI Code Review Agent on repositories**&#x20;

After connecting Bito to your self-managed GitHub Enterprise server, you'll see a list of repositories that Bito has access to.

Use the toggles in the **Code Review Status** column to **enable** or **disable** the Agent for each repository.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F8ou5QfEk0k1I9iskh94k%2Fscrnli_zBhAS7sgD29mGl_1.png?alt=media&amp;token=0a4afced-697e-4926-a0a9-659a9b4fc3ab" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To customize the Agent’s behavior, you can edit existing configurations or create new Agents as needed.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endhint %}

### **Step 6: Automated and manual pull request reviews**&#x20;

Once a repository is enabled, you can invoke the AI Code Review Agent in the following ways:

1. **Automated code review:** By default, the Agent automatically reviews all new pull requests and provides detailed feedback.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the pull request and submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and submit it to re-review the entire pull request from scratch, rather than only the latest changes.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed. To always re-review all changes, use `/review full`.
{% endhint %}

The AI-generated code review feedback will be posted as comments directly within your pull request, making it seamless to view and address suggestions right where they matter most.&#x20;

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FryhzTFegsxvL4eoZewT7%2Fscrnli_2_28_2024_8-57-29%20PM.png?alt=media&amp;token=af92cdfb-089b-4f95-8200-52adebe366dd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** To enhance efficiency, the automated code reviews are only triggered for pull requests merging into the repository’s default branch. This prevents unnecessary processing and Advanced AI requests usage.

To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review pull requests when the source or target branch matches the list.

The **Include Source/Target Branches** filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
{% endhint %}

{% hint style="info" %}
The AI Code Review Agent automatically reviews code changes up to 5000 lines when a pull request is created. For larger changes, you can use the **`/review full`** command.
{% endhint %}

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull request.
{% endhint %}

### **Step 7: Specialized commands for code reviews**

Bito also offers **specialized commands** that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.&#x20;

* **`/review security`**: Analyzes code to identify security vulnerabilities and ensure secure coding practices.&#x20;
* **`/review performance`**: Evaluates code for performance issues, identifying slow or resource-heavy areas.&#x20;
* **`/review scalability`**: Assesses the code's ability to handle increased usage and scale effectively.&#x20;
* **`/review codeorg`**: Scans for readability and maintainability, promoting clear and efficient code organization.&#x20;
* **`/review codeoptimize`**: Identifies optimization opportunities to enhance code efficiency and reduce resource usage.&#x20;

By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**&#x20;

For more details, refer to [Available Commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

### **Step 8: Chat with AI Code Review Agent**

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

To start the conversation, type your question in the comment box within the inline suggestions on your pull request, and then submit it. Typically, Bito AI responses are delivered in about 10 seconds. On GitHub and Bitbucket, you need to manually refresh the page to see the responses, while GitLab updates automatically.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FivCegqSzdY80hPdZIMGN%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=528ddcda-100d-49a8-b6b5-2b9767a23785" alt="" width="563"><figcaption></figcaption></figure>

### Step 9: Configure Agent settings

[Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) let you control how reviews are performed, ensuring feedback is tailored to your team’s needs. By adjusting the options, you can:

* Make reviews more focused and actionable.
* Apply your own coding standards.
* Reduce noise by excluding irrelevant files or branches.
* Add extra checks to improve code quality and security.

[**Learn more**](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated pull request (PR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fk5wsTj4siolCcaZqHRIX%2Fscrnli_9_13_2024_12-33-56%20PM.png?alt=media&amp;token=63cb7da9-21ca-41a1-83ba-9b107d07a6cf" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a pull request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the pull request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FP0sUIAZ3Lq0FqL9ytfPF%2Fscrnli_9_13_2024_12-49-29%20PM_cropped_3.png?alt=media&amp;token=d74d3b27-4831-4735-9559-6f9da191e910" alt=""><figcaption></figcaption></figure>


# Guide for GitLab

Integrate the AI Code Review Agent into your GitLab workflow.

Speed up code reviews by configuring the [AI Code Review Agent](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent) with your GitLab repositories. In this guide, you'll learn how to set up the Agent to receive automated code reviews that trigger whenever you create a pull request, as well as how to manually initiate reviews using [available commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Video tutorial

{% embed url="<https://youtu.be/wG09qSWFkzQ>" %}

## Prerequisites

Before proceeding, ensure you've completed all necessary prerequisites.

#### 1. Create a GitLab Personal Access Token:

For GitLab merge request code reviews, a token with **`api`** scope is required. Make sure that the token is created by a GitLab user who has the **`Maintainer`** access role.

[**View Guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)

{% hint style="info" %}
**Important:** Bito posts comments using the GitLab user account linked to the Personal Access Token used during setup. To display "Bito" instead of your name, create a separate user account (e.g., Bito Agent) and use its token for integration.
{% endhint %}

{% hint style="info" %}
We recommend setting the **token expiration** to at least one year. This prevents the token from expiring early and avoids disruptions in the AI Code Review Agent's functionality.&#x20;

Additionally, we highly recommend updating the token before expiry to maintain seamless integration and code review processes.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FghbsjA3aafRQJBQGnksv%2Fimage%20(1).png?alt=media&amp;token=6feb55f7-39b3-4d61-8e46-f6b233e64849" alt=""><figcaption><p><strong>GitLab Personal Access Token</strong></p></figcaption></figure>

#### 2. Authorizing a GitLab Personal Access Token for use with SAML single sign-on:

If your GitLab organization enforces SAML Single Sign-On (SSO), you must authorize your Personal Access Token through your Identity Provider (IdP); otherwise, Bito's AI Code Review Agent won't function properly.

For more information, please refer to these GitLab documentation:

* <https://docs.gitlab.com/ee/user/group/saml_sso/>
* <https://docs.gitlab.com/ee/integration/saml.html>
* <https://docs.gitlab.com/ee/integration/saml.html#password-generation-for-users-created-through-saml>

## Installation and configuration steps

Follow the step-by-step instructions below to install the **AI Code Review Agent** using **Bito Cloud**:

### **Step 1: Log in to Bito**

[Log in to Bito Cloud](https://alpha.bito.ai/) and select a workspace to get started.

### **Step 2: Open the Code Review Agents setup**

Click [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) under the **CODE REVIEW** section in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7jB4NvihTZqLpAX1nuaf%2Fscrnli_KuCSLAb2uwZqov.png?alt=media&amp;token=8c7fdbb7-2358-40ed-9a5f-db23cb11be40" alt=""><figcaption></figcaption></figure>

### **Step 3: Select your Git provider**

Bito supports integration with the following Git providers:&#x20;

* GitHub&#x20;
* GitHub (Self-Managed)&#x20;
* GitLab&#x20;
* GitLab (Self-Managed)&#x20;
* Bitbucket
* Bitbucket (Self-Managed)

Since we are setting up the Agent for GitLab, select **GitLab** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FETj8JmXkQeBAQ5zufjHv%2Fscrnli_7Ci4O6tHHXY58F.png?alt=media&amp;token=329d6d37-630a-409a-9f2d-b4226d8f8290" alt="" width="563"><figcaption></figcaption></figure>

### **Step 4: Connect Bito to GitLab**

To enable merge request reviews, you’ll need to connect your Bito workspace to your GitLab account.

You can either connect using **OAuth (recommended)** for a seamless, one-click setup or manually enter your **Personal Access Token**.

To connect via OAuth, simply click the **Connect with OAuth (Recommended)** button. This will redirect you to the GitLab website, where you'll need to log in. Once authenticated, you'll be redirected back to Bito, confirming a successful connection.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FrCeLccv5wvxww06Lpqtw%2Fscrnli_5jI39Zex0s92SO.png?alt=media&amp;token=df661bf6-2cdc-4d01-8225-01e4d6bd0f6a" alt=""><figcaption></figcaption></figure>

If you prefer not to use OAuth, you can connect manually using a **Personal Access Token**.

Start by [generating a Personal Access Token](https://gitlab.com/-/user_settings/personal_access_tokens) with **`api`** scope in your GitLab account. For guidance, refer to the instructions in the [Prerequisites](#prerequisites) section.

Once generated, click the **Alternatively, use Personal or Group Access Token** button.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FX6IlUtc5Y6XaJoOB9dxv%2Fscrnli_sH76XQeLbsU3aw.png?alt=media&amp;token=60bdc89d-7345-46b6-ba52-ab34e642b70c" alt=""><figcaption></figcaption></figure>

Now, enter the token into the **Personal Access Token** input field in Bito.

Click **Validate** to ensure the token is functioning properly.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fe2YSKEAzCLXKoy8nhTJE%2Fscrnli_ykor6MMedHkkFM.png?alt=media&amp;token=a226253e-dc53-4684-8c3d-0a875d93d158" alt=""><figcaption></figcaption></figure>

If you've successfully connected via OAuth or manually validated your token, you can select your **GitLab Group** from the dropdown menu.

Click **Connect Bito to GitLab** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FzxcJdx9oRmZZzLNJTJo8%2Fscrnli_mC61ET3jriAsRg.png?alt=media&amp;token=a6474328-07a5-470a-aeee-f713dd03b145" alt=""><figcaption></figcaption></figure>

&#x20;

### **Step 5: Enable AI Code Review Agent on repositories**&#x20;

After connecting Bito to your GitLab account, you'll see a list of repositories that Bito has access to.

Use the toggles in the **Code Review Status** column to **enable** or **disable** the Agent for each repository.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F0TyvAqlOA5QYyh4Kv6JD%2Fscrnli_RtCVLzUlR23QJr_1.png?alt=media&amp;token=c156d679-7e13-4700-a9ef-4693836d23e8" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To customize the Agent’s behavior, you can edit existing configurations or create new Agents as needed.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endhint %}

### **Step 6: Automated and manual merge request reviews**&#x20;

Once a repository is enabled, you can invoke the AI Code Review Agent in the following ways:

1. **Automated code review:** By default, the Agent automatically reviews all new merge requests and provides detailed feedback.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the merge request and submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and submit it to re-review the entire merge request from scratch, rather than only the latest changes.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed. To always re-review all changes, use `/review full`.
{% endhint %}

The AI-generated code review feedback will be posted as comments directly within your merge request, making it seamless to view and address suggestions right where they matter most.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBBOvTOprCCheQBy3MaQ1%2Fscrnli_9_18_2024_8-51-21%20AM.png?alt=media&amp;token=633cd07e-24c6-4eec-b285-d83754d798cf" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** To enhance efficiency, the automated code reviews are only triggered for merge requests merging into the repository’s default branch. This prevents unnecessary processing and Advanced AI requests usage.

To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review merge requests when the source or target branch matches the list.

The **Include Source/Target Branches** filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
{% endhint %}

{% hint style="info" %}
The AI Code Review Agent automatically reviews code changes up to 5000 lines when a merge request is created. For larger changes, you can use the **`/review full`** command.
{% endhint %}

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the merge request.
{% endhint %}

### **Step 7: Specialized commands for code reviews**

Bito also offers **specialized commands** that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.&#x20;

* **`/review security`**: Analyzes code to identify security vulnerabilities and ensure secure coding practices.&#x20;
* **`/review performance`**: Evaluates code for performance issues, identifying slow or resource-heavy areas.&#x20;
* **`/review scalability`**: Assesses the code's ability to handle increased usage and scale effectively.&#x20;
* **`/review codeorg`**: Scans for readability and maintainability, promoting clear and efficient code organization.&#x20;
* **`/review codeoptimize`**: Identifies optimization opportunities to enhance code efficiency and reduce resource usage.&#x20;

By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**&#x20;

For more details, refer to [Available Commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

### **Step 8: Chat with AI Code Review Agent**

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

To start the conversation, type your question in the comment box within the inline suggestions on your merge request, and then submit it. Typically, Bito AI responses are delivered in about 10 seconds. On GitHub and Bitbucket, you need to manually refresh the page to see the responses, while GitLab updates automatically.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FivCegqSzdY80hPdZIMGN%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=528ddcda-100d-49a8-b6b5-2b9767a23785" alt="" width="563"><figcaption></figcaption></figure>

### Step 9: Configure Agent settings

[Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) let you control how reviews are performed, ensuring feedback is tailored to your team’s needs. By adjusting the options, you can:

* Make reviews more focused and actionable.
* Apply your own coding standards.
* Reduce noise by excluding irrelevant files or branches.
* Add extra checks to improve code quality and security.

[**Learn more**](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated merge request (MR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZ08V4Js5ORq7j6n0qR5S%2Fscrnli_9_18_2024_8-20-30%20AM.png?alt=media&amp;token=80e6b92c-95e2-4d1b-939c-1f976136bac2" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a merge request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the merge request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FRGVVrPpKePySgQWiOrd6%2Fscrnli_9_18_2024_8-38-48%20AM_cropped.png?alt=media&amp;token=20b082f1-dd87-437c-b1dc-268c9564a27a" alt=""><figcaption></figcaption></figure>


# Guide for GitLab (Self-Managed)

Integrate the AI Code Review Agent into your self-hosted GitLab workflow.

Speed up code reviews by configuring the [AI Code Review Agent](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent) with your GitLab (Self-Managed) server. In this guide, you'll learn how to set up the Agent to receive automated code reviews that trigger whenever you create a merge request, as well as how to manually initiate reviews using [available commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Video tutorial

coming soon...

## Prerequisites

Before proceeding, ensure you've completed all necessary prerequisites.

#### 1. Create a GitLab Personal Access Token:

For GitLab merge request code reviews, a token with **`api`** scope is required. Make sure that the token is created by a GitLab user who has the **`Maintainer`** access role.

[**View Guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)

{% hint style="info" %}
**Important:** Bito posts comments using the GitLab user account linked to the Personal Access Token used during setup. To display "Bito" instead of your name, create a separate user account (e.g., Bito Agent) and use its token for integration.
{% endhint %}

{% hint style="info" %}
We recommend setting the **token expiration** to at least one year. This prevents the token from expiring early and avoids disruptions in the AI Code Review Agent's functionality.&#x20;

Additionally, we highly recommend updating the token before expiry to maintain seamless integration and code review processes.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FghbsjA3aafRQJBQGnksv%2Fimage%20(1).png?alt=media&amp;token=6feb55f7-39b3-4d61-8e46-f6b233e64849" alt=""><figcaption><p><strong>GitLab Personal Access Token</strong></p></figcaption></figure>

#### 2. Authorizing a GitLab Personal Access Token for use with SAML single sign-on:

If your GitLab organization enforces SAML Single Sign-On (SSO), you must authorize your Personal Access Token through your Identity Provider (IdP); otherwise, Bito's AI Code Review Agent won't function properly.

For more information, please refer to the following GitLab documentation:

* [SAML SSO for GitLab.com groups](https://docs.gitlab.com/user/group/saml_sso/)
* [SAML SSO for GitLab Self-Managed](https://docs.gitlab.com/integration/saml/)
* [Password generation for users created through SAML](https://docs.gitlab.com/integration/saml/#password-generation-for-users-created-through-saml)

## Installation and configuration steps

Follow the step-by-step instructions below to install the **AI Code Review Agent** using **Bito Cloud**:

### **Step 1: Log in to Bito**

[Log in to Bito Cloud](https://alpha.bito.ai/) and select a workspace to get started.

### **Step 2: Open the Code Review Agents setup**

Click [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) under the **CODE REVIEW** section in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7jB4NvihTZqLpAX1nuaf%2Fscrnli_KuCSLAb2uwZqov.png?alt=media&amp;token=8c7fdbb7-2358-40ed-9a5f-db23cb11be40" alt=""><figcaption></figcaption></figure>

### **Step 3: Select your Git provider**&#x20;

Bito supports integration with the following Git providers:&#x20;

* GitHub&#x20;
* GitHub (Self-Managed)&#x20;
* GitLab&#x20;
* GitLab (Self-Managed)&#x20;
* Bitbucket
* Bitbucket (Self-Managed)

Since we are setting up the Agent for GitLab (Self-Managed) server, select **GitLab (Self-Managed)** to proceed.

{% hint style="info" %}
**Supported versions:**

* **GitLab (Self-Managed):** 15.5 and above
  {% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FtgUKG7gdgn9GJgSAASFy%2Fscrnli_QBt6t8kukXYaYE.png?alt=media&amp;token=b312f994-faf6-49cd-a930-3ee640293f46" alt="" width="563"><figcaption></figcaption></figure>

### **Step 4: Connect Bito to GitLab** &#x20;

To enable merge request reviews, you’ll need to connect your Bito workspace to your GitLab (Self-Managed) server.

{% hint style="info" %}
If your network blocks external services from interacting with the GitLab server, whitelist all of Bito's gateway IP addresses in your firewall to ensure Bito can access your self-hosted repositories. The Agent response can come from any of these IPs.&#x20;

* **List of IP addresses to whitelist:**&#x20;
  * **`18.188.201.104`**
  * **`3.23.173.30`**
  * **`18.216.64.170`**
    {% endhint %}

You need to enter the details for the below mentioned input fields:&#x20;

* **Hosted GitLab URL:** This is the domain portion of the URL where you GitLab Enterprise Server is hosted (e.g., `https://yourcompany.gitlab.com`). Please check with your GitLab administrator for the correct URL.&#x20;
* **Personal Access Token:** Generate a **GitLab Personal Access Token** with **`api`** scope in your GitLab (Self-Managed) account and enter it into the **Personal Access Token** input field. For guidance, refer to the instructions in the [Prerequisites](/ai-code-reviews-in-git/install-run-using-bito-cloud/guide-for-gitlab-self-managed#prerequisites) section.

Click **Validate** to ensure the token is functioning properly.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fomu0dVL9I0CTQ8yC7MHO%2Fscrnli_27slie02tJkRAf_1.png?alt=media&amp;token=e2689d19-c041-48aa-90ed-6b678c224dc4" alt=""><figcaption></figcaption></figure>

If the token is successfully validated, you can select your **GitLab Group** from the dropdown menu.

* **Note:** You can select multiple groups after the setup is complete.

Click **Connect Bito to GitLab** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FU4h3BLObcIsIEN0lU95i%2Fscrnli_1L3maXu3pJtiCd.png?alt=media&amp;token=32be430f-2b99-428b-9f47-c47067966e60" alt=""><figcaption></figcaption></figure>

### **Step 5: Enable AI Code Review Agent on repositories**&#x20;

After connecting Bito to your GitLab self-managed server, you'll see a list of repositories that Bito has access to.

Use the toggles in the **Code Review Status** column to **enable** or **disable** the Agent for each repository.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FeXTvPIXX2uSyhuWGCLNI%2Fscrnli_BYisAy83ZXjb8j_1.png?alt=media&amp;token=1b4968fe-9740-498f-aebc-7e854cdf0ccf" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To customize the Agent’s behavior, you can edit existing configurations or create new Agents as needed.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endhint %}

### **Step 6: Automated and manual merge request reviews**&#x20;

Once a repository is enabled, you can invoke the AI Code Review Agent in the following ways:

1. **Automated code review:** By default, the Agent automatically reviews all new merge requests and provides detailed feedback.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the merge request and submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and submit it to re-review the entire merge request from scratch, rather than only the latest changes.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed. To always re-review all changes, use `/review full`.
{% endhint %}

The AI-generated code review feedback will be posted as comments directly within your merge request, making it seamless to view and address suggestions right where they matter most.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBBOvTOprCCheQBy3MaQ1%2Fscrnli_9_18_2024_8-51-21%20AM.png?alt=media&amp;token=633cd07e-24c6-4eec-b285-d83754d798cf" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** To enhance efficiency, the automated code reviews are only triggered for merge requests merging into the repository’s default branch. This prevents unnecessary processing and Advanced AI requests usage.

To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review merge requests when the source or target branch matches the list.

The **Include Source/Target Branches** filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
{% endhint %}

{% hint style="info" %}
The AI Code Review Agent automatically reviews code changes up to 5000 lines when a merge request is created. For larger changes, you can use the **`/review full`** command.
{% endhint %}

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the merge request.
{% endhint %}

### **Step 7: Specialized commands for code reviews**

Bito also offers **specialized commands** that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.&#x20;

* **`/review security`**: Analyzes code to identify security vulnerabilities and ensure secure coding practices.&#x20;
* **`/review performance`**: Evaluates code for performance issues, identifying slow or resource-heavy areas.&#x20;
* **`/review scalability`**: Assesses the code's ability to handle increased usage and scale effectively.&#x20;
* **`/review codeorg`**: Scans for readability and maintainability, promoting clear and efficient code organization.&#x20;
* **`/review codeoptimize`**: Identifies optimization opportunities to enhance code efficiency and reduce resource usage.&#x20;

By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**&#x20;

For more details, refer to [Available Commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

### **Step 8: Chat with AI Code Review Agent**

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

To start the conversation, type your question in the comment box within the inline suggestions on your merge request, and then submit it. Typically, Bito AI responses are delivered in about 10 seconds. On GitHub and Bitbucket, you need to manually refresh the page to see the responses, while GitLab updates automatically.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FivCegqSzdY80hPdZIMGN%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=528ddcda-100d-49a8-b6b5-2b9767a23785" alt="" width="563"><figcaption></figcaption></figure>

### Step 9: Configure Agent settings

[Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) let you control how reviews are performed, ensuring feedback is tailored to your team’s needs. By adjusting the options, you can:

* Make reviews more focused and actionable.
* Apply your own coding standards.
* Reduce noise by excluding irrelevant files or branches.
* Add extra checks to improve code quality and security.

[**Learn more**](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)

## Managing multiple GitLab groups in Bito Cloud

[Bito Cloud](https://alpha.bito.ai/) allows you to connect and manage multiple GitLab groups for **GitLab (Self-Managed)** integrations. Use the instructions below to add or remove GitLab groups for AI code reviews.

### How to add multiple GitLab groups?

You can connect more than one GitLab group to Bito for AI code reviews.

Follow these steps to add additional groups:

1. Go to the [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F4CZ7NBraXiiD6Iqq7j5a%2Fscrnli_Y8WOHXWq804QA4.png?alt=media&amp;token=bb9bd6b7-f997-4e59-8cac-344ed3bbc532" alt=""><figcaption></figcaption></figure>

2. At the top-center of the page, click the **“+” (plus) icon** next to the currently selected GitLab group name, then select **Add group** from the dropdown menu.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FMslGYbmuoV1rRShmx5Jl%2Fscrnli_W8jQLW06Gxuqt0_1.png?alt=media&amp;token=f7f30d4e-aae6-46f5-92c9-1e5cb065287c" alt=""><figcaption></figcaption></figure>

3. A popup will appear. Use the **dropdown menu** to select a GitLab group you want to add.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FbLf4ueoWPOLRQ3CxwrWI%2Fscrnli_8ZF0yXi7X0hXsw_1.png?alt=media&amp;token=91597a4e-b462-4400-8a14-65df4307c75c" alt=""><figcaption></figcaption></figure>

4. Click the **Add group** button.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F0WHxXbmnKKK9RmWfr5pF%2Fscrnli_cz6US78Ei0o7Xj_1.png?alt=media&amp;token=322cf8e0-0e92-43a0-9d6b-f8486e560f86" alt=""><figcaption></figcaption></figure>

Once added, all repositories from that group will be listed and available for AI code reviews under the default agent.

{% hint style="info" %}
**Note:** This **multiple GitLab groups** feature is currently available **only for GitLab (Self-Managed)** integrations.
{% endhint %}

### How to remove a GitLab group?

To disconnect a GitLab group from Bito Cloud:

1. Go to the [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FR7Z8pmGAEEi2saOB0MPM%2Fscrnli_Y8WOHXWq804QA4.png?alt=media&amp;token=f6dbf22d-bfb4-498c-8a87-91508990d724" alt=""><figcaption></figcaption></figure>

2. At the top-center of the page, click the **three dots icon** next to the currently selected GitLab group name, then select **Manage groups** from the dropdown menu.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FdULLEBhV1cLCGuKDWgKm%2Fscrnli_EPno749Af0t5m9_1.png?alt=media&amp;token=cf282900-50a1-489e-8a03-d19970dcb48e" alt=""><figcaption></figcaption></figure>

3. A popup will appear showing a list of connected groups. Click the **“✕” (cross) icon** next to the group you want to remove.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7RcLErjIG7OHFhhhQUkk%2Fscrnli_ObMG7t14A0Z347_1.png?alt=media&amp;token=3a242425-7690-46fb-bac0-7a7e448779b5" alt=""><figcaption></figcaption></figure>

3. Confirm the removal in the prompt.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FOwjpuYuS6IufShaNMcgZ%2Fscrnli_gARi37sN912InC_1.png?alt=media&amp;token=65fdba44-9333-4607-9b01-cddfe458c2ad" alt=""><figcaption></figcaption></figure>

Once removed, the repositories from that group will no longer appear in Bito or be included in AI code reviews.

### How to select one or more GitLab Groups?

When you have **multiple GitLab groups connected** in Bito Cloud, the group name at the top-center of the [Repositories](https://alpha.bito.ai/home/ai-agents/code-review-agent) page becomes a **dropdown menu**.

From this dropdown, you can:

* Select **a single group**
* Select **multiple groups as needed**
* Select **All groups**

The list of repositories displayed below will update automatically based on your selection—showing only the repositories from the selected groups.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FA2eUv2Rf6isNoIbtEovO%2F1_scrnli_XOow3dK4CvFTuP.png?alt=media&amp;token=a9cfb7fd-fde1-42f6-b93c-8fc594a3cbc9" alt=""><figcaption></figcaption></figure>

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated merge request (MR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZ08V4Js5ORq7j6n0qR5S%2Fscrnli_9_18_2024_8-20-30%20AM.png?alt=media&amp;token=80e6b92c-95e2-4d1b-939c-1f976136bac2" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a merge request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the merge request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FRGVVrPpKePySgQWiOrd6%2Fscrnli_9_18_2024_8-38-48%20AM_cropped.png?alt=media&amp;token=20b082f1-dd87-437c-b1dc-268c9564a27a" alt=""><figcaption></figcaption></figure>


# Guide for Bitbucket

Integrate the AI Code Review Agent into your Bitbucket workflow.

Speed up code reviews by configuring the [AI Code Review Agent](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent) with your Bitbucket repositories. In this guide, you'll learn how to set up the Agent to receive automated code reviews that trigger whenever you create a pull request, as well as how to manually initiate reviews using [available commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Video tutorial

{% embed url="<https://youtu.be/s4iKC4QRAqE>" %}

## Installation and configuration steps

Follow the step-by-step instructions below to install the **AI Code Review Agent** using **Bito Cloud**:

### **Step 1: Log in to Bito**

[Log in to Bito Cloud](https://alpha.bito.ai/) and select a workspace to get started.

### **Step 2: Open the Code Review Agents setup**

Click [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) under the **CODE REVIEW** section in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F7jB4NvihTZqLpAX1nuaf%2Fscrnli_KuCSLAb2uwZqov.png?alt=media&amp;token=8c7fdbb7-2358-40ed-9a5f-db23cb11be40" alt=""><figcaption></figcaption></figure>

### **Step 3: Select your Git provider**

Bito supports integration with the following Git providers:&#x20;

* GitHub&#x20;
* GitHub (Self-Managed)&#x20;
* GitLab&#x20;
* GitLab (Self-Managed)&#x20;
* Bitbucket
* Bitbucket (Self-Managed)

Since we are setting up the Agent for Bitbucket, select **Bitbucket** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Ff6khlPh27gsqOuxtn1DX%2Fscrnli_8CcC8oU24XyHAx.png?alt=media&amp;token=4172d5ad-bdc6-48bc-983e-c147b6e35d0f" alt="" width="563"><figcaption></figcaption></figure>

### **Step 4: Connect Bito to Bitbucket**

To enable pull request reviews, you’ll need to connect your Bito workspace to your Bitbucket account.

{% hint style="info" %}
If your [Bitbucket access control settings](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/) block external services from interacting with the Bitbucket server, whitelist all of Bito's gateway IP addresses to ensure Bito can access your repositories. The Agent response can come from any of these IPs.

* **List of IP addresses to whitelist:**
  * **`18.188.201.104`**
  * **`3.23.173.30`**
  * **`18.216.64.170`**

See the [Bitbucket documentation](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/) for more information.
{% endhint %}

Click **Install Bito App for Bitbucket**. This will redirect you to Bitbucket.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FMkEhUlMUfiK26rbEV9lS%2Fscrnli_jBYatEquCn4pVe.png?alt=media&amp;token=9e3b91d5-1858-4e85-8405-2f1623aaf5a4" alt=""><figcaption></figcaption></figure>

Now, authorize the Bito App to access your Bitbucket repositories.

Select your Bitbucket workspace from the **Authorize for workspace** dropdown menu and then click **Grant access**. Once completed, you will be redirected to Bito.

{% hint style="info" %}
**Note:** You'll only see Bitbucket workspaces where you have **Admin** access. If no workspaces appear in the dropdown, it means your account doesn’t have admin access to any workspace. To connect a workspace, make sure you have admin access for it.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fv0VauXquH5Q6mJg7vTYZ%2Ftinywow_scrnli_24x3kCekLNju4h_84371899.png?alt=media&amp;token=97b84b58-d5b6-42a7-8e02-571626b5e0bc" alt=""><figcaption></figcaption></figure>

### **Step 5: Enable AI Code Review Agent on repositories**

After connecting Bito to your Bitbucket account, you'll see a list of repositories that Bito has access to.

Use the toggles in the **Code Review Status** column to **enable** or **disable** the Agent for each repository.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBopXIGtuWOCxzt8W6gDv%2Fscrnli_Nf0yfPc0l2qOe9_1.png?alt=media&amp;token=0784b195-5887-4d30-81b6-76a62831c8e5" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To customize the Agent’s behavior, you can edit existing configurations or create new Agents as needed.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endhint %}

### **Step 6: Automated and manual pull request reviews**&#x20;

Once a repository is enabled, you can invoke the AI Code Review Agent in the following ways:

1. **Automated code review:** By default, the Agent automatically reviews all new pull requests and provides detailed feedback.
2. **Manually trigger code review:** To initiate a manual review, simply type **`/review`** in the comment box on the pull request and click **Add comment now** to submit it. This action will start the code review process.
3. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the pull request and click **Add comment now** to submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
4. **Manually trigger a full review:** Type **`/review full`** in the comment box and click **Add comment now** to submit it to re-review the entire pull request from scratch, rather than only the latest changes.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed. To always re-review all changes, use `/review full`.
{% endhint %}

{% hint style="info" %}
**Note:** After typing **`/review`**, add a space inside the comment box to ensure that **`/review`** is not highlighted as a Bitbucket slash command so that the comment can be posted correctly.
{% endhint %}

The AI-generated code review feedback will be posted as comments directly within your pull request, making it seamless to view and address suggestions right where they matter most.&#x20;

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FfXuf3LO3sIqG6dPwz4fk%2Fscrnli_9_18_2024_8-01-14%20AM.png?alt=media&amp;token=7b067b12-0e48-4900-89fa-878db4ace071" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** To enhance efficiency, the automated code reviews are only triggered for pull requests merging into the repository’s default branch. This prevents unnecessary processing and Advanced AI requests usage.

To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review pull requests when the source or target branch matches the list.

The **Include Source/Target Branches** filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
{% endhint %}

{% hint style="info" %}
The AI Code Review Agent automatically reviews code changes up to 5000 lines when a pull request is created. For larger changes, you can use the **`/review full`** command.
{% endhint %}

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull request.
{% endhint %}

### **Step 7: Specialized commands for code reviews**

Bito also offers **specialized commands** that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.&#x20;

* **`/review security`**: Analyzes code to identify security vulnerabilities and ensure secure coding practices.&#x20;
* **`/review performance`**: Evaluates code for performance issues, identifying slow or resource-heavy areas.&#x20;
* **`/review scalability`**: Assesses the code's ability to handle increased usage and scale effectively.&#x20;
* **`/review codeorg`**: Scans for readability and maintainability, promoting clear and efficient code organization.&#x20;
* **`/review codeoptimize`**: Identifies optimization opportunities to enhance code efficiency and reduce resource usage.&#x20;

By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**&#x20;

For more details, refer to [Available Commands](https://docs.bito.ai/bito-dev-agents/ai-code-review-agent/available-commands).

### **Step 8: Chat with AI Code Review Agent**

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

To start the conversation, type your question in the comment box within the inline suggestions on your pull request, and then submit it. Typically, Bito AI responses are delivered in about 10 seconds. On GitHub and Bitbucket, you need to manually refresh the page to see the responses, while GitLab updates automatically.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FivCegqSzdY80hPdZIMGN%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=528ddcda-100d-49a8-b6b5-2b9767a23785" alt="" width="563"><figcaption></figcaption></figure>

### Step 9: Configure Agent settings

[Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) let you control how reviews are performed, ensuring feedback is tailored to your team’s needs. By adjusting the options, you can:

* Make reviews more focused and actionable.
* Apply your own coding standards.
* Reduce noise by excluding irrelevant files or branches.
* Add extra checks to improve code quality and security.

[**Learn more**](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated pull request (PR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FUBoXJAhcEjR9SPwNbVKz%2Fscrnli_9_18_2024_8-43-54%20AM.png?alt=media&amp;token=ed39dd98-bc00-4f32-9abb-27a6c0aedef7" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a pull request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the pull request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FJmIqJ9p3s7J67rWEMWRk%2Fscrnli_9_18_2024_8-44-53%20AM_b.png?alt=media&amp;token=66ca75ba-35d1-40c0-961a-d550b1132d9f" alt=""><figcaption></figcaption></figure>


# Guide for Bitbucket (Self-Managed)

Integrate the AI Code Review Agent into your self-hosted Bitbucket workflow.

Speed up code reviews by configuring the [AI Code Review Agent](/ai-code-reviews-in-git/overview) with your Bitbucket (Self-Managed) server. In this guide, you'll learn how to set up the Agent to receive automated code reviews that trigger whenever you create a pull request, as well as how to manually initiate reviews using [available commands](/ai-code-reviews-in-git/available-commands).

{% hint style="info" %}
The **Free Plan** offers **AI-generated pull request summaries** to provide a quick overview of changes. For advanced features like **line-level code suggestions**, consider upgrading to the **Team Plan**. For detailed pricing information, visit our [**Pricing**](https://bito.ai/pricing/) page.

[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

## Video tutorial <a href="#video-tutorial" id="video-tutorial"></a>

{% embed url="<https://youtu.be/ZAawiQ22PMc>" %}

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before proceeding, ensure you've completed all necessary prerequisites.

### **1. Create a Bitbucket Personal Access Token:**

For Bitbucket pull request code reviews, a token with **`Project Admin`**  permission is required. Make sure that the token is created by a Bitbucket user who has the **`Admin`**  privileges.

{% hint style="info" %}
**Important:** Bito posts comments using the Bitbucket user account linked to the Personal Access Token used during setup. To display "Bito" instead of your name, create a separate user account (e.g., Bito Agent) and use its token for integration.
{% endhint %}

You can use the **Create Token** button that appears once you provide the **Hosted Bitbucket URL** and your **Bitbucket username**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F5YvKDBUEIefxIpKB5GaV%2Fscrnli_g528adnNaTXmWg_1.png?alt=media&amp;token=cf2dced9-b5ae-4ea9-bd6b-6ce1e7d1ba92" alt="" width="563"><figcaption></figcaption></figure>

Or directly visit the URL of your self-hosted Bitbucket.

To create a token for your user account:

1. Go to **Profile picture** > **Manage account** > **HTTP access tokens**.
2. Select **Create token**.
3. Set the token name, permissions, and expiry.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FFgvm4olJ3yhyo0xOiWnf%2Fscrnli_Rr1m0ddO4rSyCR_1%20(2).png?alt=media&amp;token=07dadb9b-3494-480e-8c35-aeca49af780b" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FWaRUeDccyy6D63BTQPyZ%2Fscrnli_um1SDww4ZRtLsi_1%20(1).png?alt=media&amp;token=10217b14-4a6d-4795-a987-e8f05a7b1aa6" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FlPWS1DtbgwvmwitUYvqt%2Fscrnli_mR0r6q2h3RV3kJ_1%20(1).png?alt=media&amp;token=4ae08d23-8710-4a7d-babc-1064b3062aea" alt="" width="563"><figcaption></figcaption></figure>

<a href="https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html" class="button primary">View Bitbucket documentation</a>

### **2. Authorizing a Bitbucket Personal Access Token for use with SAML single sign-on:**

If your Bitbucket organization enforces SAML Single Sign-On (SSO), you must authorize your Personal Access Token through your Identity Provider (IdP); otherwise, Bito's AI Code Review Agent won't function properly.

For more information, please refer to [Bitbucket SAML SSO documentation](https://support.atlassian.com/bitbucket-data-center/kb/how-to-configure-saml-sso-for-bitbucket-data-center-with-okta/).

## Installation and configuration steps <a href="#installation-and-configuration-steps" id="installation-and-configuration-steps"></a>

Follow the step-by-step instructions below to install the **AI Code Review Agent** using **Bito Cloud**:

### **Step 1: Log in to Bito** <a href="#step-1-log-in-to-bito" id="step-1-log-in-to-bito"></a>

[Log in to Bito Cloud](https://alpha.bito.ai/) and select a workspace to get started.

### **Step 2: Open the Code Review Agents setup** <a href="#step-2-open-the-code-review-agents-setup" id="step-2-open-the-code-review-agents-setup"></a>

Click [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) under the **CODE REVIEW** section in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FaRd44Mm4ssRuJq0JPTDY%2Fscrnli_F8cTXu9Nhus5wi.png?alt=media&amp;token=1caf8b4c-1f2d-4fee-a4b2-68bfc7cc5925" alt=""><figcaption></figcaption></figure>

### **Step 3: Select your Git provider** <a href="#step-3-select-your-git-provider" id="step-3-select-your-git-provider"></a>

Bito supports integration with the following Git providers:

* GitHub
* GitHub (Self-Managed)
* GitLab
* GitLab (Self-Managed)
* Bitbucket
* Bitbucket (Self-Managed)

Since we are setting up the Agent for Bitbucket (Self-Managed) server, select **Bitbucket (Self-Managed)** to proceed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Frk0l6UdSGntsYtRlPDik%2Fscrnli_v4wqkwtzxUUXo8.png?alt=media&amp;token=15097f2d-9e3f-45d1-8602-8bda679b0ef0" alt="" width="563"><figcaption></figcaption></figure>

### **Step 4: Connect Bito to Bitbucket** <a href="#step-4-connect-bito-to-bitbucket" id="step-4-connect-bito-to-bitbucket"></a>

To enable pull request reviews, you’ll need to connect your Bito workspace to your Bitbucket (Self-Managed) server.

{% hint style="info" %}
If your network blocks external services from interacting with the Bitbucket server, whitelist all of Bito's gateway IP addresses in your firewall to ensure Bito can access your self-hosted repositories. The Agent response can come from any of these IPs.

* **List of IP addresses to whitelist:**
  * **`18.188.201.104`**
  * **`3.23.173.30`**
  * **`18.216.64.170`**
    {% endhint %}

You need to enter the details for the below mentioned input fields:

* **Hosted Bitbucket URL:** This is the domain portion of the URL where your Bitbucket Enterprise server is hosted (e.g., `https://bitbucket.mycompany.com`). Please check with your Bitbucket administrator for the correct URL.
* **Bitbucket username:** This is your Bitbucket username used for login. Please check it from your user profile page or ask your Admin.
* **Personal Access Token:** Generate a **Bitbucket Personal Access Token** with **`Project Admin`**  permission in your Bitbucket (Self-Managed) account. Ensure you have Bitbucket **Admin** privileges. Enter the token into the **Personal Access Token** input field. You can use the **Create Token** button that appears once you provide the **Hosted Bitbucket URL** and your **Bitbucket username**.

  For guidance, refer to the instructions in the [Prerequisites](#prerequisites) section.

{% hint style="info" %}
**Important:** Bito posts comments using the Bitbucket user account linked to the Personal Access Token used during setup. To display "Bito" instead of your name, create a separate user account (e.g., Bito Agent) and use its token for integration.
{% endhint %}

Click **Validate** to ensure the token is functioning properly.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FJfYP00SupO4zpbSiTm5F%2Fscrnli_UJQnm8OmlV2PmM_1.png?alt=media&amp;token=296c329a-1095-4455-8d5a-7dbdd917b086" alt="" width="563"><figcaption></figcaption></figure>

If the token is successfully validated, click **Connect Bito to Bitbucket** to proceed.

### **Step 5: Enable AI Code Review Agent on repositories** <a href="#step-5-enable-ai-code-review-agent-on-repositories" id="step-5-enable-ai-code-review-agent-on-repositories"></a>

After connecting Bito to your Bitbucket self-managed server, you'll see a list of repositories that Bito has access to.

Use the toggles in the **Code Review Status** column to **enable** or **disable** the Agent for each repository.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FU0qx8lO9O8t6dj1lhX1r%2Fscrnli_XExOnuPOb2H8eW_1.png?alt=media&amp;token=e6075bf3-fc4f-42ec-9ff6-396e2cd5894f" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To customize the Agent’s behavior, you can edit existing configurations or create new Agents as needed.

[Learn more](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)
{% endhint %}

### **Step 6: Automated and manual merge request reviews** <a href="#step-6-automated-and-manual-merge-request-reviews" id="step-6-automated-and-manual-merge-request-reviews"></a>

Once a repository is enabled, you can invoke the AI Code Review Agent in the following ways:

1. **Automated code review:** By default, the Agent automatically reviews all new pull requests and provides detailed feedback.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the pull request and click **Add comment now** to submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and click **Add comment now** to submit it to re-review the entire pull request from scratch, rather than only the latest changes.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed. To always re-review all changes, use `/review full`.
{% endhint %}

The AI-generated code review feedback will be posted as comments directly within your pull request, making it seamless to view and address suggestions right where they matter most.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FTscI7o7pNZZbOrlNQ4Ru%2Fimage%20(3).avif?alt=media&amp;token=807682ff-a2d6-47d6-bf99-8043691346f5" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** To enhance efficiency, the automated code reviews are only triggered for pull requests merging into the repository’s default branch. This prevents unnecessary processing and Advanced AI requests usage.

To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review pull requests when the source or target branch matches the list.

The **Include Source/Target Branches** filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
{% endhint %}

{% hint style="info" %}
The AI Code Review Agent automatically reviews code changes up to 5000 lines when a pull request is created. For larger changes, you can use the **`/review full`** command.
{% endhint %}

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull request.
{% endhint %}

### **Step 7: Specialized commands for code reviews** <a href="#step-7-specialized-commands-for-code-reviews" id="step-7-specialized-commands-for-code-reviews"></a>

Bito also offers **specialized commands** that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.

* **`/review security`**: Analyzes code to identify security vulnerabilities and ensure secure coding practices.
* **`/review performance`**: Evaluates code for performance issues, identifying slow or resource-heavy areas.
* **`/review scalability`**: Assesses the code's ability to handle increased usage and scale effectively.
* **`/review codeorg`**: Scans for readability and maintainability, promoting clear and efficient code organization.
* **`/review codeoptimize`**: Identifies optimization opportunities to enhance code efficiency and reduce resource usage.

By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**

For more details, refer to [Available Commands](/ai-code-reviews-in-git/available-commands).

### **Step 8: Chat with AI Code Review Agent** <a href="#step-8-chat-with-ai-code-review-agent" id="step-8-chat-with-ai-code-review-agent"></a>

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

To start the conversation, type your question in the comment box within the inline suggestions on your pull request, and then submit it. Typically, Bito AI responses are delivered in about 10 seconds. On GitHub and Bitbucket, you need to manually refresh the page to see the responses, while GitLab updates automatically.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

### Step 9: Configure Agent settings

[Agent settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) let you control how reviews are performed, ensuring feedback is tailored to your team’s needs. By adjusting the options, you can:

* Make reviews more focused and actionable.
* Apply your own coding standards.
* Reduce noise by excluding irrelevant files or branches.
* Add extra checks to improve code quality and security.

[**Learn more**](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance)


# Integrate the AI Code Review Agent into the CI/CD pipeline

Automate code reviews in your Continuous Integration/Continuous Deployment (CI/CD) pipeline—compatible with all CI/CD tools, including Jenkins, Argo CD, GitLab CI/CD, and more.

[**Bito Cloud**](https://alpha.bito.ai/) lets you integrate the [**AI Code Review Agent**](/ai-code-reviews-in-git/overview) into your CI/CD pipeline for automated code reviews. This document provides a step-by-step guide to help you configure and run the script successfully.

## Installation and Configuration Steps

1. [**Select the appropriate Git provider guide from this link**](/ai-code-reviews-in-git/install-run-using-bito-cloud#connect-bito-to-your-git-provider) based on your Git provider, and follow the step-by-step instructions to install the **AI Code Review Agent** using **Bito Cloud**. Be sure to review the prerequisites and the installation/configuration steps provided in the documentation.
2. [**Download the bito-action-script folder from GitHub**](https://github.com/gitbito/CodeReviewAgent/tree/main/bito-action-script), which includes a shell script (`bito-actions.sh`) and a configuration file (`bito_action.properties`).
3. You can integrate the AI Code Review Agent into your CI/CD pipeline in two ways, depending on your preference:

* **Option 1: Using the** `bito_action.properties` **File**
  * Configure the following properties in the `bito_action.properties` file located in the downloaded **bito-action-script** folder.

<table><thead><tr><th width="261" align="center">Property Name</th><th>Description</th></tr></thead><tbody><tr><td align="center"><strong>agent_instance_url</strong></td><td>The URL of the Agent instance provided after configuring the AI Code Review Agent with Bito Cloud.</td></tr><tr><td align="center"><strong>agent_instance_secret</strong></td><td>The secret key for the Agent instance obtained after configuring the AI Code Review Agent with Bito Cloud.</td></tr><tr><td align="center"><strong>pr_url</strong></td><td>URL of your pull request on GitLab, GitHub, or BitBucket.</td></tr></tbody></table>

* Run the following command:
  * `./bito_actions.sh bito_action.properties`
  * **Note:** When using the properties file, make sure to provide all the three parameters in `.properties` file

* #### **Option 2: Using Runtime Values** <a href="#option-2-using-runtime-values" id="option-2-using-runtime-values"></a>
  * Provide all necessary values directly on the command line:
    * `./bito_actions.sh agent_instance_url=<agent_instance_url> agent_instance_secret=<secret> pr_url=<pr_url>`
    * Replace `<agent_instance_url>`, `<secret>`, and `<pr_url>` with your specific values.
  * **Note:** You can also override the values given in the `.properties` file or provide values that are not included in the file. For example, you can configure `agent_instance_url` and `agent_instance_secret` in the `bito_action.properties` file, and only pass `pr_url` on the command line during runtime.
    * `./bito_actions.sh bito_action.properties pr_url=<pr_url>`
    * Replace `<pr_url>` with your specific values.

4. Incorporate the AI Code Review Agent into your CI/CD pipeline by adding the appropriate commands to your build or deployment scripts. This integration will automatically trigger code reviews as part of the pipeline, enhancing your development workflow by enforcing code quality checks with every change.


# Create or customize an Agent instance

Customize the AI Code Review Agent to match your workflow needs.

{% embed url="<https://youtu.be/Oj4A8wd1bio>" %}

[Connecting your Bito workspace to GitHub, GitLab, or Bitbucket](/ai-code-reviews-in-git/install-run-using-bito-cloud#connect-bito-to-your-git-provider) provides immediate access to the [AI Code Review Agent](/ai-code-reviews-in-git/overview). To get you started quickly, Bito offers a **Default Agent** instance—pre-configured and ready to deliver AI-powered code reviews for pull requests and code changes within supported IDEs such as VS Code and JetBrains.

While the **Default Agent** is ready for use right away, Bito also gives you the option to **create new Agent instances** or **customize existing ones** to suit your specific requirements. This flexibility ensures that the Agent can adapt to a range of workflows and project needs.

For example, you might configure one Agent to disable automatic code reviews for certain repositories, another to exclude specific Git branches from review, and yet another to filter out particular files or folders.

This guide will walk you through how to create or customize an Agent instance, unlocking its full potential to streamline your code reviews.

## Creating or customizing AI Code Review Agents&#x20;

Once Bito is connected to your GitHub/GitLab/Bitbucket account, you can easily create a new Agent or customize an existing one to suit your workflow.&#x20;

1. To **create a new Agent**, navigate to the [Code Review > Repositories](https://alpha.bito.ai/home/ai-agents/code-review-agent) dashboard and click the **New Agent** button to open the Agent configuration form.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fe9yWzaBjGDsbCO0TPlE0%2Fscrnli_bfuIbaAP51Klgu.png?alt=media&amp;token=db8e0ec4-34d8-4684-b4ad-770f36b1d10b" alt=""><figcaption></figcaption></figure>

2. If you’d like to **customize an existing agent**, simply go to the same [Code Review > Repositories](https://alpha.bito.ai/home/ai-agents/code-review-agent) dashboard and click the **Settings** button next to the Agent instance you wish to modify.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FNxy8j3UEcxh947QxMj9h%2Fscrnli_4T03Igj7d1r855.png?alt=media&amp;token=698cb777-e48f-4e1b-bbbf-9e24a317f30f" alt=""><figcaption></figcaption></figure>

Once you have selected an Agent to customize, you can modify its settings in the following areas:&#x20;

&#x20;

## 1. General settings&#x20;

### Agent name&#x20;

Assign a unique alphanumeric name to your Agent. This name acts as an identifier and allows you to invoke the Agent in supported clients using the **`@<agent_name>`** command.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FXEjUlDn834h978fCjNH0%2Fscrnli_ZCd0tIRfH725KX_1.png?alt=media&amp;token=00e30f6d-66df-42f4-a3cb-58ad67f0eb36" alt=""><figcaption></figcaption></figure>

## 2. Customization options&#x20;

Bito provides six tabs for in-depth Agent customization.

These include:

1. Review
2. Custom Guidelines
3. Filters
4. Tools
5. Chat
6. Functional Validation

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F2GeZTPCoolZnQ3jvhFBE%2F10.png?alt=media&amp;token=886fb830-8c2a-4402-9654-a21ccf8d48f1" alt=""><figcaption></figcaption></figure>

Let's have a look at each tab in detail.

### a. Review

In this tab, you can configure how and when the Agent performs reviews:&#x20;

* **Review language:** Select the output language for code review feedback.  &#x20;Bito supports over 20 languages, including English, Hindi, Chinese, and Spanish. The AI code review feedback will be posted on the pull requests in the selected language.&#x20;
* **Review feedback mode:** Choose between **Essential** and **Comprehensive** review modes and tailor review request settings to fit your team's unique workflow requirements.
  * In **Essential** mode, only critical issues are posted as inline comments, and other issues appear in the main review summary under "Additional issues".
  * In **Comprehensive** mode, Bito also includes minor suggestion and potential nitpicks as inline comments.
* **Automatic review:** Toggle to enable or disable automatic reviews when a pull request is created and ready for review.&#x20;
* **Automatic incremental review:** Toggle to enable or disable reviews for new commits added to a pull request. Only changes since the last review are assessed.
  * **Batch time:** Specifies how long the AI Code Review Agent waits before running an incremental review after new commits are pushed. The value can range from **`0m` (review immediately)** to **`24h` (review after 24 hours)**. Lower values result in more frequent incremental reviews.

    **Examples:**

    * `10s` → waits **10 seconds** before running the review
    * `12m` → waits **12 minutes** before running the review
    * `1h10m` → waits **1 hour and 10 minutes** before running the review
* **Request changes comments:**  Enable this option to get Bito feedback as **"Request changes"** review comments. Depending on your organization's Git settings, you may need to resolve all comments before merging.
* **Draft pull requests:** By default, the Agent excludes draft pull requests from automated reviews. Disable this toggle to include drafts.&#x20;
* **Automatic summary:** Toggle to enable automatic generation of AI summaries for changes, which are appended to the pull request description.&#x20;
* **Change Walkthrough:** Enable this option to generate a table of changes and associated files, posted as a comment on the pull request.
* **Allow config file settings:** Enabling this setting will allow Agent Settings to be overridden at a repository level by placing a `.bito.yaml` file in the root folder of that repository. [**Learn more**](/ai-code-reviews-in-git/agent-settings/repo-level-settings)
* **Auto-apply agent rules:** Automatically detect and apply best-practice guidelines from agent configuration files like `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.windsurf/rules`, or `GEMINI.md`. When enabled, Bito uses these files to guide its code review. [**Learn more**](/ai-code-reviews-in-git/implementing-custom-code-review-rules#id-3-use-project-specific-guideline-files)
* **Generate interaction diagrams:** When enabled, Bito will post interaction diagrams during code reviews to visualize architecture and impacted changes.
* **Adaptive learning:** When enabled, Bito prioritizes future suggestions based on how developers responded to past Bito reviews.
  * **Filter unaddressed suggestions:** When enabled, Bito will reduce recommending suggestions that are consistently unaddressed. Critical suggestions may still be made.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FpxtYSjIHTkO3bijBl9EO%2F1_1.png?alt=media&amp;token=2bb7e440-4016-4533-b708-4abc4b1555bf" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FVzcTL5nQ0caUVHuKWfyb%2F2.png?alt=media&amp;token=e47027db-2e68-4334-810f-9965addbf9f3" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FKAAly95OdJxOiYDYBuUJ%2F3.png?alt=media&amp;token=257dffd9-25cd-4add-8216-3128312463f4" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FjDXl8OOdIdofbAxEgbiF%2Fscrnli_GYMPw5EbDElocs.png?alt=media&amp;token=457dc686-8ab1-41ff-8de8-fa0a42972444" alt=""><figcaption></figcaption></figure>

### b. Custom Guidelines

Create, apply, and manage custom code review guidelines to align the AI agent’s reviews with your team’s specific coding standards.

The agent will follow your guidelines when reviewing pull requests.

[**Learn more**](/ai-code-reviews-in-git/implementing-custom-code-review-rules#id-2-create-custom-code-review-guidelines)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FqmcctH3kkEwx9t59Iuny%2F5_1.png?alt=media&amp;token=484f6982-f678-4667-b317-799ac42f64d9" alt=""><figcaption></figcaption></figure>

### c. Filters

Use filters to customize which files, folders, and Git branches are reviewed when the Agent triggers automatically on pull requests:

* **Exclude Files and Folders:** A list of files/folders that the AI Code Review Agent will not review if they are present in the diff. You can specify the files/folders to exclude from the review by name or glob/regex pattern. The Agent will automatically skip any files or folders that match the exclusion list. This filter applies to both manual reviews initiated through the **`/review`** command and automated reviews.&#x20;
* **Include Source/Target Branches:** This filter defines which pull requests trigger automated reviews based on their source or target branch, allowing you to focus on critical code and avoid unnecessary reviews or AI usage. By default, pull requests merging into the repository’s default branch are subject to review. To review additional branches, you can use the [Include Source/Target Branches filter](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#include-source-target-branches-filter). Bito will review pull requests when the source or target branch matches the list. This filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.
* **Exclude Labels:** Specify pull request (PR) labels to exclude from review by name or glob/regex pattern. The agent will skip any PRs tagged with these labels in GitHub or GitLab.

{% hint style="info" %}
For more information and examples, see [Excluding Files, Folders, or Branches with Filters](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters).
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FoDyUYEgeEgHaETBSs13m%2F6_1.png?alt=media&amp;token=1bf3dc7f-f41e-4249-9e24-180b559287b8" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FRdy2ev0LKHpQikPc8DOb%2Fscrnli_spc1zf61Vl2Olo.png?alt=media&amp;token=4435cf84-ec24-4eac-b73c-f1cbc404d7d4" alt=""><figcaption></figcaption></figure>

### d. Tools

Enhance the Agent’s reviews by enabling additional tools for static analysis, security checks, and secret detection:&#x20;

* **Secret Scanner:** Enable this tool to detect and report secrets left in code changes.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBxRWhwG67YXEY1YzCS5X%2F7.png?alt=media&amp;token=80f4d8dd-0afe-441f-9c2c-c76c1027a89c" alt=""><figcaption></figcaption></figure>

### e. Chat

You can chat with the [AI Code Review Agent](/ai-code-reviews-in-git/overview) to ask follow-up questions, request alternative solutions, or get clarification on review comments. From this tab, you can manage how the agent responds to these interactions.

* **Auto reply:** Enable Bito to automatically reply to user questions posted as comments on its code review suggestions—no need to tag `@bitoagent` or `@askbito`.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FHlkbzLfeOebXiSPeQVDh%2F8.png?alt=media&amp;token=0546df4a-2861-4712-82c2-1eaddc8e3a0b" alt=""><figcaption></figcaption></figure>

### f. Functional Validation

Automatically validate pull requests against Jira tickets. Ticket references are detected in the PR description, title, or branch name.

[**Learn more**](/ai-code-reviews-in-git/jira-integration)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FqDvk5U9eGFLX3zZXJlBs%2F9.png?alt=media&amp;token=4c202619-86c9-47d5-964b-54e82a8e3db3" alt=""><figcaption></figcaption></figure>

If you are editing an existing agent, click **Save** to apply the changes.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FhFyPs3udWaoGryZNNtIu%2Fscrnli_Dy0cDQUimhLw3F.png?alt=media&amp;token=a7623f7c-0e0d-47a9-ab88-605ec686ca7e" alt=""><figcaption></figcaption></figure>

## 3. Select repositories for code review

1. If you are creating a new agent instance, click **Select repositories** after configuration to choose the Git repositories the agent will review.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FovkmqjzPOyWwf2grajKm%2F11.png?alt=media&amp;token=5f66a283-5fd7-4b41-8cdd-991f04284bf3" alt=""><figcaption></figcaption></figure>

2. To enable code review for a specific repository, simply select its corresponding checkbox. You can also enable repositories later, after the Agent has been created. Once done, click **Save and continue** to save the new Agent configuration.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F4l97XCS4fu5KW3aU5H7w%2Fscrnli_D5yUG72YO9dlpi_1.png?alt=media&amp;token=f9c1c2fd-1a2e-4303-a527-f55e549e0c13" alt=""><figcaption></figcaption></figure>

3. When you save the configuration, your new Agent instance will be added and available on the [**Code Review > Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F9EdG6H9gT3WQKHGTgMbf%2Fscrnli_P0jT2f89e9j4He.png?alt=media&amp;token=f38b7ff1-6192-4b16-bb5d-2e5e316ae737" alt=""><figcaption></figcaption></figure>


# Clone an Agent instance

Easily duplicate Agent configurations for faster setup.

Save time and effort by quickly creating a new [AI Code Review Agent](/ai-code-reviews-in-git/overview) instance using the configuration settings of an existing one. It’s a fast and simple way to set up multiple Agent instances without having to reconfigure each one.

Follow the steps below to get started:

1. [**Log in to Bito Cloud**](https://alpha.bito.ai/) and select a workspace to get started.
2. From the left sidebar, select [**Code Review Agents**](https://alpha.bito.ai/home/ai-agents/code-review-agent).

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FWAlD5Tm3CGt1ZRlSKMpy%2Fscrnli_5pO6ZemgqQagoE.png?alt=media&amp;token=ede8c747-b4a2-43ca-b825-013a5aedf169" alt=""><figcaption></figcaption></figure>

3. If your Bito workspace is connected to your GitHub/GitLab/Bitbucket account, a list of AI Code Review Agent instances configured in your workspace will appear. Locate the instance you wish to duplicate and click the **Clone** button given in front of it.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FtJeW5xZfsN21VIJTsgub%2Fscrnli_tkWuHJHpsQFmZS.png?alt=media&amp;token=00b8aa6d-0d21-4753-9ea6-078e88fa0527" alt=""><figcaption></figcaption></figure>

4. An Agent configuration form will open, pre-populated with the input field values. You can edit these values as needed.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FdYi4tC2DtqsD17guGho2%2Fscrnli_IfvRZsM0gmzHgj_1.png?alt=media&amp;token=9cc3dd35-4bb7-4272-bc38-1a64abb4ba15" alt="" width="563"><figcaption></figcaption></figure>

5. Click **Select repositories** to choose Git repositories for the new Agent.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FxcWpSGp6bW3cx1DRTfCM%2Fscrnli_QGxSmiYenNC3Lk.png?alt=media&amp;token=a7644e4d-a2fa-4136-82f9-29cfee954ca7" alt="" width="563"><figcaption></figcaption></figure>

6. To enable code review for a specific repository, simply select its corresponding checkbox. You can also enable repositories later, after the Agent has been created. Once done, click **Save and continue** to save the new Agent configuration.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fh4PMscB79SgNukvOatA2%2Fscrnli_vg5QAanR0PkKBy_1.png?alt=media&amp;token=7b86cf8c-b5a8-4a11-a41f-22849adc768c" alt=""><figcaption></figcaption></figure>

7. When you save the configuration, your new Agent instance will be added and available on the [**Code Review Agents**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FKVF4JfSXFrj1ImqWrT2q%2Fscrnli_d0bB9ZWwmQ1DQf.png?alt=media&amp;token=487f6848-d1e7-4cf1-a78d-5aab51161065" alt=""><figcaption></figcaption></figure>


# Delete unused Agent instances

Easily delete Agent instances you no longer need.

If you no longer need an [AI Code Review Agent](/ai-code-reviews-in-git/overview) instance, you can delete it to keep your workspace organized. Follow the steps below to quickly remove any unused Agents.

1. [**Log in to Bito Cloud**](https://alpha.bito.ai/) and select a workspace to get started.
2. From the left sidebar, select [**Code Review Agents**](https://alpha.bito.ai/home/ai-agents/code-review-agent).

   If your Bito workspace is connected to your GitHub/GitLab/Bitbucket account, a list of AI Code Review Agent instances configured in your workspace will appear.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FXPaSaBzjEl3Oenag60Sc%2Fscrnli_14ld2xgfJQRoXF.png?alt=media&amp;token=dfcb846f-d813-446a-be41-949603b32aec" alt=""><figcaption></figcaption></figure>

2. Before deleting an Agent, ensure that any repositories currently using it are reassigned to another Agent otherwise a warning popup will appear.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fm3GDTxzzl5x18aN7cx9f%2Fscrnli_643th6cTMQyfME_1.png?alt=media&amp;token=fab3011c-5c8d-4081-bb33-110d7b32cd8a" alt=""><figcaption></figcaption></figure>

3. Locate the Agent you wish to delete and click the **Delete** button given in front of it.

{% hint style="info" %}
**Note:** The **Default Agent** (provided by Bito) cannot be deleted.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FNPnP1XN5rBFd3u75IH1V%2Fscrnli_0DhwMLUbEr6U2q.png?alt=media&amp;token=f428971f-1cbf-4933-a496-92110c48bb2f" alt=""><figcaption></figcaption></figure>


# Install/run as a self-hosted service

Deploy the AI Code Review Agent on your machine.

The self-hosted AI Code Review Agent offers a more private and customizable option for teams looking to enhance their code review processes within their own infrastructure, while maintaining complete control over their data. This approach is ideal for organizations with specific compliance, security, or customization requirements.

## Understanding CLI vs webhooks service

When setting up the AI Code Review Agent, you have the flexibility to choose between two primary modes of operation: **CLI** and **webhooks service**.

* **CLI** allows developers to manually initiate code reviews directly from terminal. This mode is ideal for quick, on-demand code reviews without the need for continuous monitoring or integration.
* **Webhooks service** transforms the Agent into a persistent service that automatically triggers code reviews based on specific events, such as pull requests or comments on pull requests. This mode is suitable for teams looking to automate their code review processes.

For more details, visit the [**CLI vs webhooks service**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/cli-vs-webhooks-service) page.

## Deployment Options

Based on your needs and the desired integration level with your development workflow, choose one of the following options to install and run the AI Code Review Agent:

{% hint style="info" %}
Before proceeding, ensure you've completed all necessary [**prerequisites for self-hosted**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/prerequisites) AI Code Review Agent.
{% endhint %}

1. [**Install/run via CLI**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/install-run-via-cli): Ideal for developers seeking a simple, interactive way to conduct code reviews from the command line.
2. [**Install/run via webhooks service**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/install-run-via-webhooks-service): Perfect for teams looking to automate code reviews through external events, enhancing their CI/CD workflow.
3. [**Install/run via GitHub Actions**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/install-run-via-github-actions): A great option for GitHub users to seamlessly integrate automated code reviews into their GitHub Actions workflows.


# Prerequisites

Key requirements for self-hosting the AI Code Review Agent.

## Minimum System Requirements

A machine with the following minimum specifications is recommended for Docker image deployment and for obtaining optimal performance of the AI Code Review Agent.

| Requirement     | Minimum Specification |
| --------------- | --------------------- |
| CPU Cores       | 4                     |
| RAM             | 8 GB                  |
| Hard Disk Drive | 80 GB                 |

***

## Supported Operating Systems

* Windows
* Linux
* macOS

***

## OS Prerequisites

<table><thead><tr><th width="192" align="center">Operating System</th><th>Installation Steps</th></tr></thead><tbody><tr><td align="center"><strong>Linux</strong></td><td><p><strong>You will need:</strong></p><ol><li><p><strong>Bash</strong> (minimum version 4.x)</p><ul><li><p>For Debian and Ubuntu systems</p><p><code>sudo apt-get install bash</code></p></li></ul><p></p><ul><li><p>For CentOS and other RPM-based systems</p><p><code>sudo yum install bash</code></p></li></ul></li></ol><p> </p><ol start="2"><li><p><strong>Docker</strong> (minimum version 20.x)</p><ul><li><a href="https://docs.docker.com/engine/install/">View Guide</a></li></ul></li></ol><p> </p></td></tr><tr><td align="center"><strong>macOS</strong></td><td><p><strong>You will need:</strong></p><ol><li><p><strong>Bash</strong> (minimum version 4.x)</p><p><code>brew install bash</code></p></li></ol><p></p><ol start="2"><li><p><strong>Docker</strong> (minimum version 20.x)</p><ul><li><a href="https://docs.docker.com/engine/install/">View Guide</a></li></ul></li></ol><p> </p></td></tr><tr><td align="center"><strong>Windows</strong></td><td><p><strong>You will need:</strong></p><ol><li><p><strong>PowerShell</strong> (minimum version 5.x)</p><ul><li><a href="https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4">View Guide</a></li><li>Note: In PowerShell version 7.x, run <code>Set-ExecutionPolicy Unrestricted</code> command. It allows the execution of scripts without any constraints, which is essential for running scripts that are otherwise blocked by default security settings.</li></ul></li></ol><p></p><ol start="2"><li><p><strong>Docker</strong> (minimum version 20.x)</p><ul><li><a href="https://docs.docker.com/engine/install/">View Guide</a></li></ul></li></ol><p> </p></td></tr></tbody></table>

***

## Required Access Tokens

* **Bito Access Key:** Obtain your Bito Access Key. [**View Guide**](/help/account-and-settings/access-key)
* **GitHub Personal Access Token (Classic):** For GitHub PR code reviews, ensure you have a CLASSIC personal access token with repo access. We do not support fine-grained tokens currently. [**View Guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)  &#x20;

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBZH0vDwrPqYQPMIxIyNW%2Fimage.png?alt=media&amp;token=a4c42d8d-61a5-4cdb-87a1-622c0ba8f1ae" alt=""><figcaption><p><strong>GitHub Personal Access Token (Classic)</strong></p></figcaption></figure>

* **GitLab Personal Access Token:** For GitLab PR code reviews, a token with API access is required. [**View Guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FghbsjA3aafRQJBQGnksv%2Fimage%20(1).png?alt=media&amp;token=6feb55f7-39b3-4d61-8e46-f6b233e64849" alt=""><figcaption><p><strong>GitLab Personal Access Token</strong></p></figcaption></figure>

* **Snyk API Token (Auth Token):** For Snyk vulnerability reports, obtain a Snyk API Token. [**View Guide**](https://docs.snyk.io/getting-started/how-to-obtain-and-authenticate-with-your-snyk-api-token)


# CLI vs webhooks service

From one-time reviews to continuous automated reviews.

On your machine or in a Private Cloud, you can run the AI Code Review Agent via either CLI or webhooks service. This guide will teach you about the key differences between CLI and webhooks service and when to use each mode.

## Difference Between CLI and webhooks service

The main difference between CLI and webhooks service lies in their operational approach and purpose. In CLI, the docker container is used for a one-time code review. This mode is ideal for isolated, single-instance analyses where a quick, direct review of the code is needed.

On the other hand, webhooks service is designed for continuous operation. When set in webhooks service mode, the AI Code Review Agent remains online and active at a specified URL. This continuous operation allows it to respond automatically whenever a pull request is opened in a repository. In this scenario, the git provider notifies the server, triggering the AI Code Review Agent to analyze the pull request and post its review as a comment directly on it.

## When to Use CLI and When to Use webhooks service

Selecting the appropriate mode for code review with the AI Code Review Agent depends largely on the nature and frequency of your code review needs.

### CLI: Ideal for Specific, One-Time Reviews

CLI mode is best suited for scenarios requiring immediate, one-time code reviews. It's particularly effective for:

* Conducting quick assessments of specific pull requests.
* Performing periodic, scheduled code analyses.
* Reviewing code in environments with limited or no continuous integration support.
* Integrating with batch processing scripts for ad-hoc analysis.
* Using in educational settings to demonstrate code review practices.
* Experimenting with different code review configurations.
* Reviewing code on local setups or for personal projects.
* Performing a final check before pushing code to a repository.

CLI mode stands out for its simplicity and is perfect for standalone tasks where a single, direct execution of the code review process is all that's needed.

### Webhooks service: For Continuous, Automated Reviews

Webhooks service, on the other hand, is the go-to choice for continuous code review processes. It excels in:

* Continuously monitoring all pull requests in a repository.
* Providing instant feedback in collaborative projects.
* Seamlessly integrating with CI/CD pipelines for automated reviews.
* Performing automated code quality checks in team environments.
* Conducting real-time security scans on new pull requests.
* Ensuring adherence to coding standards in every pull request.
* Streamlining the code review process in large-scale projects.
* Maintaining consistency in code review across multiple projects.
* Enhancing workflows in remote or distributed development teams.
* Offering prompt feedback in agile development settings.

Webhooks service is indispensable in active development environments where consistent monitoring and immediate feedback are critical. It automates the code review process, integrating seamlessly into the workflow and eliminating the need for manual initiation of code reviews.


# Install/run via CLI

CLI mode is best suited for immediate, one-time code reviews.

1. **Prerequisites:** Before proceeding, ensure you've completed all necessary [**prerequisites for self-hosted**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/prerequisites) AI Code Review Agent.
2. **Start Docker:** Ensure Docker is running on your machine.
3. **Repository Download:** [**Download the AI Code Review Agent**](https://github.com/gitbito/codereviewagent) GitHub repository to your machine.
4. **Extract and Navigate:**

* Extract the downloaded .zip file to a preferred location.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBauSkjRmacbzGKV3ESwO%2F1.PNG?alt=media&amp;token=4faa99de-529c-4b75-bb73-2c5bccf26850" alt=""><figcaption></figcaption></figure>

* Navigate to the extracted folder and then to the “cra-scripts” subfolder.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FeupW2typotZUOO8hbmke%2F2.PNG?alt=media&amp;token=f955c60c-cdd4-480a-8bda-f90ef3c5376c" alt=""><figcaption></figcaption></figure>

* Note the full path to the “cra-scripts” folder for later use.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FJB3b2oKe3UEEz0xBIzI1%2Fcra_5.png?alt=media&amp;token=86d352d7-990b-4392-9e3f-3cf451b22d5c" alt=""><figcaption></figcaption></figure>

5. **Open Command Line:**
   * Use Bash for Linux and macOS.
   * Use PowerShell for Windows.
6. **Set Directory:**
   * Change the current directory in Bash/PowerShell to the “cra-scripts” folder.
   * Example command: `cd [Path to cra-scripts folder]`
   * Adjust the path based on your extraction location.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F1VSZoDtgl9NwqFqu3A44%2F6.PNG?alt=media&amp;token=3fdefd2a-dad1-436d-911f-51f216d1ef76" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FFGkgrLhGlvDiTc5lLePW%2F7.PNG?alt=media&amp;token=2058e7a7-7819-49cc-ad69-8b4b90af9d12" alt=""><figcaption></figcaption></figure>

7. **Configure Properties:**
   * Open the **bito-cra.properties** file in a text editor from the “cra-scripts” folder. Detailed information for each property is provided on [**Agent Configuration: bito-cra.properties File**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file) page.
   * Set mandatory properties:
     * mode = cli
     * pr\_url
     * bito\_cli.bito.access\_key
     * git.provider
     * git.access\_token

{% hint style="info" %}
**Note:** Valid values for git.provider are GITHUB, GITLAB, or BITBUCKET.
{% endhint %}

* Optional properties (can be skipped or set as needed):
  * git.domain
  * code\_feedback
  * static\_analysis
  * dependency\_check
  * dependency\_check.snyk\_auth\_token
  * review\_scope
  * exclude\_branches
  * exclude\_files
  * exclude\_draft\_pr

{% hint style="info" %}
**Note:** Detailed information for each property is provided on [**Agent Configuration: bito-cra.properties File**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file) page.
{% endhint %}

{% hint style="info" %}
Check the [**Required Access Tokens**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/prerequisites#required-access-tokens) guide to learn more about creating the access tokens needed to configure the Agent.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Ftwj5rCsz3vdrUfflvjxI%2Fproperties_file.png?alt=media&amp;token=e39a928d-accf-454a-af03-ffb97dbc68a5" alt=""><figcaption></figcaption></figure>

8. **Run the Agent:**
   * On Linux/macOS in Bash: Run `./bito-cra.sh bito-cra.properties`
   * On Windows in PowerShell: Run `./bito-cra.ps1 bito-cra.properties`

{% hint style="info" %}
This step might take time initially as it pulls the Docker image and performs the code review.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FSjDE0OgQ9x2lZfR5mjh6%2F8.PNG?alt=media&amp;token=f122f4a8-cd4f-46e2-8afd-6fa7efc80234" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FK41KV7WlXAmuZpZCqojj%2Fcra_6.png?alt=media&amp;token=0c66339b-6cce-4942-b4d5-f1ae85cdae64" alt=""><figcaption></figcaption></figure>

9. **Final Steps:**
   * The script may prompt values of mandatory/optional properties if they are not preconfigured.
   * Upon completion, a code review comment is automatically posted on the Pull Request specified in the **pr\_url** property.

{% hint style="info" %}
**Note:** To improve efficiency, the AI Code Review Agent is disabled by default for pull requests involving the **"main"** branch. This prevents unnecessary processing and token usage, as changes to the **"main"** branch are typically already reviewed in release or feature branches. To change this default behavior and include the **"main"** branch, please [**contact support**](mailto:support@bito.ai).
{% endhint %}

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated pull request (PR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fk5wsTj4siolCcaZqHRIX%2Fscrnli_9_13_2024_12-33-56%20PM.png?alt=media&amp;token=63cb7da9-21ca-41a1-83ba-9b107d07a6cf" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a pull request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the pull request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FP0sUIAZ3Lq0FqL9ytfPF%2Fscrnli_9_13_2024_12-49-29%20PM_cropped_3.png?alt=media&amp;token=d74d3b27-4831-4735-9559-6f9da191e910" alt=""><figcaption></figcaption></figure>


# Install/run via webhooks service

The webhooks service is best suited for continuous, automated reviews.

## Prerequisites

### Minimum System Requirements

A machine with the following minimum specifications is recommended for Docker image deployment and for obtaining optimal performance of the AI Code Review Agent.

| Requirement     | Minimum Specification |
| --------------- | --------------------- |
| CPU Cores       | 4                     |
| RAM             | 8 GB                  |
| Hard Disk Drive | 80 GB                 |

***

### Supported Operating Systems

* Windows
* Linux
* macOS

***

### OS Prerequisites

<table><thead><tr><th width="192" align="center">Operating System</th><th>Installation Steps</th></tr></thead><tbody><tr><td align="center"><strong>Linux</strong></td><td><p><strong>You will need:</strong></p><ol><li><p><strong>Bash</strong> (minimum version 4.x)</p><ul><li><p>For Debian and Ubuntu systems</p><p><code>sudo apt-get install bash</code></p></li></ul><p></p><ul><li><p>For CentOS and other RPM-based systems</p><p><code>sudo yum install bash</code></p></li></ul></li></ol><p> </p><ol start="2"><li><p><strong>Docker</strong> (minimum version 20.x)</p><ul><li><a href="https://docs.docker.com/engine/install/">View Guide</a></li></ul></li></ol><p> </p></td></tr><tr><td align="center"><strong>macOS</strong></td><td><p><strong>You will need:</strong></p><ol><li><p><strong>Bash</strong> (minimum version 4.x)</p><p><code>brew install bash</code></p></li></ol><p></p><ol start="2"><li><p><strong>Docker</strong> (minimum version 20.x)</p><ul><li><a href="https://docs.docker.com/engine/install/">View Guide</a></li></ul></li></ol><p> </p></td></tr><tr><td align="center"><strong>Windows</strong></td><td><p><strong>You will need:</strong></p><ol><li><p><strong>PowerShell</strong> (minimum version 5.x)</p><ul><li><a href="https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4">View Guide</a></li><li>Note: In PowerShell version 7.x, run <code>Set-ExecutionPolicy Unrestricted</code> command. It allows the execution of scripts without any constraints, which is essential for running scripts that are otherwise blocked by default security settings.</li></ul></li></ol><p></p><ol start="2"><li><p><strong>Docker</strong> (minimum version 20.x)</p><ul><li><a href="https://docs.docker.com/engine/install/">View Guide</a></li></ul></li></ol><p> </p></td></tr></tbody></table>

***

### Required Access Tokens

* **Bito Access Key:** Obtain your Bito Access Key. [**View Guide**](/help/account-and-settings/access-key)
* **GitHub Personal Access Token (Classic):** For GitHub PR code reviews, ensure you have a CLASSIC personal access token with repo access. We do not support fine-grained tokens currently. [**View Guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)  &#x20;

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBZH0vDwrPqYQPMIxIyNW%2Fimage.png?alt=media&amp;token=a4c42d8d-61a5-4cdb-87a1-622c0ba8f1ae" alt=""><figcaption><p><strong>GitHub Personal Access Token (Classic)</strong></p></figcaption></figure>

* **GitLab Personal Access Token:** For GitLab PR code reviews, a token with API access is required. [**View Guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FghbsjA3aafRQJBQGnksv%2Fimage%20(1).png?alt=media&amp;token=6feb55f7-39b3-4d61-8e46-f6b233e64849" alt=""><figcaption><p><strong>GitLab Personal Access Token</strong></p></figcaption></figure>

* **Snyk API Token (Auth Token):** For Snyk vulnerability reports, obtain a Snyk API Token. [**View Guide**](https://docs.snyk.io/getting-started/how-to-obtain-and-authenticate-with-your-snyk-api-token)

***

## Installation and Configuration Steps

1. **Prerequisites:** Before proceeding, ensure you've completed all necessary [**prerequisites for self-hosted**](#prerequisites) AI Code Review Agent.
2. **Server Requirement:** Ensure you have a server with a domain name or IP address.
3. **Start Docker:** Initialize Docker on your server.
4. **Clone the repository:** [**Clone the AI Code Review Agent**](https://github.com/gitbito/codereviewagent) GitHub repository to your server using the following command:
   * `git clone https://github.com/gitbito/CodeReviewAgent.git`
   * **Note:** It is recommended to clone the repository instead of downloading the .zip file. This approach allows you to easily [**update the Agent**](#how-to-update-the-self-hosted-ai-code-review-agent) later using the `git pull` command.
5. **Open the repository folder:**
   * Navigate to the repository folder and then to the “cra-scripts” subfolder.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FYaZdU057J1qY8mpafUQP%2F2.PNG?alt=media&amp;token=4ad6af3d-47be-442b-9c5d-2bdc0400c944" alt=""><figcaption></figcaption></figure>

* Note the full path to the “cra-scripts” folder for later use.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FmuagwhDXqUteSbOTJNPp%2Fcra_5.png?alt=media&amp;token=7f776742-cd2f-4db2-8a00-b2165ee44752" alt=""><figcaption></figcaption></figure>

6. **Open Command Line:**
   * Use Bash for Linux and macOS.
   * Use PowerShell for Windows.
7. **Set Directory:**
   * Change the current directory in Bash/PowerShell to the “cra-scripts” folder.
   * Example command: `cd [Path to cra-scripts folder]`
   * **Note:** Adjust the path based on where you cloned the repository on your system.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FGnsxyvCury17bK6ojK9V%2F6.PNG?alt=media&amp;token=fca033ea-6f05-4bf8-a033-75ee11be7e4a" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F8A09WmtAoKU9Cln7b3uf%2F7.PNG?alt=media&amp;token=da370a92-d4e5-4710-a097-4fa789fe54a3" alt=""><figcaption></figcaption></figure>

8. **Configure Properties:**
   * Open the **bito-cra.properties** file in a text editor from the “cra-scripts” folder. Detailed information for each property is provided on [**Agent Configuration: bito-cra.properties File**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file) page.
   * Set mandatory properties:
     * mode = server
     * bito\_cli.bito.access\_key
     * git.access\_token
   * Optional properties (can be skipped or set as needed):
     * git.provider
     * git.domain
     * code\_feedback
     * static\_analysis
     * dependency\_check
     * dependency\_check.snyk\_auth\_token
     * server\_port
     * review\_scope
     * exclude\_branches
     * exclude\_files
     * exclude\_draft\_pr

{% hint style="info" %}
**Note:** Valid values for git.provider are GITHUB or GITLAB.
{% endhint %}

{% hint style="info" %}
**Note:** Detailed information for each property is provided on [**Agent Configuration: bito-cra.properties File**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file) page.
{% endhint %}

{% hint style="info" %}
Check the [**Required Access Tokens**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/prerequisites#required-access-tokens) guide to learn more about creating the access tokens needed to configure the Agent.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FRlugvd7UX2qXOoAwhnsL%2Fcra_9.png?alt=media&amp;token=0522b55c-a95a-4264-9853-980d09cfcfa9" alt=""><figcaption></figcaption></figure>

9. **Run the Agent:**
   * **On Linux/macOS in Bash:**
     * Run `./bito-cra.sh service start bito-cra.properties`
     * **Note:** It will provide the Git Webhook secret in encrypted format.
   * **On Windows in PowerShell:**
     * Install OpenSSL
       * Reference-1: <https://wiki.openssl.org/index.php/Binaries>
       * Reference-2: <https://slproweb.com/products/Win32OpenSSL.html>
     * Run `./bito-cra.ps1 service start bito-cra.properties`
     * **Note:** It will provide the Git Webhook secret in encrypted format.

{% hint style="info" %}
This step might take time initially as it pulls the Docker image and performs the code review.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FzalttOI7Osr6BzwS94fW%2F8.PNG?alt=media&amp;token=8615d023-cd00-4fc1-9616-9b6df3abd6c0" alt=""><figcaption></figcaption></figure>

10. **Provide Missing Property Values:** The script may prompt for values of mandatory/optional properties if they are not preconfigured.
11. **Copy Webhook Secret:** During the script execution, a webhook secret is generated and displayed in the shell. Copy the secret displayed under **"Use below as Gitlab and Github Webhook secret:"** for use in GitHub or GitLab when setting up the webhook.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F2eGxT6LoIlvMmHmC3avR%2Fscrnli_1_22_2024_7-34-26%20AM.png?alt=media&amp;token=dc037dff-e5aa-43b4-809c-e1d01f838a27" alt=""><figcaption></figcaption></figure>

## Webhook Setup Guide

[**GitHub Webhook Setup Guide**](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks)**:**

* Login to your [GitHub](https://github.com/) account.
* Navigate to the main page of the repository. Under your repository name, click **Settings**.
* In the left sidebar, click **Webhooks**.
* Click **Add webhook**.
* Under **Payload URL**, enter the URL of the webhook endpoint. This is the server's URL to receive webhook payloads.
  * **Note:** The GitHub Payload URL should follow this format: `https://<domain name/ip-address>/api/v1/github_webhooks`, where `https://<domain name/ip-address>` should be mapped to Bito's AI Code Review Agent container, which runs as a service on a configured TCP port such as 10051. Essentially, you need to append the string **"/api/v1/github\_webhooks"** (without quotes) to the URL where the AI Code Review Agent is running.
  * For example, a typical webhook URL would be `https://cra.example.com/api/v1/github_webhooks`
* Select the **Content type** “application/json” for JSON payloads.
* In **Secret token**, enter the webhook secret token that you copied above. It is used to validate payloads.
* Click on **Let me select individual events** to select the events that you want to trigger the webhook. For code review select these:
  * **Issue comments** - To enable Code Review on-demand by issuing a command in the PR comment.
  * **Pull requests** - To auto-trigger Code Review when a pull request is created.
  * **Pull request review comments** - So, you can share feedback on the review quality by answering the feedback question in the code review comment.
* To make the webhook active immediately after adding the configuration, select **Active**.
* Click **Add webhook**.

[**GitLab Webhook Setup Guide**](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#configure-a-webhook-in-gitlab)**:**

* Login to your [GitLab](https://gitlab.com/users/sign_in) account.
* Select the repository where the webhook needs to be configured.
* On the left sidebar, select **Settings > Webhooks**.
* Select **Add new webhook**.
* In **URL**, enter the URL of the webhook endpoint. This is the server's URL to receive webhook payloads.
  * **Note:** The GitLab webhook URL should follow this format: `https://<domain name/ip-address>/api/v1/gitlab_webhooks`, where `https://<domain name/ip-address>` should be mapped to Bito's AI Code Review Agent container, which runs as a service on a configured TCP port such as 10051. Essentially, you need to append the string **"/api/v1/gitlab\_webhooks"** (without quotes) to the URL where the AI Code Review Agent is running.
  * For example, a typical webhook URL would be `https://cra.example.com/api/v1/gitlab_webhooks`
* In **Secret token**, enter the webhook secret token that you copied above. It is used to validate payloads.
* In the **Trigger** section, select the events to trigger the webhook. For code review select these:
  * **Comments** - for on-demand code review.
  * **Merge request events** - for automatic code review when a merge request is created.
  * **Emoji events** - So, you can share feedback on the review quality using emoji reactions.
* Select **Add webhook**.

[**BitBucket Webhook Setup Guide**](https://support.atlassian.com/bitbucket-cloud/docs/create-and-trigger-a-webhook-tutorial/)**:**

* Login to your [BitBucket](https://bitbucket.org/) account.
* Navigate to the main page of the repository. Under your repository name, click **Repository Settings**.
* In the left sidebar, click **Webhooks**.
* Click **Add webhook**.
* Under **URL**, enter the URL of the webhook endpoint. This is the server's URL to receive webhook payloads.
  * **Note:** The BitBucket Payload URL should follow this format: `https://<domain name/ip-address>/api/v1/bitbucket_webhooks`, where `https://<domain name/ip-address>` should be mapped to Bito's AI Code Review Agent container, which runs as a service on a configured TCP port such as 10051. Essentially, you need to append the string **"/api/v1/bitbucket\_webhooks"** (without quotes) to the URL where the AI Code Review Agent is running.
  * For example, a typical webhook URL would be `https://cra.example.com/api/v1/bitbucket_webhooks`
* In **Secret token**, enter the webhook secret token that you copied above. It is used to validate payloads.
* In the **Triggers** section, select the events to trigger the webhook. For code review select these:
  * **Pull Request > Comment created** - for on-demand code review.
  * **Pull Request > Created** - for automatic code review when a merge request is created.
* Select **Save**.

***

## Using the AI Code Review Agent

After configuring the webhook, you can invoke the AI Code Review Agent in the following ways:

{% hint style="info" %}
**Note:** To improve efficiency, the AI Code Review Agent is disabled by default for pull requests involving the **"main"** branch. This prevents unnecessary processing and token usage, as changes to the **"main"** branch are typically already reviewed in release or feature branches. To change this default behavior and include the **"main"** branch, please [**contact support**](mailto:support@bito.ai).
{% endhint %}

1. **Automated Code Review**: If the webhook is configured to be triggered on the **Pull requests** event (for GitHub) or **Merge request** event (for GitLab), the agent will automatically review new pull requests as soon as they are created and post the review feedback as a comment within your PR.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the pull request and submit it. If the webhook is configured to be triggered on the **Issue comments** event (for GitHub) or **Comments** event (for GitLab), this action will initiate the code review process. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and submit it to re-review the entire pull request from scratch, rather than only the latest changes.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong> If an incremental review is already scheduled when you trigger a manual <code>/review</code>, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual <code>/review</code> is treated as a full review so that no changes are missed. To always re-review all changes, use <code>/review full</code>.</p></div>

   Bito also offers specialized commands that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.

   * **`/review security`:** Analyzes code to identify security vulnerabilities and ensure secure coding practices.
   * **`/review performance`:** Evaluates code for performance issues, identifying slow or resource-heavy areas.
   * **`/review scalability`:** Assesses the code's ability to handle increased usage and scale effectively.
   * **`/review codeorg`:** Scans for readability and maintainability, promoting clear and efficient code organization.
   * **`/review codeoptimize`:** Identifies optimization opportunities to enhance code efficiency and reduce resource usage.

   By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**

   For more details, refer to [Available Commands](/ai-code-reviews-in-git/available-commands).

   <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FrcIGhiEeBRVPV69BaaiW%2Fscrnli_2_28_2024_8-57-29%20PM.png?alt=media&amp;token=845b4c88-5b7a-4e7a-a9fb-13648095a15e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull request.
{% endhint %}

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated pull request (PR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fk5wsTj4siolCcaZqHRIX%2Fscrnli_9_13_2024_12-33-56%20PM.png?alt=media&amp;token=63cb7da9-21ca-41a1-83ba-9b107d07a6cf" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a pull request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the pull request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FP0sUIAZ3Lq0FqL9ytfPF%2Fscrnli_9_13_2024_12-49-29%20PM_cropped_3.png?alt=media&amp;token=d74d3b27-4831-4735-9559-6f9da191e910" alt=""><figcaption></figcaption></figure>

***

## How to update the self-hosted AI Code Review Agent

Please follow these steps:

1. **Update the Agent's repository:**
   * Pull the latest changes from the <https://github.com/gitbito/CodeReviewAgent> repository by running the following command in your terminal, ensuring you are inside the repository folder:
   * `git pull origin main`
2. **Restart the Docker container:**
   * To restart the Docker container running as a service, use the below command.
   * **On Linux/macOS in Bash:** Run `./bito-cra.sh service restart bito-cra.properties`
   * **On Windows in PowerShell:** Run `./bito-cra.ps1 service restart bito-cra.properties`

***

## Stop Docker Container

To stop the Docker container running as a service, use the below command.

* On Linux/macOS in Bash: Run `./bito-cra.sh service stop`
* On Windows in PowerShell: Run `./bito-cra.ps1 service stop`

***

## Check Status

To check the status of Docker container running as a service, use the below command.

* On Linux/macOS in Bash: Run `./bito-cra.sh service status`
* On Windows in PowerShell: Run `./bito-cra.ps1 service status`


# Install/run via GitHub Actions

Seamlessly integrate automated code reviews into your GitHub Actions workflows.

## Prerequisites

* **Bito Access Key:** Obtain your Bito Access Key. [**View Guide**](/help/account-and-settings/access-key)
* **GitHub Personal Access Token (Classic):** For GitHub PR code reviews, ensure you have a CLASSIC personal access token with repo access. We do not support fine-grained tokens currently. [**View Guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBZH0vDwrPqYQPMIxIyNW%2Fimage.png?alt=media&amp;token=a4c42d8d-61a5-4cdb-87a1-622c0ba8f1ae" alt=""><figcaption><p><strong>GitHub Personal Access Token (Classic)</strong></p></figcaption></figure>

***

## Installation and Configuration Steps:

1. **Enable GitHub Actions:**
   * Login to your [GitHub](https://github.com/) account.

   * Open your repository and click on the "Settings" tab.

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FvHdaHm4Z56JwiwmEFP6s%2Fscrnli_2_21_2024_3-01-34%20AM.png?alt=media&amp;token=032babc3-47ef-46bc-b077-387717ad37fb" alt=""><figcaption></figcaption></figure>

   * Select "Actions" from the left sidebar, then click on "General".

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FA0Zjef3Jhzo4JYTtCxqc%2Fscrnli_2_21_2024_3-06-05%20AM.png?alt=media&amp;token=f4231134-afed-4978-888f-1c250f0bf12e" alt=""><figcaption></figcaption></figure>

   * Under "Actions permissions", choose "Allow all actions and reusable workflows" and click "Save".

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FNjcCGFCnyxfBVTjJPT5Q%2Fscrnli_2_21_2024_3-08-42%20AM.png?alt=media&amp;token=70f465bf-8623-479a-a437-aed85c6b1605" alt=""><figcaption></figcaption></figure>

2. **Set Up Environment Variables:**
   * Still in the "Settings" tab, navigate to "Secrets and variables" > "Actions" from the left sidebar.

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FKLj5Wg3Ip6u58RHA3s1E%2Fscrnli_2_21_2024_3-11-29%20AM.png?alt=media&amp;token=8700dac2-cd6e-484a-a22a-25245d6a664a" alt=""><figcaption></figcaption></figure>

   * **Configure the following under the "Secrets" tab:**

     For each secret, click the **New repository secret** button, then enter the exact name and value of the secret in the form. Finally, click **Add secret** to save it.

     * **Name:** `BITO_ACCESS_KEY`
       * **Secret:** Enter your Bito Access Key here. Refer to the [guide for obtaining your Bito Access Key](/help/account-and-settings/access-key#creating-an-access-key).
     * **Name:** `GIT_ACCESS_TOKEN`
       * **Secret:** Enter your GitHub Personal Access Token (Classic) with repo access. We do not support fine-grained tokens currently. For more information, see the [Prerequisites](#prerequisites) section.

{% hint style="info" %}
Check the above ["Prerequisites"](#prerequisites) section to learn more about creating the access tokens needed to configure the Agent.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FI6QvP52ueBYA9tsFQ7l5%2Fscrnli_5_8_2024_9-16-14%20PM.png?alt=media&amp;token=2fe9491d-175f-4576-831f-8b7385ada5cb" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIDpWabR1EZLLGXzxCyHC%2Fscrnli_2_21_2024_3-16-52%20AM.png?alt=media&amp;token=424856b3-49c8-432a-be7c-60549bf876da" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FGuEDWm1KqYCrNTZOqM6p%2Fscrnli_5_8_2024_9-00-51%20PM.png?alt=media&amp;token=4f92c5a3-42a0-4b4a-aeef-b2c8df065b41" alt=""><figcaption></figcaption></figure>

* **Configure the following under the "Variables" tab:**

  For each variable, click the **New repository variable** button, then enter the exact name and value of the variable in the form. Finally, click **Add variable** to save it.

  * **Name:** `STATIC_ANALYSIS_TOOL`
    * **Value:** Enter the following text string as value: `fb_infer,astral_ruff,mypy`
  * **Name:** `GIT_DOMAIN`
    * **Value:** Enter the domain name of your Enterprise or self-hosted GitHub deployment or skip this if you are not using Enterprise or self-hosted GitHub deployment.
    * **Example of domain name:** `https://your.company.git.com`
  * **Name:** `EXCLUDE_BRANCHES`
    * **Value:** Specify branches to exclude from the review by name or valid glob/regex patterns. The agent will skip the pull request review if the source or target branch matches the exclusion list.
    * **Note:** For more information, see [**Source or Target branch filter**](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#source-or-target-branch-filter).
  * **Name:** `EXCLUDE_FILES`
    * **Value:** Specify files/folders to exclude from the review by name or glob/regex pattern. The agent will skip files/folders that match the exclusion list.
    * **Note:** For more information, see [**Files and folders filter**](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#files-and-folders-filter).
  * **Name:** `EXCLUDE_DRAFT_PR`
    * **Value:** Enter `True` to disable automated review for draft pull requests, or `False` to enable it.
    * **Note:** For more information, see [**Draft pull requests filter**](/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters#draft-pull-requests-filter).

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FMQ6h8wLoIqq1xVMtEtpr%2Fscrnli_5_8_2024_9-06-44%20PM.png?alt=media&amp;token=13b7916d-157f-444c-9a1e-b36da99a4d6f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FcyXbRNa1JYxzj2a1c5Kq%2Fscrnli_5_8_2024_9-05-52%20PM.png?alt=media&amp;token=249cdd7a-3af4-4e4a-84e0-e8b3131e5cbb" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FiZGNOMmwNgetznzOpd3g%2Fscrnli_6_8_2024_2-42-08%20PM.png?alt=media&amp;token=d337d0a1-d55d-4cb3-876c-806337847de8" alt=""><figcaption></figcaption></figure>

3. **Create the Workflow Directory:**
   * In your repository, create a new directory path: `.github/workflows`.

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F5DqiIeX3txynw6vpvCiM%2Fscrnli_2_21_2024_3-26-03%20AM.png?alt=media&amp;token=152acdbf-7c37-4362-b31b-497fbe0c38d8" alt=""><figcaption></figcaption></figure>

4. **Add the Workflow File:**
   * [**Download this `test_cra.yml` file**](https://github.com/gitbito/codereviewagent/blob/main/.github/workflows/test_cra.yml) from AI Code Review Agent's GitHub repo.

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fh4LN96R8F82Y1GYnfsd9%2Fscrnli_4_25_2024_11-33-39%20AM.png?alt=media&amp;token=e6a5a35c-30d2-4420-8f68-7a978d82cb1f" alt=""><figcaption></figcaption></figure>

   * In your repository, upload this `test_cra.yml` file inside the `.github/workflows` directory either in your source branch of each PR or in a branch (e.g. main) from which all the source branches for PRs will be created.

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FgpBbMpIdcmNoAzRPQOfz%2Fscrnli_2_21_2024_3-30-18%20AM.png?alt=media&amp;token=1b48e29b-973e-4c4e-a56f-89a01823798b" alt=""><figcaption></figcaption></figure>

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FfeuTY2qVrnDM9KECS7Nw%2Fscrnli_2_21_2024_3-35-03%20AM.png?alt=media&amp;token=14793b09-2082-4a7e-985f-b5bb03bdfaa6" alt=""><figcaption></figcaption></figure>

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FBHt1t7XeGt0NfW5S8SyF%2Fscrnli_2_21_2024_3-36-52%20AM.png?alt=media&amp;token=70184475-2a52-468d-8f3d-82aad598acd4" alt=""><figcaption></figcaption></figure>

   * Commit your changes.

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F9y1cx93l2yEq6uMyn5mj%2Fscrnli_2_21_2024_3-39-40%20AM.png?alt=media&amp;token=9a58194c-4d80-408f-b01a-f24de236c6ba" alt=""><figcaption></figcaption></figure>

     <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FvHx8lu7qa5sgb3FJWUvY%2Fscrnli_2_21_2024_3-42-14%20AM.png?alt=media&amp;token=9a788f5a-4d6e-4caf-a113-9b392e5efb02" alt=""><figcaption></figcaption></figure>

## Customizations for self-hosted GitHub

1. Create a self-hosted Runner using Linux image and x64 architecture as described in the [**GitHub documentation**](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners).
2. Create a copy of Bito's repository [**gitbito/codereviewagent**](https://github.com/gitbito/CodeReviewAgent) main branch into your self-hosted GitHub organization e.g. "myorg" under the required name e.g. "gitbito-bitocodereview". In this example, now this repository will be accessible as "myorg/gitbito-bitocodereview".
3. Update `test_cra.yml`as below:
   * **Change line from:**
     * runs-on: ubuntu-latest
   * **to:**
     * runs-on: \<label of the self-hosted GitHub Runner> e.g. self-hosted, linux etc.
4. Update `test_cra.yml`as below:
   * **Replace all lines having below text:**
     * uses: gitbito/codereviewagent\@main
   * **with:**
     * uses: myorg/gitbito-bitocodereview\@main
5. Commit and push your changes in `test_cra.yml` .

## Using the AI Code Review Agent

After configuring the GitHub Actions, you can invoke the AI Code Review Agent in the following ways:

{% hint style="info" %}
**Note:** To improve efficiency, the AI Code Review Agent is disabled by default for pull requests involving the **"main"** branch. This prevents unnecessary processing and token usage, as changes to the **"main"** branch are typically already reviewed in release or feature branches. To change this default behavior and include the **"main"** branch, please [**contact support**](mailto:support@bito.ai).
{% endhint %}

1. **Automated Code Review**: The agent will automatically review new pull requests as soon as they are created and post the review feedback as a comment within your PR.
2. **Manually trigger an incremental review:** Type **`/review`** in the comment box on the pull request and submit it. This reviews only the changes made since the last review (such as new commits), keeping feedback focused on what's new.
3. **Manually trigger a full review:** Type **`/review full`** in the comment box and submit it to re-review the entire pull request from scratch, rather than only the latest changes.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong> If an incremental review is already scheduled when you trigger a manual <code>/review</code>, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual <code>/review</code> is treated as a full review so that no changes are missed. To always re-review all changes, use <code>/review full</code>.</p></div>

   Bito also offers specialized commands that are designed to provide detailed insights into specific areas of your source code, including security, performance, scalability, code structure, and optimization.

   * **`/review security`:** Analyzes code to identify security vulnerabilities and ensure secure coding practices.
   * **`/review performance`:** Evaluates code for performance issues, identifying slow or resource-heavy areas.
   * **`/review scalability`:** Assesses the code's ability to handle increased usage and scale effectively.
   * **`/review codeorg`:** Scans for readability and maintainability, promoting clear and efficient code organization.
   * **`/review codeoptimize`:** Identifies optimization opportunities to enhance code efficiency and reduce resource usage.

   By default, the **`/review`** command generates inline comments, meaning that code suggestions are inserted directly beneath the code diffs in each file. This approach provides a clearer view of the exact lines requiring improvement. However, if you prefer a code review in a single post rather than separate inline comments under the diffs, you can include the optional parameter: **`/review #inline_comment=False`**

   For more details, refer to [Available Commands](/ai-code-reviews-in-git/available-commands).

   <figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FryhzTFegsxvL4eoZewT7%2Fscrnli_2_28_2024_8-57-29%20PM.png?alt=media&amp;token=af92cdfb-089b-4f95-8200-52adebe366dd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull request.
{% endhint %}

## Screenshots

### Screenshot # 1

{% hint style="info" %}
*AI-generated pull request (PR) summary*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fk5wsTj4siolCcaZqHRIX%2Fscrnli_9_13_2024_12-33-56%20PM.png?alt=media&amp;token=63cb7da9-21ca-41a1-83ba-9b107d07a6cf" alt=""><figcaption></figcaption></figure>

### Screenshot # 2

{% hint style="info" %}
**Changelist** showing key changes and impacted files in a pull request.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FyH8h3KVhYqjy8nSHQCby%2Fchangelist_by_bito.png?alt=media&amp;token=99c64f3d-f554-47fd-aab7-f2d8d9994c09" alt=""><figcaption><p>Changelist in AI Code Review Agent's feedback.</p></figcaption></figure>

### Screenshot # 3

{% hint style="info" %}
*AI code review feedback posted as comments on the pull request.*
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FP0sUIAZ3Lq0FqL9ytfPF%2Fscrnli_9_13_2024_12-49-29%20PM_cropped_3.png?alt=media&amp;token=d74d3b27-4831-4735-9559-6f9da191e910" alt=""><figcaption></figcaption></figure>


# Agent Configuration: bito-cra.properties File

Setting up your agent: understanding the bito-cra.properties file

{% hint style="info" %}
**Note:** This file is only available for people who are using the [**self-hosted**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service) version of AI Code Review Agent.
{% endhint %}

The **bito-cra.properties** file offers a comprehensive range of options for configuring the [**AI Code Review Agent**](/ai-code-reviews-in-git/overview), enhancing its flexibility and adaptability to various workflow requirements.

## bito-cra.properties Available Options

<table><thead><tr><th width="232" align="center">Property Name</th><th>Supported Values</th><th width="141">Is Mandatory?</th><th>Description</th></tr></thead><tbody><tr><td align="center"><strong>mode</strong></td><td><ul><li>cli</li><li>server</li></ul></td><td>Yes</td><td>Whether to run the Docker container in CLI mode for a one-time code review or as a webhooks service to continuously monitor for code review requests.</td></tr><tr><td align="center"><strong>pr_url</strong></td><td>Pull request URL in GitLab, GitHub and Bitbucket</td><td>Yes, if the mode is CLI.</td><td><p>The pull request provides files with changes and the actual code modifications.<br><br>When the <code>mode</code> is set to <code>server</code>, the <code>pr_url</code> is received either through a webhook call or via a REST API call.</p><p> </p><p>This release only supports webhook calls; other REST API calls are not yet supported.</p></td></tr><tr><td align="center"><strong>code_feedback</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>Setting it to <code>True</code> activates general code review comments to identify functional issues. If set to <code>False</code>, general code review will not be conducted.</td></tr><tr><td align="center"><strong>bito_cli.bito.access_key</strong></td><td><p>A valid Bito Access Key generated through Bito's web UI.</p><p> </p><p><a href="https://docs.bito.ai/account-and-settings/access-key">Learn More</a></p></td><td>Yes</td><td>Bito Access Key is an alternative to standard email and OTP authentication.</td></tr><tr><td align="center"><strong>git.provider</strong></td><td><ul><li>GITLAB</li><li>GITHUB</li><li>BITBUCKET</li></ul></td><td>Yes, if the mode is CLI.</td><td>The name of git repository provider.</td></tr><tr><td align="center"><strong>git.access_token</strong></td><td>A valid Git access token provided by GITLAB or GITHUB or BITBUCKET</td><td>Yes</td><td>You can use a personal access token in place of a password when authenticating to GitHub/GitLab/BitBucket in the command line or with the API.</td></tr><tr><td align="center"><strong>git.domain</strong></td><td>A URL where Git is hosted.</td><td>No</td><td>It is used to enter the custom URL of self-hosted GitHub/GitLab Enterprise.</td></tr><tr><td align="center"><strong>static_analysis</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>Enable or disable static code analysis, which is used to uncover functional issues in the code.</td></tr><tr><td align="center"><strong>static_analysis_tool</strong></td><td><ul><li>fb_infer</li><li>astral_ruff</li><li>mypy</li></ul></td><td>No</td><td>Comma-separated list of static analysis tools to run (e.g., <code>fb_infer,astral_ruff,mypy</code>).</td></tr><tr><td align="center"><strong>linters_feedback</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>Enables feedback from linters like ESLint, golangci-lint, and Astral Ruff.</td></tr><tr><td align="center"><strong>secret_scanner_feedback</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>Enables detection of secrets in code. For example, passwords, API keys, sensitive information, etc.</td></tr><tr><td align="center"><strong>dependency_check</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>This feature is designed to identify security vulnerabilities in open-source dependency packages, specifically for JS/TS/Node.JS and GoLang. Without this input, reviews for security vulnerabilities will not be conducted.</td></tr><tr><td align="center"><strong>dependency_check.snyk_auth_token</strong></td><td>A valid authentication token for accessing Snyk's cloud-based security database.</td><td>No</td><td>If not provided, access to Snyk's cloud-based security database for checking security vulnerabilities in open-source dependency packages will not be available.</td></tr><tr><td align="center"><strong>code_context</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>Enables enhanced code context awareness.</td></tr><tr><td align="center"><strong>server_port</strong></td><td>A valid and available TCP port number.</td><td>No</td><td>This is applicable when the <code>mode</code> is set to <code>server</code>. If not specified, the default value is <code>10051</code>.</td></tr><tr><td align="center"><strong>review_comments</strong></td><td><ul><li>1</li><li>2</li></ul></td><td>No</td><td><p>Set the value to <code>1</code> to display the code review in a single post, or <code>2</code> to show code review as inline comments, placing suggestions directly beneath the corresponding lines in each file for clearer guidance on improvements.</p><p><br>The default value is <code>2</code>.</p></td></tr><tr><td align="center"><strong>review_scope</strong></td><td><ul><li>security</li><li>performance</li><li>scalability</li><li>codeorg</li><li>codeoptimize</li></ul></td><td>No</td><td>Specialized commands to perform detailed analyses on specific aspects of your code.<br><br>You can provide comma-separated values to perform multiple types of code analysis simultaneously.<br><br><a href="/ai-code-reviews-in-git/available-commands#review-scope"><strong>Learn more</strong></a></td></tr><tr><td align="center"><strong>include_source_branches</strong></td><td>Glob/regex pattern.</td><td>No</td><td>Comma-separated list of branch patterns (glob/regex) to allow as pull request sources.</td></tr><tr><td align="center"><strong>include_target_branches</strong></td><td>Glob/regex pattern.</td><td>No</td><td>Comma-separated list of branch patterns (glob/regex) to allow as pull request targets.</td></tr><tr><td align="center"><strong>exclude_files</strong></td><td>Glob/regex pattern.</td><td>No</td><td><p>A list of files/folders that the AI Code Review Agent will not review if they are present in the diff.</p><p></p><p>By default, these files are excluded: <code>*.xml</code>, <code>*.json</code>, <code>*.properties</code>, <code>.gitignore</code>, <code>*.yml</code>, <code>*.md</code><br><br><a href="/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters"><strong>Learn more</strong></a></p></td></tr><tr><td align="center"><strong>exclude_draft_pr</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>A binary setting that enables/disables automated review of pull requests (PR) based on the draft status.<br><br>The default value is <code>True</code> which skips automated review of draft PR.<br><br><a href="/ai-code-reviews-in-git/excluding-files-folders-or-branches-with-filters"><strong>Learn more</strong></a></td></tr><tr><td align="center"><strong>cra_version</strong></td><td><ul><li>latest</li><li>Any specific version tag</li></ul></td><td>No</td><td>Sets the agent version to run (<code>latest</code> or a specific version tag).</td></tr><tr><td align="center"><strong>post_as_request_changes</strong></td><td><ul><li>True</li><li>False</li></ul></td><td>No</td><td>Posts feedback as 'Request changes' review comments. Depending on your organization's Git settings, you may need to resolve all comments before merging.</td></tr><tr><td align="center"><strong>support_email</strong></td><td>Email address</td><td>No</td><td>Contact email shown in error messages.</td></tr><tr><td align="center"><strong>suggestion_mode</strong></td><td><ul><li>essential</li><li>comprehensive</li></ul></td><td>No</td><td><p>Controls AI suggestion verbosity. Available options are <code>essential</code> and <code>comprehensive</code>.<br></p><p>In <strong>Essential</strong> mode, only critical issues are posted as inline comments, and other issues appear in the main review summary under "Additional issues".</p><p><br>In <strong>Comprehensive</strong> mode, Bito also includes minor suggestion and potential nitpicks as inline comments.</p></td></tr></tbody></table>

&#x20;

&#x20;


# Available commands

Invoke the AI Code Review Agent manually or within a workflow.

The [**AI Code Review Agent**](/ai-code-reviews-in-git/overview) offers a suite of commands tailored to developers' needs. You can manually trigger a code review by entering any of these commands in the comment box below a pull/merge request on GitHub, GitLab, or Bitbucket and submitting the comment. Alternatively, if you are using the self-hosted version, you can configure these commands in the [**bito-cra.properties file**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file) for automated code reviews.

{% hint style="info" %}
It may take a few minutes to get the code review posted as a comment, depending on the size of the pull/merge request.
{% endhint %}

## /review

This command provides a broad overview of your code changes, offering suggestions for improvement across various aspects but without diving deep for secure coding or performance optimizations or scalability improvements etc. This makes it ideal for catching general code quality issues that might not necessarily be critical blockers but can enhance readability, maintainability, and overall code health.

Think of it as a first-pass review to identify potential areas for improvement before delving into more specialized analyses.

By default, `/review` performs an **incremental review**. It analyzes only the changes made since the last review (such as new commits pushed after a previous review) rather than re-reviewing the entire pull/merge request. This keeps feedback focused on what's new and avoids repeating suggestions on code that was already reviewed.

{% hint style="info" %}
**Note:** If an incremental review is already scheduled when you trigger a manual `/review`, the scheduled incremental review is skipped to avoid a duplicate review. Also, if the most recent automated review did not complete successfully, a manual `/review` is treated as a full review so that no changes are missed.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FxlP180wDIuX69YbFO92n%2Fimage%20(9).png?alt=media&amp;token=567f8c72-51aa-4682-8946-b540dc3258ec" alt=""><figcaption></figcaption></figure>

## /review full

The `/review full` command performs a manual **full review** of the pull/merge request. Instead of looking only at the changes since the last review, it re-analyzes the entire set of changes in the request from scratch.

**Use case:** Use `/review full` when you want a complete re-review of all changes. For example, after significant rework, or when you want the Agent to reassess the whole request rather than only the latest commits.

**Example:** Add a comment with `/review full` to the pull/merge request.

## Review Scope

Five specialized commands are available to perform detailed analyses on specific aspects of your code. Details for each command are given below.

1. `/review security`
2. `/review performance`
3. `/review scalability`
4. `/review codeorg`
5. `/review codeoptimize`

{% hint style="info" %}
You can provide comma-separated values to perform multiple types of code analysis simultaneously.

**Example:** `/review performance,security,codeoptimize`
{% endhint %}

### Combining general feedback with specialized review scopes

If you'd like to receive general code quality feedback alongside specialized analyses, include the `general` keyword in your review command.

For example, to receive feedback on general code quality, performance, and security, use:

* **Example:** `/review general,performance,security`

This ensures a holistic review encompassing both general code quality and specific areas of concern.

## /review security

This command performs an in-depth analysis of your code to identify vulnerabilities that could allow attackers to steal data, gain unauthorized access, or disrupt your application. This includes checking for weaknesses in input validation, output encoding, authentication, authorization, and session management. It also looks for proper encryption of sensitive data, secure coding practices, and potential misconfigurations that could expose your system.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fp7zoap8rRgTdWt8kqGxN%2Fscrnli_3_28_2024_2-59-52%20AM_1.png?alt=media&amp;token=a4e78f8a-f0e6-4dcc-ba64-1e40a1cbea9b" alt=""><figcaption><p>Highlighting the security vulnerability detected and the proposed solution.</p></figcaption></figure>

## /review performance

This command evaluates the current performance of the code by pinpointing slow or resource-intensive areas and identifying potential bottlenecks. It helps developers understand where the code may be underperforming against expected benchmarks or standards. It is particularly useful for identifying slow processes that could benefit from further investigation and refinement.

This includes checking how well your code accesses data and manages tasks like database interactions and memory usage.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FoUbz3zRLYdIafoSro9AH%2Fscrnli_3_28_2024_3-05-21%20AM_2_1.png?alt=media&amp;token=27535222-fdb7-4ce8-9d58-8ec4c2eede7d" alt=""><figcaption><p>Highlighting the performance issue detected and the proposed solution.</p></figcaption></figure>

## /review scalability

This command analyzes your code to identify potential roadblocks to handling increased usage or data. It checks how well the codebase supports horizontal scaling and whether it is compatible with load balancing strategies. It also ensures the code can handle concurrent requests efficiently and avoids bottlenecks from single points of failure. The command further examines error handling and retry mechanisms to promote system resilience under pressure.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FvDYzSi6S0qB9IymAJtji%2Fscrnli_3_28_2024_3-05-21%20AM_1_1.png?alt=media&amp;token=d0668429-845b-44a8-868d-8addaff3da15" alt=""><figcaption><p>Highlighting the scalability issue detected and the proposed solution.</p></figcaption></figure>

## /review codeorg

This command scans your code for readability, maintainability, and overall clarity. This includes checking for consistent formatting, clear comments, well-defined functions, and efficient use of data structures. It also looks for opportunities to reduce code duplication, improve error handling, and ensure the code is written for future growth and maintainability.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZXYio6wPTj0DsUxW8Uz0%2Fscrnli_3_28_2024_2-53-13%20AM_1.png?alt=media&amp;token=ea6cdeb2-8b20-4c11-b48b-c049e7d9fd26" alt=""><figcaption><p>Highlighting the code structure issue detected and the proposed solution.</p></figcaption></figure>

## /review codeoptimize

This command helps identify specific parts of the code that can be made more efficient through optimization techniques. It suggests refactoring opportunities, algorithmic improvements, and areas where resource usage can be minimized. This command is essential for enhancing the overall efficiency of the code, making it faster and less resource-heavy.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FTKHJZ5xZ5ueLqlAVi7u8%2Fscrnli_3_28_2024_2-01-01%20AM_1.png?alt=media&amp;token=27a7e6c0-77d7-4611-aabf-8eae284e635f" alt=""><figcaption><p>Precise code optimization advice pinpointing exact lines in a file.</p></figcaption></figure>

## Control code review workflow

These commands allow you to manage the AI Code Review Agent's behavior directly within your pull requests across GitHub, GitLab, and Bitbucket.

### /pause

Pauses automatic AI reviews on the current pull request.

**Use case:** Useful when significant changes are underway, and you want to prevent the AI from reviewing incomplete code.

**Example:** Add a comment with `/pause` to the pull request.

### /resume

Resumes the automatic AI reviews that were previously paused on the pull request.

**Use case:** Once your code changes are ready for review, use this command to re-enable the AI's automatic analysis.

**Example:** Add a comment with `/resume` to the pull request.

### /resolve

Marks all Bito-posted review comments as resolved.

**Use case:** After addressing the issues highlighted by the AI, use this command to clean up the comment threads.

**Example:** Add a comment with `/resolve` to the pull request.

{% hint style="info" %}
**Note:** The `/resolve` command is currently supported in GitLab and Bitbucket.
{% endhint %}

### /abort

Cancels all in-progress AI code reviews on the current pull request.

**Use case:** If an AI review is no longer needed or was initiated by mistake, this command stops the process.

**Example:** Add a comment with `/abort` to the pull request.

## Display Code Review in a Single Post

By default, the `/review` command generates inline comments, placing code suggestions directly beneath the corresponding lines in each file for clearer guidance on improvements. If you prefer a single consolidated code review instead of separate inline comments, use the `#inline_comment` parameter and set its value to `False`.

**Example:** `/review #inline_comment=False`

**Example:** `/review scalability #inline_comment=False`

{% hint style="info" %}
**Note:** The `/review` command defaults to `#inline_comment=True`, so you can omit this parameter when its value is `True`.
{% endhint %}


# Chat with AI Code Review Agent

Ask questions about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

Ask questions directly to the AI Code Review Agent regarding its code review feedback. You can inquire about highlighted issues, request alternative solutions, or seek clarifications on suggested fixes.

Real-time collaboration with the AI Code Review Agent accelerates your development cycle. By delivering immediate, actionable insights, it eliminates the delays typically experienced with human reviews. Developers can engage directly with the Agent to clarify recommendations on the spot, ensuring that any issues are addressed swiftly and accurately.

Bito supports over 20 languages—including English, Hindi, Chinese, and Spanish—so you can interact with the AI in the language you’re most comfortable with.

## How to chat?

To start a conversation, type your question directly as a reply to the Agent’s code review comment.&#x20;

The AI Code Review Agent will **analyze your comment and determine** if it’s a valid and relevant question.&#x20;

* If the agent decides it’s a valid question, it will respond with helpful insights.
* If the agent determines it’s unclear, off-topic, or not related to its feedback, it will **not respond**.

To help the agent recognize your question faster, you can also **tag your comment** with **@bitoagent** or **@askbito**. Tagging informs the Agent that your message is intended as a question. However, **tagging does not guarantee a reply**. The agent will still **analyze your comment and decide** whether it is a valid question worth responding to.

Bito usually responds within about 10 seconds.

* On **GitHub** and **Bitbucket**, you may need to manually refresh the page to see the response.
* On **GitLab**, updates happen automatically.

{% hint style="info" %}
**Note:** The AI Code Review Agent will only respond to questions posted as a reply to its own comments.\
It will not reply to questions added on threads that it didn’t start.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FhvDrQ1DMSqIECpvjdstX%2Fscrnli_fUCdzJyMPFpLu9_2.jpg?alt=media&amp;token=89b64664-0bea-4835-afba-5e85372338d2" alt="" width="563"><figcaption></figcaption></figure>

### What you can ask about

When chatting with the AI Code Review Agent, you can ask questions to better understand or improve the code feedback it provided. Here are examples of what you can ask:

* **Clarifications about a highlighted issue**\
  Ask the AI to explain why it flagged a certain line of code or why something might cause a problem.
* **Request for alternative solutions**\
  Request different ways to fix or improve the code beyond what was originally suggested.
* **Deeper explanations**\
  If you want to understand the technical reasoning behind a suggestion (e.g., security concerns, performance impacts, best practices), you can ask for more detailed explanations.
* **Request for examples**\
  Ask the AI to provide an example snippet showing the corrected or improved code.
* **Trade-off discussions**\
  Ask the AI about pros and cons of different approaches it may have suggested (e.g., performance vs. readability).
* **Best practices guidance**\
  Request advice on best practices related to the specific code snippet — such as naming conventions, error handling, optimization tips, or design patterns.
* **Language-specific advice**\
  If you’re working in a particular language (e.g., JavaScript, Python, Java), you can ask for language-specific guidance related to the comment.
* **Request for more context**\
  If the suggestion feels too "short" or "surface level," you can ask the AI to explain more about the broader coding or architectural concept behind its feedback.
* **Security and safety questions**\
  If a suggestion touches on security (like input validation, authentication, or encryption), you can ask for further security-related advice.
* **Testing and validation**\
  Ask the AI if it recommends writing any tests based on its code suggestions and what those tests might look like.

{% hint style="info" %}
**Tip:** Feel free to ask your question in your preferred language! Bito supports over 20 languages, including English, Hindi, Chinese, and Spanish.
{% endhint %}

### What you cannot ask about

The AI can only answer questions related to its **own code review comments**.

* **You cannot** ask general questions about the repository or unrelated topics.
* **You cannot** start a new thread independently — your question must be a reply to a comment made by Bito’s AI Code Review Agent.

If your comment is not linked to a Bito review comment, the AI will **not respond**.


# Implementing custom code review rules

Customize Bito’s AI Code Review Agent to enforce your coding practices.

Bito’s [AI Code Review Agent](/ai-code-reviews-in-git/overview) offers a flexible solution for teams looking to enforce custom code review rules, standards, and guidelines tailored to their unique development practices. Whether your team follows specific coding conventions or industry best practices, you can customize the Agent to suite your needs.

We support three ways to customize AI Code Review Agent’s suggestions:&#x20;

1. [**Provide feedback on Bito-reported issues in pull requests**](#id-1-provide-feedback-on-bito-reported-issues), and the AI Code Review Agent automatically adapts by creating code review rules to prevent similar suggestions in the future.
2. [**Create custom code review guidelines**](#id-2-create-custom-code-review-guidelines). Define rules through the [Custom Guidelines](https://alpha.bito.ai/home/ai-agents/custom-guidelines) dashboard in Bito Cloud and apply them to agent instances in your workspace, or add them directly to your repository using a [.bito.yaml file](/ai-code-reviews-in-git/agent-settings/repo-level-settings).
3. [**Use project-specific guideline files**](#id-3-use-project-specific-guideline-files). Add guideline files (like `.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`) to your repository, and the AI Code Review Agent automatically uses them during pull request reviews to provide feedback aligned with your project's standards.

## 1- Provide feedback on Bito-reported issues

AI Code Review Agent refines its suggestions based on your feedback. When you **provide negative feedback on Bito-reported issues in pull requests**, the Agent automatically adapts by creating **custom code review rules** to prevent similar suggestions in the future.

Depending on your Git platform, you can provide negative feedback in the following ways:

* **GitHub:** Select the checkbox given in feedback question at the end of each Bito suggestion or leave a negative comment explaining the issue with the suggestion.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FREsLjCbSETT4ng9V2urf%2Fscrnli_uijoVDl73Faal3.png?alt=media&amp;token=b3f6ab0e-d06f-435c-9411-2784fe3b4eb8" alt=""><figcaption></figcaption></figure>

* **GitLab:** React with negative emojis (e.g., thumbs down) or leave a negative comment explaining the issue with the suggestion.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FIwUQHSeKUQoOMG2Hkuc5%2Fscrnli_T3dqxb73IGQCQX.png?alt=media&amp;token=55faaf4d-8257-45c5-9a9e-a58598d438a4" alt=""><figcaption></figcaption></figure>

* **Bitbucket:** Provide manual review feedback by leaving a negative comment explaining the issue with the suggestion.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FRagYwO9GOvrNWOkcvAAY%2Fscrnli_1JWWOjCcvIVHRc.png?alt=media&amp;token=83cd24a6-32eb-4b83-8b6e-3fcc704f0c86" alt="" width="563"><figcaption></figcaption></figure>

The **custom code review rules** are displayed on the [**Learned Rules**](https://alpha.bito.ai/home/ai-agents/review-rules) dashboard in Bito Cloud.

These rules are applied at the repository level for the specific programming language.

By default, newly generated custom code review rules are disabled. Once negative feedback for a specific rule reaches a threshold of 3, the rule is automatically enabled. You can also manually enable or disable these rules at any time using the toggle button in the **Status** column.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F5nhsxVcDUiGQB7BG2ubh%2Fscrnli_RSAeHezIwIR9Ja.png?alt=media&amp;token=c026270e-d340-4feb-b648-7fed0e090aa8" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** Providing a positive reaction emoji or comment has no effect and will not generate a new code review rule.
{% endhint %}

After you provide negative feedback, Bito generates a new code review rule in your workspace. The next time the AI Code Review Agent reviews your pull requests, it will automatically filter out the unwanted suggestions.

## 2- **Create custom code review guidelines**

We understand that different development teams have unique needs. To accommodate these needs, we offer the ability to implement **custom code review guidelines** in Bito’s [AI Code Review Agent](/ai-code-reviews-in-git/overview).

Once you add guidelines, the agent will follow them when reviewing pull requests.

You can manage guidelines in two ways:

1. [**Through the Bito Cloud dashboard**](https://alpha.bito.ai/home/ai-agents/custom-guidelines) - Create, apply, and edit guidelines entirely in the web interface
2. [**Using a `.bito.yaml` file**](/ai-code-reviews-in-git/agent-settings/repo-level-settings) - Add custom guidelines directly to your repository for version-controlled, repository-specific configuration

By enabling custom code review guidelines, Bito helps your team maintain consistency and improve code quality.

{% hint style="info" %}
**Note:** Custom review guidelines are available on the [**Professional Plan**](https://bito.ai/pricing/). Enabling this feature will upgrade your workspace to the **Professional Plan**.\
[**Visit pricing page**](https://bito.ai/pricing/)
{% endhint %}

### How to add a guideline

#### Step 1: Open the **Custom Guidelines** tab

* Sign in to [Bito Cloud](https://alpha.bito.ai/).
* Click [Custom Guidelines](https://alpha.bito.ai/home/ai-agents/custom-guidelines) in the sidebar.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FWyaHHs2jeqqtciaNwnlf%2Fscrnli_89a02mkxIZwF1j.png?alt=media&amp;token=2b3ecd82-91b4-44ac-874a-be700e4c5a61" alt=""><figcaption></figcaption></figure>

#### Step 2: Fill the form

**A. Manual setup**

1. Click **Add guidelines** button from the top right.
2. Fill out:
   * **Guideline name**
   * **Language** (select a specific programming language or select **General** if the guideline applies to all languages)
   * **Custom Guidelines and Rules** (enter your guidelines here)
3. Click **Create guideline**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fkf8i8x3CAOFr0DDxkoLY%2Fscrnli_pL9L6X0q4ZzoQu.png?alt=media&amp;token=e6542c5b-c121-422e-b9a5-6c2fd1ecbb35" alt="" width="563"><figcaption></figcaption></figure>

**B. Use a Template**

1. Click **Add guidelines** button from the top right.
2. Choose a template from the **Use template** dropdown menu.
3. Review/edit fields as needed.
4. Click **Create guideline**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FuXpSbSVzVbvHpME4HQJT%2Fscrnli_VbfcVt9RI01jRh.png?alt=media&amp;token=a2997a4e-22d7-4c16-9c37-54548aff0416" alt="" width="563"><figcaption></figcaption></figure>

#### Step 3: Apply to an Agent

* After creating a guideline, you’ll see an **Apply review guideline** dropdown.
* Select the **Agent instance**, then click **Manage review guidelines** to open its settings.

{% hint style="info" %}
**To apply the guideline later:** go to [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent), find the Agent instance, click **Settings**, and manage guidelines there.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FikJjSQFsqVVgbk1X4lrF%2Fscrnli_Hrlv93i7v03AvS.png?alt=media&amp;token=48612ba8-2db3-485e-ba91-7b52182746fb" alt="" width="563"><figcaption></figcaption></figure>

#### Step 4: Save configuration

On the Agent settings page, hit **Save** (top-right) to apply guideline changes.

{% hint style="info" %}
**Note:** Visit the [**Custom Guidelines**](https://alpha.bito.ai/home/ai-agents/custom-guidelines) tab to edit or delete any guideline.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fnn3bFOYEfxzxUJxoDwRA%2Fscrnli_K7jwJZpHs15W6R.png?alt=media&amp;token=ec0ade53-1f64-4128-8008-263a7e765479" alt=""><figcaption></figcaption></figure>

### Managing review guidelines from agent settings

Efficiently control which custom guidelines apply to your AI Code Review Agent through the Agent settings interface.

1. Go to [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) dashboard from the Bito Cloud sidebar.
2. Click **Settings** next to the target agent instance.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FNpRzcdMJCARZJGr6zsfu%2Fscrnli_7EzY56dyc0u017.png?alt=media&amp;token=3a96a9b3-695f-4662-8e2e-dce3731020c9" alt=""><figcaption></figcaption></figure>

3. Navigate to the **Custom Guidelines** section. Here you can either create a new guideline or select from existing guidelines.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FjMyWG2I1k48LEV9gjqjr%2Fscrnli_oktJf4u3e0VkU0.png?alt=media&amp;token=ccb1a18f-1d77-463c-8996-a6e1bb611f9d" alt=""><figcaption></figcaption></figure>

3. **Create a new guideline**
   * If you click **Create a new guideline** button, you will see the same form as mentioned earlier where you can enter the details to create a review guideline.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FvTHf5T3XDheW0tEU8iM4%2Fscrnli_IOT11izz4107ka.png?alt=media&amp;token=19f2da6f-f7e5-4fd9-a274-bf7ee6d1671d" alt=""><figcaption></figcaption></figure>

4. **Or select an existing guideline**
   * If you click **Select from existing guidelines** button, you will get a popup screen from where you can select from a list review guidelines you already created. Use checkboxes to enable or disable each guideline for the selected agent and then click **Add selected**.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FpSCt7YJ81pd4W7n4H5Od%2Fscrnli_3JcRnxBHQ135wD.png?alt=media&amp;token=aa2a8893-4e2f-44ff-9a66-5f960e8ec202" alt=""><figcaption></figcaption></figure>

5. Once you’ve applied or adjusted guidelines, click the **Save** button in the top-right corner to confirm changes.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Ftm0jWnSPBLc49zA8FhGL%2Fscrnli_K7jwJZpHs15W6R.png?alt=media&amp;token=4c5a3503-71a0-48ab-9bad-f805f39bd43a" alt=""><figcaption></figcaption></figure>

### FAQs

#### What types of custom code review guidelines can be implemented?

You can implement a wide range of custom code review guidelines, including:&#x20;

* Style and formatting guidelines&#x20;
* Security best practices&#x20;
* Performance optimization checks&#x20;
* Code complexity and maintainability standards
* etc.

#### Is "custom code review guidelines" feature available in Team Plan?

No, this feature is available on the [**Professional Plan**](https://bito.ai/pricing/). Enabling the **"custom code review guidelines"** feature also upgrades your workspace to the **Professional Plan**.

For more details on **Professional Plan**, visit our [**Pricing Page**](https://bito.ai/pricing/).

## 3- Use project-specific guideline files

The AI Code Review Agent can read guideline files directly from your repository and use them during code reviews. These are the same guideline files that AI coding assistants (like Cursor, Windsurf, and Claude Code) use to help developers write code.

By adding these files to your repository, the agent automatically follows your project's specific coding standards, architecture patterns, and best practices when reviewing pull requests.

### Supported guideline files

The AI Code Review Agent currently supports analyzing the following guideline files that are commonly used by different AI coding agents:

CRA currently supports analyzing the following guideline files that are commonly used by different AI coding agents:

| `.cursor/rules/*.mdc`  | Cursor IDE               |
| ---------------------- | ------------------------ |
| `.windsurf/rules/*.md` | Windsurf IDE             |
| `CLAUDE.md`            | Claude Code              |
| `GEMINI.md`            | Gemini CLI               |
| `AGENTS.md`            | OpenAI CodeX, Cursor IDE |

### How to organize your guideline files

**Multiple files in one directory**

You can split your guidelines across multiple files:

```
.cursor/rules/project-overview.mdc
.cursor/rules/architecture-principles.mdc
.cursor/rules/security-standards.mdc
```

For Windsurf, use the `.md` extension:

```
.windsurf/rules/coding-standards.md
.windsurf/rules/api-patterns.md
```

**Module-specific guidelines:**

Place guideline files in subdirectories to create rules for specific parts of your codebase:

```
.cursor/rules/global-standards.mdc
providers/.cursor/rules/provider-implementation.mdc
auth/.cursor/rules/authentication-rules.mdc
```

The agent finds all relevant guideline files based on which files changed in your pull request.

{% hint style="info" %}
**Note:** Rule precedence (where subdirectory rules override parent-level rules) will be added in a future release. Currently, the agent considers all applicable guideline files equally.
{% endhint %}

### How citations work

Every relevant Bito comment includes a **Citations** section that links to the specific guideline that triggered the comment. The link takes you directly to the relevant line in your guideline file, making it easy to verify the feedback and understand why it was given.

### Example scenario

Let's say you're building an application that integrates multiple LLM providers. Your guideline file specifies:

* All providers must extend the `BaseLLMProvider` class
* All providers must implement standard methods like `generateResponse()` and `streamResponse()`
* New providers must be registered in the `config/providers.json` file

When someone submits a pull request to add a new provider, the agent can catch issues like:

* The new provider doesn't extend the base class
* Required methods are missing
* The provider wasn't added to the configuration file

Each comment links back to the specific guideline, so the developer knows exactly what needs to be fixed.

### Sample guideline file

Here's an example `AGENT.md` file to help you get started:

{% code expandable="true" %}

````markdown
# LLM Proxy Architecture & Design Document

## Document Overview

### Purpose
This document serves as a coding guideline and technical reference for AI agents working with this codebase. It provides comprehensive information about the current architecture, design patterns, implementation details, and the rationale behind design decisions. AI agents should use this document to understand the existing code structure, maintain consistency when making modifications, and follow established patterns when extending functionality.

### What This Document Covers
- **System Architecture**: High-level overview of components and their interactions
- **Design Patterns**: Detailed explanation of the Factory Pattern implementation
- **Component Design**: In-depth analysis of each system component
- **Data Flow**: Request/response lifecycle through the system
- **Design Decisions**: Rationale behind current architectural choices
- **Implementation Details**: Code structure, conventions, and patterns in use

---

## Table of Contents
1. [System Architecture](#system-architecture)
2. [Design Patterns](#design-patterns)
3. [Component Design](#component-design)
4. [Data Flow](#data-flow)
5. [Design Decisions](#design-decisions)
6. [Error Handling Strategy](#error-handling-strategy)
7. [Security Considerations](#security-considerations)
8. [Coding Conventions](#coding-conventions)

---

## System Architecture

### High-Level Overview

The LLM Proxy application follows a layered architecture with clear separation between the presentation layer (FastAPI), business logic layer (Provider implementations), and integration layer (external LLM APIs).

```
┌─────────────────────────────────────────────┐
│           FastAPI Application               │
│         (Presentation Layer)                │
│   - Request validation (Pydantic)           │
│   - Route handling (/chat endpoint)         │
│   - Response formatting                     │
└────────────────┬────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────┐
│          Provider Factory                   │
│        (Abstraction Layer)                  │
│   - Provider selection logic                │
│   - Instance creation                       │
└────────────────┬────────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
┌──────────────┐   ┌──────────────┐
│   OpenAI     │   │  Anthropic   │
│   Provider   │   │   Provider   │
│              │   │              │
│ (Concrete    │   │ (Concrete    │
│  Impl.)      │   │  Impl.)      │
└──────┬───────┘   └──────┬───────┘
       │                  │
       ▼                  ▼
┌──────────────┐   ┌──────────────┐
│  OpenAI API  │   │ Anthropic API│
└──────────────┘   └──────────────┘
```

### Component Layers

1. **Presentation Layer** (`main.py`)
   - Handles HTTP requests/responses
   - Validates input using Pydantic models
   - Manages API endpoints

2. **Abstraction Layer** (`providers/factory.py`)
   - Implements Factory Pattern
   - Routes requests to appropriate providers
   - Decouples client code from concrete implementations

3. **Business Logic Layer** (`providers/*.py`)
   - Abstract base class defines contract
   - Concrete providers implement LLM-specific logic
   - Handles API communication and response parsing

4. **Integration Layer**
   - External API calls via httpx
   - Authentication management
   - Network error handling

---

## Design Patterns

### Factory Design Pattern

The application implements the **Factory Design Pattern** to create provider instances without exposing creation logic to the client.

#### Pattern Components

1. **Abstract Product** (`LLMProvider`)
```python
class LLMProvider(ABC):
    def __init__(self, model: str):
        self.model = model
    
    @abstractmethod
    def generate_response(self, prompt: str) -> str:
        pass
```

**Purpose**: Defines the contract that all concrete providers must implement.

2. **Concrete Products** (`OpenAIProvider`, `AnthropicProvider`)
```python
class OpenAIProvider(LLMProvider):
    def generate_response(self, prompt: str) -> str:
        # OpenAI-specific implementation
        pass
```

**Purpose**: Implement provider-specific logic while adhering to the base contract.

3. **Factory** (`ProviderFactory`)
```python
class ProviderFactory:
    @staticmethod
    def get_provider(provider_name: str, model: str) -> LLMProvider:
        providers = {
            "openai": OpenAIProvider,
            "anthropic": AnthropicProvider
        }
        return providers[provider_name.lower()](model)
```

**Purpose**: Encapsulates provider instantiation logic.

#### Benefits of This Pattern

- **Loose Coupling**: Client code depends on abstractions, not concrete classes
- **Open/Closed Principle**: Open for extension (new providers), closed for modification
- **Single Responsibility**: Each provider handles only its specific implementation
- **Testability**: Easy to mock providers for testing
- **Scalability**: Adding new providers requires minimal changes

---

## Component Design

### 1. Base Provider (`providers/base.py`)

**Responsibility**: Define the contract for all LLM providers

**Key Design Decisions**:
- Uses ABC (Abstract Base Class) to enforce implementation
- Stores model name as instance variable for reuse
- Single abstract method keeps interface simple

**Design Rationale**:
- Python's ABC ensures compile-time checking of implementations
- Simple interface reduces cognitive load for implementers
- Storing model allows for provider-specific model validation in future

### 2. OpenAI Provider (`providers/openai_provider.py`)

**Responsibility**: Implement OpenAI Chat Completions API integration

**Key Features**:
- Environment-based API key management
- Message format conversion (user prompt → OpenAI format)
- Response parsing (extract content from choices)
- Timeout handling (30 seconds)

**API Contract**:
```
POST https://api.openai.com/v1/chat/completions
Headers: Authorization: Bearer <key>
Body: {
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "prompt"}]
}
```

**Error Handling**:
- Validates API key presence on initialization
- Catches HTTP errors and wraps with descriptive messages
- Re-raises exceptions for upstream handling

### 3. Anthropic Provider (`providers/anthropic_provider.py`)

**Responsibility**: Implement Anthropic Messages API integration

**Key Features**:
- Custom header format (x-api-key, anthropic-version)
- Max tokens configuration (1024)
- Content array response parsing

**API Contract**:
```
POST https://api.anthropic.com/v1/messages
Headers: 
  x-api-key: <key>
  anthropic-version: 2023-06-01
Body: {
  "model": "claude-3-sonnet",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "prompt"}]
}
```

**Design Choices**:
- Hard-coded max_tokens provides consistent behavior
- Version header ensures API stability
- Array access for content assumes single response

### 4. Provider Factory (`providers/factory.py`)

**Responsibility**: Create provider instances based on string identifiers

**Implementation Strategy**:
- Dictionary-based mapping for O(1) lookup
- Case-insensitive provider names
- Descriptive error messages for invalid providers

**Extensibility**:
```python
# Adding new provider:
providers = {
    "openai": OpenAIProvider,
    "anthropic": AnthropicProvider,
    "deepseek": DeepseekProvider,  # Just add here
}
```

### 5. FastAPI Application (`main.py`)

**Responsibility**: HTTP interface and request orchestration

**Key Components**:

1. **Request Model**:
```python
class ChatRequest(BaseModel):
    provider: str
    model: str
    prompt: str
```
- Leverages Pydantic for automatic validation
- Clear field names match user expectations

2. **Response Model**:
```python
class ChatResponse(BaseModel):
    provider: str
    model: str
    response: str
```
- Echoes input parameters for traceability
- Returns plain text response

3. **Endpoint Handler**:
```python
@app.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    provider = ProviderFactory.get_provider(request.provider, request.model)
    response_text = provider.generate_response(request.prompt)
    return ChatResponse(...)
```

**Error Mapping**:
- `ValueError` (invalid provider) → HTTP 400
- Generic `Exception` (API errors) → HTTP 500

---

## Data Flow

### Request Lifecycle

```
1. Client sends POST /chat
   ↓
2. FastAPI receives request
   ↓
3. Pydantic validates request body
   ↓
4. ProviderFactory.get_provider() called
   ↓
5. Factory returns concrete provider instance
   ↓
6. provider.generate_response() called
   ↓
7. Provider makes HTTP call to LLM API
   ↓
8. Provider parses response
   ↓
9. Response wrapped in ChatResponse model
   ↓
10. JSON response sent to client
```

### Detailed Flow Example (OpenAI)

```python
# Client Request
POST /chat
{
  "provider": "openai",
  "model": "gpt-4",
  "prompt": "Tell me a joke"
}

# Internal Processing
1. Pydantic validates: ChatRequest object created
2. Factory called: ProviderFactory.get_provider("openai", "gpt-4")
3. OpenAIProvider instantiated with model="gpt-4"
4. generate_response("Tell me a joke") called
5. HTTP POST to OpenAI API:
   {
     "model": "gpt-4",
     "messages": [{"role": "user", "content": "Tell me a joke"}]
   }
6. OpenAI responds with completion
7. Extract: data["choices"][0]["message"]["content"]
8. Return text to endpoint
9. Wrap in ChatResponse

# Client Response
{
  "provider": "openai",
  "model": "gpt-4",
  "response": "Why did the chicken cross the road?..."
}
```

---

## Design Decisions

### 1. Why Factory Pattern?

**Decision**: Use Factory Pattern instead of simple if/else logic

**Rationale**:
- **Scalability**: Adding providers doesn't require modifying existing code
- **Testability**: Easy to mock factory for unit tests
- **Maintainability**: Provider logic isolated in separate classes
- **Professional Standard**: Industry-recognized pattern for this use case

**Alternative Considered**: Direct instantiation with if/else
```python
# Rejected approach
if provider == "openai":
    result = OpenAIProvider(model).generate_response(prompt)
elif provider == "anthropic":
    result = AnthropicProvider(model).generate_response(prompt)
```
**Why Rejected**: Violates Open/Closed Principle, harder to extend

### 2. Why httpx Over Official SDKs?

**Decision**: Use httpx for HTTP calls instead of official provider SDKs

**Rationale**:
- **Minimal Dependencies**: Keeps requirements.txt small
- **Unified Interface**: Single HTTP client for all providers
- **Transparency**: Direct API calls are easier to debug
- **Control**: Full control over request/response handling

**Trade-offs**:
- Less abstraction (must handle response parsing)
- No built-in retry logic
- Manual API version management

### 3. Synchronous vs Asynchronous

**Decision**: Use synchronous HTTP calls with httpx.Client

**Rationale**:
- **Simplicity**: Easier to understand and debug
- **Current Scale**: Single request doesn't benefit from async
- **API Constraints**: LLM APIs are inherently blocking

**Future Consideration**: Switch to async if supporting streaming responses

### 4. Error Handling Strategy

**Decision**: Simple try/except with HTTP status code mapping

**Rationale**:
- **Simplicity**: Requirements specified basic error handling
- **Client Clarity**: HTTP status codes are standard
- **Debugging**: Error messages preserved in exceptions

**Not Included** (but recommended for production):
- Structured logging
- Retry logic
- Rate limiting
- Circuit breakers

### 5. Environment Variables for API Keys

**Decision**: Use environment variables instead of configuration files

**Rationale**:
- **Security**: Prevents accidental commit of credentials
- **12-Factor App**: Follows best practices for configuration
- **Flexibility**: Easy to change without code modification
- **Cloud-Ready**: Works seamlessly with container orchestration


---

## Error Handling Strategy

### Current Implementation

```python
try:
    provider = ProviderFactory.get_provider(request.provider, request.model)
    response_text = provider.generate_response(request.prompt)
    return ChatResponse(...)
except ValueError as e:
    # Invalid provider name
    raise HTTPException(status_code=400, detail=str(e))
except Exception as e:
    # API errors, network issues, etc.
    raise HTTPException(status_code=500, detail=str(e))
```

### Error Categories

1. **Client Errors (400)**:
   - Invalid provider name
   - Unsupported model
   - Malformed request

2. **Server Errors (500)**:
   - Missing API keys
   - Network timeouts
   - API errors (rate limits, service unavailable)
   - Response parsing failures


---

## Security Considerations

### Current Implementation

1. **API Key Management**:
   - Stored in environment variables
   - Never logged or returned in responses
   - Validated on provider initialization

2. **Request Validation**:
   - Pydantic models enforce type safety
   - No SQL injection risk (no database)
   - No command injection (no shell execution)

### Current Limitations

1. **No Rate Limiting**: The application does not implement rate limiting
2. **No Authentication**: Endpoints are publicly accessible
3. **No Input Sanitization**: Prompt length and content are not validated beyond Pydantic type checking
4. **No Retry Logic**: Failed API calls are not automatically retried

---

## Coding Conventions

### File Organization

**Current Structure**:
```
llm-proxy/
├── main.py                      # FastAPI application entry point
├── providers/                   # Provider package
│   ├── __init__.py             # Package exports
│   ├── base.py                 # Abstract base class
│   ├── openai_provider.py      # OpenAI implementation
│   ├── anthropic_provider.py   # Anthropic implementation
│   └── factory.py              # Factory implementation
├── requirements.txt             # Python dependencies
├── .env.example                # Environment variable template
└── README.md                   # User documentation
```

### Naming Conventions

1. **Classes**: PascalCase (e.g., `LLMProvider`, `OpenAIProvider`)
2. **Functions/Methods**: snake_case (e.g., `generate_response`, `get_provider`)
3. **Constants**: UPPER_SNAKE_CASE (e.g., `OPENAI_API_KEY`)
4. **Files**: snake_case (e.g., `openai_provider.py`)

### Code Patterns

1. **Provider Implementation**:
   - Inherit from `LLMProvider`
   - Validate API key in `__init__`
   - Implement `generate_response(prompt: str) -> str`
   - Use httpx.Client with 30-second timeout
   - Wrap errors with descriptive messages

2. **Error Handling**:
   - Use `try/except` blocks in provider implementations
   - Raise `ValueError` for missing API keys
   - Raise generic `Exception` with descriptive messages for API errors
   - Let FastAPI endpoint handle HTTP status code mapping

3. **Environment Variables**:
   - Load with `os.getenv()`
   - Validate presence in provider `__init__`
   - Use pattern: `{PROVIDER}_API_KEY`

4. **Type Hints**:
   - All methods should include type hints
   - Use Pydantic models for request/response validation
   - Return type explicitly stated

### Documentation Standards

1. **Docstrings**: All classes and methods include docstrings
2. **Comments**: Inline comments explain non-obvious logic
3. **README**: User-facing documentation with examples

### Dependencies

**Current Dependencies**:
- `fastapi==0.109.0`: Web framework
- `uvicorn[standard]==0.27.0`: ASGI server
- `pydantic==2.5.3`: Data validation
- `httpx==0.26.0`: HTTP client
- `python-dotenv==1.0.0`: Environment variable management

**Rationale**: Minimal, well-maintained dependencies that serve specific purposes.

---

## Summary

This document captures the current state of the LLM Proxy application. When working with this codebase, AI agents should:

1. **Follow the Factory Pattern**: All new providers must inherit from `LLMProvider` and be registered in `ProviderFactory`
2. **Maintain Consistency**: Use the same error handling, timeout values, and code structure as existing providers
3. **Respect Abstractions**: Keep provider-specific logic within provider classes
4. **Update Documentation**: Any changes to architecture should be reflected in this document
5. **Preserve Simplicity**: The design prioritizes simplicity and clarity over advanced features

The architecture demonstrates clean separation of concerns through the Factory Design Pattern, making the codebase maintainable and understandable for both human developers and AI agents.

````

{% endcode %}


# Excluding files, folders, or branches with filters

Customize which files, folders, and Git branches are reviewed when the Agent triggers automatically on pull requests.

The [AI Code Review Agent](/ai-code-reviews-in-git/overview) offers powerful filters to exclude specific files and folders from code reviews and gives you precise control over which Git branches are included in automated reviews.

These filters can be configured at the Agent instance level, overriding the default behavior.

## Exclude Files and Folders filter

A list of files/folders that the AI Code Review Agent will not review if they are present in the diff. You can specify the files/folders to exclude from the review by name or glob/regex pattern. The Agent will automatically skip any files or folders that match the exclusion list.

This filter applies to both manual reviews initiated through the `/review` command and automated reviews triggered via webhook.

By default, these files are excluded: `*.xml`, `*.json`, `*.properties`, `.gitignore`, `*.yml`, `*.md`

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F8qrlYfC2AhUXtfITPKks%2Fscrnli_67LP18Ctwr8Zli.png?alt=media&amp;token=91709f9b-b295-412e-8595-af17eac6cf53" alt=""><figcaption></figcaption></figure>

### Examples

{% hint style="info" %}
**Note:**

* Patterns are case sensitive.
* Don’t use double quotes, single quotes or comma in the pattern.
* Users can pass both types of patterns - Unix files system based glob pattern or regex.
  {% endhint %}

| Exclusion Rule for Files & Folders                                                                      | Applicable Pattern                       | Matched Examples                                                                                                                                 | Not Matched Examples                                                          |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Exclude all properties files in all folders and subfolders                                              | `*.properties`                           | `resource/config.properties`, `resource/server/server.properties`                                                                                | `resource/config.yaml`, `resource/config.json`                                |
| Exclude all files, folders and subfolders in folder starting with `resources`                           | `resources/`                             | `resources/application.properties`, `resources/config/config.yaml`                                                                               | `app/resources/file.txt`, `config/resources/service.properties`               |
| Exclude all files, folders and subfolders in folder `src/com/resources`                                 | `src/com/resources/`                     | `resources/application.properties`, `resources/config/config.yaml`                                                                               | `app/resources/file.txt`, `config/resources/service.properties`               |
| Exclude all files, folders and subfolders in subfolder `resource` and in parent folder `src`            | `src/*/resource/*`                       | <p><code>src/com/resource/main.html</code>,</p><p><code>src/com/resource/script/file.css</code>, <code>src/com/resource/app/script.js</code></p> | `src/resource/file.txt`, `src/com/config/file.txt`, `app/com/config/file.txt` |
| Exclude non-css files from folder `src/com/resource/` and subfolders                                    | `^src\/com\/resource\\/(?!.*\\.css$).*$` | <p><code>src/com/resource/main.html, src/com/resource/app/script.js</code>, </p><p><code>src/com/config/file.txt</code></p>                      | `src/com/resource/script/file.css`                                            |
| Exclude specific file `controller/webhook_controller.go`                                                | `controller/webhook_controller.go`       | `controller/webhook_controller.go`                                                                                                               | `controller/controller.go`, `controller/webhook_service.go`                   |
| Exclude non-css files from folder starting with `config` and its subfolders                             | `^config\\/(?!.*\\.css$).*$`             | `config/server.yml`, `config/util/conf.properties`                                                                                               | `config/profile.css`, `config/styles/main.css`                                |
| Exclude all files & folders                                                                             | `*`                                      | `resource/file.txt`, `config/file.properties`, `app/folder/`                                                                                     | `-`                                                                           |
| Exclude all files & folders starting with name `bito` in `module` folder                                | `module/bito*`                           | `module/bito123`, `module/bitofile.js`, `module/bito/file.js`                                                                                    | `module/filebito.js`, `module/file2.txt`, `module/util/file.txt`              |
| Exclude single-character folder names                                                                   | `*/?/*`                                  | `src/a/file.txt`, `app/b/folder/file.yaml`                                                                                                       | `folder/file.txt`, `ab/folder/file.txt`                                       |
| Exclude all folders, subfolders and files in those folders except folder starting with `service` folder | `^(?!service\\/).*$`                     | `config/file.txt`, `resources/file.yaml`                                                                                                         | `service/file.txt`, `service/config/file.yaml`                                |
| Exclude all files in all folders except `.py`, `.go`, and `.java` files                                 | `^(?!.*\\.(py\|go\|java)$).*$`           | `config/file.txt`, `app/main.js`                                                                                                                 | `main.py`, `module/service.go`, `test/Example.java`                           |
| Exclude non-css files from folder `src/com/config` and its subfolders                                   | `^config\\/(?!.*\\.css$).*$`             | `config/server.yml`, `config/util/conf.properties`                                                                                               | `config/profile.css`, `config/styles/main.css`                                |

## Include Source/Target Branches filter

This filter defines which pull requests trigger automated reviews based on their source or target branch, allowing you to focus on critical code and avoid unnecessary reviews or AI usage.

By default, pull requests merging into the repository’s default branch are subject to review. To extend review coverage, additional branches may be specified using explicit branch names or valid glob/regex patterns. When the source or target branch of a pull request matches one of the patterns on your inclusion list, Bito’s AI Code Review Agent will trigger an automated review.

This filter applies only to automatically triggered reviews. Users should still be able to trigger reviews manually via the `/review` command.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F00UMeHuAITRMKGaBoZjO%2Fscrnli_P386e3Jr001VDd.png?alt=media&amp;token=826ced85-028e-4317-852e-05ac8185a80b" alt=""><figcaption></figcaption></figure>

**Watch video tutorial:**

{% embed url="<https://youtu.be/31h8V-ip0J8>" %}

### Examples

{% hint style="info" %}
**Note:**

* Patterns are case sensitive.
* Don’t use double quotes, single quotes or comma in the pattern.
* Users can pass both types of patterns - Unix files system based glob pattern or regex.
  {% endhint %}

| Inclusion Rules for Branch                                                                                         | Pattern                                               | Matched Examples                                | Not Matched Examples                                |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------- |
| Include any branch that starts with name `BITO-`                                                                   | `BITO-*`                                              | `BITO-feature`, `BITO-123`                      | `feature-BITO`, `development`                       |
| Include any branch that does not start with `BITO-`                                                                | `^(?!BITO-).*`                                        | `feature-123`, `release-v1.0`                   | `BITO-feature`, `BITO-123`                          |
| Include any branch which is not `BITO`                                                                             | `^(?!BITO$).*`                                        | `feature-BITO`, `development`                   | `BITO`                                              |
| Include branches like `release/v1.0` and `release/v1.0.1`                                                          | `release/v\\d+\\.\\d+(\\.\\d+)?`                      | `release/v1.0`, `release/v1.0.1`                | `release/v1`, `release/v1.0.x`                      |
| Include any branch ending with `-test`                                                                             | `*-test`                                              | `feature-test`, `release-test`                  | `test-feature`, `release-testing`                   |
| Include the branch that has keyword `main`                                                                         | `main`                                                | `main`, `main-feature`, `mainline`              | `master`, `development`                             |
| Include the branch named `main`                                                                                    | `^main$`                                              | `main`                                          | `main-feature`, `mainline`, `master`, `development` |
| Include any branch name that does not start with `feature-` or `release-`                                          | `^(?!release-\|feature-).*$`                          | `hotfix-123`, `development`                     | `feature-123`, `release-v1.0`                       |
| Include branches with names containing digits                                                                      | `.*\\d+.*`                                            | `feature-123`, `release-v1.0`                   | `feature-abc`, `main`                               |
| Include branches with names ending with `test` or `testing`                                                        | `.*(test\|testing)$`                                  | `feature-test`, `bugfix-testing`                | `testing-feature`, `test-branch`                    |
| Include branches with names containing a specific substring `test`                                                 | `*test*`                                              | `feature-test`, `test-branch`, `testing`        | `feature`, `release`                                |
| Include branches with names containing exactly three characters                                                    | `^.{3}$`                                              | `abc`, `123`                                    | `abcd`, `ab`                                        |
| Include branch names starting with `release`, `hotfix`, or `development` but not starting with `Bito` or `feature` | `^(?!Bito\|feature)(release\|hotfix\|development).*$` | `release-v1.0`, `hotfix-123`, `development-xyz` | `Bito-release`, `feature-hotfix`, `main-release`    |
| Include all branches where name do not contains version like `1.0`, `1.0.1`, etc.                                  | `^(?!.\\b\\d+\\.\\d+(\\.\\d+)?\\b).*`                 | `feature-xyz`, `main`                           | `release-v1.0`, `hotfix-1.0.1`                      |
| Include all branches which are not alphanumeric                                                                    | `^.[^a-zA-Z0-9].$`                                    | `feature-!abc`, `release-@123`                  | `feature-123`, `release-v1.0`                       |
| Include all branches which contains space                                                                          | `.*\\s.*`                                             | `feature 123`, `release v1.0`                   | `feature-123`, `release-v1.0`                       |

## Draft pull requests filter

A binary setting that enables/disables automated review of pull requests (PR) based on the draft status. Enter `True` to disable automated review for draft pull requests, or `False` to enable it.

The default value is `True` which skips automated review of draft PR.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Feq4VAtW5pzAXmMb56Tkh%2Fscrnli_6lY6vx73F6U1U6.png?alt=media&amp;token=34238de9-542e-490f-a9df-4d2daf762e21" alt=""><figcaption></figcaption></figure>

## How to configure the filters?

### Bito Cloud (Bito-hosted Agent)

You can configure filters using the Agent configuration page. For detailed instructions, please refer to the [**Install/run Using Bito Cloud**](/ai-code-reviews-in-git/install-run-using-bito-cloud) documentation page.

### CLI or webhooks service (self-hosted Agent)

You can configure filters using the [**bito-cra.properties file**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file). Check the options `exclude_branches`, `exclude_files`, and `exclude_draft_pr` for more details.

### GitHub Actions (self-hosted Agent)

You can configure filters using the GitHub Actions repository variables: `EXCLUDE_BRANCHES`, `EXCLUDE_FILES`, and `EXCLUDE_DRAFT_PR`. For detailed instructions, please refer to the [**Install/Run via GitHub Actions**](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/install-run-via-github-actions) documentation page.


# Code review analytics

Get in-depth insights into your code review process.

The user-friendly [**Code Review Analytics**](https://alpha.bito.ai/home/dashboard?view=overview) dashboards help you track key metrics such as pull requests reviewed, issues found, lines of code reviewed, and understand individual contributions.

This helps you identify trends and optimize your development workflow.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FKxLzGfPTC4vu4aOQKb9O%2Fscrnli_Ir0TnJTHsuycit.png?alt=media&amp;token=e64bd906-58d6-4fad-a9e7-efb7d1dff7b2" alt=""><figcaption><p>Code Review Analytics dashboard</p></figcaption></figure>

Bito provides four distinct analytical views to help you understand your code review performance from multiple perspectives:

1. [**Overview**](#overview-dashboard): High-level workspace metrics and trends
2. [**Submitter Analytics**](#submitter-analytics-dashboard): Individual contributor performance and patterns
3. [**Repository Analytics**](#repository-analytics-dashboard): Repository and language-specific insights
4. [**PR Analytics**](#pr-analytics-dashboard): Detailed pull request and issue tracking

## "Overview" dashboard

The [**Overview dashboard**](https://alpha.bito.ai/home/dashboard?view=overview) provides a comprehensive high-level view of your workspace's code review performance, showing pull requests reviewed, issues found, and their categorization.

### Key metrics:

* **Code Requests Reviewed - This Month**: Total number of code reviews completed by Bito, including both pull requests from git workflows and IDE-based reviews
* **Lines Reviewed - This Month**: Total lines of code analyzed across all pull request diffs
* **Repositories Reviewed - This Month**: Number of unique repositories that received code review coverage
* **Submitters - This Month**: Count of unique developers (based on Git handles) whose pull requests were reviewed by Bito
* **Issues Found - This Month**: Total number of issues identified across all reviewed code
* **Issues Categories - This Month**: Visual breakdown of issues by primary categories (Security, Performance, Functionality, etc.)
  * *Note: When issues span multiple categories, Bito assigns the most relevant primary category*
* **Merged PRs - This Month**: Number of Bito-reviewed pull requests that were subsequently merged or closed
* **Issues Evaluated for Acceptance Rate - This Month**: Issues in merged pull requests evaluated for potential fixes
* **Acceptance Rate (Merged PRs) - This Month**: Percentage of agent-identified issues that were potentially addressed
  * *Calculated based on code changes detected in related hunks when pull requests were merged*
  * *Available for reviews conducted on or after August 8th, 2024*
  * *Note: This is an approximation based on code change detection*
* **Pull Requests Skipped - This Month**: Pull requests excluded from review due to:
  * Matching exclusion filters in agent configuration
  * Empty diffs
  * Invalid Bito plan status
* **Skip Reason - This Month**: Breakdown of why specific pull requests were skipped

{% hint style="info" %}
Use the **Filters** button (top-right) to customize your view. You can also export the data to PowerPoint or PDF using the **Share menu** button (top-right).
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FqJ0D9jAs0glc0H9ROZJR%2Fscrnli_yyMt5LrYSUQ3qJ.png?alt=media&amp;token=e16114e3-7331-402e-972a-425239827e85" alt=""><figcaption></figcaption></figure>

## "Submitter Analytics" dashboard

The [**Submitter Analytics dashboard**](https://alpha.bito.ai/home/dashboard?view=Submitter_Analytics) helps you gain insights into individual contributor patterns and performance with user-level statistics and visualizations.

### Key metrics:

* **Pull Requests Reviewed - This Month**: Number of pull requests reviewed for each developer. It helps you identify most active team members.
  * Shows top 30 contributors by pull request count
  * Remaining contributors aggregated under 'Other'
* **Lines of Code Reviewed - This Month**: Lines of code reviewed by Bito per developer. It is useful for understanding workload distribution.
  * Displays contributors with minimum 100 lines reviewed
  * Top 30 contributors shown individually
  * Remaining contributors grouped under 'Other'
* **Issues Reported Per 1K Lines - This Month**: Issue density normalized by code volume for developers with at least 1,000 lines of code, enabling fair comparison across different contribution levels. It helps identify patterns in code quality by developer
* **Issue Distribution by Category - This Month**: Breakdown of issues by type for each developer, showing both total count and percentage. Categories with fewer than 5 issues are excluded, with bar height representing total issues and width showing percentage distribution. It helps identify individual strengths and areas for improvement.

{% hint style="info" %}
Use the **Filters** button (top-right) to customize your view. You can also export the data to PowerPoint or PDF using the **Share menu** button (top-right).
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FYwQ2asUTRCbyoOknsNn3%2Fscrnli_Yl7Tdpt26UqS9f.png?alt=media&amp;token=494a6728-7373-46eb-8676-9c4032c6d700" alt=""><figcaption></figcaption></figure>

## "Repository Analytics" dashboard

The [**Repository Analytics dashboard**](https://alpha.bito.ai/home/dashboard?view=Repository_Analytics) helps you understand repository-level performance and language-specific trends across your codebase.

### Key metrics:

* **Pull Requests Reviewed - This Month**: Review activity across repositories (top 30 shown, remainder grouped as 'Other'). It identifies which codebases receive most attention.
* **Lines of Code Reviewed (Repo) - This Month**: Lines of code reviewed by Bito in each repository (top 30 displayed individually). It helps you understand where development effort is concentrated.
* **Lines of Code Reviewed (Language) - This Month**: Breakdown of reviewed code by programming language. It is useful for resource allocation and expertise planning.
* **Issues Reported Per 1K Lines (Repo) - This Month**: Issue density for repositories with at least 1,000 lines of changes. It identifies repositories that may need additional attention
* **Issues Reported Per 1K Lines (Language) - This Month**: Issue rates across different programming languages (minimum 100 lines required). It helps you identify language-specific training needs.
* **Issue Distribution by Category × Language - This Month**: Issues categorized by both type and programming language, with visualization showing total count (bar height) and percentage distribution (bar width). Categories with fewer than 5 issues excluded. It reveals language-specific issue patterns.
* **Issue Distribution by Category × Repo - This Month**: Issues analyzed across category and repository dimensions, excluding categories with fewer than 5 issues. The visualization shows total issues (bar height) and percentage distribution (bar width). It identifies repository-specific issue trends.

{% hint style="info" %}
Use the **Filters** button (top-right) to customize your view. You can also export the data to PowerPoint or PDF using the **Share menu** button (top-right).
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FooK9QmyVwWBYNrvttO9o%2Fscrnli_4gE0fJ9rkURd5b.png?alt=media&amp;token=5824e6d1-a2b6-4cd1-9352-54915880adf7" alt=""><figcaption></figcaption></figure>

## "PR Analytics" dashboard

The [**PR Analytics dashboard**](https://alpha.bito.ai/home/dashboard?view=PR_Analytics) helps you dive deep into individual pull request performance with detailed pull request and issue-level analytics.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FXudgINW1mbwoPtnazD78%2Fscrnli_II4AGo4vqv2vVE.png?alt=media&amp;token=e7a12ffb-3f68-4b03-af66-fa6663c1dd01" alt=""><figcaption></figcaption></figure>

The dashboard organizes pull requests into three tabs:

### **1. "Reviewed (Feedback)" tab**

* Shows pull requests where Bito provided actionable feedback
* These pull requests contain issues that require your attention
* Click any pull request to access comprehensive details including every feedback item with its category (Security, Performance, Linter, Functionality, etc.), affected programming language, and direct links to the specific code location within the pull request for quick reference.
* Useful for tracking reviews that generated value

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2Fkegk2JYQHNFNdJgHpBJq%2Fscrnli_22JO8JVrE9yVoM.png?alt=media&amp;token=48aa58b4-a94b-4b7c-a350-ff27c21a4748" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FWW4ljirRWUKEBGEHAKoL%2Fscrnli_E38sxBtZlAhnF5.png?alt=media&amp;token=f1c178a7-eaf5-4aa1-a32e-dc05b9b1b0b7" alt=""><figcaption></figcaption></figure>

### **2. "Reviewed (No Feedback)" tab**

* Shows pull requests that Bito reviewed but found no actionable issues
* Indicates clean code submissions

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FxCfH9nvhHWZrm3LaFHz0%2Fscrnli_90KG4YxvxuK0RP_1.png?alt=media&amp;token=814f9f19-8ca6-4960-bc88-34b197ce60c3" alt=""><figcaption></figcaption></figure>

### **3. "Skipped" tab**

* Shows pull requests that Bito didn't review due to configuration settings or other constraints
* Includes skip reasons for transparency

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FkveUgvqJzQjAZZ6I9n1R%2Fscrnli_02ms4739jUKR2y_1.png?alt=media&amp;token=6c8e777c-65b2-4924-bdab-d7b24055d524" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Use the **Filter** button (top-left) to customize views by:

* Specific submitters
* Date ranges
* Pull request status
  {% endhint %}

## **Benefits for technical leadership**

The detailed code review analytics reports enables tech leads and reviewers to:

* **Trace patterns**: Identify recurring issues across pull requests
* **Spot trends**: Recognize systematic problems in code quality
* **Connect insights**: Link high-level analytics to specific code examples
* **Targeted mentoring**: Provide specific guidance based on actual code issues
* **Process improvement**: Adjust development practices based on concrete data

## Best practices for using analytics

#### 1. Regular review cadence

* Check [Overview](#overview-dashboard) metrics for trend monitoring
* Review [Submitter Analytics](#submitter-analytics-dashboard) for team performance discussions
* Analyze [Repository Analytics](#repository-analytics-dashboard) for strategic planning
* Use [PR Analytics](#pr-analytics-dashboard) for issue tracking and mentoring

#### 2. Filtering for insights

* Use date filters to compare time periods
* Filter by specific teams or repositories during retrospectives
* Focus on high-activity contributors or repositories for targeted improvements

#### 3. Export and sharing

* Export monthly reports for stakeholder updates
* Share repository-specific insights with relevant teams
* Use PowerPoint exports for executive presentations
* Archive PDF reports for compliance or historical analysis

#### 4. Action-oriented analysis

* Identify submitters who might benefit from additional code review training
* Focus attention on repositories with high issue density
* Address language-specific patterns through targeted workshops
* Use acceptance rate trends to validate review effectiveness


# Request changes comments

Block merges until code issues are fixed.

Bito’s **Request changes comments** feature helps enforce code quality by blocking merges until all AI-generated review comments are resolved—fully supported in GitHub, GitLab, and Bitbucket.

When enabled, Bito identifies actionable issues in pull requests and posts them as **formal “Request changes” review comments**. If your repository uses **branch protection rules** that require all review conversations to be resolved before merging, Bito’s flagged comments will automatically block the pull request until addressed.

This ensures developers don’t accidentally merge incomplete or unreviewed code.

{% embed url="<https://youtu.be/E_2awjmFBfo>" %}

## How it works

### 1. Enable comment resolution rules in your Git provider

#### **GitHub:**

* Go to your repository → **Settings** → **Branches**
* Create or edit a branch protection rule (e.g., for `main`)
* Enable:
  * ✅ Require a pull request before merging
  * ✅ Require conversation resolution before merging

#### **GitLab:**

* Go to your project → **Settings** → **Merge requests**
* Under **Merge checks**, enable:
  * ✅ All threads must be resolved
* Click **Save changes** button.

#### **Bitbucket:**

* Go to your repository → **Repository settings** → **Branch restrictions**
* Click **Add a branch restriction** button.
* Under **Select branches**, define the target branches where this restriction should apply. Pull requests merging into these branches will be blocked until all "Request changes" comments are resolved. You can choose one of two options:
  * **By branch name or pattern**: Enter a specific branch name (e.g., `main`) or use a wildcard pattern to cover multiple branches. For example, using an asterisk `*` applies the restriction across all branches, while `release/*` applies it to every release branch.
  * **By branch type**: Select a branch type (e.g., `development`, `release`) from the dropdown menu.
* Switch to **Merge settings** tab.
* Under **Merge checks**, enable:
  * ✅ No changes are requested
* Under **Merge conditions**, enable:
  * ✅ Prevent a merge with unresolved merge checks
  * ***Note:** This setting is only available if your organization uses **Bitbucket Cloud Premium**. It will block anyone from merging the PR if there are unresolved "request change" comments.*\
    *On **Standard Bitbucket Cloud**, this option is unavailable; users will see a warning if they attempt to merge with unresolved "request change" comments, but the merge will still be allowed.*
* Click **Save** button.

{% hint style="info" %}
**Note:** Request change comments usually have to be resolved by the person who posted them. Since here these comments are posted by Bito, the user must comment **`/resolve`** in the pull request to resolve them.
{% endhint %}

### 2. Turn on “Request changes comments” in Bito

* Go to **Repositories** in the Bito dashboard.
* Click on **Settings** for your desired AI Code Review Agent instance.
* Enable the toggle: **“Request changes comments”**
* Save changes

When this is on, Bito will flag **actionable AI feedback** as formal review comments requiring resolution. Informational or minor suggestions will remain as regular comments.

### 3. What happens in a pull request

* Bito runs an AI code review on your pull request or merge request.
* Actionable issues are posted as **change requests**.
* Your Git provider treats these comments according to your configured merge rules.
* If comment resolution is required, the merge is blocked until the flagged issues are resolved.

## Example workflow

1. Developer opens a pull request or merge request.
2. Bito reviews the code and posts a “request change” comment on a problematic line.
3. The Git provider blocks the merge due to unresolved comments or threads.
4. Developer fixes the issue and marks the thread as resolved.
5. Merge becomes possible once all conditions are met.

## Why use this feature?

* Enforces follow-up on critical AI-detected issues.
* Works natively with GitHub, GitLab, and Bitbucket workflows.
* Ensures only reviewed and clean code gets merged.
* Helps maintain consistent code quality at scale.


# Jira integration

Bring Jira issue requirements into every pull request and get validation results back automatically.

{% hint style="info" %}
**Note:** The Jira integration is available on the [**Professional Plan**](https://bito.ai/pricing/).
{% endhint %}

Bito integrates with Jira to automatically validate pull request code changes against linked Jira ticket requirements, helping ensure your implementations align with the specified requirements in those tickets.

## How it works

When you create a pull request, Bito automatically:

1. **Detects Jira ticket references** in your pull request description, title, or branch name
2. **Crawls the linked Jira tickets** to extract requirements from issue descriptions and related Stories/Epics
3. **Analyzes your code changes** against these requirements
4. **Provides structured validation results** directly in your pull request comments

## **Jira integration options in Bito**

Bito supports two ways to connect with Jira, depending on where your Jira instance is hosted:

1. [**Jira Cloud**](#connect-bito-with-jira-cloud-hosted-by-atlassian)**:** for Jira sites hosted by Atlassian (e.g., `https://mycompany.atlassian.net`).
2. [**Jira Data Center**](#connect-bito-with-jira-data-center-hosted-on-your-own-server)**:** for Jira instances hosted on your own company domain or servers (e.g., `https://jira.mycompany.com`).

## Connect Bito with Jira Cloud (hosted by Atlassian)

{% stepper %}
{% step %}

### Connect Bito to Jira

1. Navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page in your Bito dashboard
2. In the **Available integrations** section, you will see **Jira**. Click **Connect** to proceed.
3. Select the option **Jira Cloud**. You will be redirected to the official Jira website, where you need to grant Bito access to your Atlassian account.
4. Click **Accept** to continue. If the integration is successful, you will be redirected back to Bito.
   {% endstep %}

{% step %}

### Agent-specific settings

After completing the initial setup, you can control Jira integration on a per-agent basis:

1. Go to the [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page in your Bito dashboard.
2. Find the Agent instance you want to connect with Jira and open its settings.
3. Within the Agent settings screen, click on the **Integrations** tab.
4. Locate the **Functional validation** option and **enable** this setting to activate automatic pull request validation against Jira tickets.
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
**Note:** The **Functional validation** feature must be enabled in your Bito agent settings for the integration to work.
{% endhint %}

## Connect Bito with Jira Data Center (hosted on your own server)

{% stepper %}
{% step %}

### Connect Bito to Jira

1. Navigate to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page in your Bito dashboard
2. In the **Available integrations** section, you will see **Jira**. Click **Connect** to proceed.
3. Select the option **Jira Data Center (self-managed)**.
4. Provide connection details:
   * **Domain URL**: Enter the base URL for your Jira instance (e.g. `https://jira.mycompany.com`).
   * **Personal Access Token**: Enter a valid Personal Access Token with admin permissions. Read the [official Jira documentation](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) to learn how to create a Personal Access Token.
5. Click **Connect to Jira**. You will be redirected to your self-hosted Jira website, where you need to grant Bito access to your Jira account.
6. Click **Allow** to continue. If the integration is successful, you will be redirected back to Bito.
   {% endstep %}

{% step %}

### Agent-specific settings

After completing the initial setup, you can control Jira integration on a per-agent basis:

1. Go to the [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page in your Bito dashboard.
2. Find the Agent instance you want to connect with Jira and open its settings.
3. Within the Agent settings screen, click on the [**Functional validation** tab](https://docs.bito.ai/ai-code-reviews-in-git/pages/c2rnX1WC7HSmQdYRsJvG#f.-functional-validation).
4. Locate the **Functional validation** option and **enable** this setting to activate automatic pull request validation against Jira tickets.
   {% endstep %}
   {% endstepper %}

## Linking Jira tickets to pull requests

Bito offers multiple ways to link your Jira tickets with pull requests. You can use any of these methods:

#### Method 1: Branch name

Name your source branch using the Jira issue key:

```
feature/QP-123-implement-user-authentication
bugfix/QP-456-fix-login-error
```

#### Method 2: Pull request description

Include the Jira ticket reference in your PR description:

```
This PR implements user authentication as specified in QP-123.

Related tickets: QP-123, QP-124
```

OR

```
This PR implements shopping cart functionality as specified in:
https://your-company.atlassian.net/browse/QP-3
https://your-company.atlassian.net/browse/QP-7
```

#### Method 3: Pull request title

Include the Jira issue key in your PR title:

```
QP-123: Implement user authentication feature
[QP-456] Fix login validation error
```

## Understanding the validation results

When Bito completes its analysis, it adds a **"Functional Validation by Bito"** table to your pull request comments. This table contains four columns:

#### Source

Displays the **Jira issue key** (e.g., "QP-11", "QP-123") that references the specific Jira ticket being validated.

#### Requirement / Code Area

Shows a brief description of the requirement or task that needs to be completed, summarizing what needs to be done according to the Jira ticket.

#### Status

Indicates the completion status of each requirement:

* **Met**: The requirement has been fully implemented in the pull request
* **Missed**: The requirement has not been addressed in the pull request
* **Partial**: The requirement has been partially implemented but still needs additional work
* **Conflict**: A change contradicts another requirement (e.g., two requirements cannot both be satisfied by the current code).
* **Out‑of‑scope**: The change is not in the requirements (the code change does not relate to any defined requirement).

#### Notes

Provides detailed information about the validation status:

* **For "Met" items**: Explains what has been successfully implemented
* **For "Missed" items**: Describes what is missing and needs to be addressed
* **For "Partial" items**: Details what has been completed and what still remains to be done
* **For "Conflict" items**: Describes why there is a contradiction between requirements and what might need to be resolved.
* **For "Out‑of‑scope" items**: Explains why the change is considered outside the defined requirements.

## Example validation output

Here's what a typical validation table looks like:

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZLqYnwgMQ0bSmzdAUbmv%2Fscrnli_KjIe1WJ48Jm3Cf.png?alt=media&amp;token=932928cb-447a-4cb9-956a-fc246a96c30f" alt=""><figcaption></figcaption></figure>

## Benefits

* **Automated quality assurance**: Ensure code changes meet specified requirements
* **Improved collaboration**: Bridge the gap between project management and development
* **Reduced manual reviews**: Bito AI automatically catches missing implementations during code review
* **Better traceability**: Maintain clear links between requirements and code changes

By leveraging Bito's Jira integration, your development team can maintain higher code quality while ensuring that all requirements are properly addressed in every pull request.

## Best practices

#### For developers

* Always reference Jira tickets in your pull requests using one of the supported methods
* Review the validation table and address any "Missed" or "Partial" items before merging

#### For teams

* Ensure Jira tickets contain clear, detailed requirements
* Use consistent naming conventions for branches and pull request titles
* Enable functional validation for all relevant agents

## Troubleshooting

**Validation table not appearing:**

* Check that your Jira integration is properly configured in the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page
* Verify that **Functional validation** is enabled in your agent settings
* Ensure your pull request contains valid Jira issue key references

**Incorrect validation results:**

* Review your Jira ticket descriptions for clarity and completeness
* Verify that linked Stories/Epics contain relevant requirements
* Check that your code changes are in the expected areas


# Confluence integration

Make sure every code change follows the requirements and guidance recorded in your Confluence pages.

{% hint style="info" %}
**Note:** The Confluence integration is available only on the [**Enterprise Plan**](https://bito.ai/pricing/).
{% endhint %}

Bito integrates with Confluence to enhance functional validation by enriching pull request requirements with deeper context from linked documentation.

It fetches relevant details from Confluence pages linked in Jira issues or directly in pull request – such as edge cases, design decisions, or test scenarios – and incorporates them into structured validation results.

This improves accuracy when validating code changes and ensures that every pull request is aligned with the requirements.

## How it works

When a pull request is opened, Bito automatically:

1. **Detects Confluence references.** Bito looks for Confluence page links in the pull request description or in any linked Jira issues.

{% hint style="info" %}
**Note:** If [Jira integration](/ai-code-reviews-in-git/jira-integration) is enabled, Bito finds the Confluence pages associated with the linked Jira tickets.
{% endhint %}

2. **Fetches documentation.** Bito retrieves the content of those Confluence pages and extracts key information (requirements, design decisions, acceptance criteria, etc.).
3. **Validates code against the docs.** It compares your code changes to the enriched context and generates structured validation feedback.
4. **Reports results in the PR.** Bito posts a "Functional Validation" table directly in your pull request comments, showing how each documented requirement is met, missed, or partially implemented.

## Integration steps

{% stepper %}
{% step %}

### Connect Bito with Confluence

1. In your Bito dashboard, go to the [**Manage integrations**](https://alpha.bito.ai/home/cra-integrations) page.
2. Under **Available integrations**, find **Confluence** and click **Connect**.
3. Click **Authorize with your Confluence account**. You will be redirected to Atlassian's site to grant Bito access to your Confluence workspace. This uses OAuth to securely link your Confluence content.
4. Sign in to your Atlassian account if prompted, then click **Accept**. After successful authorization, you will be returned to Bito.
   {% endstep %}

{% step %}

### Agent-specific settings

After completing the initial setup, you can control Confluence integration on a per-agent basis:

1. Go to the [**Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page in your Bito dashboard.
2. Find the Agent instance you want to connect with Confluence and open its settings.
3. Within the Agent settings screen, click on the [**Functional validation** tab](https://docs.bito.ai/ai-code-reviews-in-git/pages/c2rnX1WC7HSmQdYRsJvG#f.-functional-validation).
4. Locate the **Functional validation** option and enable it to enhance pull request validation by incorporating relevant context from linked Confluence pages.
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
**Note:** The **Functional validation** feature must be enabled in your Bito agent settings for the integration to work.
{% endhint %}

## Linking Confluence pages to pull requests

For Bito to fetch the right documentation, your pull requests must reference the relevant Confluence pages:

* **With Jira integration:** Ensure your Jira issues link to the Confluence pages (for example, by using the *Jira Issue* macro on the Confluence page). When a Confluence page mentions a Jira issue key, Jira automatically creates a link to that page. Bito will follow those links to gather the documentation context.
* **Without Jira integration:** Include a link to the Confluence page directly in the pull request description. Bito will use that URL to retrieve the page content for validation.

{% hint style="info" %}
**Note:** Bito supports both full Confluence page URLs (with page ID) and short Confluence URLs.<br>

**Supported examples:**

* `https://yourcompany.atlassian.net/wiki/spaces/SPACEKEY/pages/123456789/Page-Title`
* `https://yourcompany.atlassian.net/wiki/x/AbCdE`
  {% endhint %}

## Understanding the validation results

When Bito completes its analysis, it adds a **"Functional Validation by Bito"** table to your pull request comments. This table contains four columns:

#### Source

Displays the **Jira issue key** (e.g., "QP-11", "QP-123") that references the specific Jira ticket being validated.

#### Requirement / Code Area

Shows a brief description of the requirement or task that needs to be completed, summarizing what needs to be done according to the Jira ticket and Confluence page.

#### Status

Indicates the completion status of each requirement:

* **Met**: The requirement has been fully implemented in the pull request
* **Missed**: The requirement has not been addressed in the pull request
* **Partial**: The requirement has been partially implemented but still needs additional work
* **Conflict**: A change contradicts another requirement (e.g., two requirements cannot both be satisfied by the current code).
* **Out‑of‑scope**: The change is not in the requirements (the code change does not relate to any defined requirement).

#### Notes

Provides detailed information about the validation status:

* **For "Met" items**: Explains what has been successfully implemented
* **For "Missed" items**: Describes what is missing and needs to be addressed
* **For "Partial" items**: Details what has been completed and what still remains to be done
* **For "Conflict" items**: Describes why there is a contradiction between requirements and what might need to be resolved.
* **For "Out‑of‑scope" items**: Explains why the change is considered outside the defined requirements.

## Example validation output

Here's what a typical validation table looks like:

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FZLqYnwgMQ0bSmzdAUbmv%2Fscrnli_KjIe1WJ48Jm3Cf.png?alt=media&amp;token=932928cb-447a-4cb9-956a-fc246a96c30f" alt=""><figcaption></figcaption></figure>

## Benefits

* **Improved traceability:** Syncing code validation with Confluence documentation creates a clear audit trail from requirements to implementation.
* **Single source of truth:** By pulling from Confluence (the team’s central documentation hub), Bito ensures developers review code against the definitive requirements. Teams spend less time context-switching between tools.
* **Aligned development:** Automatic validation against documented scenarios helps catch missing features or edge cases early, reducing manual review effort and improving quality.

## Troubleshooting

* **No "Functional validation" table in pull request:** Check that Confluence is connected under [*Manage integrations*](https://alpha.bito.ai/home/cra-integrations) and that the [Functional Validation setting is enabled](https://docs.bito.ai/ai-code-reviews-in-git/pages/c2rnX1WC7HSmQdYRsJvG#f.-functional-validation) for your Agent. Also verify that your PR or its linked Jira issues actually reference the Confluence pages.
* **Missing or incorrect context:** Make sure the Confluence pages contain the up-to-date requirements or test scenarios.
* **Authorization errors:** If Bito can't access Confluence, try re-authorizing the integration. Ensure your Atlassian account has permission to read the relevant Confluence pages.


# Interaction diagram

Visualize code changes and their impact with automated sequence diagrams.

The **Interaction Diagram** is a visual feature in Bito's [AI Code Review Agent](/ai-code-reviews-in-git/overview) that automatically generates sequence diagrams to help you quickly understand the impact of code changes in your pull requests.

This diagram visualizes how different components of your code interact with each other, making code reviews faster and more intuitive.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F8CfF2JsDQidxrSRngzxQ%2Fscrnli_S6UpbwjKn6AfL1.png?alt=media&amp;token=0e65a067-402a-4c90-b766-896c762bac11" alt="Interaction diagram by Bito"><figcaption><p><strong>Interaction Diagram by Bito</strong></p></figcaption></figure>

### How to enable

1. Navigate to the [Code Review > Repositories](https://alpha.bito.ai/home/ai-agents/code-review-agent) dashboard.
2. Click the **Settings** button next to the Agent instance you wish to modify.
3. Under **Review** tab, enable the **Generate interaction diagrams** option.

Once enabled, Bito will automatically post interaction diagrams during code reviews.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FSaUBPFgiJCvDetaChxVw%2Fscrnli_f5R90M2Ur6HW53.png?alt=media&amp;token=e9473999-cfef-4aed-a3fa-eeb9d16a6dd1" alt=""><figcaption></figcaption></figure>

### Understanding sequence diagrams

A sequence diagram is a type of visual diagram that shows how different parts of your system interact with each other over time.

It illustrates the flow of operations by displaying the order in which methods are called and how data flows between different components.

This makes it easy to trace the execution path of your code and understand dependencies between modules.

### Diagram components

#### Boxes

The main components in the diagram are displayed as boxes. The level of detail shown depends on the size of your code changes:

* **Small changes**: Boxes may represent individual classes or functions with detailed interactions
* **Large changes**: Boxes may represent higher-level abstractions for better readability

Bito's AI automatically determines the appropriate level of detail based on your pull request.

#### Labels and indicators

Within boxes, you'll see labels that provide quick insights:

**Change type:**

Indicates what kind of modification was made to each module in your codebase.

* 🟩 **Added** - New code introduced to the codebase. These are components, functions, or classes that didn't exist before this pull request.
* 🔄 **Updated** - Existing code that has been modified. This indicates changes to the logic, behavior, or implementation of existing components.
* **Deleted** - Code that has been removed from the codebase. These components are no longer present after this pull request is merged.

**Impact level:**

Shows the scope and significance of changes to help you prioritize your code review efforts.

* **Low** - Minimal impact (● ○ ○)
  * Changes are localized and unlikely to affect other parts of the system. Safe to review with standard attention.
* **Medium** - Moderate impact (● ● ○)
  * Changes affect multiple components or have moderate complexity. Requires careful review of interactions and side effects.
* **High** - Significant impact (● ● ●)
  * Changes are extensive or critical, affecting core functionality or multiple system areas. Demands thorough review and testing.

These visual indicators help you identify critical changes at a glance.

#### Arrows and flow

**Solid arrows (→)**: Represent forward calls flowing left to right

* Example: If `main()` calls `UserService`, a solid arrow points from `main()` to `UserService`

**Dotted arrows (⇢)**: Represent return flows going right to left

* Example: When `UserService` returns data to `main()`, a dotted arrow points back from `UserService` to `main()`

**Circular arrows (↻)**: Indicate internal calls within the same module

* Example: One component of `UserService` calling another component within `UserService`

#### Control flow blocks

**Alt block (if-else logic)**

* Displayed as a dotted box around multiple lines
* Contains two sections separated by a dotted line representing "if" and "else" branches
* Shows conditional execution paths in your code

**Opt block (optional parameters)**

* Used for functions with parameter overloading
* Contains a single section for optional execution flow
* Represents code that may or may not execute depending on optional parameters

Code outside these blocks represents the normal execution flow.

### Platform-specific behavior

#### GitHub

* Diagrams are posted in **Mermaid format**
* Interactive controls available:
  * Pan (move top, bottom, left, right)
  * Expand/collapse
  * Zoom in/out

#### GitLab

* Diagrams are posted in **Mermaid format**
* **Note**: For very large diagrams, GitLab may not render automatically. You'll see a notice box with a **"Display"** button - click it to manually render the diagram

#### Bitbucket

* Diagrams are posted as **image format**

{% hint style="info" %}
**Note:** If you see a "syntax error" or "unable to render" message, try refreshing the page.
{% endhint %}

### Incremental reviews

When you run incremental reviews (for example, by using the `/review` command in pull request comments), the existing interaction diagram will be updated rather than creating a new comment with a separate diagram.

### Interaction diagram vs impact analysis diagram

Bito can generate two types of diagrams, but only one is displayed at a time:

* **Interaction diagram**: Generated by the standard Code Review Agent, focusing on code changes in the current pull request
* **Impact analysis diagram**: Generated using [Bito AI Architect](/ai-architect/overview) with complete cross-repository codebase understanding.
  * **Note:** This feature is not publicly available yet. Please contact Bito at [**support@bito.ai**](mailto:support@bito.ai) to have it enabled for your account.

{% hint style="info" %}
**Note:** If both **Impact Analysis** and **Interaction Diagram** are enabled, only the Impact Analysis diagram will be shown.
{% endhint %}

### Best practices

* Review the diagram before diving into code details to get a high-level understanding
* Use impact indicators to prioritize which changes need closer examination
* Follow the arrow flows to understand the execution path
* Pay special attention to "High" impact modules

### Troubleshooting

* **Diagram not appearing**: Verify that **"Generate interaction diagrams"** is enabled in [Bito Cloud](https://alpha.bito.ai/) settings
* **Rendering issues**:
  * In GitLab, you may need to click the **Display** button to manually render the diagram.
  * Refresh the page - this often resolves transient rendering errors.
* **Syntax errors**: In some cases, the Mermaid diagram may contain syntax errors that prevent it from rendering. Try updating the pull request so the diagram is regenerated.


# Agent settings

Learn how to customize the AI Code Review Agent.

Bito's [AI Code Review Agent](/ai-code-reviews-in-git/overview) supports different configuration methods depending on the deployment environment:

1. **Bito-hosted** – The agent runs on Bito's infrastructure and is configured through the [Bito web UI](https://alpha.bito.ai/).
2. **Self-hosted** – The agent runs on user-managed infrastructure and is configured by editing the [`bito-cra.properties` file](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file).

The sections below provide configuration guidance for each setup.

## Bito-hosted agent configuration

In Bito-hosted AI Code Review Agent, you can configure the agent through the [Bito web UI](https://alpha.bito.ai/).

To customize an existing agent, open the [**Code Review > Repositories**](https://alpha.bito.ai/home/ai-agents/code-review-agent) page and click the **Settings** button next to the Agent instance to be modified.

The agent settings page allows configuration of options such as:

* **Agent name** – Define a unique name for easy identification.
* **Review options** – Choose the review mode (Essential or Comprehensive), set feedback language, and enable features like auto-review, incremental review, summaries, and change walkthroughs.
* **Custom guidelines** – Create and apply custom code review rules tailored to your team’s standards directly from the dashboard.
* **Filters** – Exclude specific files, folders, or branches from review to focus on relevant code.
* **Tools** – Enable additional checks, such as secret scanning and static analysis.
* **Chat** – Configure how the agent responds to follow-up questions in pull request comments and manage automatic replies.

These settings tailor the agent’s behavior to match team workflows and project needs. For detailed guidance, see [Create or customize an Agent instance](https://docs.bito.ai/ai-code-review-agent/install-run-using-bito-cloud/create-or-customize-an-agent-instance).

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance">Create or customize an Agent instance</a></td></tr></tbody></table>

{% embed url="<https://youtu.be/Oj4A8wd1bio>" %}

## Self-hosted agent configuration

In self-hosted deployments, configuration is managed by editing the [`bito-cra.properties` file](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file). This file defines how the agent operates and connects to required services.

Key configuration options include:

* **Mode**
  * `mode = cli`: Processes a single pull request using a manual URL input.
  * `mode = server`: Runs as a webhook service and listens for incoming events from Git platforms.
* **Authentication**
  * `bito_cli.bito.access_key`: Required for authenticating the agent with the Bito platform.
  * `git.provider`, `git.access_token`, etc.: Required for connecting to the appropriate Git provider (e.g., GitHub, GitLab, Bitbucket).
* **General feedback settings**
  * `code_feedback`: Enables or disables general feedback comments in reviews.
* **Analysis tools**
  * `static_analysis`: Enables static code analysis.
  * `dependency_check`: Enables open-source dependency scanning.
  * `dependency_check.snyk_auth_token`: Required when using Snyk for vulnerability detection.
* **Review format and scope**
  * `review_comments`: Defines output style (e.g., single post or inline comments).
  * `review_scope`: Limits the review focus to specific concerns such as security, performance, or style.
* **Filters**
  * `include_source_branches` and `include_target_branches`: Restrict reviews to pull requests that match specified source and target branch patterns.
  * `exclude_files`: Skips selected files based on glob patterns.
  * `exclude_draft_pr`: Skips draft pull requests when enabled (default: `True`).

Each property is documented in detail on the [bito-cra.properties file documentation](/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file) page.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Learn more</strong></mark></td><td><a href="/ai-code-reviews-in-git/install-run-as-a-self-hosted-service/agent-configuration-bito-cra.properties-file">Agent Configuration: bito-cra.properties File</a></td></tr></tbody></table>


# Repo level settings

Configure repository-specific Code Review Agent settings using the .bito.yaml file.

Repo-level Agent settings let you control how the [**AI Code Review Agent**](/ai-code-reviews-in-git/overview) behaves for each repository.&#x20;

By placing a **`.bito.yaml`** file in the root of your repository, you can define custom review preferences that apply only to that repository.&#x20;

Bito automatically detects the presence of a `.bito.yaml` file in a repository and applies its configuration to override the global Agent settings defined by admins in the Bito Cloud UI.

This gives developers fine-grained control while admins maintain global oversight and billing management.

## Why use repo-level settings&#x20;

Large organizations often have different review needs across projects.&#x20;

Centralized (agent-level) settings don’t scale well — especially when each repo has its own coding standards, branch structure, or tooling.&#x20;

**Repo-level configuration helps by:**&#x20;

* Enabling custom review behavior per repository.
* Allowing custom guidelines flexibility at the repo level.&#x20;
* Keeping settings version-controlled and transparent.

## How it works&#x20;

1. Add a `.bito.yaml` file to the root of your repository. To get started, [download a sample `.bito.yaml` file](https://github.com/gitbito/repo-level-settings-file).
2. Add the [supported configuration fields](#supported-settings-in-.bito.yaml-file) (key-value pairs) to specify how the Code Review Agent should behave for that repository.
3. When the Code Review Agent runs, Bito automatically detects the file and applies those settings for that repository.

{% hint style="info" %}
**Note:** Repo-level overrides are applied only if your workspace admin has enabled **“Allow config file settings”** in [Agent Settings](/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance). This option is **required** for repo-level overrides to take effect and is **turned on by default**.
{% endhint %}

## Enabling repo-level overrides&#x20;

Admins can manage this from the [Agent Settings](https://docs.bito.ai/ai-code-reviews-in-git/install-run-using-bito-cloud/create-or-customize-an-agent-instance) panel.&#x20;

* **Setting name:** Allow config file settings&#x20;
* **Description:** Enabling this allows repositories to override Agent Settings by placing a `.bito.yaml` file in the repo root.

{% hint style="info" %}
**Note:** Only workspace admins can toggle this setting from the Bito dashboard (cannot be changed via `.bito.yaml` file).
{% endhint %}

## Supported settings in `.bito.yaml` file

You can override the following Code Review Agent settings:&#x20;

<table data-header-hidden><thead><tr><th width="257.99993896484375">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>suggestion_mode</strong> </td><td><p>Controls how detailed the review comments are.<br><br>Choose between <strong>Essential</strong> and <strong>Comprehensive</strong> review modes:</p><ul><li>In <strong>Essential</strong> mode, only critical issues are posted as inline comments, and other issues appear in the main review summary under "Additional issues".</li><li>In <strong>Comprehensive</strong> mode, Bito also includes minor suggestion and potential nitpicks as inline comments.</li></ul><p><br><strong>Valid values:</strong> <code>essential</code> or <code>comprehensive</code></p></td></tr><tr><td><strong>post_description</strong> </td><td>Automatically create summary of changes and append to your existing pull request summary.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>post_changelist</strong></td><td>Adds a walkthrough section to pull request comments.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>include_source_branches</strong></td><td>Source branches defined using comma-separated GLOB or regex patterns for which Bito automatically reviews pull requests.<br><br><strong>Example:</strong> <code>"feature/*, release/*, main"</code>    </td></tr><tr><td><strong>include_target_branches</strong></td><td>Target branches defined using comma-separated GLOB or regex patterns for which Bito automatically reviews pull requests.<br><br><strong>Example:</strong> <code>"feature/*, release/*, main"</code></td></tr><tr><td><strong>exclude_files</strong></td><td>Comma-separated file path GLOB patterns to exclude from code reviews.<br><br><strong>Example:</strong> <code>"*.md, *.yaml, config/*"</code></td></tr><tr><td><strong>exclude_draft_pr</strong></td><td>Excludes draft pull requests from automatic reviews.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>secret_scanner_feedback</strong></td><td>Enables or disables secret scanning feedback. Bito detects and reports secrets left in code changes.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>linters_feedback</strong></td><td>Run Linting tools during code reviews.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>custom_guidelines</strong></td><td><p>Adds repo-defined coding guidelines, supporting both general and language-specific configurations.<br><br>Provide the <strong>name</strong> and <strong>path</strong> to review guidelines that you want bito to follow. These files must exist in your <strong>source branch</strong> at review time.<br><br>We accept up to 3 general guidelines and 1 language specific guideline per language.<br><br><strong>Example:</strong></p><pre class="language-yaml"><code class="lang-yaml">custom_guidelines:
  general:
    - name: "Global Checks"
      path: "./guidelines/global_checks.txt"
    - name: "Security Rules"
      path: "./guidelines/security.txt"
    - name: "Legacy Style Guide"
      path: "./guidelines/legacy.txt"
    - name: "Performance Checks"
      path: "./guidelines/perf.txt"
    - name: "Code Style"
      path: "./guidelines/style.txt"
  per_language:
    python:
      name: "Python Best Practices"
      path: "./guidelines/py.txt"
    javascript:
      name: "JS Style Guide"
      path: "./guidelines/js.txt"
    typescript:
      name: "TS Checks"
      path: "./guidelines/ts.txt"
    java:
      name: "Java Coding Standards"  
      Path: "./guidelines/java.txt"
</code></pre></td></tr><tr><td><strong>dependency_check.enabled</strong></td><td><p>Run Dependency Check analysis during code reviews.<br></p><p><strong>Valid values:</strong> <code>true</code> or <code>false</code></p></td></tr><tr><td><strong>repo_level_guidelines_enabled</strong></td><td>When enabled, Bito will automatically detect and use best-practice guidelines from agent configuration files such as <code>CLAUDE.md</code>, <code>AGENTS.md</code>, <code>GEMINI.md</code>, <code>.cursor/rules</code>, or <code>.windsurf/rules</code> during code reviews.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>sequence_diagram_enabled</strong></td><td>When enabled, Bito will generate interaction diagrams during code reviews to visualize the architecture and impacted components in the submitted changes.<br>Currently, it is supported for GitHub and GitLab.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>static_analysis.fb_infer.enabled</strong></td><td>Run Static Analysis tools during code reviews for providing better feedback.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code></td></tr><tr><td><strong>labels_excluded</strong></td><td>Comma-separated list of labels that, if present on a pull request or merge request, skip automatic review.<br><br>This is case-sensitive by default. For example, if we mention "Bug" in the repo-level <code>.bito.yaml</code> file and the tagged label is "bug", we won't match it. Users can use regex to make it case-insensitive, e.g., <code>(?i)^bug$</code> or <code>(?i)bug</code>.<br><br><strong>Example:</strong> <code>"wip, do-not-review, chore, size/*"</code></td></tr><tr><td><strong>post_as_request_changes</strong></td><td>Enable this option to get Bito feedback as "Request changes" review comments. Depending on your Git provider settings, you may need to resolve all comments before merging.<br><br>For GitHub, this will automatically enable auto-approve for resolved PRs.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code> </td></tr><tr><td><strong>functional_validation_enabled</strong></td><td>Enable this option to automatically validate pull requests against Jira ticket referenced in PR description, title, or branch name.<br><br>Jira Integration must be completed from <a href="https://alpha.bito.ai/">Bito dashboard</a> for this to work.<br><br><strong>Valid values:</strong> <code>true</code> or <code>false</code> </td></tr></tbody></table>

&#x20;

## Sample `.bito.yaml` file

```yaml
suggestion_mode: comprehensive       # 'essential' = only major issues, 'comprehensive' = everything
post_description: true                # Include summary description in PR comment
post_changelist: true                 # Include walkthrough of changes

include_source_branches: feature/**,bugfix/**
include_target_branches: main,develop
exclude_files: docs/**,README.md

exclude_draft_pr: true            # Don't review draft PRs
secret_scanner_feedback: true      # Enable secret scanning feedback
linters_feedback: true             # Enable linting / static analysis

custom_guidelines:
  general:
    - name: "Global Checks"
      path: "./guidelines/global_checks.txt"
    - name: "Security Rules"
      path: "./guidelines/security.txt"
    - name: "Legacy Style Guide"
      path: "./guidelines/legacy.txt"
    - name: "Performance Checks"
      path: "./guidelines/perf.txt"
    - name: "Code Style"
      path: "./guidelines/style.txt"
  per_language:
    python:
      name: "Python Best Practices"
      path: "./guidelines/py.txt"
    javascript:
      name: "JS Style Guide"
      path: "./guidelines/js.txt"
    typescript:
      name: "TS Checks"
      path: "./guidelines/ts.txt"
    java:
      name: "Java Coding Standards"  
      Path: "./guidelines/java.txt"  

```

## Download `.bito.yaml` file&#x20;

### From GitHub:

You can download a sample `.bito.yaml` configuration file directly from Bito’s official GitHub repository.&#x20;

This file includes all supported configuration fields with example values to help you get started quickly.&#x20;

1. Go to the [Bito GitHub repository](https://github.com/gitbito/repo-level-settings-file).&#x20;
2. Open the `.bito.yaml` file.&#x20;
3. Click the **Download raw file** button to download it.

### From Bito Cloud UI:

You can also download the sample `.bito.yaml` configuration file from the Bito Cloud UI.&#x20;

* Go to [Repositories](https://alpha.bito.ai/home/ai-agents/code-review-agent) dashboard.&#x20;
* Click the **Download settings file** button given in the Agent panel.&#x20;

{% hint style="info" %}
**Note:** Web browsers such as Google Chrome do not allow downloading files that begin with a dot `.`. As a result, when you download the sample settings file, it will be saved with a different name (for example, `agent.yaml` or `bito.yaml`). To use it correctly, rename the file to `.bito.yaml` before adding it to your repository.
{% endhint %}

{% hint style="info" %}
**Note:** By default, files that start with a dot `.` are hidden in most file explorers.

To view hidden files:&#x20;

* **Windows:** In File Explorer, go to the top menu bar, click **View**, then enable **Hidden items**.&#x20;
* **macOS:** Press `Command + Shift + .` in Finder.
* **Linux:** Run `ls -a` in your terminal.
  {% endhint %}

{% hint style="info" %}
**Note:** On macOS, the Finder app may not allow naming a file starting with a dot (e.g., `.bito.yaml`). In that case, open Terminal and use the following command to rename the file (replace `filename.yaml` with your actual file name):

`mv filename.yaml .bito.yaml`&#x20;
{% endhint %}

## Rules and limits

* The `.bito.yaml` file is read from the **source branch** of the pull request.&#x20;
* If a repo defines custom guidelines, agent-level guidelines are ignored for that repository.&#x20;
* If any property in the `.bito.yaml` file contains an invalid value, the entire configuration file will be rejected and default Agent Settings will be used instead.&#x20;
* If a property is missing in the `.bito.yaml` file, the corresponding value from the global Agent Settings will be used instead.


# FAQs

Answers to popular questions about the AI Code Review Agent.

## How do I whitelist Bito's gateway IP address for my on-premise Git platform?

To ensure the [AI Code Review Agent](/ai-code-reviews-in-git/overview) operates smoothly with your **GitHub (Self-Managed)**, **GitLab (Self-Managed)**, or **Bitbucket (Self-Managed)**, please whitelist all of Bito's gateway IP addresses in your firewall to allow incoming traffic from Bito. This will enable Bito to access your self-hosted repository.

**List of IP addresses to whitelist:**

* **`18.188.201.104`**
* **`3.23.173.30`**
* **`18.216.64.170`**

The agent response can come from any of these IPs.

## How can I prevent the AI Code Review Agent from stopping due to token expiry?

You should set a longer expiration period for your **GitHub Personal Access Token (Classic)**, **GitLab Personal Access Token**, or **Bitbucket Personal Access Token**. We recommend setting the expiration to at least one year. This prevents the token from expiring early and avoids disruptions in the AI Code Review Agent's functionality.

Additionally, we highly recommend updating the token before expiry to maintain seamless integration and code review processes.

For more details on how to create tokens, follow these guides:

* **GitHub Personal Access Token (Classic):** [**View Guide**](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
* **GitLab Personal Access Token:** [**View Guide**](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)
* **Bitbucket Personal Access Token:** [**View Guide**](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html)

## Why does Bito need access to my Git account?&#x20;

Bito requires certain permissions to analyze pull requests and provide AI-powered code reviews. It never stores your code and only accesses the necessary data to deliver review insights.

## What permissions does Bito need?&#x20;

Bito requires: &#x20;

1. Read access to code and metadata: To analyze PRs and suggest improvements&#x20;
2. Read and write access to issues and pull requests: To post AI-generated review comments &#x20;
3. Read access to organization members: To provide better review context&#x20;

## I don’t have admin permissions. Can I still use Bito?&#x20;

If you don’t have admin access, you’ll need your administrator to install Bito on your organization’s Git account. Once installed, you can use it for PR reviews on allowed repositories. GitHub also sends a notification to the organization owner to request the organization owner to install the app.

## Does Bito store my code?&#x20;

No, Bito does not store or train models on your code. It only analyzes pull request data in real-time and provides suggestions directly within the PR.

## Can I choose which repositories Bito has access to?&#x20;

Yes, after installation, you can select specific repositories instead of granting access to all. You can also manage repository access later through our web dashboard.

## What happens after I install the Bito App?&#x20;

Once installed, you’ll be redirected to Bito, where you can:&#x20;

1. Select repositories for AI-powered reviews&#x20;
2. Customize review settings to fit your workflow&#x20;
3. Open a pull request to start receiving AI-driven suggestions

## Where can I get help if I have issues installing Bito?&#x20;

Contact <support@bito.ai> for any assistance.&#x20;


# Overview

Get instant feedback on your code changes directly within your code editor.

Unlock the power of AI-driven code reviews in VS Code, Cursor, Windsurf, and all JetBrains IDEs (including IntelliJ IDEA, PyCharm, WebStorm, and more) with Bito's [AI Code Review Agent](/ai-code-reviews-in-git/overview). This tool provides real-time, human-like feedback on your code changes, catching common issues before you submit a pull request.

The AI Code Review Agent helps you improve your code as you develop, so you don't have to wait for days to get feedback. This accelerates development cycles, boosts team productivity, and ensures higher code quality.

You can start using the Agent immediately—no setup is required!

<p align="center"><a href="https://marketplace.visualstudio.com/items?itemName=Bito.Bito" class="button primary">Install on VS Code</a><a href="https://plugins.jetbrains.com/plugin/18289-chatgpt-gpt-4o--bito-ai-code-assistant" class="button primary">Install on JetBrains</a><a href="https://open-vsx.org/extension/Bito/Bito" class="button primary">Install on Cursor</a><a href="https://open-vsx.org/extension/Bito/Bito" class="button primary">Install on Windsurf</a></p>

{% embed url="<https://youtu.be/RhgtIVuQTTw>" %}

## Prerequisites

1. Install the latest Bito IDE extension for [VS Code](https://marketplace.visualstudio.com/items?itemName=Bito.Bito), [JetBrains](https://plugins.jetbrains.com/plugin/18289-chatgpt-gpt-4o--bito-ai-code-assistant), [Cursor](https://open-vsx.org/extension/Bito/Bito), or [Windsurf](https://open-vsx.org/extension/Bito/Bito).
2. A workspace subscribed to the Bito **Team Plan**. [Read documentation](/help/billing-and-plans/managing-workspace-plan) on how to upgrade.

{% hint style="info" %}
[**Get a 14-day FREE trial of Bito's AI Code Review Agent.**](https://alpha.bito.ai/home/welcome)
{% endhint %}

3. The root of your project must use a supported Version Control System such as Git, Perforce, or SVN, and be opened in the supported IDE.

## How to use the Agent in IDE?

1. Open the Bito IDE extension.
2. Login to your workspace subscribed to the Bito **Team Plan**.
3. Type **`@codereview`** in the chat box to open a menu and select from the following actions:
   * **localchanges:** Review only the changes you’ve made in your local workspace that haven’t been staged yet. This is useful for quickly checking your current edits before moving them forward.
   * **stagedchanges:** Review the changes you’ve staged in Git but haven’t committed yet. This helps ensure only clean, well-reviewed updates get committed.
   * **uncommittedchanges:** Review all modifications that exist locally but aren’t yet committed—both staged and unstaged. Ideal for a full review of your current working directory.
   * **path:** Review a specific file or multiple files by providing their paths. This allows you to target critical files without running a review across your entire project.
   * **commitId:** Review one commit or a range of commits by referencing their commit IDs. Perfect for validating code history, checking incremental updates, or reviewing PR-related commits.

{% hint style="info" %}
**Supported review options based on your Version Control System (VCS):**

* If your project uses **Git**, all five review options are available.
* If your project uses a **non-Git VCS** (e.g., Perforce, SVN), only two review options are available:

  * **uncommittedchanges**
  * **path**

  Unsupported options will be hidden automatically.
  {% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FGn2V5FTwYtxPuCNchVkI%2Fscrnli_9HHvA5zvpYGTZW.png?alt=media&amp;token=ced5c22f-1be9-4f59-8189-4d2bdcdbb8ec" alt=""><figcaption></figcaption></figure>

4. After that, choose between **Essential** and **Comprehensive** review modes:
   * In **Essential** mode, only critical issues are posted.
   * In **Comprehensive** mode, Bito also includes minor suggestion and potential nitpicks.
5. Submit to get the code review feedback.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F0j3ANS8kCL2k701K2Fnb%2Fscrnli_In07VqlCg1h2JX.png?alt=media&amp;token=3681155f-56cb-4ee2-98db-d23c1ca3b904" alt=""><figcaption></figcaption></figure>

## Start code review from context menu

You can also invoke the AI Code Review Agent directly from the **context menu** by right-clicking in the code editor and selecting commands under the **"Bito Code Review Agent"** menu.

This provides faster, on-the-go access to code reviews right where you work.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FmTmQV5vdOwcH1F9nTQKq%2FScreenshot%202025-10-03%20195645.png?alt=media&amp;token=ee08a39a-a8bb-4c07-8038-0d7e00291448" alt=""><figcaption></figcaption></figure>

## Reviewing the feedback

Once the AI code review is complete, you'll receive a notification in the IDE. You can view the feedback in the Bito Panel, which includes a list of issues and their fixes.

Each item will contain the following details:

* **Issue description:** Description of the identified issue.
* **Fix description:** Recommended approach or steps to resolve the issue.
* **File path:** The file containing the issue.
* **Code suggestion:** The AI-generated code fix for the issue.

{% hint style="info" %}
Each code suggestion includes an **Apply** button. Click it to open the diff view, where you can review the changes and choose to accept or undo them.
{% endhint %}

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F1cJ05HHTKAujAMuDvx4o%2FScreenshot%202025-08-08%20215021.png?alt=media&amp;token=e489d83d-7cda-4fef-baf9-2525e6a5c60b" alt=""><figcaption></figcaption></figure>

## Code review session history

To view past code reviews, click the **Session history** icon in the top-right corner of the Bito Panel. This opens the **Session history** tab, which lists all your previous code review sessions.

From the list, click any session to open it and view the complete code review details along with the AI suggestions.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FDcBc1t3l7tHN9O1HNSzj%2Fscrnli_y9PGf09WQU5cq7.png?alt=media&amp;token=79debcfd-5c60-4bf3-b38e-4e49667125dd" alt=""><figcaption></figcaption></figure>


# Installation guide


# Installing on Visual Studio Code

It takes less than 2 minutes

Get up and running with Bito in just a few steps! Bito seamlessly integrates with Visual Studio Code, providing powerful AI-driven code reviews directly within your editor. Click the button below to quickly install the Bito extension and start optimizing your development workflow with context-aware [AI Chat](/ai-code-reviews-in-ide/ai-chat-in-bito), and more.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Install on VS Code</strong></mark></td><td><a href="https://marketplace.visualstudio.com/items?itemName=Bito.bito">https://marketplace.visualstudio.com/items?itemName=Bito.bito</a></td></tr></tbody></table>

## Video guide

Watch the video below to learn how to download the Bito extension on VS Code.

{% embed url="<https://www.loom.com/share/28bb3b7d1000422fb2459c4aee16463d>" %}
How to install Bito extension on VS Code
{% endembed %}

## Step-by-step instructions

1. In Visual Studio Code, go to the extension tab and search for Bito.

<div align="left"><figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FOG7YiSRkjlDEBdbe9KNq%2Fimage.png?alt=media&amp;token=5d8f0ae4-a82a-4d10-a768-112a1d626310" alt=""><figcaption></figcaption></figure></div>

2. Install the extension. We recommend you restart the IDE after the installation is complete.

{% hint style="info" %}
Starting with Bito version 1.3.4, the extension is only supported on VS Code versions 1.72 and higher. Bito does not support VS Code versions below 1.72, and earlier versions of Bito do not function properly on these older versions.
{% endhint %}

3. After a successful install, the Bito logo appears in the Visual Studio Code pane.

<img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FhKqWVGtnM77IwKTs7GBM%2Fimage.png?alt=media&amp;token=551802db-1ab3-4060-a8fd-314c97ab57d0" alt="" data-size="original">

4. Click the Bito logo to launch the extension and complete the setup process. You will either need to create a new workspace if you are the first in your company to install Bito or join an existing workspace created by a co-worker. See [Managing  workspace members](/help/account-and-settings/managing-workspace-members)

{% hint style="info" %}
Visual Studio Code Marketplace Link <https://marketplace.visualstudio.com/items?itemName=Bito.bito>
{% endhint %}

## Setup Bito extension in VS Code running through SSH

SSH (Secure Shell) is a network protocol that securely enables remote access, system management, and file transfer between computers over unsecured networks.

Visual Studio Code IDE allows developers to access and collaborate on projects from any connected machine remotely. The corresponding extension \[Remote -SSH] must be installed on the host machine's Visual Studio Code IDE to utilize this feature.

The Bito VS Code extension seamlessly integrates with Remote development via SSH, allowing developers to utilize Bito features and capabilities on their remote machines.

### Remote SSH connection and setup

Please follow the instructions given in the links below:

* <https://code.visualstudio.com/docs/remote/ssh>
* <https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse>

**Video Guide:**

{% embed url="<https://www.loom.com/share/29af0fa7133b4173a1c51b1ee1a71095>" %}

## Setup Bito extension in VS Code running through WSL

Running VS Code on WSL allows developers to work in a Linux-like environment directly from Windows. This kind of setup is to take advantage of development experience on both operating systems.

WSL provides access to Linux command-line tools, utilities, and applications, to enhance productivity and streamline the development process.

This setup ensures a consistent development environment across different systems, making it easier to develop, test, and deploy applications that will run on Linux servers.

### WSL connection and setup

Please follow the instructions given in the links below:

* <https://code.visualstudio.com/docs/remote/wsl-tutorial>
* <https://learn.microsoft.com/en-us/windows/wsl/install>

**Video Guide:**

{% embed url="<https://www.loom.com/share/ac1b89c9c04a4c4e9de3067deb319d2b>" %}


# Installing on JetBrain IDEs

It takes less than 2 minutes

Get up and running with Bito in just a few steps! Bito seamlessly integrates with popular JetBrains IDEs such as IntelliJ IDEA, PyCharm, and WebStorm, providing powerful AI-driven code reviews directly within your editor. Click the button below to quickly install the Bito extension and start optimizing your development workflow with context-aware [AI Chat](/ai-code-reviews-in-ide/ai-chat-in-bito), and more.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>Install on JetBrains</strong></mark></td><td><a href="https://plugins.jetbrains.com/plugin/18289-chatgpt-gpt-4--bito-ai-code-assistant">https://plugins.jetbrains.com/plugin/18289-chatgpt-gpt-4--bito-ai-code-assistant</a></td></tr></tbody></table>

## Video guide

Watch the video below to learn how to download the Bito extension on JetBrains IDEs.

{% embed url="<https://www.loom.com/share/0dbbbdb278114cb88f2cbb9806849ff7>" %}
How to install Bito extension on JetBrains IDEs
{% endembed %}

## Step-by-step instructions

1. In JetBrains IDEs such as IntelliJ, go to **File -> Settings** to open the **Settings** dialog, and click **Plugins -> Marketplace** tab in the settings dialog. Search for Bito.

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2F6Nlx25tskAb3rLzvaR58%2Fimage.png?alt=media&amp;token=14bafff5-49af-4251-83ec-15b059cace17" alt=""><figcaption><p>Settings in IntelliJ IDE</p></figcaption></figure>

2\. Click "Install" to install the Bito extension. We recommend you restart the IDE after the installation is complete.

{% hint style="info" %}
Starting with Bito version 1.3.4, the extension is only supported on JetBrains versions 2021.2.4 and higher. JetBrains version 2021.1.3 is no longer supported from Bito version 1.3.4 onward.
{% endhint %}

3\. Bito panel will appear on the right-hand sidebar. Click it to complete the setup process. You will either need to create a new workspace if you are the first in your company to install Bito or join an existing workspace created by a co-worker. See [Managing  workspace members](/help/account-and-settings/managing-workspace-members)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FrW565i0d8YPg8jc2eymy%2Fimage.png?alt=media&amp;token=bd30680d-ea29-436c-afa2-a242075bc8b7" alt=""><figcaption><p>Bito in IntelliJ right-hand side bar</p></figcaption></figure>

{% hint style="info" %}
The menu to invoke the settings dialog may differ for different IDEs of the JetBrains family. The screenshots highlighted above are for the IntelliJ IDEA. You can access the Bito extension directly from the JetBrains marketplace at <https://plugins.jetbrains.com/plugin/18289-bito>.
{% endhint %}


# Installing on Cursor

It takes less than 2 minutes

Get up and running with Bito in just a few steps! Bito seamlessly integrates with Cursor, providing powerful AI-driven code reviews directly within your editor. Click the button below to quickly install the Bito extension and start optimizing your development workflow with context-aware [AI Chat](/ai-code-reviews-in-ide/ai-chat-in-bito), and more.

<a href="https://open-vsx.org/extension/Bito/Bito" class="button primary">Install on Cursor</a>

### Installation Steps

#### Step 1: Open Cursor IDE

Launch Cursor IDE on your computer.

{% hint style="info" %}
**Note:** Bito’s IDE plugin supports **Cursor version 2.0.77 and later**. Please ensure your Cursor installation is updated to this version or newer before installing the plugin.
{% endhint %}

#### Step 2: Access the extensions marketplace

From the top menu, click **View -> Extensions** to open the Extensions marketplace.

{% hint style="info" %}
You can also use keyboard shortcut to open the Extensions view:

* **Windows/Linux:** Press `Ctrl+Shift+X`
* **Mac:** Press `Cmd+Shift+X`
  {% endhint %}

#### Step 3: Search for Bito and install the extension

1. In the Extensions search bar at the top, type **"Bito"**
2. Look for the official Bito extension in the search results. The extension should be published by "Bito".
3. Click the **Install** button
4. Wait for the installation to complete (this usually takes just a few seconds)

<figure><img src="https://2860197046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYgNBTrPKG0DuVdAyDvSa%2Fuploads%2FEd27G45ygwn3MM2NTVpf%2Fscrnli_Tj3vmbTOoP0EL5.png?alt=media&amp;token=4764d6a4-4d65-43bc-a26a-dd9bc81319db" alt="" width="406"><figcaption></figcaption></figure>

#### Step 4: Sign in to Bito

Once installed, you'll need to authenticate:

1. Click **"Sign up or Sign-in"**
2. Bito authentication screen will display.
3. Log in with your Bito account credentials (or create a new account)

#### Step 5: Verify installation

To confirm Bito is working correctly:

1. You should see the Bito icon in your Cursor IDE sidebar
2. Click on it to open the Bito panel
3. You should now have access to all Bito features


# Installing on Windsurf

It takes less than 2 minutes

Get up and running with Bito in just a few steps! Bito seamlessly integrates with Windsurf, providing powerful AI-driven code reviews directly within your editor. Click the button below to quickly install the Bito extension and start optimizing your development workflow with context-aware [AI Chat](/ai-code-reviews-in-ide/ai-chat-in-bito), and more.

<a href="https://open-vsx.org/extension/Bito/Bito" class="button primary">Install on Windsurf</a>

### Installation Steps

#### Step 1: Open Windsurf IDE

Launch Windsurf IDE on your computer.

{% hint style="info" %}
**Note:** Bito’s IDE plugin supports **Windsurf version 1.11.0 and later**. Please ensure your Windsurf installation is updated to this version or newer before installing the plugin.
{% endhint %}

#### Step 2: Access the extensions marketplace

From the top menu, click **View -> Extensions** to open the Extensions marketplace.

{% hint style="info" %}
You can also use keyboard shortcut to open the Extensions view:

* **Windows/Linux:** Press `Ctrl+Shift+X`
* **Mac:** Press `Cmd+Shift+X`
  {% endhint %}

#### Step 3: Search for Bito and install the extension

1. In the Extensions search bar at the top, type **"Bito"**
2. Look for the official Bito extension in the search results. The extension should be published by "Bito"
3. Click the **Install** button and wait for the installation to complete (this usually takes just a few seconds).

#### Step 4: Sign in to Bito

Once installed, you'll need to authenticate:

1. Click **"Sign up or Sign-in"**
2. Bito authentication screen will display.
3. Log in with your Bito account credentials (or create a new account)

#### Step 6: Verify installation

To confirm Bito is working correctly:

1. You should see the Bito icon in your Windsurf IDE sidebar
2. Click on it to open the Bito panel
3. You should now have access to all Bito features
4. Try asking Bito a simple question to test the connection


# Vim/Neovim Plugin

Vim/ Neovim Plugin for Bito Using Bito CLI

We are excited to announce that one of our users has developed a dedicated Vim and Neovim plugin for Bito, integrating it seamlessly with your favorite code editor. This plugin enhances your coding experience by leveraging the power of Bito's AI capabilities directly within Vim and Neovim.

**Installation**

To get started with "vim-bitoai," follow these steps:

**Step 1: Install Bito CLI**

Make sure you have Bito CLI installed on your system. If you haven't installed it, you can find detailed instructions in the Bito CLI repository at[ https://github.com/gitbito/CLI](https://github.com/gitbito/CLI).

**Step 2: Install the Plugin**

Open your terminal and navigate to your Vim or Neovim plugin directory. Then, clone the "vim-bitoai" repository using the following command:

```sh
git clone https://github.com/zhenyangze/vim-bitoai.git

```

**Step 3: Configure the Plugin**

Open your Vim or Neovim configuration file and add the following lines:

```sh
" Vim Plug
Plug 'zhenyangze/vim-bitoai'

" NeoBundle
NewBundle 'zhenyangze/vim-bitoai'

" Vundle
Plugin 'zhenyangze/vim-bitoai'
```

Save the configuration file and restart your editor or run :source \~/.vimrc (for Vim) or  :source \~/.config/nvim/init.vim (for Neovim) to load the changes.

**Step 4: Verify the Installation**

Open Vim or Neovim, and you should now have the "vim-bitoai" plugin installed and ready to use.

**Usage**

You can use its powerful features once you have installed the "vim-bitoai" plugin. Here are some of the available commands:

* BitoAiGenerate: Generates code based on a given prompt.
* BitoAiGenerateUnit: Generates unit test code for the selected code block.
* BitoAiGenerateComment: Generates comments for methods, explaining parameters and output.
* BitoAiCheck: Performs a check for potential issues in the code and suggests improvements.
* BitoAiCheckSecurity: Checks the code for security issues and provides recommendations.
* BitoAiCheckStyle: Checks the code for style issues and suggests style improvements.
* BitoAiCheckPerformance: Analyzes the code for performance issues and suggests optimizations.
* BitoAiReadable: Organizes the code to enhance readability and maintainability.
* BitoAiExplain: Generates an explanation for the selected code.

To execute a command, follow these steps:

1. Open a file in Vim or Neovim that you want to work on.
2. Select the code block you want to act on. You can use visual mode or manually specify the range using line numbers.
3. Execute the desired command by running the corresponding command in command mode. For example, to generate code based on a prompt, use the : BitoAiGenerate command.\
   Note: Some commands may prompt you for additional information or options.
4. The plugin will communicate with the Bito CLI and execute the command, providing the output directly within your editor.

By leveraging the "vim-bitoai" plugin, you can directly harness the power of Bito's AI capabilities within your favorite Vim or Neovim editor. This integration lets you streamline your software development process, saving time and effort in repetitive tasks and promoting efficient coding practices.

**Customization**

The "vim-bitoai" plugin also offers customization options tailored to your specific needs. Here are a few variables you can configure in your Vim or Neovim configuration file:

* **g:bito\_buffer\_name\_prefix:** Sets the prefix for the buffer name in the Bito history. By default, it is set to 'bito\_history\_'.
* **g:vim\_bito\_path:** Specifies the path to the Bito CLI executable. If the Bito CLI is not in your system's command path, you can provide the full path to the executable.
* **g:vim\_bito\_prompt\_{command}:** Allows you to customize the prompt for a specific command. Replace {command} with the desired command.

To define a custom prompt, add the following line to your Vim or Neovim configuration file and replace your prompt with the desired prompt text:

```javascript
if !exists("g:vim_bito_prompt_{command}")
    let g:vim_bito_prompt_{command}="your prompt"
endif
```

Remember to restart your editor or run the appropriate command to load the changes.

We encourage you to explore the "vim-bitoai" plugin and experience the benefits of seamless integration between Bito and your Vim or Neovim editor. Feel free to contribute to the repository or provide feedback to help us further improve this plugin and enhance your coding experience.




---

[Next Page](https://docs.bito.ai/llms-full.txt/1)

