> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Using the Chatbot
> Chat with AI right inside the desktop app: it retrieves, reads, and connects the documents on your computer, and answers with citations.
## What the Chatbot Is
The Chatbot is the AI chat window built into the Linkly AI desktop app, and it's also the app's **default startup window** — install the app, open it, and this is the first thing you see.
The one thing that sets it apart from an ordinary AI chat tool: **it comes with a full retrieval toolset and can see every document you've indexed**. There's nothing to upload and nothing to paste. You ask a question, and it goes off to search, read, and cross-check on its own, then answers with citations.
Sign in to your Linkly AI account and the official models are ready; the retrieval tools are already built in
Every keyword it searched, every file it read, everything it got back — all of it can be expanded
### How It Divides Up with the Search Launcher
The app has two entry points, and they're easy to mix up:
| Entry point | Good for | How to open it |
| ----------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Search launcher](/docs/en/use-launcher) | You already know which file you want, and want to find and preview it in seconds | Global shortcut `⌘⇧L` / `Ctrl+Shift+L` |
| **Chatbot** (this page) | You have a question that needs reading, comparing, and summarizing across several documents | Click the tray icon; on macOS the Dock icon works too |
A simple rule: **use the launcher to find a file, use the Chatbot to ask a question.**
**The Chatbot has no global shortcut of its own.** `⌘⇧L` / `Ctrl+Shift+L` always opens the search launcher, never the Chatbot. To open the Chatbot, click the tray icon (or the Dock icon on macOS).
***
## Opening It, and What You See
The window defaults to 1200×800 and can be resized freely, down to a minimum of 880×640. **Closing the window only hides it — the app keeps running in the background**, and clicking the tray icon brings you straight back to the conversation you left.
The interface has three columns:
**New chat** sits at the top, followed by three entry points — **Note**, **Find Files** (which opens the search launcher), and **Settings** — and below those, your chats grouped by date (Today / Yesterday / Previous 7 days / This month / Earlier). Right-click or hover any chat to **Rename** or **Delete** it.
A row of small buttons runs along the very bottom: **Model quota**, index status, **Keyboard Shortcuts**, and **Official Website**.
The message stream plus the composer. The toolbar to the right of the composer holds the **model picker** and the **context window usage** percentage.
Two tabs:
* **Files in this chat** — split into **Referenced** and **Read**, these are the files the AI actually touched during this conversation
* **Library files** — a searchable file tree, whose context menu offers **Add to chat**, **Reveal in Finder** / **Show in Explorer**, **Transcribe now**, and more
Click any file to drill in and preview its text; the workspace can also be maximized and used as a reader.
### Shortcuts Inside the Window
These shortcuts **only work while the Chatbot window has focus**:
| Shortcut | Action |
| ---------------------- | --------------------------- |
| `⌘N` / `Ctrl+N` | New chat |
| `⌘⇧N` / `Ctrl+Shift+N` | Open notes |
| `⌘B` / `Ctrl+B` | Collapse / expand sidebar |
| `⌥⌘B` / `Ctrl+Alt+B` | Collapse / expand workspace |
| `⌘,` / `Ctrl+,` | Open settings |
### Index Status
The index button at the bottom of the sidebar has three states: a spinner reading **Indexing…**, a checkmark reading **Index up to date**, and a red **Indexing error**. Clicking it takes you to **Settings → Index**.
If the AI says it can't find a file you're certain exists, check this button first — usually indexing hasn't finished, or that directory was never added in the first place.
***
## Scoping with @
This is the Chatbot's most used feature, and the most frequently misunderstood one. Type `@` in the composer and a picker appears, offering four kinds of target:
* **Local libraries** ([about libraries](/docs/en/use-libraries))
* **Cloud libraries** ([about cloud libraries](/docs/en/use-cloud-library))
* **Folders**
* **Individual files**
Once selected, a row of chips appears above the composer. There's no hard limit on how many you can mention at once; **anything past the first line collapses into a `+N` chip** you can hover to see the full list.
**`@` is a scope suggestion to the AI, not a hard filter.**
The targets you pick are written at the start of your message as references (paths, library identifiers, document ids), and a fixed passage in the system prompt tells the model how to interpret them. The app **does not pre-read any document text** — the model still has to fetch content itself by calling the retrieval tools.
Put another way: you're **telling the AI to look here first**, not **restricting it to searching only here**. It complies the overwhelming majority of the time, but the model may not follow it to the letter — especially when the answer genuinely isn't inside that scope.
**`@` applies per message, not once per conversation.** Mention a library in this message and the next message without an `@` goes back to global scope. To stay in the same scope over several turns, mention it in every message.
### The Picker's Two Groups Behave Differently
The picker is split into two groups, and they behave noticeably differently:
| Group | Behavior |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Knowledge libraries** | Everything is listed as soon as it opens; pick straight from the list |
| **Files and folders** | **You have to type a keyword first** to get candidates, capped at 8 by default |
The **Files and folders** group also **matches on filename (basename) only, never on path**. To mention `~/Projects/2026/annual-review.docx`, typing `annual` or `review` finds it, but typing `Projects` won't (that only matches a folder actually named `Projects`).
### Four Conditions a Cloud Library Must Meet to Be Mentionable
If a cloud library isn't showing up in the picker, check these one by one:
1. You're [signed in to your Linkly AI account](/docs/en/linkly-account) (or have a Cloud API key configured)
2. The library has been linked on **the web** with the **Link** button
3. Its toggle is switched on under **Settings → Libraries → Connected cloud libraries**
4. The cloud library is **not bound to a local library**
Condition 4 is deliberate: a bound cloud library appears only through its corresponding local entry, so the same content isn't listed twice in the picker. To mention it, pick the local library instead.
### There Is No File Upload
The Chatbot **does not support uploading files or adding attachments**. Anything you reference with `@` has to be **already indexed**. To have the AI read a new file, first add the directory it lives in under **Settings → Folders**, or simply drop it into `~/LinklyAI` (which is watched by default), and mention it once indexing finishes.
***
## Choosing a Model and Checking Your Quota
### Two Kinds of Model Source
| Source | How to set it up |
| -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **[Linkly AI official models](/docs/en/model-service)** | Sign in under **Settings → Account** — no keys to fill in at all |
| **Any OpenAI-compatible endpoint** | **Settings → AI → Providers → Custom provider**, then fill in the Base URL and API Key |
The second kind covers both third-party cloud APIs and servers running on your own machine, such as **Ollama** and **LM Studio** (local servers usually need no key). 12 presets are offered when adding one, to fill things in quickly: OpenAI, DeepSeek, Mistral, Groq, OpenRouter, Qwen, MiniMax, Moonshot, Zhipu, SiliconFlow, Ollama, and LM Studio.
Presets **only prefill the address**; they don't include a model list. Once the address is in, the next step can auto-discover models from the provider's `/v1/models` endpoint, or you can enter model ids by hand.
Switching models happens in **the toolbar to the right of the composer**, grouped by provider. **Settings → AI** is where you set the default model for new chats, along with a pinned response language.
**A chat model has to support tool calling (function calling).** Models that don't simply never appear in the list — everything the Chatbot can do rests on calling the retrieval tools, and without tool calling it's just an ordinary chat box that knows nothing about your files.
### How the Quota Works
Quota for Linkly AI's official models is **not counted per token, nor per request** in isolation. It's a **shared pool**: each model has its own **multiplier**, shown as a badge in the model picker, and the lower the multiplier the less quota a request costs.
Quota runs across **three parallel time windows, each counted independently**:
| Window | What it's for |
| ------- | -------------------------------------------------- |
| 5 hours | Prevents burning through everything in one sitting |
| 7 days | Weekly usage |
| 30 days | Monthly usage |
Filling any one window gets you rate-limited — even if the other two still have room. To check: click the **quota button** at the bottom of the sidebar, which shows three ring gauges and their individual reset times.
When you run out, an **amber banner** appears above the composer telling you the limit has been reached and when it resets. The banner can be dismissed, but the actual enforcement lives on the server — dismissing it doesn't buy you an extra message. Free accounts don't see Pro-only models in the model list at all (the server filters them out); but if your Pro subscription lapses while your default model is still set to one of them, sending gets you a different banner prompting you to upgrade.
Third-party and local models don't consume Linkly AI quota; they're billed however you've arranged it with that provider.
***
## Chats and Context Compaction
### Chats
Every chat is stored in **a local SQLite database on your machine**. There is **no limit on how many, no automatic cleanup, and no retention period** — nothing goes away unless you delete it. Tool call inputs, outputs, statuses, and errors, along with the model's reasoning, are all persisted too, so coming back to an old conversation days later still gives you every detail.
Titles are generated automatically: an interim title is taken from the opening of your first message, and a proper one is generated in the background afterward using the same model. **Chats you've renamed by hand are never overwritten.**
### Context Compaction
As a conversation grows, the full message history stops fitting into the model's context window. Linkly AI's answer to that is **compaction**:
* **The automatic trigger is 80% of the model's context window**
* **To trigger it manually**: type `/compact` in the composer
**If the model's context window size is unknown, compaction never fires automatically.**
The window size comes from the `context_length` field returned by the provider's `/v1/models`. Custom providers and local Ollama / LM Studio setups frequently don't supply it, in which case the usage percentage can't be shown and automatic compaction won't happen — the conversation just keeps growing until the model itself errors out. With those models, keep an eye on the length yourself and run `/compact` or start a new chat when it's time.
Compaction is **append-only**, which matters:
* Only **the oldest stretch of messages** is folded into a summary; **the original messages are never deleted**
* Folded messages are **still visible in the interface**, they just no longer go into the context sent to the model
* **The most recent stretch of messages is kept verbatim**, with no summarizing at all
The summary itself is structured into six parts: the user's goal, every user message, key conclusions, documents read, tools and retrieval results (including negative results), and open questions. The model's reasoning content is discarded during compaction.
What you see in the interface is an extra expandable divider in the middle of the message stream: **Earlier messages compacted (N)**. Open it for the summary; the original messages remain readable underneath.
**The 80% automatic compaction gives no advance warning** — it just happens quietly. Only when the context is genuinely full (100%) do you get the banner reading **This conversation has filled the context window.**, with a **Compact** button attached.
To see it coming, watch the **context window usage** percentage in the composer toolbar.
When the topic shifts, starting a new chat (`⌘N` / `Ctrl+N`) is almost always the better deal: compaction costs an extra model call and loses detail, whereas a new conversation is clean, cheap, and faster.
***
## Seeing What the AI Is Doing
The Chatbot deliberately lays its process out for you, and that's the key to judging whether an answer can be trusted.
### Tool Calls
Every search and every file read is a tool call. Runs of consecutive calls are **folded into a single group**: expanded automatically while running so you can watch progress, collapsed automatically when finished to keep the message stream clean.
**Expanding a group shows you the full inputs and results** — exactly which keywords it searched, what scope it restricted itself to, how many results came back, which call failed. When an answer looks wrong, this is usually where the reason is sitting in plain sight (a poorly chosen keyword, say, or a directory that was never indexed).
### Citations
Facts in the answer that come from a document carry a clickable **citation marker** at the end of the sentence, which jumps to the source. Files that were cited or read are collected automatically into **Files in this chat** in the workspace on the right, so you can go through them one by one.
***
## Exporting
The Chatbot supports **exporting one item at a time**, with the output landing in your system Downloads folder:
| What you export | Available formats | Where to find it |
| --------------------------- | ----------------- | -------------------------------------- |
| A single AI response | Markdown / HTML | **Download response**, below the reply |
| A single table in a message | CSV / Markdown | **Download table**, above the table |
**There is no whole-conversation export**, and no PNG or XLSX support. To keep a whole conversation, your options today are exporting item by item, or selecting and copying.
***
## FAQ
That's by design. The global shortcut `⌘⇧L` / `Ctrl+Shift+L` is bound to the [search launcher](/docs/en/use-launcher); the Chatbot has no global shortcut of its own, so open it from the tray icon (or the Dock icon on macOS). In-window shortcuts such as `⌘N` and `⌘B` only work once the Chatbot window has focus.
Because `@` is a **scope suggestion** rather than a hard filter. The selected targets are attached as references at the start of the message, and the model decides how to use them — it will usually search that scope first, but may widen the search when it comes up empty.
If you need a strict limit, the most reliable approach is to say so explicitly in the message, for example: only look in the ml-papers library, and if it isn't there just say so.
Work through this in order:
1. **Did you type a keyword?** The **Files and folders** group only produces candidates after you type something, shows at most 8 by default, and an overly broad word gets crowded out by other files.
2. **Did you type the filename?** Matching looks only at the filename itself, never the path. A directory name from the middle of the path won't find the file.
3. **Is the file indexed?** Check the index status button at the bottom of the sidebar, or confirm under **Settings → Folders** that the directory has been added.
They're never deleted automatically. Chats live in a local database with **no limit on how many and no retention period**, including the complete inputs and outputs of every tool call. Delete the ones you don't need from the list on the left.
That depends on the model you pick. With Linkly AI's official models, or any third-party cloud API, the message content is sent to that model service — **including the document excerpts the AI retrieved**.
If you'd rather nothing left your machine, add a local Ollama or LM Studio provider under **Settings → AI** and use one of its models; the conversation then never leaves the device (the local model does have to support tool calling).
The retrieval capability is exactly the same. The difference is **where you use it**:
* **Chatbot** — works out of the box with no MCP configuration, and comes with a file tree, citation panel, and document preview: an interface built around reading material.
* **[MCP](/docs/en/use-mcp) / [CLI](/docs/en/use-cli)** — brings Linkly AI's retrieval tools into the AI tools you already use, which suits writing code, running agents, and anything else that has to work alongside the rest of your toolchain.
You can use both at once; they don't interfere with each other.
Yes. Compaction is append-only — **the original messages are never deleted**, they just stop going into the context sent to the model. Open the **Earlier messages compacted (N)** divider in the message stream to read all of the original text.
One caveat: from that point on the model **only sees the summary**, not the original text. If it seems to have forgotten a detail, just restate the key information in a new message.
***
## Further reading
* [Using the Launcher](/docs/en/use-launcher) — pinpoint a single file fast
* [Using Libraries](/docs/en/use-libraries) — group documents by topic to make `@` more useful
* [Using Cloud Libraries](/docs/en/use-cloud-library) — take a library off your machine and keep it online around the clock
* [Using Notes](/docs/en/use-notes) — the card notes living in the same window
* [Tools Introduction](/docs/en/tools-intro) — the full reference for the retrieval tools behind the Chatbot
* [FAQ](/docs/en/faq) — general questions about installation, indexing, and connectivity
* [Model Service](/docs/en/model-service) — the full account of the official model service and how quota works
* [Account](/docs/en/linkly-account) — what signing in unlocks, and the difference between Free and Pro