Using fella

The full guide to fella: installing it, opening a folder, asking questions, reading the working, choosing a model, adding packs, and keeping everything on your own computer. Covers fella 0.1.2.

What fella is

fella is a small local-first desktop app for personal analytics. Point it at a folder of your own files — bank statements, health exports, workout logs, notes, receipts — and ask questions in plain language:

“How did my spending change this year?”
“What patterns are in my workouts?”
“Which factors affect my coffee brewing results?”
“Summarize the trends in these documents.”

It is built for a regular person doing personal analytics — not analysts, not developers — so it is plain-language throughout and copes with a messy real-world folder. Three things are true of every answer:

Deterministic: Every figure comes from a real calculation — SQL, or Python when SQL can’t express it — never from the model guessing. A verification pass re-runs the calculation behind the answer and checks every number.
Shows its working: A fold under each reply holds the exact files read, queries run, sample rows, timings, and the self-checks. Nothing about how an answer was reached is hidden.
Read-only: fella reads your folder; it never writes, moves, or deletes anything, and it produces answers, not files. Nothing leaves your computer except the request to the model you choose — and the default model runs locally.

fella is deliberately not a general task agent: no file-management, no chores, and the base has a small, fixed set of tools. Everything extra — themes, skills, connections to outside data — is opt-in and described under Packs.

Install

Requirements

macOS 10.15+, Windows 10+, or Linux with WebKitGTK 4.1 (libwebkit2gtk-4.1, present on current GNOME / KDE desktops).
A model. A local Ollama works out of the box and keeps everything on your machine. No local machine to run one on? /login with Ollama Cloud for free-tier hosted models, or bring an API key for another provider.
No account, no sign-up. The app is a single self-contained binary.

One line

On macOS or Linux:

curl -fsSL https://lilfella.app/install.sh | sh

On Windows, in PowerShell:

irm https://lilfella.app/install.ps1 | iex

The scripts download the latest build from the releases page and put the app in place.

By hand

Prefer to do it yourself? Grab the build for your system from the latest release and verify it against the SHA256SUMS file there.

macOS: the .dmg. Drag fella to Applications, then right-click it and choose Open the first time (the build is unsigned).
Windows: the -setup.exe. If a SmartScreen warning appears, choose More info, then Run anyway.
Linux: the .AppImage (chmod +x, then run) or the .deb.

Give fella a model

Local, private (default): install Ollama and run ollama pull llama3.1. fella uses it on localhost:11434 automatically. The model must support tool calling.
Hosted, free: no local install needed — open fella, type /login, and pick Ollama Cloud. Its free tier covers a set of starter models at no cost. See Hosted providers.
Hosted, other providers: the same way (/login), at your discretion — these are typically paid per token.

Build from source

For contributors, or to run an unreleased revision. Needs Rust 1.88+, Node 22+ with pnpm, and on Linux the GTK / WebKit libraries listed in the repo:

git clone https://github.com/Avijit-Kumar-GIT/fella
cd fella && pnpm install
pnpm tauri dev          # or:  pnpm tauri build

The default build is SQLite-only, to stay small. cargo build --features duckdb swaps in DuckDB for .parquet support and faster large-file queries (about 30 MB heavier).

Open a folder

When fella starts, choose the folder you want to ask about. Use the button on the welcome screen, drag a folder onto the window, or type /open (/open <path> skips the picker). The folder is your workspace; fella only ever looks inside it.

fella then scans the folder: it walks up to three directories deep, skips dotfiles, honours a .fellaignore file if there is one (see Rescanning and ignoring), and treats a fella.md at the root as your context rather than data (see Workspace context).

Tabular files and spreadsheets become tables you can query straight away. Documents are catalogued and read on demand when a question needs them. /files lists everything fella found and which table each file became.

How an answer is built

When you ask a question, fella runs a short reasoning loop:

It reads your question alongside a summary of your files and any workspace context.
It calls its tools against your files — listing files, checking a table’s schema, running SQL, searching documents — one step at a time, up to 20 steps.
It drafts an answer in plain language, leading with the headline.
A verification pass (no extra model call) re-executes any SQL the answer cites, confirms the headline figure is unchanged, confirms every table it names really exists, and flags any number in the answer that did not come from a tool result. The result is the ✓ / ⚠ checklist in the working.

A plain message with no folder open (“hello”) just gets a normal reply — no tools are run. If fella uses all 20 steps without finishing, it makes one last pass with no tools and gives a hedged answer that says so. The step budget is configurable with the FELLA_MAX_STEPS environment variable.

One optional Background: line of general knowledge is allowed in an answer, and it never contains figures — every number is from your files.

What fella can do

The base has exactly seven built-in tools. Every call, and its result, is captured in the working whether or not the answer cites it; every call can carry a short plain-language note explaining why fella ran it.

fella’s built-in tools and what each returns
Tool	What it does
`list_files`	The files in your folder: kind, row count or size, and which table each one became.
`describe_schema`	One table’s columns: type, how often each is empty, distinct count, min and max.
`sample_rows`	The first few rows of a table, so fella can see the shape of the data before querying it.
`run_sql`	A read-only SQL query. Only a single `SELECT` / `WITH` is allowed — writes, schema changes, `ATTACH`, `COPY` and file-reading functions are rejected — and a watchdog stops a runaway query after 15 s (`FELLA_QUERY_TIMEOUT_SECS`).
`grep_files`	A case-insensitive regular-expression search across every catalogued document, returning the matching lines with their file and line number. No index.
`read_file`	The full extracted text of one document, capped at roughly 16,000 characters.
`run_python`	Python for statistics SQL can’t express (regressions, distributions). It runs with a throwaway working directory, a stripped environment, and time and memory limits — a guard rail, not a security sandbox — and a `sql()` helper hands your data back as a DataFrame. SQL is always tried first; Python is the escape hatch.

A connector can add more tools; they appear here and in the working exactly like the built-ins, under a <name>__<tool> prefix.

The working

Under each answer is a fold-away line like ▸ working · 3 steps · 412 rows · 0.7s. Open it to see every tool fella called, the SQL or Python it ran, a sample of the rows that came back, timings, and the self-checks from the verification pass, rendered as a ✓ / ⚠ checklist.

The working is collapsed by default. Esc collapses every open fold at once.

When fella won’t guess

fella does not fill in a plausible number

If your files cannot answer a question, fella says so plainly rather than estimating. Every figure in an answer is traceable to a query result you can see in the working; anything that is general knowledge is marked as such and carries no numbers.

Stopping and retrying

Press Esc, or click the pulsing dot next to the input box, to stop an answer while it is running. A stopped run keeps whatever it had gathered so far and replies Stopped.

/retry asks your last question again — useful after you switch to a stronger model, or if an answer was cut short.

Supported files

Supported file kinds, their formats, and how fella uses each
Kind	Formats	How it is used
Tabular	`.csv` `.tsv` `.json` `.ndjson`	Column types are detected (whole number, decimal, true/false, text); loaded into a table you can query with SQL.
Spreadsheets	`.xlsx`	Each sheet becomes its own table, with types inferred the same way.
Documents	`.pdf` `.txt` `.md` `.log`	Text is extracted and searched or read on your machine (see Documents). No index.

.parquet files are listed but need the DuckDB build; on the standard build a query against one returns a clear message telling you to rebuild with --features duckdb, or convert the file to CSV. Scanned or photographed PDFs (no text layer) are out of scope — fella extracts text, it does not run OCR.

How tables are named

Each tabular file becomes a table named after the file, lower-cased with punctuation turned into underscores — Bank Statement 2024.csv becomes bank_statement_2024. If two files would collide, the second gets a numeric suffix. /files shows every name, and /schema <name> shows one table’s columns and how empty each is.

Documents

There is no index and no embedding step. fella reads documents directly: grep_files runs a regular-expression search across all of them and returns matching lines with their location, and read_file pulls the full text of one file. This works identically on every model provider — a local model reads your PDFs and notes just as well as a hosted one.

Rescanning and ignoring

If files in the folder change, type /reindex to scan it again. /files lists what fella currently sees.

To keep files out of the scan, put a .fellaignore in the folder root — one glob pattern per line, like a .gitignore. Dotfiles are skipped already.

The local model

Out of the box, fella talks to Ollama on your own computer, so nothing you ask goes to anyone else. Install Ollama, then pull a tool-calling model once:

ollama pull llama3.1

fella looks for Ollama on localhost:11434 automatically and shows an up / down dot in the status line. A model without tool-calling support will connect but can’t drive the analysis loop.

Hosted providers

To use a hosted model, type /login, pick a provider, and paste an API key (or do it in one line: /login <name> key <key>). Supported providers:

Vercel AI Gateway — one key covers hundreds of models from many vendors.
OpenAI
xAI (Grok)
Ollama Cloud — hosted versions of the Ollama models. Its free tier covers a set of starter models at no cost, the easiest way to try fella without a local model or a paid key.
OpenRouter
Custom — any endpoint that speaks the OpenAI wire format; you supply its base URL.

/auth shows what you are signed in to; /logout <name> removes a key. Keys are saved to auth.json, a file only you can read (see Privacy and security). Everything — including questions about your PDFs and notes — works on every provider, because fella reads documents directly with no embedding step.

Choosing and configuring

/model on its own shows the current provider and model.

/model <name>: Switch to another model on the current provider. With more than one tab open, only the active tab switches; the provider is shared across tabs.
/model provider|base_url|model <value>: Set a single field. Setting base_url (with provider set to custom) is how you point fella at any other OpenAI-compatible endpoint.

Provider, base URL and model live in fella’s settings; the API key lives separately in auth.json.

Connection health

The status line at the bottom shows the workspace, the current model, an Ollama up / down dot, and how long the last answer took. If a hosted provider is unreachable, an answer returns a clear message and the dot goes red — transient failures are retried with backoff, and a partial answer is kept.

Tabs

Each tab is a separate conversation with its own transcript. Open one with /tab or Ctrl+T, close it with Ctrl+W, and switch with Ctrl+1–9. The folder and the provider are shared across tabs; each tab can pick its own model with /model.

Focus mode

/focus, or Ctrl+Shift+F, hides the tab strip and the folder header for a plain single view. Run it again to bring them back.

Past conversations

fella starts a fresh conversation each time it launches; the previous one is archived to a file. /history shows the folder those files are saved in (and how many there are). /clear starts over in the current tab, saving the old conversation first. ↑ brings back your last input.

Workspace context — `fella.md`

fella works with nothing set up, but a plain fella.md at the root of your folder lets you tell it how your files are organised and what your terms mean:

Statements are one file per month, named statement-YYYY-MM.csv.
Amounts are in GBP. Ignore the TRANSFER category — it is money moving
between my own accounts, not spending.

It is inert text, prepended to the model’s context on every question. There is no pack to install and no trust prompt, because fella is read-only. The data scan skips it.

Packs

Packs are opt-in extensions. None ship with fella, and default answer quality never depends on one. A pack is exactly one of three kinds:

Theme: A colour scheme — a map of the app’s colour tokens. One active at a time; inert data.
Skill: Markdown notes fed into the model’s context: vocabulary, file conventions, caveats it should always apply. Several can be enabled at once. A skill can only shape how fella words and interprets an answer — there is no tool for it to call. (A fella.md is the same idea, kept local to one folder.)
Connector: A link to a data source outside your folder — see Connectors.

Manage them with /packs:

/packs: List what is installed and enabled.
/packs install <id>: Install by id from the reviewed catalog. Every file is checked against a published hash.
/packs add <path>: Add a local pack directory. It is marked unverified, with a line on what it can do or reach.
/packs enable <id> · /packs disable <id>: Turn a skill or theme on or off.
/packs remove <id>: Uninstall.
/packs browse: Open the packs repository to find ids.

A hosted browse gallery is not live yet — for now, /packs browse opens the fella-extensions repository. Adding a local pack and installing by id both work today. Anything installed from outside the reviewed list stays marked unverified. Nothing auto-updates and nothing nags on launch.

Connectors

A connector (an mcp pack) lets fella read a source outside your local folder — Notion, a notes repo, a wiki — through a remote Model Context Protocol server. It is off until you connect it with a token.

/connect: List connectors and their status.
/connect <id>: Paste the token and turn it on.
/connect <id> off · /connect <id> forget: Turn it off, or turn it off and clear the token.

A connector’s tools show up in the reasoning loop and the working like the built-ins, prefixed <id>__<tool>. fella stays read-only about it: a tool the server marks read-only is used normally, one that declares no effects is used but flagged in the working, and one marked as writing or destructive is withheld — fella tells you when that happens. The token is stored in auth.json alongside your API keys.

Commands

You never need commands — everything has another way in — but they are quicker once you know them. Type / in the app to see the list, or Ctrl+K for the command palette.

/open <path>: Choose the folder fella looks at. Without a path, opens the picker.
/files: List the files fella found and the table each became.
/schema <name>: Show a table’s columns, types, and how often they are empty.
/sql <query>: Run a read-only query yourself, without the model. Still recorded in the working.
/login, /logout <name>, /auth: Sign in to a hosted provider, sign out, or see what is signed in.
/model: Show or change the provider, model, or endpoint.
/reindex: Scan the folder again for new or changed files.
/update: Check for a newer release and install it. See Updating.
/packs: Themes, skills and connectors you have added. /packs browse to find more.
/connect: Connect a data source you installed as a connector pack.
/tab: Open another conversation in a new tab.
/focus: Hide the tabs and header for a plain view (again to undo).
/history: Show where past conversations are saved.
/retry: Ask your last question again.
/clear: Start this conversation over (the old one is saved).
/help: The full list, in the app.

Keys

Enter: Send.
Shift+Enter: New line.
↑: Bring back your last message.
Ctrl+K: Open the command palette.
Ctrl+L: Clear the screen.
Ctrl+T · Ctrl+W · Ctrl+1–9: New tab · close tab · switch tab.
Ctrl+Shift+F: Toggle focus mode.
Esc: Stop a running answer, otherwise collapse every working fold.

Privacy and security

fella is read-only. It opens your files to read them and does nothing else to the folder: no writing, no moving, no deleting, no generated files. There are no permission prompts because there is nothing to permit. The read-only boundary is the whole safety story.

The only thing that leaves your computer is the request you send to the model you have chosen. With the local model, nothing leaves at all. With a hosted provider, your question and the parts of your files needed to answer it go to that provider, and nowhere else. An enabled connector talks to its own service because you set it up to.

Credentials — API keys and connector tokens — live in auth.json, a 0600 file (readable only by you) in the app’s data folder. They are not in the database, not in the browser, and never printed to the transcript.

run_python runs a snippet the model wrote as your user, with a stripped environment and time and memory limits. It is a guard rail, not a jail: it can still read files outside the workspace and reach the network. SQL is always preferred; Python is the rare escape hatch for statistics SQL can’t do.

Builds are unsigned. Verify a download against the SHA256SUMS file on the release page before you run it.

Updating

Type /update any time to check for a newer release. If one exists, fella downloads it, verifies it against the release's checksum, and installs it — the app closes, then you reopen it. fella never checks on its own: /update only reaches the network when you ask it to, the same as re-running the one-line install command or re-downloading the build by hand, which still work too. Signing, notarisation, and Homebrew / winget packages are planned.

Troubleshooting

The Ollama dot is red: Ollama isn’t running, or the model isn’t pulled. Start Ollama and run ollama pull llama3.1.
“Rebuild with --features duckdb” on a .parquet file: The standard build is SQLite-only. Build from source with cargo build --features duckdb, or convert the file to CSV.
macOS: “fella can’t be opened”: Right-click the app and choose Open the first time (the build is unsigned).
Windows: SmartScreen blocks the installer: Choose More info, then Run anyway.
Linux: the app won’t launch: Install WebKitGTK 4.1 (libwebkit2gtk-4.1).
An answer stalls or comes back weak: Press Esc to stop it, then /retry — or switch to a stronger model with /model and /retry.

Changelog

The short version, in plain language. Full technical release notes live on GitHub.

v0.1.2: Reopen a past conversation: /history now lists your saved conversations, and /history <n> loads one back into a new tab. Columns that mix numbers with text (a price column with the odd note in a cell) now add up correctly instead of quietly dropping the messy rows. Plus a new app icon, a tighter default window size, and a Windows fix for the mouse pointer disappearing over the folder picker.
v0.1.1: Added /update: check for a newer release and install it without redownloading by hand. Fixed a bug where rescanning a folder (/reindex) could wrongly say a file was no longer readable, even though nothing about it had changed.
v0.1.0 — first public release: fella is out. Point it at a folder and ask questions in plain language — every answer is a real calculation over your files, with a fold showing exactly how it got there. Works fully offline with a local model by default, or connect a hosted one (including a free option) if you would rather not run one yourself.