Chat Features

The chat is more than a text box: it knows your files, shows artifacts and charts, logs tool calls and automatically compresses long histories.

Sending Messages

Send – via button or Enter (switchable to Ctrl+Enter).
Stop – a running response can be canceled at any time.
Jump to bottom – a floating button takes you to the end of long histories.

When a Message Doesn't Get Through

Sometimes no answer arrives. In most of these cases Apis AI solves the problem by itself and tells you in the conversation what it is doing. These are the messages you may see:

What you see	What it means and what you can do
API Limit - Retry in 30s (Attempt 1/3)	The service asks you to slow down and tells the app how long to wait. Apis AI waits, counts the seconds down and tries again – up to three attempts. You do not have to do anything; a running attempt can be canceled with Stop.
an error naming the API limit	All three attempts were refused. Wait for the time the message names and send your text again.
Tool calls disabled	The context window of the model is too small for the tools that are switched on. So that your message still arrives, the app sends this first message without tools – you get an answer, just without file or MCP access. Raise Context Window under Providers & Models or choose a model with more room.
Tool Fallback	The model could not do anything with the tools on this turn. The app sends the same message once more without tools, so you still get an answer.
Output budget spent on reasoning	Typical of models that think before answering: the whole output budget goes into the thinking, and nothing is left for the answer. Apis AI retries on its own – first with a limited thinking budget, then without thinking, then with a hint to answer right away.
A notice that the answer was stopped because the output budget is used up	Even the retries brought no answer out of the model. Raise Max Output Tokens under Parameters, choose a different model, or split your request into smaller steps.
The provider did not return a response (empty output)…	The service delivered nothing at all. Send again or switch the model.

Other errors appear as a note above the input field with a small cross to close it. Which message belongs to which case – a missing API key or an empty model list, for example – is collected in FAQ & Troubleshooting. Your conversation is not lost in any of this: as soon as things get tight, Apis AI summarizes the older part (see History Compression).

Questions from the AI

Sometimes the AI has to decide something that you should decide yourself – for example which of two approaches it should take, or whether it may overwrite a file. In those cases it stops and asks instead of guessing: the questions appear right in the conversation, and your answer is sent with Continue.

Several questions in a row – the app pages through them (e.g. "Question 1 of 2"); you answer one after the other.
Suggested answers – as a rule the AI offers a few options with a short explanation and marks one of them as recommended.
Your own answer – instead of a suggestion you can always type your own text.
Multiple choices – for some questions you may pick more than one option.

While the AI waits for your answer, the response is simply paused – nothing is lost. If you would rather not answer, cancel the response with Stop.

Linking Files (@)

Reference files from your shared folders directly in the text:

Summarize @bericht.md and add the figures from @daten/q3.csv

While you type, a suggestion list appears. The AI receives the file content as context and – if allowed – can also write or edit it. Image files referenced this way are automatically sent as image input (see below).

Images & Screenshots

Models with image input (vision) can look at pictures. In the "+" menu choose Images to add one or more image files to your next message; the thumbnails appear above the input field and can be removed individually before sending. The image is downscaled and embedded, so it is available to the model even if the file is moved later.

You can also paste an image straight from the clipboard with Ctrl+V (or ⌘+V). If the clipboard contains an image, it is attached – even when it also carries text (browsers and office apps usually do). Text paste is handled separately, so normal text pasting keeps working.

Attaching never blocks the interface: as soon as an image is added, a placeholder chip appears immediately at the final thumbnail size, while the preview is decoded in the background. The finished thumbnail then replaces the placeholder without the toolbar jumping. Removing or reordering images does not decode the remaining previews again, and the same background decoding is used for the images in sent messages and in the artifact preview. If an image cannot be decoded, the chip falls back to a neutral image icon instead of failing.

Important: the Images entry is only active when the selected model supports image input. For all other models it stays grayed out ("Not supported") and cannot be clicked – this avoids requests that the provider would reject. The app detects this per model (Ollama and OpenRouter via their capability APIs, Claude and Gemini by model family, otherwise by model name).

The AI can also take a screenshot itself when a vision model is active:

list_screens – lists the available monitors with index and resolution.
capture_screenshot – captures the chosen screen (or the primary one) and returns it to the AI as an image; the screenshot appears directly at the tool call in the chat.

On X11 the app uses the native Java capture. On Wayland that only sees XWayland content, so it prefers the desktop tools (grim, spectacle, gnome-screenshot, import, scrot, maim) and captures the screen without any prompt; the requested monitor is then cropped out of the combined image.

Documents (PDF & Text)

In the "+" menu choose Documents to attach PDFs or text files (TXT, Markdown, CSV, JSON, XML, YAML, HTML, log files, …) to your next message. The attached documents appear as chips above the input field and can be removed individually before sending.

How the document reaches the model depends on the selected model:

Native document support (Claude, Gemini): the file is sent to the provider as-is, so the model sees layout, tables and images inside a PDF.
Without native support (Ollama, llama.cpp, DeepSeek, OpenRouter, …): the text is extracted locally first – PDFs are parsed with Apache PDFBox – and inserted into the prompt. The extraction is cached, so a reloaded conversation does not have to parse the file again.

Very large documents are truncated to keep the request within the context window. This works in every chat and in learning mode. Files you only want to reference (without loading their content) are still linked with @ (see Linking Files (@)).

Speech Input

With speech input enabled (see Speech Input), two buttons appear next to the "+" menu:

Microphone (dictation) – click it, speak, then click stop: the transcript is inserted into the input field. Clicking Send while recording transcribes and sends immediately.
Voice chat – click the speaker button next to the microphone. Apis AI then listens continuously, shows a live preview while you speak and sends every finished sentence automatically once you stop talking. Speaking while the AI is still answering interrupts the answer, just like sending a normal message. Click the button again to stop.

Setup and troubleshooting: Speech Input.

Skills in Chat

The "+" menu on the input field bundles attachments and skills:

Skills – enable skills manually selectable per chat (see Rules & Skills).
Images – add images for vision models (only active when the model supports it).
Documents – attach PDFs and text files (see Documents).

Below that, the same menu also holds the per-chat settings that used to sit as separate pills next to the input:

Provider / Model – switch provider or model for this chat (searchable list, favorites, refresh).
Terminal sandbox – override the global sandbox setting for this chat (Default (global), Sandbox On, Full Access).
Todo reminder – override the global reminder for this chat (Default (global), on, off).
Thinking – toggle extended thinking for this chat when the model supports it.

The model list is fetched once per provider and then cached for the rest of the app run. Opening the submenu or switching chats/providers does not start a new search (for llama this means no repeated GGUF folder scan). Only the refresh button in the list header forces a new query – e.g. so freshly added .gguf files show up without restarting the app. While a provider has never been loaded, the list stays empty and a spinner runs; on error the list stays empty rather than showing stale entries. Changing a provider's endpoint, key, GGUF folders or auto-start in the settings drops its cached list and loads it again.

Hovering a row opens its submenu to the right; the panel itself stays in place. Every setting here applies only to the current chat.

Active Provider & Model

Right next to the "+" menu a small chip is always visible in the input row. It shows the provider and model that are active for the current chat, e.g. Ollama · qwen3:14b. You no longer have to open the "+" menu to see which model will answer.

Per chat – every chat shows its own provider/model pair; switching chats switches the chip.
Updates immediately – when you change the provider or model in the "+" menu, the chip follows right away, without switching the chat or restarting.
Thinking active – a small brain icon appears in the chip when extended thinking is enabled for this chat.
Long names – the chip stays on one line, is shortened with an ellipsis and shows the full text as a tooltip on hover. The microphone and send buttons always remain fully usable.
No model selected – the chip shows Select a model… as a placeholder.

The chip is purely informational; click the "+" menu to actually switch provider or model.

Artifacts & Charts

Code blocks, SVG drawings and diagrams are collected in the right panel under Preview:

Code – with syntax highlighting and copy function.
SVG – directly rendered preview.
Charts – the AI creates diagrams via the chart tool; the diagram appears directly at the tool call and can be downloaded or saved as PNG.

Inline References to Generated Images

Diagrams the AI creates (create_chart) and screenshots it takes (capture_screenshot) are no longer only shown at the tool call. The AI can point at them from its running text: each generated image gets a short reference token such as [[art:1]]. Where the AI writes that token, the app places the image on its own full-width line in the message – right where it belongs, without scrolling through every tool call.

The token is assigned when the image is created and is handed to the AI in the tool result; the AI only ever uses tokens it actually received.
The image gets its own line (never squeezed between words): text before and after the token flows around it as separate paragraphs.
The chart's tool call is collapsed by default – the image itself is shown where the AI references it, so you no longer have to scroll through tool calls. Expand the tool call only if you want its raw details.
Numbering is per conversation and follows the order in which the images were created.
The image also stays attached to its tool call (and remains downloadable there).
Works in normal chat and in learning mode.

Markdown, Code & Trees

Responses are rendered as Markdown: headings, lists, tables, quotes, links, inline code as well as bold and italic. Markdown is also rendered inside quotes (> …) – headings, lists, code and tables appear there just as they do in the body text.

Mathematics is displayed: display formulas in $$ … $$ or \[ … \] are rendered as formula images (fractions, roots, superscripts/subscripts, Greek letters and operators). Inline formulas in $ … $ or $ … $ appear directly in the text with superscript/subscript characters. For actual calculations the AI uses the math_resolve tool (see Tools & Security): it evaluates single expressions or a whole batch and labels every result as exact, float approximation, undefined (domain) or NaN, so it does not have to guess at arithmetic and you can tell an exact value from a rounded one.

Code blocks appear in the bundled monospace font JetBrains Mono (uniform character width regardless of the system) with syntax highlighting, copy button and horizontal scrolling.

Every message can be selected and copied with the mouse: select text with the mouse button held down, then Ctrl+C (or ⌘+C). This also applies to thoughts, tool output and the entire message history.

ASCII trees made of box-drawing characters – such as scene or file trees – are recognized automatically by the app and rendered as a graphical tree instead of plain text:

each node as a chip, the root highlighted in color,
type labels such as (Node3D) as a badge,
comments after ←/→ as a muted annotation,
drawn connecting lines instead of dashes.

This also works without a code fence. Use the button at the top right to switch between tree and text view; the copy function always returns the original text.

Tool Calls & Thoughts

On every turn you see collapsed:

Thoughts (thinking) – the model's reasoning steps, provided thinking is active. During this the app shows "Thinking…".
Tool calls – count and status (running / OK / error) including the result. File changes appear as a Git-style diff.

The AI can use tools until the configured max tool rounds limit is reached (0 = no limit). Which tools a model receives in the first place is decided per model on the card Tool Selection per Model – see Settings.

Tool Failure Reminder If the same tool fails over and over, Apis AI steps in: after a few failed attempts in a row (configurable under Settings → Parameters) a short note appears in the conversation – it names the tool and how many attempts have failed – and the AI is asked to change its method instead of repeating the same call. One successful call starts the count over, and only a handful of such notes are sent per run, so they never become noise themselves. The same safety net works in workflow steps and keeps an agent from getting stuck in an endless tool loop.

Auto-Scroll & Long Thinking

While an answer or a thinking block streams in, the view follows the new content automatically – as long as you stay at the bottom. As soon as you scroll up, following stops so you can read in peace; scroll back to the bottom (or click the down-arrow button that appears) and the view follows along again. This also works with a single thinking block that is taller than the window: the view keeps the newest lines in sight instead of pinning the block to the top.

File Edits & Diffs

Every change the AI makes to a file appears in the conversation as a Git-style diff: removed lines in red with a leading -, added lines in green with a leading + and, above them, a neutral header line naming the file and the changed line range. The view uses the monospace font, scrolls on its own and is capped in height, so even extensive edits do not push the chat apart.

Tool calls appear collapsed as a row with the tool name and its status (running, OK, error). Clicking the row opens it – for a file edit that reveals the diff instead of the raw arguments. Scripts are the only exception: their terminal output is visible while they run.

How the AI Edits a File

For changes to an existing file the AI has exactly one tool: local_edit_file. It replaces one contiguous line range – startLine to endLine, 1-based and inclusive – with the text passed in newContent. Everything outside that range stays untouched; empty new text simply removes the range, so the diff then shows only removed lines.

Read first – before the first edit the AI reads the file with local_read_file in numbered mode. That is how it knows the correct line numbers.
Line numbers shift – after every edit the lines below the change move. The AI therefore reads the file again before each further edit. A range that does not fit the file is rejected with an error, and nothing is written.
New files – local_write_file creates files or overwrites them completely. It is not used for partial changes, because a full rewrite would hide what actually changed.
Large edits – the diff shows up to 200 removed and 200 added lines per edit; beyond that a summary line names how many further lines there are. The file itself is always written in full.

Shell Edits Are Blocked If the AI tries to modify an existing text file in a shared folder through the terminal – for example with sed -i, perl -pi, tee or a > redirect – the command is rejected and the AI is told to use local_edit_file instead, so that the change stays visible as a diff. Binary files and paths outside your shared folders are not affected.

Checking and Reverting a Change

The status at the tool call tells you whether the edit went through; on an error the file was left unchanged. Since the diff contains the removed lines, a change can be taken back: ask the AI to restore the previous wording of that range – it sees the removed lines in the diff and edits the same spot again.

Deleting a whole file is a separate step and asks for confirmation as long as Can delete files on its own is off (see Tools & Security). File tools only reach shared folders, and in a workflow node they can be switched off entirely – without file tools there are no diffs either.

Precise Wording Pays Off Name the file and the spot, for example Change the timeout in line 42 of config.yml to 30. That is exactly the edit the AI can carry out and document as a diff.

History Compression

As soon as the history reaches the compression threshold, the app summarizes older messages into a structured handover report. The threshold is measured against the usable input budget (context window minus a reserve for the answer: min. 20,000 or max. tokens). The 75 % threshold applies to the messages; the tool schemas that are sent along only trigger a compression when the whole request no longer fits the usable budget. That way a chat with many tools does not compress on every turn even though the messages leave plenty of room. The real token usage reported by the provider is used as that overflow bound, so the estimate calibrates itself after the first turn. A notice in the conversation marks the compressed messages; the most recent messages stay in their original form.

One rolling report instead of a growing stack – a new compression does not add another report: the earlier report and the new conversation are merged into one updated report, and only that one is sent. The superseded reports stay visible and searchable in the chat/archive, but no longer cost context. That is what keeps a long chat from permanently overflowing.
Tool results are summarized, then dropped – tool results count as facts for the report (distilled, not dumped) and leave the context once they are folded. A tool-heavy turn therefore shrinks instead of just adding a report.
Tool schemas count – the tool definitions sent to the model (files, shell, MCP, tasks, …) are part of the budget. If they alone fill the usable budget, compression cannot help; the app says so once instead of compressing in a loop. The budget line in the log names history and tools separately.
Calibration via usage – for OpenAI-compatible providers the app asks for the real prompt tokens of the request (stream_options.include_usage). Providers that do not support the flag are simply sent the request once more without it; the app then keeps working with the estimate.
The original goal is preserved – the first message of the chat (your original task) and the pinned active task are never compressed and are sent to the AI again after every compression.
Strict local templates – the summarize request carries exactly one system message, so local chat templates (which only allow a system message at the very beginning) do not abort it.
Verbatim tail by budget – the messages that stay in full length are chosen by a token budget, not only by a fixed count. Eight very long messages no longer blow up the tail.
Report quality – the handover report must contain all five sections. A report without any usable content is rejected and the history stays unchanged; the reason is shown in the chat. Individual sections that legitimately have nothing to say (e.g. no architectural decisions) are allowed.
Provider overflow – if the provider still rejects a request as too long, media in older messages is replaced and the app compresses once, then repeats the request exactly once. Only when this one replay does not succeed either does the turn end with an error; the cause (including the number of system messages in the summarize request) is written to the log.

Archive: Looking Up Lost Details

The complete original messages remain stored even when they are no longer in context. The AI can look them up specifically:

history_overview – lists all messages (including compressed ones) with ID and preview.
history_search – searches the entire history for keywords and returns matching snippets.
history_read – reads a specific original message by ID or index.

This way the AI does not have to guess early instructions (such as "use AI only to explain, not to replace") but can find them verbatim.

Large Tool Outputs Very large tool results (e.g. extensive file or research output) are offloaded: only the beginning plus a handle remains in context. The AI reads the rest on demand with tool_result_read. Optionally (see Settings → Parameters), old tool outputs are pruned before a summary: they are replaced by their handle whenever this frees more than 20,000 tokens. This way the history hits the compression threshold less often and the summary itself stays cheap.

Rewind – Back to an Earlier Message

Every user message has a Return button. It deletes everything after that message and puts your text back into the input field so you can change and resend it. Stored compressed histories are restored in the process. Rewind is available in normal chats as well as in learning mode and is disabled while a generation is running.

Tasks

The AI can create and maintain tasks via task management. They appear in the right panel under Tasks with status (Open / In Progress / Done / Discarded) and optional subtasks.

Todo Reminder The AI can gently check off open tasks itself after completed tool calls. The reminder is configurable globally and per chat or node.

Long-Term Plan

While Tasks are a scratchpad for a single response, the Long-Term Plan is for goals that span several messages or sessions – for example “learn linear functions” or a multi-week project. The AI maintains it via the plan tools and it appears in the right panel above the tasks.

Plan entries are saved with the conversation: they survive new user messages and a history compression. On every new message the AI is reminded of the open entries, so it does not lose the thread even in long chats. Entries have the same statuses as tasks (Open / In Progress / Done / Discarded) and can have subtasks.

Available in chat and learning mode The long-term plan is available in regular chat and in learning mode. It is not available in workflows.

Confirmations

When the AI wants to delete a file and the Can delete files on its own option is disabled, the app asks first. You can confirm or reject the action. Details under Tools & Security.