FAQ and troubleshooting

We have no repository — is Buff right for us?

Yes. For a department without code there is a space — a workplace with questions about documents, research and a knowledge base; it needs no repository. The whole track is in Buff without a repository, examples by department in Recipes by role.

Who can create a space and connect Notion or Google Drive?

A space is created by the organisation owner or a member with permission on the whole organisation. Connections to documents are set up by your IT specialist on the connector — once, for all departments. You can yourself share a Drive folder with the account they name and connect the integration to a Notion section. See What to ask your administrator for.

What do I do, and what does the administrator do?

You: create or get a space, ask a question, maintain the department’s knowledge base, and if needed share a Drive folder or connect the integration to Notion pages. The administrator: install the connector, set up the connection, enter your space in it, select the sections and folders, press “Check connection”. A checklist to hand over is in What to ask your administrator for.

How do I ask about a file that is not in the connected sources?

Attach it to a question in “Ask” — Word, Excel, PowerPoint, PDF or text, up to 10 MB; the agent will read the content. A scan without a text layer cannot be read. Research takes no attachments — the file is attached to a question or put into a connected folder. See How to ask a good question.

Why is there no link in the answer, or a “not found”?

Usually one of four things: the folder or section you need is not selected in the connection; the connection is not running; the account under which documents are read has no access to the folder; the document is a scan without a text layer. An answer without a link is a reason to ask “based on which document?”. The full breakdown is in What “not found” means.

Is there a mobile app?

Yes — the Buff app for iPhone and Android. Approve a formulation, answer a clarification, accept a review, ask a question with a photo of a document, allow a command in Buff Code — from your phone, with notifications. It is paired from the workspace: “Settings → Phone” — step by step. It is not paid for separately: usage is charged on the organisation’s plan.

What does a question cost and where can I see it?

You pay for the AI agent’s work, in roubles, by the volume of what it read and wrote; adding people costs 0 ₽. The cost of a conversation — the sum over all its questions and answers — is shown in the conversation header, the organisation’s spend in the balance card and in the billing history, visible to the owner. We do not quote ballpark figures — it depends on the plan and on how many documents had to be read. See What a question costs.

Does the AI agent see documents I have no access to?

The agent reads what is open to the connector’s account in the selected sections and folders — not what is open to you personally. So connect to a department’s space only that department’s documents, and grant access to the space to those entitled to read those documents: support does not see the HR space until it is granted access. A question from a comment in an external system is the exception: the bot answers anyone who asked in a selected place, so do not open connections with restricted documents where outsiders — customers, contractors, guests — see and comment on the pages and tickets. Do not connect personnel files or other personal data. See Documents: what leaves and what does not.

A question or research — which to choose?

If the answer fits on a screen and you will read it yourself — “Ask”. If the result will be forwarded or kept, or it has to reconcile several documents with each other — research: a second agent checks every statement against the sources. The decision table is in A question or research?.

Does it work with CRM, Bitrix24, 1C?

They are not in the ready-made catalogue — they are connected with a custom tool: IT downloads a ready one or writes one, adds it to the connector, marks the read-only tools, and the system is available to the agent at once, on a par with the catalogue. See A system not in the catalogue.

It says “the organisation requires single sign-on” — how do I sign in?

Your organisation has turned on “SSO only” mode: password sign-in is closed for members. On the sign-in screen press “Sign in with company SSO” and enter your work email or the organisation name — the corporate provider then confirms the sign-in. In detail — Single sign-on.

The 2FA code does not arrive

Check your spam folder — emails with the code sometimes end up there. You can request the code again.

“No token” when publishing

Add an upstream access token in Settings → Repositories. Publishing is unavailable without it. Or connect the repository through the connector — then the token stays with you and does not need to be entered in the UI.

My git is behind a firewall / self-hosted / I do not want to hand over tokens

Run the connector — a lightweight agent in your network. It connects git that is not reachable from the internet and carries repositories over to us (and pull requests back), while the access token stays with you. It also works for cloud github.com / gitlab.com / bitbucket.org if you do not want to hand us tokens.

We want to ask the bot right in the tracker

Install your tracker’s integration in the connector: Jira (Data Center, Server and Cloud), GitLab, GitHub, Gitea and Forgejo, Bitbucket (requests in pull requests), Redmine. The team writes a question as a comment — the answer arrives in the same place, and access to the tracker stays with you.

The bot does not respond to a mention in the tracker

Three usual causes: the repository or project is not in the connection’s visibility scope (an empty list means “nowhere”); the request is not addressed to the bot — check the account and the alias; the connection is not running — look at its status and log on the agent’s local page. A breakdown by symptom is in “Tracker integrations”.

An answer to a question from a pull request was computed “from the main branch”

This means the repository is not connected to Buff as a code source: there is nowhere to read the branch from, and the bot says so honestly. Connect it with the same connector, in the “Repositories” section.

The model in “Ask” does not see our wiki / Notion / documents

The source connection must name this project (or space) as “the project the work goes to” and have the “running” status — then its tools appear for the model in “Ask” and in deep research, in any project. Connected systems are not read in task development or audits. See Knowledge sources and Custom MCP servers.

Integrations do not start, but git works

Either the agent lacks the privileges to place an integration under a separate OS user (root or CAP_SETUID is required), or the machine has no suitable Python. The agent’s local page says which of the two it is — see “Installation”.

A task is “stuck” or stopped

Check the run status: it may have been stopped — it can be resumed.

A discrepancy during sync

Sync is one-way (upstream → mirror). Check the state of the branches in the Repositories section.

I cannot add a task

If the project is still preparing its development tools, ordinary tasks are temporarily hidden — wait until they are ready.

How does a knowledge entry differ from a task statement?

A statement describes one piece of work and lives along with it. Knowledge is what is true for all work in the project or organisation: a rule, a fact or a pitfall. A rule you add to every other task statement should be moved to the knowledge base — it will reach every run by itself.

Why did the model ignore my entry?

Three usual causes. The description does not answer its question — the model decides from the one-line description whether to open the body; rewrite it as “when this entry will come in handy”. The entry contradicts the code — the model is told plainly that when they disagree, the code is right. The entry is archived — then it does not reach the model at all. If the entry must always be followed, set the “show to the model upfront” flag: the model will receive it in full in every task — see how it reaches the model.

An entry I did not write has appeared in the knowledge base

The AI wrote it after finished work — this is the extraction pass. Every entry shows its author: the AI icon and the stage name. Such entries can be edited and archived like any others; the “AI” author filter shows them as a feed. The AI does not write rules and does not write to the organisation scope at all, and it cannot touch an entry with the “permanent” flag.