Assistant & RAG

Ask a question about your codebase

The shortest path from nothing to a cited answer about your own repository. Steps 1 and 2 are done by an organization manager, once.

1. Add an embeddings provider. Open Settings → Providers and add a connection: a name, a base URL (the form suggests OpenRouter's https://openrouter.ai/api/v1; any OpenAI-spec endpoint works) and an API key. Then open Settings → Models and, for RAG embeddings, pick that connection; also pick a chat model for the assistant. There is no platform key behind this: until an embeddings connection is chosen, repositories are chunked but nothing is embedded and Ask finds nothing to answer from. Ask says so in a banner and links managers to these two pages; other members are told to ask a manager.
2. Link the repository. Connect GitHub under Services and attach the repository to a project (on New project, or Project settings → Repository). See the web path for the steps. Attaching it connects the repository as a source and starts indexing; you do not add it again by hand.
3. Wait for it to be searchable. Indexing is not instant, and the page tells you where it is rather than implying it is done. A source reads Embedded only once every chunk of its current content has a vector; before that it reads Indexing or Embedding N of M, and a failure reads Embedding failed with the reason. On Ask's Sources panel an embedded source reads Live, and one still being indexed reads Indexing. A push to the repository re-indexes it, and an hourly sweep catches a push that was missed. Each re-index also drops files that were deleted or renamed in the default branch, and eval sets and test fixtures (priv/rag_eval/, test/fixtures/, any testdata/) are never indexed.
4. Ask. On the project page choose Ask about <project> (/o/<org>/projects/<project>/ask). The assistant opens scoped to that project, and the Sources panel lists its repositories, tickets and uploads with their state; a manager can re-index a source from there. Type a question; the answer lists the passages it was built from. A scope with no indexed sources shows Nothing embedded instead of answering from nowhere.

Connect a source

A source is a set of files the assistant can read. Three kinds ship today: a bucket (a storage bucket your org already owns), a repo (a connected git repository), and tickets (a Flicker project's tickets and their documents). More kinds plug in behind the same interface. A project's own tickets, repos and buckets are connected and indexed automatically — when the project is created, and again when a repository is attached. Turn on Keep indexed and new content is chunked and indexed as it lands — no manual re-index. A bucket source can also be restricted to a key prefix, so only the part of the bucket you point at is embedded.

Every source says what its sync is doing, read from the source and its background jobs rather than assumed: Not synced yet, Queued (behind other work), Syncing (with how long it has been running), Synced (and when), Sync failed (with the reason), or Paused: auto-sync is off — a manager can turn it back on from the source page. Opening a source does not start a sync; use the Sync action.

A source reads Embedded only when every chunk of its current content has a vector. Until then the corpus pages say what is true instead: Indexing, Embedding N of M, Embeddings not configured, or Embedding failed, with the counts.

Choose an embeddings connection

Embeddings run on your provider, billed to your key. In Settings → Model selection, pick which of your provider connections RAG embeddings use. Only the connection is yours to choose: the model is fixed to BGE-M3 (1024 dimensions), because every stored vector was made with it and a different model would make the existing index unsearchable. Until a connection is chosen, sources are still chunked but nothing is embedded, and the corpus pages say so. Choosing one — or fixing a key the provider rejected — queues the waiting documents automatically. A key the provider rejects stops embedding at the first attempt, the affected documents show the rejection, and it is never retried with anyone else's key — Flicker's included.

When you save a provider connection, Flicker cleans the pasted key (stray quotes, spaces and invisible characters are removed) and asks the provider whether it accepts it. A key the provider rejects is not saved. If the provider cannot be reached at that moment, the connection is saved with a warning that the key could not be verified.

A connection's base URL must be https and its host must resolve only to public addresses: private, loopback, link-local, tailnet and cloud-metadata addresses are refused, because Flicker sends your key with every request. This is checked when you save and again on every call, which connects to the exact address it checked and does not follow redirects. A connection saved earlier with an http:// URL is refused on every call and flagged in Settings → Providers; add it again with an https URL.

Hybrid retrieval

The assistant is agentic: it decomposes a question into sub-questions, runs a hybrid search for each — pgvector semantic similarity and Postgres full-text — and merges the results with Reciprocal Rank Fusion. Hybrid beats either alone: vectors catch meaning, full-text catches exact terms and rare tokens. A failed sub-query degrades to fewer results rather than dropping the answer.

Before it answers, every source is named with its repository, so two repositories' README.md are two different files. A ticket document that a newer version replaced is marked historical rather than shown as current, a #N ticket cited by a doc is fetched too, and AGENTS.md, docs and code rank above tests, migrations and ticket records. Only the sources the answer actually cites are listed under it.

Ask

Open Assistant under your project and ask in plain language; the answer is grounded in the passages it retrieved, and the model behind it is pluggable. A retrieval playground lets you inspect exactly what was retrieved for a query and tune the pipeline before you ship it.

Ask on a project page opens the assistant scoped to that one project; switch the scope to another project, or to Everything for the whole organization. The Sources panel lists what the scope searches — the project's repositories, tickets and uploads — and whether each is live, still indexing or embedding, or failed and why. Organization managers can re-index a source from there.

If the organization has no embeddings model or no chat model selected, or the provider now refuses a selected connection's key, the assistant says which, and links managers to Settings → Providers and Settings → Models.

Drafts: the assistant proposes, you confirm

Ask the assistant to file a ticket, track something or send a suggestion, and it can answer with a draft card under its reply: a title, a body, a priority (tickets) or kind (suggestions), and the project it would go to. A project-scoped chat prefills that project; otherwise you choose one of your organization's projects. Edit anything, then Create ticket or Send as suggestion, or Discard.

A ticket card can also include an editable task contract. Check Make factory-ready to approve that contract when you create the ticket. Any member who can create tickets can do this: the same click writes the contract, adds the factory tag and selects the ticket for development, exactly the three steps the ticket page allows. If any step fails, nothing is created.

The assistant itself cannot create anything. Its tools only search and read, plus two propose tools that write nothing: a draft is inert until you click. The click is checked again on the server (your membership, that the draft is from your own chat, that the project is in your organization), creates the record once even if you click twice, and links the card to it. The record notes which chat it came from, who confirmed it, and the sources the answer cited. A chat can receive at most ten drafts an hour.

This is deliberate. The assistant reads tickets, repositories and documents that anyone could have written, and a model that could file things on its own could be talked into it by that text. A draft is the most such text can produce, and you can discard it.