Welcome to Ekorbia

Ekorbia is a native desktop integrated productivity environment for local AI models. It runs entirely on your machine — there are no cloud services, no API keys, and nothing leaves your computer unless you explicitly tell it to.

Ekorbia is powered by Ollama, an open-source runtime that lets you download and run language models locally. If you can run a chat model in Ollama, you can use it in Ekorbia.

What Ekorbia gives you

• Multi-tab chat with independent conversations
• File and folder attachments with local retrieval-augmented generation (RAG) — ask questions over your own documents without uploading anything
• Images and vision — drop a screenshot or photo into a chat and ask about it (with a vision-capable model)
• A prompts library backed by plain Markdown files you can share, edit, and version-control
• Watches — ambient background jobs that monitor folders, RSS feeds, and web pages and summarize what changes
• A quick-query overlay — Spotlight-style panel that pops up over any app for fast one-off questions
• Screenshot capture — press a hotkey, drag a region, and a new chat opens with the screenshot attached
• Saving files from chat — let the model write HTML, scripts, configs, or notes straight to a folder you choose, sandboxed and atomic
• A memory file — a single Markdown file you control that Ekorbia injects into every chat as personal context
• Private chats — ephemeral sessions whose messages and attachments never touch the database
• Full-text search across chat history — find anything you’ve ever discussed
• Five themes — One Dark, One Light, Ayu Dark, Ayu Mirage, Ayu Light

Privacy and storage

Everything you do with Ekorbia stays on your machine:

• Chats are stored in a local SQLite database in your app data directory
• Prompts live as Markdown files in a folder you choose
• Attachments are indexed locally; embeddings are computed by a local model
• Watches poll the URLs and folders you configure, summarize with the local model you choose, and write notes to a local file
• Saved files from chat go to a folder you pick, never anywhere else

Nothing is sent to a third party. The only network traffic Ekorbia generates is between the app and your local Ollama server, and any URLs you explicitly point a watch at.

Where to start

If you’re new to Ekorbia, follow the Getting started section in order:

1. Install Ekorbia
2. Pull your first model
3. Your first chat

Otherwise, dip into whichever section sounds useful. Every page is self-contained, with links back to related features.

Install Ekorbia

Ekorbia is a native macOS desktop app. Before you can run it you need two things on your machine:

1. Ollama — the local AI model runtime
2. A chat model — at least one model pulled into Ollama (covered in the next page)

This page walks through installing Ollama and the Ekorbia app itself.

Install Ollama

Download Ollama from ollama.com and run the installer.

After it installs, Ollama runs in the background and exposes a local API on port 11434. Ekorbia talks to it over that port — no configuration needed on your end.

You can verify Ollama is running by opening your terminal and typing:

ollama --version

If you see a version number, you’re good. If the command isn’t found, restart your terminal — the installer adds Ollama to your PATH but only new shells pick that up.

Ekorbia can start Ollama for you. When you launch Ekorbia, it checks whether Ollama is already running. If it isn’t, a small banner appears offering to start it. You don’t have to interact with Ollama directly day-to-day.

Install Ekorbia

Download the latest Ekorbia DMG from the website and drag the app to your Applications folder. The first launch may show a Gatekeeper prompt — right-click the app icon and choose Open if macOS won’t let you double-click it.

On first launch Ekorbia runs a brief onboarding tour covering the hotkeys, attachments, memory file, and prompts library. You can skip it any time with Esc, and re-open it later from Settings → General → Help → Show tour again.

What gets created on your machine

On first run, Ekorbia creates a few things — all on your local disk, none on a server:

Both the prompts folder and memory file paths are configurable in Settings. The app data folder is fixed by macOS convention.

Next: Pull your first model →

Pull your first model

Ekorbia doesn’t ship with any models. You pull them yourself, one at a time, from Ollama’s library. Picking a good first model depends on what you have in mind.

A quick model-picking primer

Models come in different sizes (1b, 7b, 26b, …) and capabilities (chat-only, vision, tool use). Bigger models are smarter but slower and need more RAM. Roughly:

If you’re not sure, llama3 is a solid all-rounder that fits comfortably on most machines.

Pull a chat model

Open your terminal and run:

ollama pull llama3

The first pull will download several gigabytes — keep the terminal open and wait. Subsequent pulls of other models reuse shared layers and are usually faster.

You can pull as many models as you want; they all live side-by-side. Switch between them inside Ekorbia using the model picker in the bottom-right of the composer (covered in The chat window).

Pull a vision model (optional, but recommended)

If you want to drop images and screenshots into chats, you need a vision-capable model. Two good choices:

ollama pull gemma3:4b      # small, fast, can see images
ollama pull gemma4:26b     # larger, smarter, also sees images

If you have a vision model installed, Ekorbia will automatically switch to it when you attach an image — see Images and vision models.

Pull an embedding model (for attachments and search)

To attach files or folders and have Ekorbia find relevant chunks when you ask questions, you need an embedding model. The default Ekorbia expects is:

ollama pull nomic-embed-text

nomic-embed-text is small (about 270 MB), fast, and produces high-quality embeddings. You can use any other Ollama embedding model — change it in Settings → Attachments → Embedding model.

You only need this if you plan to attach files or folders. Pure text chats don’t use embeddings.

Checking what you have

Anytime you want to see what’s installed:

ollama list

You’ll get a table of models with their sizes and modified dates.

Removing a model

ollama rm <model-name>

Ekorbia is fine with you removing a model that’s set as the active one — at the next launch it falls back to the first installed model so you’re never stranded.

Next: Your first chat →

Your first chat

With Ollama running and at least one chat model pulled, you’re ready to use Ekorbia.

Launch the app

Open Ekorbia from your Applications folder. The main window appears with:

• Sidebar on the left — your history of chats, plus a search box and a + New chat button at the top
• Chat pane in the middle — currently empty
• Right panel on the right with three tabs (📋 Prompts, 👁 Watches, 📄 Files)
• Composer at the bottom — where you type
• Status bar at the very bottom — shows Ollama’s status and any background indexing

Pick your model

In the bottom-right of the composer there’s a model picker showing the active model’s name. Click it to see every model currently installed in Ollama. Pick one.

Your choice persists across launches — Ekorbia remembers the last model you used and re-opens to it. If that model is no longer installed (e.g. you ran ollama rm), Ekorbia silently falls back to the first available one.

Badges on the model name. If the active model can use tools (write files automatically), a small TOOL badge appears next to its name. If you’ve attached an image to the chat, a VISION badge appears on the image chip when the model can see it.

Send your first message

Click in the composer and type something — anything from “Hello” to a real question. Press Enter to send. (To insert a newline without sending, use Shift+Enter.)

The model’s reply streams in token-by-token. While it’s streaming, the Send button turns into a Stop button — see Streaming and the Stop button.

Tabs

Click + New chat in the top-left to open a second conversation in a new tab. Each tab has its own message history, model, and attachments. Switching tabs is instant.

To rename a chat, click its title at the top of the chat pane. Press Enter to save, Esc to cancel. Renames flow through to the history sidebar.

What’s next

You now know enough to use Ekorbia for basic chat. The rest of this guide covers the features that make Ekorbia more than a chat front-end:

• Attaching files and folders — ask questions over your own documents
• The prompts library — reusable system prompts stored as Markdown files
• Watches — ambient background summarization of folders, feeds, and URLs
• Quick-query overlay — Spotlight-style popup that works over any app
• Screenshot capture — region-select a screenshot straight into a vision chat
• Saving files from chat — let the model write files directly to disk
• Memory file — personal context Ekorbia injects into every chat

If you ever want to re-run the in-app onboarding tour, head to Settings → General → Help → Show tour again.

The chat window

The chat window is the heart of Ekorbia. This page covers what every part of it does.

Layout

The composer in detail

Left to right, the composer has:

1. Paperclip (📎) — attach an individual file (.txt, .md, .pdf, or an image). See Attaching files.
2. Folder icon (📁) — attach a whole folder. See Attaching folders.
3. Prompt-attach button (📋) — attach a system prompt from your library to this chat. See Prompts library.
4. Textarea — what you type. Multi-line, expands as you type. Enter sends, Shift+Enter inserts a newline.
5. Model picker — shows the active model’s name. Click to see every installed model and switch mid-conversation.
6. Send button — turns into a Stop button while a reply is streaming.

Attached files, folders, and prompts appear as chips above the textarea. Click the × on any chip to detach it.

Private chats hide the attachment buttons. Because attachments would normally persist to disk, private/ephemeral chats hide the paperclip and folder icons entirely. See Private chats.

Tabs

Every tab is independent: it has its own message history, model selection, attachments, and tool-call output directory. Switching tabs is instant — they’re all kept in memory.

Tabs with attached files show a small paperclip plus a count in the tab strip, so you can see at a glance which conversations have context loaded.

Model picker

Clicking the model name opens a dropdown listing every model currently installed in Ollama (queried live each time the picker opens, so a freshly-pulled model appears immediately).

The picker shows:

• The model’s name
• Any capability badges — TOOL for tool-capable models, VISION for vision-capable models

Your selection sticks across launches. If the model you previously picked has been removed, Ekorbia silently falls back to the first available one.

The quick-query overlay keeps a separate model preference, so you can have a heavy model in the main window for in-depth chats and a small fast model in the overlay for quick lookups.

Status bar

The bottom strip tells you what’s happening with the underlying systems:

• Ollama not running — start Ollama (Ekorbia will offer to do it for you)
• Model not pulled — the active model isn’t installed; pull it with ollama pull <name> or pick a different one
• Cold / Warming / Loaded — Ollama load state of the active model
• Indexing docs/ — 42/87 — appears when any attachment is currently being chunked and embedded; aggregates across all in-flight indexing jobs

The status bar can be hidden in Settings → General.

Related pages

• Streaming and the Stop button
• Edit and retry messages
• Markdown and code blocks
• Exporting chats

Streaming and the Stop button

When you send a message in Ekorbia, the model’s reply streams in token-by-token rather than appearing all at once. You see the response forming live, which is helpful for two reasons: you can start reading early, and you can interrupt it cleanly if it’s heading the wrong direction.

Stopping a streaming reply

While a reply is streaming, the Send button in the composer turns into a Stop button. Click it (or press the keyboard shortcut shown on hover) to halt generation immediately.

When you stop:

• Whatever was generated up to the cut-off point is kept and saved
• The partial message is marked as Stopped in the assistant’s response so you can see exactly where it was interrupted
• The conversation history stays consistent — no orphan rows, no half-saved tool calls

Stopping is non-destructive. You can edit the user message and resend, retry the assistant message to regenerate, or just keep going — the stopped reply is preserved as if the model had ended there on its own.

What happens behind the scenes

Ekorbia talks to Ollama over an HTTP streaming endpoint. Each chunk Ollama emits is rendered into the UI as soon as it arrives, with Markdown re-parsed on every chunk so headings, lists, and code blocks render correctly while the reply is still being written.

If your model supports tool calls (the TOOL badge on the model picker), tool calls only arrive in the final chunk of a turn — Ollama doesn’t stream them progressively. The visible token stream pauses briefly between the model’s text and the tool invocation, which is normal.

Related pages

• Edit and retry messages — for what to do with a stopped reply
• Saving files from chat — when tool calls produce file writes

Edit and retry messages

Two things rarely go right on the first try: the question you asked, and the answer you got. Ekorbia makes both fixable.

Edit a user message

Every message you sent has a small pencil icon that appears when you hover over it. Click it to:

1. Pull the message text back into the composer for editing
2. Truncate the conversation from that point onward (everything after the edited message is removed)
3. Send the revised message to the model, which then re-answers from your new wording

This is the right move when you realize partway through that you phrased the question badly and the model has gone down the wrong path. Edit, resend, and the conversation effectively rewinds.

The full database stays consistent. The truncated messages are removed from the chat, the full-text search index is updated to match, and there are no orphan rows. Re-editing the same message is fine.

Retry an assistant message

The most recent assistant reply has a retry icon (a small circular arrow) on hover. Click it to regenerate the same reply from scratch using the same context and the same model.

Useful when:

• The model gave you a reasonable but not-quite-right answer and you want to roll the dice
• A streaming reply got cut off by network hiccup or you accidentally pressed Stop too early
• You want to compare two answers to the same question (copy the first, then retry)

The previous reply is replaced in-place — Ekorbia doesn’t keep both. If you want to compare, copy the first reply to a scratchpad before retrying.

What edit and retry do not do

• They don’t preserve the previous reply alongside the new one
• They don’t re-run any attached file’s indexing — attachments are reused
• They don’t change the active model — switch the model in the picker if you want a different one to answer

Related pages

• Streaming and the Stop button
• The chat window

Markdown and code blocks

Assistant replies in Ekorbia are rendered as Markdown. Your own messages stay as plain text — you see exactly what you typed.

This page is mostly about what the rendering supports and what the code-block UI gives you.

What renders

The Markdown renderer supports the full common set:

• Headings (#, ##, ###, …)
• Bullet lists, numbered lists, nested lists
• Bold, italic, inline code, strikethrough
• Blockquotes
• Tables with column alignment
• Inline links
• Fenced code blocks with language tags
• Horizontal rules

Anything potentially unsafe — <script> tags, javascript: links, inline event handlers — is sanitized before rendering. The assistant cannot inject code that runs in the app, no matter what it puts in its reply.

Code blocks

Fenced code blocks (```python, ```rust, etc.) get the deluxe treatment:

• Syntax highlighting via highlight.js with the GitHub Dark color scheme
• A Copy button that appears in the top-right corner of the block on hover — click to copy the contents to your clipboard
• A Save button next to Copy on models without tool support (more on that in a moment)

The Save button on code blocks

If the active model can use tools (the TOOL badge is visible), the model will save files itself via the Saving files from chat flow — there’s no Save button on individual code blocks because the file is already written.

If the active model doesn’t support tools, fenced code blocks get a per-block Save button instead. Ekorbia infers a filename from:

1. A comment hint inside the block, like <!-- index.html --> or # main.py
2. The fenced language tag (html → untitled.html, python → untitled.py, etc.)

The save flows through the same sandbox and permission modal as the tool path. Files saved this way are tagged manual in the saved-files list.

Inline code and copy behaviour

Inline code is rendered in a monospaced font but doesn’t get a Copy button — triple-click to select and copy normally.

What user messages look like

To keep typing transparent, user messages are NOT rendered as Markdown — you see exactly what you typed, character for character. This matters when you’re working out a prompt: you can tell at a glance whether you forgot to escape something.

Related pages

• The chat window
• Saving files from chat
• Exporting chats — Markdown rendering is what’s preserved when you export to .md

Exporting chats

Sometimes you want a conversation outside of Ekorbia — to paste into a doc, share with a colleague, archive for later, or round-trip into another tool. Ekorbia exports any chat to either Markdown or JSON.

How to export

Click the kebab menu (⋯) in the top-right of the chat pane. You’ll see two options:

• Export to Markdown — clean, human-readable transcript
• Export to JSON — full structured data including tool calls and timestamps

A save dialog opens; pick where to write the file.

The kebab is hidden on private chats. There’s nothing on disk to export from an ephemeral session. See Private chats.

Markdown export

The Markdown export reads like a conversation, not a debug transcript:

## You

How do I install Ekorbia?

## Assistant

Download the latest DMG from the website...

Each message is tagged with its role as a level-2 heading, then the body verbatim. Assistant replies keep their full Markdown formatting (headings, lists, code blocks), so the export renders correctly when you open it in any Markdown viewer.

Tool-call internals are filtered out. Messages from the assistant invoking a tool (role: tool) are noise to a human reader, so Markdown exports drop them. You see the conversation as you’d remember it, not as the model would.

JSON export

The JSON export preserves every row in the conversation, including:

• System messages (memory file, attached prompts, citation injection)
• User messages
• Assistant messages
• Tool calls (function name, arguments)
• Tool results (the response the model received from the tool)
• Timestamps
• Source attribution (whether a file save came from a tool call or a manual code-block save)

This format is the right pick if you want to round-trip into another tool or post-process programmatically.

What you can do with an export

• Paste a Markdown export into Notion / Obsidian / your wiki as a clean writeup
• Email a Markdown export to a colleague — most mail clients render it
• Pipe a JSON export through jq to extract specific messages or build a dataset
• Diff two JSON exports to see how a conversation evolved if you re-ran with a different prompt

The export is read-only — your chat in Ekorbia stays untouched.

Related pages

• Markdown and code blocks — what Markdown exports preserve
• Private chats — why exports are disabled in ephemeral mode

Searching chat history

Ekorbia indexes every message you’ve ever sent or received with full-text search. The search box at the top of the History sidebar is the way in.

How it works

Start typing in the sidebar search box. After about 150 ms of idle time, Ekorbia searches across every message ever saved — both user and assistant — and shows ranked results below the title matches in a Messages section.

Each result row shows:

• The parent chat’s title
• A three-line snippet of the matching message with the matched words highlighted
• A relevance ranking (best matches first, using BM25 scoring)

Clicking a result opens the parent chat with the same query terms highlighted in every message, so you can scan around the hit for context.

Search syntax

The search is forgiving and tuned for natural typing:

• Multi-word queries AND together — code review finds messages containing both words
• Prefix matching is automatic — interrog matches “interrogation,” “interrogating,” etc.
• Punctuation is ignored — it's searches the same as its
• Case-insensitive — Bug and bug are equivalent

You don’t need to learn any operators — type what you remember about the message and the relevant chats float to the top.

Searching titles only

If you just want to find a chat by name (not by message body), the title-match results appear above the Messages section. Type a few characters of the title and the relevant chat appears at the top.

When search results seem stale

In rare cases (e.g. after restoring from a backup, or after a database migration), the search index can drift out of sync with the messages. Ekorbia keeps the index in sync automatically via database triggers, but if you ever suspect it’s stale:

• Close and reopen the app — the index is verified at startup
• If results still look wrong, file an issue

Related pages

• Edit and retry messages — both keep the search index consistent
• The chat window

Attaching files

Click the paperclip in the composer to attach one or more individual files to the current chat. The model can then answer questions about their contents.

Supported file types

Other file types aren’t accepted — the picker filters them out. If you need to ask about a different format, convert it to text first (e.g. PDF a Word document, or copy-paste a spreadsheet’s contents into a .md file).

What “attached” actually means

When you attach a file, you see a small chip above the composer with the filename and a progress indicator. What happens behind that chip depends on the file’s size:

• Small text files (under 8 KB) — inlined verbatim into the next prompt. Zero indexing latency; the model sees the whole file as part of your message.
• Larger text files and PDFs — extracted, chunked, and embedded with your configured embedding model (default nomic-embed-text). When you ask a question, Ekorbia retrieves the most relevant chunks and includes those in the prompt — see Citations and sources.
• Images — handed directly to a vision-capable model as base64; no chunking or embedding involved.

The chip lifecycle

A file chip moves through these states:

Click the × on any chip to detach. Detaching deletes the embeddings for that file too — re-attaching re-indexes from scratch.

File size limits

There’s no hard cap on file size, but very large files (hundreds of MB of text) take time to embed and your local machine has to fit it all in memory while indexing. For PDFs, the practical ceiling is somewhere around 50 MB before things slow noticeably — split larger PDFs if you can.

What the chat sees

When you send a message, Ekorbia constructs the prompt roughly like:

1. (Optional) The contents of your memory file as a system message
2. (Optional) Any attached prompts as system messages
3. Retrieved chunks from your attachments, labelled with citation indices [1], [2], …
4. The chat history
5. Your new message

The model is instructed to use the citation indices when referencing attached content. See Citations and sources for what the user-facing result looks like.

Related pages

• Attaching folders — same flow, but for entire directories
• Images and vision models — how images route to vision-capable models
• Citations and sources — how retrieved chunks become a Sources footer

Attaching folders

Click the folder icon in the composer to attach an entire directory tree to the current chat. Ekorbia walks the folder, filters to a configurable set of file types, indexes everything, and lets the model answer questions across the whole collection.

What gets included

By default, the folder walker includes:

• .md (Markdown)
• .txt (plain text)
• .pdf (PDFs — text extracted, page by page)

…and skips noise directories:

• .git, node_modules, target, dist, build, .venv, and several others

Both the file-type allow-list and the directory ignore-list are editable in Settings → Attachments. You can add .org or .rst to the allow-list, or add vendor/ to the ignore-list, for example.

Limits

• Up to 1000 files per folder are indexed. Larger folders are truncated with a warning chip; narrow the scope or attach a sub-folder.
• Symlinks are not followed — to keep the walker safe from cycles.
• Hidden files (starting with .) are skipped by default along with the standard ignore-dirs.

Watching the chip

Folder indexing is the longest-running attachment operation. The chip updates live so you can see progress:

The status bar at the bottom of the window aggregates all in-flight indexing across attachments and tabs (Indexing docs/ — 42/87), so you know when local work is still happening.

Incremental re-index

When you change a file inside an attached folder, Ekorbia notices via the file’s modification time the next time the folder is re-indexed. To trigger a re-index:

1. Click the ↻ refresh icon on a Ready folder chip

Only files whose modification time has changed since the last index will be re-embedded. Unchanged files keep their existing chunks — re-indexing a 500-file folder where one note changed takes seconds, not minutes.

Asking questions across a folder

Once the folder is Ready, ask anything — Ekorbia retrieves the top-6 most relevant chunks from across all files at send time and includes them as context for the model.

In the assistant’s reply, citation markers like [3] appear inline. Below the reply, a Sources footer shows file chips that match the citations. Folder chips can be expanded to show which sub-files contributed and their relevance scores. Shift-click any source chip to reveal that file in Finder.

See Citations and sources for the full footer behavior.

Changing the embedding model

If you change your embedding model in Settings → Attachments → Embedding model, existing embeddings become unusable until re-indexed (different models produce non-comparable vectors).

When that happens, a yellow banner appears above the chat:

N attachments were embedded with a different model. Re-index them with X to make them searchable again.

One click handles the lot — every stale attachment in every chat is re-indexed with the new model.

Related pages

• Attaching files
• Citations and sources
• Settings — for folder filters and embedding model

Images and vision models

Ekorbia supports image attachments through any vision-capable model in Ollama (Gemma 3/4, LLaVA, llama 3.2 Vision, etc.). Drop a .png, .jpg, .jpeg, or .webp into a chat and a model that can see it will see it.

What counts as a vision model

When Ekorbia loads a model from Ollama, it checks the model’s metadata for vision support. Models that can see images get a small VISION badge in the model picker.

To pull a vision-capable model:

ollama pull gemma3:4b        # small and fast
ollama pull gemma4:26b       # larger, smarter
ollama pull llava            # classic vision model

Attaching an image

Two ways:

1. Paperclip in the composer — choose any image file
2. Screenshot capture — press the hotkey, drag a region, and a new chat opens with the screenshot already attached

The image appears as a chip above the composer, just like other attachments. If the active model can see it, a VISION badge appears on the chip.

Mixed vision/text model behavior

What happens depends on whether your active model can see images:

When the active model is vision-capable

The image is encoded as base64 and included in the request to Ollama. The model receives it as part of your message and can describe, analyze, or answer questions about it.

When the active model is NOT vision-capable

Ekorbia checks whether any vision-capable model is installed:

• At least one available — Ekorbia automatically switches to it and shows a toast: “Switched to vision model: gemma3:4b”. The original model is restored if you remove the image.
• None available — A toast warns you the image will be ignored. You can still attach it (no error), but the model can’t see it. Pull a vision model to fix the situation: ollama pull gemma3:4b.

This auto-switch only happens for image attachments — text attachments never trigger a model swap.

What images do NOT do

• They are not chunked or embedded. Vision works directly on pixels, not on a text representation.
• They are not included in Citations and sources — citation markers refer to text chunks only. The image’s filename appears in the Sources footer as a non-citation chip so you can see what visual context was sent.
• They are not stored permanently as part of the chat unless the image came from your filesystem to begin with. Screenshot captures live in your temp directory and may be cleaned up by the OS on reboot.

Related pages

• Attaching files
• Screenshot capture
• Pull your first model — pulling a vision model

Citations and sources

When you ask a question against attached files or folders, Ekorbia retrieves the most relevant chunks and gives them to the model with citation indices. The model is instructed to mark its references inline as [1], [2], [3], and so on. Below the reply you’ll see a Sources footer with clickable chips that match those indices.

What a citation marker looks like

In the rendered reply, markers appear next to the claim they support:

The watcher runs every 30 seconds by default [2]. You can change this in the form’s Cadence field [3].

Clicking a marker scrolls (or jumps) the page to the matching chip in the Sources footer.

The Sources footer

Below the reply, each cited file appears as a chip:

• Filename + size badge
• A [3] label matching the marker in the reply
• A relevance score (higher = better match)
• Folder chips can be expanded to show which sub-files inside the folder contributed, each with its own score

Click a chip to open the file with your OS default application. Shift-click to reveal it in Finder.

Why citations matter

Without citation markers, you’d have to take the model’s word that it found the answer in your attachments. With them, you can:

• Spot-check claims against the source (“the model says X — did it really come from notes.md?”)
• Track down a particular section of a long document
• Notice when the model is answering without citing — usually a sign it’s making something up rather than using your content

Top-k chunks

By default, Ekorbia retrieves the top 6 most relevant chunks across all attachments. You can adjust this in Settings → Attachments → Top-k chunks. Higher values give the model more context (more citations possible) but slower responses and larger token usage.

How relevance is scored

Both your question and your attached content are passed through your embedding model. Each chunk gets a similarity score against the question, and the top N are picked. The score shown on each chip is the cosine similarity — closer to 1.0 means more relevant.

This is semantic search, not keyword search. Asking “how do I undo a commit” finds chunks about git reset even though the chunk doesn’t contain the word “undo.”

Images in the Sources footer

Image attachments appear in the Sources footer as non-citation chips (no [N] label). They were sent to the model as visual context, but the model can’t cite a pixel region the way it cites a text chunk. The chip is there so you can see what visual context contributed.

Related pages

• Attaching files
• Attaching folders
• Settings — Top-k and embedding model

Saving files from chat

Some models can do more than just emit text — they can call tools, including a write_file tool that saves any content the model generates directly to disk. Ekorbia exposes this safely, with permission controls and a sandbox.

When the feature is available

A model can save files when it supports tool calls. You’ll see a TOOL badge next to the model name in the picker for any tool-capable model. Models known to support tools include:

• gemma4 (any size)
• llama3.1 and llama3.2
• qwen2.5
• mistral-nemo
• Most newer mid-and-large models

For models that don’t support tools, you can still save individual code blocks manually — see the fallback section below.

First-save permission flow

The first time a model in a given chat tries to save a file, a modal appears:

You have three options:

• Allow — pick an output folder (pre-filled to ~/Library/Application Support/dev.ekorbia.desktop/Outputs/<chat-slug>/). All future saves in this chat go to this folder.
• Block — prevents any saves for this chat. The model is told it can’t save; subsequent tool calls return an error and no modal re-appears.
• Not now — skips this single write only. The modal will re-appear on the next attempt.

The choice sticks until you change it. You can change it later from the Files panel (see below).

The Files panel

Open the third tab in the right sidebar (the document icon, alongside Prompts and Watches) to see every file the model saved in the current chat.

Each row shows:

• Relative path (relative to the output folder)
• Byte size
• Age (e.g. “2 minutes ago”)
• Version count if the model has overwritten the file (v3 means the model has saved this path 3 times)
• Reveal button — opens the file in Finder
• Open button — opens the file with your default application
• Click the row to scroll the chat to the message that produced the save

Header buttons

In the Files panel header you can:

• Change… — pick a new output folder for this chat
• Reveal — open the current output folder in Finder
• Block — prevent any further saves for this chat

Atomic writes

Every save is atomic: Ekorbia writes to a temporary file in the same directory, then renames it into place. If the app crashes mid-write, the previous version of the file stays intact. You never end up with a partially-written file.

Sandbox

All saved files are sandboxed to the output folder you picked. Any path the model tries to write that:

• Contains .. segments (e.g. ../etc/passwd)
• Starts with / (absolute path)
• Resolves through a symlink outside the output folder
• Contains a NUL byte

…is rejected. The model receives an error from the tool and typically tries again with a corrected path, or gives up gracefully.

Fallback: saving code blocks manually

For models that don’t support tools, fenced code blocks in assistant messages get a per-block Save button (next to the Copy button).

Ekorbia infers a filename for the save:

1. From a comment hint inside the code block — <!-- index.html -->, # main.py, // config.json
2. Otherwise, from the fenced language tag — python → untitled.py, html → untitled.html

The save flows through the same permission modal and sandbox as the tool path. Files saved this way are tagged manual in the Files panel so you can distinguish them from tool-generated saves.

Common use cases

• Have a model write a small Python script and save it where you can run it
• Generate an HTML mockup and have the model save it as index.html + styles.css
• Draft a few config files (docker-compose.yml, nginx.conf, …) in one go
• Take dictation into Markdown notes that go straight into a folder you sync elsewhere

Related pages

• Markdown and code blocks — for the manual code-block Save button
• Settings — for output-folder defaults
• Private chats — saves are disabled in ephemeral mode

Prompts library

Ekorbia’s prompts library is a folder of Markdown files. Each .md file is one reusable system prompt — a persona, a task template, a style guide, anything you want the model to start each chat with already in mind. The library is git-friendly, shareable, and editable in any text editor.

The library lives at ~/Documents/Ekorbia/Prompts/ by default. You can change the location in Settings → Prompts.

What ships out of the box

Ekorbia includes 28 built-in prompts covering common use cases:

• Album Deep Dive
• Brainstorm
• Cliff Notes
• Cloudflare Uptime Watcher
• Cover Letter Writer
• Devil’s Advocate
• Email Draft
• Explain Simply
• Google Cloud Uptime Watcher
• How Does It End
• Job Posting Watcher
• Lateral Thinking Puzzles
• Log Triage
• Murder Mystery Interrogation
• New Listing Watcher
• Notes Synthesizer
• Personal Website Builder
• Price / Availability Watcher
• Professional Website Builder
• Rental Watcher
• Research Paper Tracker
• Resume Coach
• Sensitive Doc Q&A
• Should I Watch This
• Summarize
• Text Adventure
• Tone Reframer
• Translate → Spanish / French / German
• Wikipedia Edit Watcher

If you ever delete some of these by accident, Settings → Prompts → Restore built-in prompts re-copies them.

Using a prompt in a chat

In the composer, click the prompt-attach button (📋 icon) to see your prompts. Pick one and it attaches as a chip above the textarea. When you send your message, the prompt is included as a system message at the top of the conversation.

You can attach multiple prompts to a single chat — they’re concatenated in attach order. Click the × on a prompt chip to detach it.

The prompts panel

Open the Prompts tab in the right sidebar to see the full library:

• Search box at the top — searches across prompt names, body text, and tags
• Favorite filter chips — five colored buckets you can use to categorize personal favorites
• Tag filter chips — free-text tags pulled from each prompt’s frontmatter
• Sort options — Recent / A→Z / Z→A / Favorite (default: A→Z)
• List on the left, prompt body on the right — the column is resizable

Right-click any prompt in the list for actions:

• Attach to current chat
• Edit (opens the .md file in your default editor)
• Reveal in Finder
• Set favorite color (None / Red / Yellow / Green / Blue / Purple)
• Delete

The .md file format

Every prompt is a Markdown file with optional YAML frontmatter:

---
name: Email Draft
tags: [writing, work]
description: Write a professional email from rough bullet points.
---

You are a professional email drafter. Given a list of bullet points or rough
notes, produce a clear, concise, polite email...

The body below --- is the prompt content. Everything after the closing --- is what the model sees when this prompt is attached.

Filename is the stable ID. The .md filename (without extension) uniquely identifies the prompt. The display name in frontmatter is just for the UI — renaming a prompt is renaming the file, which keeps things consistent if you sync the folder via git or Dropbox.

Favorites

Favorites are five colored buckets — Red, Yellow, Green, Blue, Purple — that you can assign to individual prompts via right-click. They’re a personal categorization system: maybe Red is “everyday,” Blue is “for research,” Green is “watchers.” Use them however helps you find things.

Favorite colors are local to your machine — they live in Ekorbia’s local database and don’t travel with the .md files if you share them. This is deliberate: your favorites are personal, not metadata for the prompt itself.

Importing prompts

Click Import in the Prompts panel header to import .md or .txt files into your library. Plain-text files become Markdown files with no frontmatter — fine to start with, edit later.

Sharing prompts

Because prompts are plain Markdown files in a folder you control, you can:

• Sync the folder via git, Dropbox, iCloud, etc. — everything but favorite color travels with the file
• Email a .md file to someone with Ekorbia — they drop it in their prompts folder and it appears in their library
• Build a team prompt repo — a shared folder of best-practice prompts everyone pulls from

Related pages

• The chat window — for the prompt-attach button in the composer
• Settings — for changing the prompts folder location

Watches

A Watch is an ambient background job that monitors something — a folder, an RSS feed, or a web page — and summarizes anything new to a notes file. Set one up and forget about it; Ekorbia polls in the background and writes a running log of summaries.

Open the Watches tab in the right sidebar to see your watches. Click + Configure to create a new one, or the pencil icon on an existing row to edit it.

The three kinds of watch

All three kinds share the same notes file, model, and (optional) summarization prompt. They differ only in what they watch and how they decide there’s something new.

Common settings for all watches

Every watch has:

• Name — what shows in the list (free-form)
• Source — the folder path, feed URL, or web URL
• Model — which Ollama model summarizes new events (defaults to your main chat model)
• Summarization prompt — optional system prompt; you can pick one of the included *-Watcher prompts or none
• Notes file — where summaries are appended (defaults to ~/Documents/Ekorbia/notes.md)
• Cadence — how often to poll (in seconds)
• Notify — toggle for native OS notifications when new events arrive

Folder watches

Point at a directory; Ekorbia scans it every 30 seconds for new files. For each new .pdf, .txt, or .md, it extracts text and summarizes via the configured model.

Files that already existed when the watch was created are not summarized — only new arrivals trigger summaries.

RSS watches

Paste any RSS 1.0, RSS 2.0, or Atom feed URL. Ekorbia handles all three formats. For each previously-unseen entry, the summary is built from whichever of these is longest:

1. The <content> element
2. <summary> or <description>
3. The article body fetched from the entry’s link (if the feed only ships a teaser)

That fallback to fetching the linked article is what makes RSS watches useful even on feeds that don’t include full content.

Click “Test” before saving to see how many entries the feed currently exposes — catches typos before you commit.

URL watches

Paste any public web URL. Ekorbia fetches the page, strips HTML to text, and only summarizes when the visible text actually changes. This makes URL watches ideal for:

• Release-note pages
• Changelogs
• Leaderboards
• Status pages
• Job listings
• Any page that updates occasionally and you don’t want to keep refreshing

Snapshot mode vs Diff mode

URL watches have two modes:

• Snapshot (default) — when the page changes, the whole new page goes to the model
• Diff — only the added/removed lines (unified diff, 3 lines of context) go to the model

Diff mode is the right choice when you mostly care about deltas — for a long-lived changelog, sending only what’s changed since last poll keeps summaries tight and token costs low.

Diff mode’s first fetch is always a snapshot. There’s no prior content to diff against on the very first poll, so the first summary is always a full-page snapshot. Subsequent polls produce diff-only summaries.

Advanced: CSS selector

If a page has a lot of nav/footer/sidebar noise, you can specify a CSS selector in the watch form to narrow extraction to a sub-tree:

• article
• main
• .post-content
• #changelog

Anything matching the selector is extracted; everything else is ignored. If the selector matches nothing on a given poll, Ekorbia falls back to the whole page — a watch never silently dies from a typo.

Per-watch cadence

Each watch has its own poll interval. The defaults are tuned to be reasonable for each kind, but you can change them in the form:

• Folder: 30 seconds (good for active dev folders)
• RSS: 600 seconds = 10 min
• URL: 1800 seconds = 30 min

There’s a Run now button on each row that bypasses the cadence and polls immediately — useful when you don’t want to wait.

OS notifications

Toggle Notify in the watch form to get a native OS notification whenever new events arrive (macOS Notification Center). Multiple events from the same poll cycle are coalesced into a single banner (“5 new items from My Folder”) rather than five separate alerts. Watches with notifications enabled show a 🔔 in the list.

On macOS the watch form shows a small inline explainer before macOS’s permission dialog fires the first time, so you understand what you’re granting.

Editing a watch

Click the pencil icon between the on/off toggle and the trash icon on any watch row. The form opens pre-filled. Saving runs an upsert that preserves pipeline state (the URL’s last-seen content, the RSS feed’s seen-entry list, the next poll time) — so the next poll continues from where it left off rather than firing a baseline summary again.

The activity feed

The Watches panel shows the activity feed below the watch list. Each entry shows:

• The watch’s kind glyph (📁 / 📡 / 🌐)
• The source label
• The model that summarized
• Processing dots (animated when in flight)
• The full summary, inline (long ones truncate; click to expand)

Chat with your notes

The “Chat with notes” button at the top of the Watches panel opens a new chat with the accumulated notes file injected as a system message. This is useful when you’ve collected dozens of summaries and want to ask cross-cutting questions like “what’s been changing in the kubernetes docs this month?”

Related pages

• Prompts library — for picking a summarization prompt
• Settings — for default watch cadence and notes file path

Quick-query overlay

The quick-query overlay is a Spotlight-style panel that pops up over any app. It’s for short, throwaway questions you don’t want to interrupt your work for — quick lookups, definitions, “how do I…” questions.

Press ⌘⇧Space (default) anywhere on your Mac to open it. Press Esc or click elsewhere to dismiss.

Why it exists separately

Switching to the main Ekorbia window for a 10-second question is friction. The overlay is designed to:

• Never steal focus from whatever you were doing — the cursor stays where it was
• Auto-hide on blur — click anywhere outside the overlay and it vanishes
• Have its own model preference — keep a small, fast model in the overlay and a heavy reasoning model in the main window
• Stream responses inline — see the answer as it’s generated

The overlay isn’t meant for long multi-turn chats. When a question grows into a real conversation, the “Send to main” button promotes the session into a full chat tab in the main window so you can continue from there.

What’s in the overlay

Top to bottom:

• Search box / composer — type your question
• Model picker (small button) — pick which model the overlay uses (separate from the main window’s model)
• Prompt picker (small button) — attach a single system prompt if you want
• Send button — fires the query

After you send:

• The model’s reply streams in below the composer
• Send to main appears — clicking it opens a new tab in the main Ekorbia window with the same conversation, so you can continue with attachments, edits, etc.
• Clear — empties the overlay for the next question

Customizing the hotkey

Open Settings → General → Overlay hotkey and click the current shortcut. Press the new combination — it’s recorded immediately. The shortcut is registered globally (works in any app).

Pick something that doesn’t collide with macOS or another app you use. Combinations involving Cmd + Shift + Space (default), Cmd + Option + …, or Cmd + Ctrl + … tend to be safe.

Limitations vs the main window

The overlay is deliberately small:

• No attachments — no paperclip or folder buttons. If you need file context, use the main window.
• No multi-turn history — each overlay session is one question, one answer. Send to main if you want to continue.
• No tabs — only one conversation at a time.
• No saved files panel — the overlay can’t save files to disk.

Everything in the overlay is in-memory only. Closing it discards the conversation (unless you sent it to main first).

Related pages

• Settings — for the overlay hotkey and model
• Screenshot capture — a sibling hotkey-driven feature
• Private chats — for similarly ephemeral conversations in the main window

Screenshot capture

Press ⌘⇧1 (default) anywhere on your Mac to capture a screenshot straight into an Ekorbia chat.

How it works

The hotkey invokes macOS’s native region selector — the same crosshair UI you already know from Cmd+Shift+4:

• Drag for a region
• Press Space to switch to window-capture mode
• Press Esc to cancel

When you complete a capture, Ekorbia immediately:

1. Saves the PNG to your system temp directory
2. Opens a new chat tab in the main window
3. Attaches the screenshot to that tab as a vision attachment
4. Switches to the new tab so you can start typing your question

You can then ask anything about what’s in the screenshot — “what does this error mean?” / “transcribe this whiteboard” / “what’s wrong with this layout?”

When you have a vision model installed

If your active model can see images, you’re good — type your question, send, and the model gets the screenshot as part of the request.

When you DON’T have a vision model active

Ekorbia handles this gracefully:

• A vision model is installed but isn’t your active model — Ekorbia auto-switches the new tab to a vision-capable model and shows a toast: “Switched to vision model: gemma3:4b”.
• No vision model is installed — A toast warns you the image will be ignored. To fix this, pull a vision model: ollama pull gemma3:4b, then re-attach (or recapture).

Customizing the hotkey

Open Settings → General → Screenshot hotkey and click the current shortcut. Press the new combination — it’s recorded immediately. The shortcut is registered globally.

Pick something that doesn’t collide with macOS’s own shortcuts (notably Cmd+Shift+3, Cmd+Shift+4, Cmd+Shift+5).

Where the PNG file lives

The captured PNG is written to your system temp directory (/var/folders/.../T/). Ekorbia references it from the attachment store by path. Don’t delete the file before sending the first message — that’s when the bytes are read and base64-encoded into the request.

After the message is sent, the PNG can be safely deleted; macOS reclaims temp files on reboot in any case.

Workflow tips

• One-question screenshots: capture, type your question, get an answer, close the tab. Same flow as the overlay but with visual context.
• Annotated screenshots: take the screenshot, then drag-attach a separate annotated version on top (paperclip button) — vision models can compare the two.
• Combining with the memory file: if you frequently ask “explain this error message” type questions, add a system instruction in your Memory file like “When I attach a screenshot of an error, explain plainly what it means and give one concrete fix to try first.”

Related pages

• Images and vision models
• Quick-query overlay — sibling hotkey-driven feature
• Settings — for the screenshot hotkey

Memory file

The memory file is a single user-edited Markdown file that Ekorbia injects as a system message at the start of every chat. It’s the cleanest way to give the model habitual context you’d otherwise re-type into every prompt.

By default it lives at:

~/Documents/Ekorbia/memory.md

You can change the path in Settings → Memory.

What it’s good for

Anything you find yourself repeating to the model:

• Facts about you — name, location, time zone, role, areas of expertise
• Preferences — writing style, formality level, code conventions, “answer in metric”
• Project conventions — naming patterns, tech stack, “we use Python 3.12 and FastAPI”
• Standing instructions — “always include a TL;DR at the top”, “explain assumptions before answering”

Think of it like the model’s prior context about you, separate from any individual conversation.

How to edit it

In Settings → Memory, click Edit memory. Ekorbia opens the file in your OS default Markdown/text editor. If the file doesn’t exist yet, Ekorbia creates it from a small template so you have something to edit.

Save the file in your editor and the changes take effect on the next message you send — no Ekorbia restart needed.

Read-only from the model’s perspective

This is deliberate and important: the write_file tool (used by tool-capable models — see Saving files from chat) cannot touch the memory file. The model can read what’s in it; only you can edit it externally.

The memory file is your shared context with the model. It is not something the model gets to rewrite on its own.

Soft size cap

Ekorbia inlines the memory file into every chat send, so its content scales token cost linearly with size. There’s a soft cap of about 10 KB beyond which an inline warning appears.

For reference, 10 KB is roughly:

• 2,000 words
• 6 pages of prose
• A long-form bullet list of personal facts and preferences

If you find yourself wanting to put more than that in the memory file, consider using attachments for project-specific or per-topic context — those only contribute the chunks relevant to your current question, not the whole document on every send.

Memory vs prompts vs attachments

Ekorbia gives you three places to put context. Use each for what it’s best at:

Memory file is for “facts about me that should be in every chat.” Prompts are for “this conversation should have a specific persona or task.” Attachments are for “ask questions over this specific document or folder.”

Resetting

In Settings → Memory, Reset to default points the memory file path back to ~/Documents/Ekorbia/memory.md. The existing file at the current path is not deleted — only the configured path is reset.

Related pages

• Prompts library
• Saving files from chat — why the memory file is read-only to the model
• Settings

Private chats

A private chat is an ephemeral session. Nothing about it touches the database — messages, attachments, file saves never persist. The conversation lives only in memory and disappears when you close the tab.

To start one, click the lock icon beside the + New chat button in the sidebar.

Visual indicators

A private chat is never visually confused with a normal one:

• The tab in the tab strip shows a lock glyph next to the title
• A banner above the composer reminds you the conversation is private and ephemeral
• The export kebab (⋯) is hidden — there’s nothing on disk to export
• The paperclip and folder icons in the composer are hidden — attachments would persist to disk via the attachment store, defeating the purpose

What’s still there

You can still:

• Send and receive messages
• See streaming responses, stop generation mid-stream
• Edit and retry messages within the session
• Switch models mid-conversation
• Use Markdown rendering and code blocks (with Copy)
• Have multiple private chats open simultaneously in different tabs

What’s NOT there

• No chat history in the sidebar (the chat doesn’t appear in the History list at all)
• No attachments — paperclip and folder buttons are hidden
• No file saves — even tool-capable models can’t write files in a private chat
• No export — Markdown and JSON exports are hidden
• No search index — private messages aren’t indexed for Chat search

Switching tabs while a private chat is open

Switching the active tab away from a private chat doesn’t destroy it. The conversation stays in memory until the tab itself is closed. So you can have a sensitive scratch conversation open in one tab, do something in another, and come back to the private chat exactly where you left it.

What does destroy a private chat:

• Closing its tab (× button)
• Quitting Ekorbia

When to use a private chat

Good fits:

• Quick scratch work — exploring an idea you don’t want cluttering your history
• Sensitive prompts — anything you’d be uncomfortable having stored locally (even encrypted at rest on your machine)
• Test prompts — iterating on a system prompt to see what works without polluting your real chats
• One-offs you don’t need to find later — drafts, throwaway translations, fact lookups

Bad fits:

• Real work you might want to find again — there’s no history, no search, no export
• Conversations with attachments — attachments are disabled
• Tool-using sessions where the model writes files — file saves are disabled

The memory file still applies

A private chat does include your Memory file as a system message — that’s part of your standing context, not part of any specific conversation, and it stays consistent regardless of whether the chat persists.

Related pages

• The chat window — for the normal-chat composer
• Exporting chats — for why export is hidden in private mode
• Memory file — still applies even in private chats

Settings

Open settings from the gear icon in the bottom-left of the sidebar, or with the keyboard shortcut shown there on hover.

Settings is organized into four tabs.

General

The General tab covers the app’s appearance and hotkey configuration.

To set a hotkey, click the current shortcut value and press the new combination. Press Esc to cancel a recording without changing it.

Prompts

Settings for the Prompts library.

Memory

Settings for the Memory file.

Attachments

Settings that apply to files, folders, and embeddings.

Re-indexing after an embedding-model change

If you change the embedding model, existing chunks become unusable (different models produce non-comparable vectors). A yellow Stale-Embeddings banner appears above the chat with a one-click Re-index all button. Use it to re-embed every attachment with the new model.

You can also re-index a single folder anytime via the ↻ refresh icon on its chip.

Persisted UI state

These are saved automatically (not in the Settings panel — they update as you use the app):

• Sidebar width
• Right-panel width
• Prompt-list column width
• Panel open/closed state
• Right-panel selected tab (Prompts / Watches / Files)
• Selected model (per-window for main, separately for the overlay)
• Active theme
• Folder filters (in case you’ve customized them)

All of this survives across launches.

Related pages

• Themes
• Keyboard shortcuts
• Prompts library
• Memory file

Keyboard shortcuts

Two kinds of shortcut in Ekorbia: global (work in any app) and in-app (work when Ekorbia is focused).

Global shortcuts

Both global shortcuts are customizable in Settings → General.

Pick combinations that don’t collide with macOS (notably Cmd+Shift+3/4/5 for built-in screenshots) or other apps you use frequently.

In the composer

In the overlay

In the main window

In the History sidebar

In a code block (in an assistant reply)

There are no keyboard shortcuts on individual code blocks — they’re click-targets, not focusable.

Onboarding tour

Hotkeys you cannot bind

A few combinations are reserved by macOS and can’t be used as global hotkeys:

• Cmd+Q, Cmd+W, Cmd+H, Cmd+M — app-level controls
• Cmd+Tab, Cmd+Space (alone) — system switchers
• Cmd+Shift+3, Cmd+Shift+4, Cmd+Shift+5 — macOS screenshot menu

Ekorbia will refuse to record any of these in the hotkey-capture field.

Related pages

• Settings — for changing the global hotkeys
• Quick-query overlay
• Screenshot capture

Themes

Ekorbia ships with five themes. Pick one in Settings → General → Theme — the change applies instantly without restart.

The five themes

All five share the same UI structure — the same icons, layouts, spacing, and font. Only the color palette changes.

What changes with a theme

• Backgrounds (chat pane, sidebar, composer, panels)
• Foreground text colors at three levels (primary, secondary, muted)
• Accent colors (used for the model picker, badges, links, focus rings)
• Code-block highlighting follows the theme (One Dark / GitHub Dark for dark themes; a light variant for light themes)
• Markdown rendering inherits the theme palette

What doesn’t change

• Layout — the same window structure regardless of theme
• Font — Inter for UI, JetBrains Mono for code, Instrument Serif for limited accents
• Icons — same set in every theme

Switching mid-session

Switching themes does not affect:

• Your chat history
• Open tabs
• Streaming replies in progress
• Any in-flight indexing

You can switch as often as you like; the choice is persisted, so the next launch comes back with the same theme.

Why these five

Ekorbia’s themes are based on the One and Ayu color families — both originated as editor themes (Atom and Sublime/VS Code respectively) and are tuned for hours of legibility. They cover the major dimensions:

• Dark vs light
• Cool vs warm undertone
• High vs low contrast

If you can’t find a comfortable theme among these five, file an issue with what you’d want.

Related pages

• Settings — for picking a theme

Troubleshooting

Common issues and how to fix them.

Status bar says “Ollama not running”

Ekorbia can’t reach Ollama at http://localhost:11434.

Fix:

1. Click the Start Ollama prompt that should appear near the status bar, or
2. Open Ollama from your Applications folder yourself, or
3. From a terminal, run ollama serve

If Ollama is running and Ekorbia still says it isn’t, the port may be blocked or in use by another process. Check with lsof -i :11434.

Status bar says “Model not pulled”

The active model isn’t installed in Ollama.

Fix: either pull it —

ollama pull <model-name>

— or switch to a model that is installed via the model picker in the composer.

If you just pulled a model and Ekorbia doesn’t see it yet, click the model picker — Ekorbia queries Ollama live each time you open it.

A model loads but generates nothing

Possible causes:

1. The model is still warming up. First-token latency on large models can be several seconds. The status bar shows Warming… during this phase.
2. Your machine is out of memory. Big models (26B+) can exceed available RAM and Ollama will eventually error out. Check Activity Monitor; switch to a smaller model.
3. The context window is full. Very long conversations with attachments can hit the model’s context limit. Start a new chat or trim attachments.

An attachment is stuck on “Indexing”

If a folder or large file chip has been stuck at 42/87 for many minutes without progress:

Possible causes:

1. Your embedding model isn’t installed. Run ollama pull nomic-embed-text (or whatever model you’ve configured in Settings → Attachments).
2. Ollama is overloaded. If the chat model is also running, your machine may be RAM-starved. Try detaching one of them.
3. A particular file is corrupt or extraction failed. Detach the attachment and re-attach without that file.

To stop a stuck indexing job, click the × on the chip — Ekorbia cancels the in-flight embedding and discards partial work.

“Stale Embeddings” yellow banner

You changed your embedding model in Settings → Attachments → Embedding model. Existing attachment chunks were embedded with the old model and can’t be searched against the new one.

Fix: click Re-index all in the banner. Every attached file in every chat is re-embedded with the new model. This may take a few minutes if you have many attachments.

Vision model doesn’t see attached images

Verify:

1. The model has the VISION badge in the model picker
2. The image is .png, .jpg, .jpeg, or .webp (other formats aren’t supported)
3. The image is under ~20 MB — very large images can fail to encode

If the model is vision-capable but still ignores images, restart Ekorbia (which re-reads model capabilities from Ollama).

A code block’s Save button doesn’t appear

The Save button on individual code blocks appears only when the active model doesn’t support tools. If you’re using a tool-capable model, the model writes files via the Saving files from chat flow — there’s no per-block Save button because the file is already written.

To save a code block from a tool-capable model, copy it (the Copy button is always there) and paste into your editor manually.

Tool-capable model isn’t writing files

Possible causes:

1. You previously chose “Block” on this chat’s first-save modal. Open the Files panel header → Change… to pick a folder, which un-blocks saves.
2. The model isn’t trying. Some tool-capable models won’t call write_file unless explicitly asked. Try “Save the result to a file called foo.html.”
3. The model’s tool call failed. Check the chat for a tool-error message; common issues are path traversal (.. in the path) or unsupported characters.

Quick-query overlay won’t open

Verify:

1. The Ekorbia app is running (the overlay needs the main process alive even if the main window is closed)
2. The hotkey isn’t being captured by another app (test it in TextEdit — if a Cmd+Shift+Space combo types a space, another app has stolen it)
3. The hotkey hasn’t been changed without you remembering — check Settings → General → Overlay hotkey

Screenshot capture toasts “Switched to vision model” and nothing happens

The screenshot was captured successfully but your previous active model can’t see images. Ekorbia auto-switched the new tab to a vision model. Type your question and send — the vision model will see the screenshot.

If no toast appeared but the screenshot tab opened anyway, no vision model is installed. Pull one:

ollama pull gemma3:4b

…and either re-take the screenshot or detach + re-attach the existing one.

A watch is silent

Verify:

1. The watch toggle is on (top-left of its row)
2. The cadence has actually elapsed since the last poll (folder=30s, RSS=10min, URL=30min — click Run now to bypass)
3. There’s actually something new to summarize (URL watches stay silent when content hasn’t changed; this is correct behavior)
4. The model the watch uses is installed (ollama list)

The activity feed in the Watches panel shows the last poll time — if it hasn’t updated, the poller isn’t reaching the source.

A watch shows an error in its activity feed

Click the error entry to expand it. Common errors:

• Network errors — the URL is unreachable; check that the page works in a browser
• Parse errors on RSS — the feed isn’t valid RSS/Atom; check the URL points at the feed XML, not the page
• CSS selector matched nothing — Ekorbia falls back to whole-page extraction; the next summary will use the whole page
• Folder doesn’t exist — the watched directory was moved or deleted

The watch will keep retrying on its cadence; once the underlying problem is fixed, the next poll picks up cleanly.

Themes look broken / fonts wrong

Ekorbia uses Inter, JetBrains Mono, and Instrument Serif. If these aren’t on your machine, the app falls back to system equivalents — but the fallback may look different from intended.

Fix: install the fonts, or accept the fallback. Ekorbia doesn’t bundle font files (yet).

Something else

If you’re stuck and the page above doesn’t cover it:

• Check the README at the project’s repository
• Open a fresh chat and ask Ekorbia itself — sometimes the model can talk you through the symptom

If you’ve found a real bug, please open an issue with reproduction steps.

Related pages

• Pull your first model
• Settings
• Saving files from chat