[← README](../../README.md) · [Docs index](../README.md) · [Reference](README.md) # Where things are kept Coxswain keeps its settings, its memory and its caches in the usual folders of each system. Use this page to find a file, or to remove everything. To see what takes room and get it back, use [Disk use](disk-use.md): Settings → *Privacy and updates* → *Disk use*, **F9** → *Disk use*, or `coxswain --disk`. ![Settings at Finding files with Details → Background reading open: Start with my session, Read now, the path /home/demo/.cache/coxswain/search.db with Show in panel, and Delete what was read (284 KB)](../screenshots/search-helper-session.png) *Settings → Finding files → Details → Background reading shows where the search store is and how large it is; Meaning shows the model's folder the same way, and Privacy and updates → Where things are kept lists every path.* ## Contents - [How to use it](#how-to-use-it) - [Every file and folder](#every-file-and-folder) - [On each system](#on-each-system) - [What you see](#what-you-see) - [Settings and config.toml](#settings-and-configtoml) - [In the terminal app](#in-the-terminal-app) - [Removing everything](#removing-everything) - [Questions](#questions) ## How to use it `coxswain --paths` prints them for your machine: ``` $ coxswain --paths config /home/me/.config/coxswain/config.toml state /home/me/.local/share/coxswain/state.json cache /home/me/.cache/coxswain name index /home/me/.cache/coxswain/index.bin search store /home/me/.cache/coxswain/search.db models /home/me/.cache/coxswain/models previews /home/me/.cache/coxswain/previews archive looks /home/me/.cache/coxswain/peek ``` In the desktop app, Settings (**Ctrl+,**) → *Privacy and updates* → *Where things are kept* lists the same paths, each with **Show in panel**, and the bottom of Settings says *Settings are stored in …* with the path of `config.toml`. *Finding files* → *Details* → *Background reading* shows the search store and *Built-in models* each model with its folder ([Built-in models](../search/models.md)). (`coxswain-gui --settings=privacy` opens it there.) ## Every file and folder | What | Path (Linux) | Holds | Safe to delete? | |---|---|---|---| | `config.toml` | `~/.config/coxswain/config.toml` | Your settings ([Configuration](configuration.md)) | Yes: everything goes back to its default | | `scripts/` | `~/.config/coxswain/scripts/` | Your scripts for **F2**, in both apps ([Scripts](../commands/scripts.md)) | They are yours | | `state.json` | `~/.local/share/coxswain/state.json` | The desktop app's session (panes, tabs, views, the preview engine you picked), favourites, colour tags, folder notes, recent repositories; the last update check; notices dismissed | Only if you want to lose tags and notes. A damaged file is moved aside to `state.json.bad`, never overwritten | | `index.bin` | `~/.cache/coxswain/index.bin` | The name index, saved so it loads at once | Yes: it is built again. **Clear** in [Disk use](disk-use.md), or `coxswain --disk clear index` | | `search.db` (with `-wal`, `-shm`) | `~/.cache/coxswain/search.db` | The text of your files, every file's size and date, folder totals, duplicate hashes, meaning vectors, the latest errors, [transcripts of speech](../search/transcripts.md) | Yes: it fills again. While Coxswain runs, use **Clear** in [Disk use](disk-use.md) (or **Delete what was read** in Settings → *Finding files* → *Details* → *Background reading*, or `coxswain --disk clear store`), which goes through the helper; by hand only with no Coxswain running | | `models/` | `~/.cache/coxswain/models/multilingual-e5-small-614241f6/` | The built-in model for search by meaning, about 465 MB | Yes: **Delete** under Settings → *Finding files* → *Details* → *Built-in models*, or `coxswain --models delete multilingual-e5-small` ([Built-in models](../search/models.md)) | | `models/` | `~/.cache/coxswain/models/qwen3-1.7b-d7f544ee/`, `qwen3-4b-a06e946b/`, `qwen3-14b-a04a82c4/` | The [built-in chat models](../search/ask-builtin.md) for Ask, 1.0 GB, 2.3 GB and 8.4 GB, when downloaded | Yes: **Delete** under Settings → *Finding files* → *Details* → *Built-in models*, or `coxswain --models delete unused` for all not in use, unfinished downloads and older versions too ([Built-in models](../search/models.md)) | | `models/` | `~/.cache/coxswain/models/whisper/` | Whisper's models for [transcripts of speech](../search/transcripts.md), 74.1 MB to 547 MB each, when turned on | Yes: **Delete** under Settings → *Finding files* → *Details* → *Built-in models* (*Whisper*), which turns transcribing off | | `peek/` | `~/.cache/coxswain/peek//` | The one file inside an archive being previewed or viewed, copied out for the look; replaced by the next, and left-overs of earlier runs go after a day | Yes, any time | | `nested/` | `~/.cache/coxswain/nested//` | Archives inside archives you opened, each copied out once to be looked into ([Archives as folders](../files/archives.md#limits)); the oldest goes past eight, all of them when the app ends, and left-overs of a run that crashed go after a day. Counted with the copies to look at in [Disk use](disk-use.md) | Yes, any time | | `archive-index/` | `~/.cache/coxswain/archive-index/` | What the compressed tars you opened hold, where each file starts in them and (`.seek`) the places a `.tar.gz`, `.tar.bz2` or `.tar.zst` can be unpacked from, so they open at once the next time ([Archives as folders](../files/archives.md#limits)); 256 at most, the oldest go first. Counted with the copies to look at in [Disk use](disk-use.md) | Yes, any time | | `inside-/` | `~/.cache/coxswain/inside-/` | The search helper reading the text of a file [inside an archive](../search/archives.md): one file at a time, deleted as soon as it is read, the folder when the archive is done | Yes, when no helper runs | | `previews/` | `~/.cache/coxswain/previews/` | PDFs, SVGs and pages made by tools (LaTeX, LibreOffice, PlantUML, pandoc, calibre for e-books), one folder per file and engine; those not shown for 30 days go by themselves, and past 4 GB the ones shown longest ago | Yes: Settings → *Previews* → *Previews made so far* → *Clear* does it | | `staging/` | `~/.cache/coxswain/staging/` | The folders a running app wrote passing names in (a copy's `.name.coxswain-tmp-…`, a save's `.name.coxswain-….tmp`), so the next start removes what a run that crashed or was killed left there; held by each running app and helper, so the others know it is alive and leave its work alone | Yes, when no Coxswain runs | | `index.addr`, `index.lock` | `~/.cache/coxswain/` | The helper's port and token (readable by you alone), and its lock | Only while no helper runs | | `helper.log` | `~/.cache/coxswain/` | When the helper started and left, and what failed; the whole text of an error the status line said short (readable by you alone) | Yes; it is emptied past 1 MB, or by **Clear** in Disk use | | `made-outside.txt` | `~/.cache/coxswain/` | The folders Coxswain made outside its own (Tectonic's cache, made by a LaTeX preview), so [Disk use](disk-use.md#outside-coxswains-folder) lists only those | Yes; Disk use then no longer lists them | | `libreoffice-profile/`, `libreoffice-index-profile/` | `~/.cache/coxswain/` | LibreOffice's own profiles for previews and for reading old Office files, so your open LibreOffice is left alone | Yes | | Session registration | `~/.config/autostart/coxswain-index.desktop` (FreeBSD, the other BSDs, illumos, and the Flatpak, in the host's `~/.config`), `~/.config/systemd/user/coxswain-index.service` (Linux), `~/Library/LaunchAgents/dk.mwo.coxswain.index.plist` (macOS), the `coxswain-index` value under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` (Windows) | Only with *Start with my session* | Use `coxswain --index-service off` instead | | `scratch/` | `~/.cache/coxswain/scratch/-/` | The work of reading a file's text with tesseract, LibreOffice or calibre, of cutting sound for a transcript, of a virus scan's list, and files on their way from one archive to another | Removed when each run ends; what a run that crashed or was killed left goes at the next start of either app or the search helper. *scratch/* in [Disk use](disk-use.md) | | `media/` | `~/.cache/coxswain/media/` | ffmpeg's, ImageMagick's, GDAL's, OpenSCAD's and kicad-cli's work while [Convert video or audio](../files/convert-media.md), [Convert or edit pictures](../files/edit-pictures.md), [Convert geodata](../previews/geodata.md#convert-geodata), [Export 3D model](../previews/openscad.md#export-3d-model), [Export from KiCad](../previews/kicad.md#export-from-kicad) or a preview of theirs runs; the result goes next to the original (a preview's into `previews/`) | Removed when each run ends; a crashed run's goes at the next start. In *scratch/* in [Disk use](disk-use.md) | | `geo/` | `~/.cache/coxswain/geo/` | GDAL's work while it reads [geodata](../previews/geodata.md)'s facts (its map and Convert geodata work in `media/`) | Removed when each run ends; a crashed run's goes at the next start. In *scratch/* in [Disk use](disk-use.md) | | `magick/` | `~/.cache/coxswain/magick/policy.xml` | The policy an installed ImageMagick runs under, and the container's too ([How a picture is kept from doing harm](../files/edit-pictures.md#how-a-picture-is-kept-from-doing-harm)) | Yes: written again when needed | | `ocr/` | `~/.cache/coxswain/ocr/` | OCRmyPDF's work while [Make PDF searchable](../files/searchable-pdf.md) runs; the copy itself goes next to the PDF | Removed when each run ends; a crashed run's goes at the next start. In *scratch/* in [Disk use](disk-use.md) | | `export/` | `~/.cache/coxswain/export/` | The work of [Build PDF of AsciiDoc](../files/asciidoc-pdf.md) and [Export draw.io diagram](../files/drawio-export.md); the results go next to the files | Removed when each run ends; a crashed run's goes at the next start. In *scratch/* in [Disk use](disk-use.md) | | `clamav/` | `~/.cache/coxswain/clamav/` | ClamAV's virus database for [Scan for viruses](../files/virus-scan.md), about 110 MB | Yes: fetched again before the next scan. **Clear** in [Disk use](disk-use.md), or `coxswain --disk clear clamav` | | `clamscan/` | `~/.cache/coxswain/clamscan//` | The list of files a virus scan reads, and freshclam's config | Removed when each scan ends; a crashed run's goes at the next start. In *scratch/* in [Disk use](disk-use.md) | | `drag/` | `~/.cache/coxswain/drag//` | Files dragged out of an archive to another program, kept a day so it can still read them | Yes; a run's go a day after it ends. In *scratch/* in [Disk use](disk-use.md) | | `provenance/` | `~/.cache/coxswain/provenance//` | Bills of materials made to be shown | Yes. In *scratch/* in [Disk use](disk-use.md) | | `chess/` | `~/.cache/coxswain/chess/` | Chess analyses kept, so a game analysed before shows at once: the newest 1000 | Yes: analysed again. *chess/* in [Disk use](disk-use.md) | | `cbv/` | `~/.cache/coxswain/cbv//` | ChessBase archives (`.cbv`) unpacked to be read, by the apps and by the search helper: up to 16 GB each, four at most per run | Removed when the run ends; a crashed run's at the next start. In *chess/* in [Disk use](disk-use.md) | | `quarantine/` | `~/.local/share/coxswain/quarantine/` | Files you moved into quarantine after a [virus scan](../files/virus-scan.md#the-quarantine-folder), readable by you alone on Linux and macOS, with `quarantine.log` (when, what was found, where each came from) | They are yours: delete them when you are sure, or copy one back | | `coxswain-replace-…` | The system's temporary folder | The files as they were before a [find and replace](../files/find-and-replace.md), so it can be undone (256 MB at most per replace) | Removed when the undo is forgotten; those of a run that ended go at the next start of either app or the search helper | | Tools' own caches | `~/.cache/typst`, `~/.config/kicad`, `~/.cache/kicad`, fontconfig's | What an installed Typst, kicad-cli or fontconfig keeps when a preview runs it, theirs as for your own use | Yes; the tools make them again. Not listed in Disk use | | Tectonic's cache | `~/.cache/tectonic` (`~/.cache/Tectonic` with older tectonic, `~/Library/Caches/Tectonic` on macOS, `%LOCALAPPDATA%\TectonicProject\Tectonic` on Windows) | TeX packages tectonic downloads when a LaTeX preview uses it; tectonic's own, shared with your own use of it | Yes: downloaded again. Disk use lists it when Coxswain made it | Archive passwords are not in any file: they live in the app's memory until it quits. The cache folder and the state folder, with everything directly in them, are readable by you alone: each start sets the folders to `700` and the files to `600`, so an install from before 1.26.4 is corrected the first time it starts after the update. ## On each system | Folder | Linux | macOS | Windows | |---|---|---|---| | Config (`config.toml`, `scripts/`) | `~/.config/coxswain/` (or `$XDG_CONFIG_HOME/coxswain/`) | `~/Library/Application Support/coxswain/` | `%APPDATA%\coxswain\` | | State (`state.json`) | `~/.local/share/coxswain/` (or `$XDG_DATA_HOME/coxswain/`) | `~/Library/Application Support/coxswain/` | `%APPDATA%\coxswain\` | | Cache (index, store, model, previews) | `~/.cache/coxswain/` (or `$XDG_CACHE_HOME/coxswain/`) | `~/Library/Caches/coxswain/` | `%LOCALAPPDATA%\coxswain\` | On FreeBSD, NetBSD, OpenBSD and illumos the folders are those of Linux. On macOS and Windows the config and state share one folder. ## What you see - `coxswain --paths` prints seven lines, the name left-aligned in 13 characters, then the path. A line with no path means the system has no such folder (rare: a user without a home folder). - Settings → *Finding files*: the *Words* line says *Files read: 107 · waiting: 0 · 284 KB on disk*; under *Details* → *Background reading* is the path of `search.db` with **Show in panel**: the active panel opens the cache folder with the cursor on `search.db`, and the preview shows its tables (**F3** in the terminal app their first rows too). *Details* → *Meaning* has the same button for the built-in model's folder, and *Privacy and updates* → *Where things are kept* one for every path. - The cache folder is never read into text search or search by meaning (it is left out like a hidden folder, also on macOS and Windows where it is not hidden), so the index never holds itself, its previews or the copies looked at. Its files are still found by name. - Settings → *Previews*: *Previews made so far*: *12.4 MB in the cache; made again when a source changes; those not shown for 30 days go by themselves*, with *Clear*. - Settings → *Privacy and updates* → *Disk use* (the total beside its heading): every row with its size, what clearing costs, **Show in panel** and **Clear** ([Disk use](disk-use.md)). - **Space** (or **F3** in the terminal app) on `index.bin` or `search.db` shows what it holds ([Data previews](../previews/data.md#coxswains-own-index-and-store)). ## Settings and config.toml None of these places can be changed in `config.toml`. They follow the system's folders; on Linux the `XDG_CONFIG_HOME`, `XDG_DATA_HOME` and `XDG_CACHE_HOME` variables move them. ## In the terminal app The same folders and files: both apps share `config.toml`, `state.json`, the cache and the helper. The terminal app writes to `state.json` only for the update check and notices; it does not use `scripts/` or `previews/`. ## Removing everything Uninstall the app the way you installed it ([README → Install](../../README.md#install)), then: 1. Turn off *Start with my session* if it was on: `coxswain --index-service off`. 2. Close every Coxswain window and the terminal app, and wait ten minutes for the helper to leave (or end the `coxswain --index-helper` process). 3. Delete the three folders above: config, state and cache. 4. Container images Coxswain pulled stay in podman or docker until you remove them there (or beforehand with *Remove* on the kind's row in Settings → *Previews* → *Preview tools*, or with *Clear* under *Outside Coxswain's folder* in [Disk use](disk-use.md); `coxswain --disk clear images`). So does Tectonic's cache (`coxswain --disk clear tectonic` beforehand, when Coxswain made it). A model pulled with Ollama goes with `ollama rm bge-m3`. ## Questions #### The cache folder is large. What takes the room? Usually `search.db` (the text of your files) and `models/` (465 MB, when search by meaning is on with the built-in model), then `previews/`. Settings → *Privacy and updates* → *Disk use* (or `coxswain --disk`) shows the size of each, with what clearing it costs and a **Clear** button ([Disk use](disk-use.md)). #### Can I move the cache to another disk? Coxswain uses the system's cache folder. On Linux, set `XDG_CACHE_HOME` for the session; on other systems, a symbolic link from `coxswain` in the cache folder to the other disk works. #### Is my config shared between the terminal app and the desktop app? Yes: one `config.toml` for both, and one search helper and cache. #### How do I copy my tags, notes and favourites to another machine? Copy `state.json` while no Coxswain runs. Tags and notes are kept by full path, so they show only where the same paths exist. #### I deleted `search.db` and Find finds no words in files. It fills again from the start: the helper reads your files anew, at half speed. **Read now** in Settings → *Finding files* reads at full speed. #### What is `state.json.bad`? A `state.json` that could not be read when an app started (not JSON, or not text), moved aside so a new one could be saved; when a `state.json.bad` is there already, the newer one is `state.json.